PHP Manual

# PHP 手册

2026-06-22
中文翻译人员：
戴劼
乔楚
袁玉强
王远之
段小强
陈伯乐
周梦康
肖理达
肖盛文
褚兆玮
鲍国枭
鲁飞

# 版权信息

Copyright © 1997 - 2026，PHP 文档组版权所有。分发本资料须遵守 Creative Commons Attribution 3.0 或更新版许可中阐明的条款及条件。Creative Commons Attribution 3.0 许可的副本已随本手册发行。其最新版本位于 » http://creativecommons.org/licenses/by/3.0/。

# PHP 手册

# 关于本手册

PHP，即 PHP: Hypertext Preprocessor，是一种被广泛应用的开源通用脚本语言，尤其适用于 Web 开发并可嵌入 HTML 中去。它的语法借鉴了 C、Java 和 Perl，易于学习。该语言的主要目标是允许 web 开发人员快速编写动态生成的 web 页面，但 PHP 的用途远不只于此。

本手册内容主要由函数参考构成，但也包含了语言参考，PHP 一些主要产品特点的说明以及其它补充信息。

这份手册涵盖了 PHP 最近的两个主要版本 (7 和 8) 的相关信息。手册中只包含与 PHP 版本捆绑的扩展信息，并且不包含函数早期版本的更改信息。有关早期 PHP 版本的存档手册，可以在 » PHP 网站“Documentation”页面的“More documentation”章节找到。

可在 » https://www.php.net/download-docs.php 下载此手册的各种格式。更多关于如何开发本手册的信息可参阅附录：“关于本手册”。如果你对 PHP 的历史感兴趣，可访问相关附录。

# 作者与贡献者

有大量贡献者目前正在帮助我们开展工作，或者过去曾为该项目提供过大量帮助。还有许多不知名的人帮助在手册中写下用户评论，并不断地包含在参考中，也很感谢他们的努力。下面所提供的列表均以字母顺序排序。

# 作者与编辑

下列人员曾经或者目前正在为本手册添砖加瓦： 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和 Andrei Zmievski.

下列人员对本手册做了相当数量的编辑工作： Stig Bakken, Peter Cowburn, Gabor Hojtsy, Hartmut Holzgraefe, Philip Olson和 Egon Schmid.

# 用户评论维护者

目前最活跃的维护者是： Daniel Brown, Nuno Lopes, Felipe Pena, Thiago Pojda和 Maciek Sokolewicz.

下列人员为维护用户评论作出了巨大的努力: 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和 Jeroen van Wolffelaar.

## 中文翻译外部支持团队

PHP 手册中文翻译工作是一项长期而又艰巨的工作。如果您有兴趣加入，请参阅 » 中文手册翻译指南。

## 中文翻译贡献者名单

感谢以下贡献者为 PHP 中文翻译工作做出的贡献： Jiania（洪建家）、verdana（穆少磊）、Gregory（宋琪）、黄啸宇、 codingall.com（赵磊）、cuimuxi（崔玉松）、cztviztor、gaojian1226、HaoHappy（陈浩）、HonestQiao（乔楚）、 kendotom、lgg860911、loosen.copen、miusun01（李鼎峰）、ping3608、r.anerg（罗翀）、suppersoft（paris.wang） 、 fising（王祥中）、wind.golden（陈金）、Luffy（鲁飞）、mowangjuanzi（鲍国枭）。

# 入门指引

# PHP是什么并且可以做什么？

# PHP 是什么？

PHP（“PHP: Hypertext Preprocessor”，超文本预处理器的字母缩写）是一种被广泛应用的开放源代码的多用途脚本语言，它可嵌入到 HTML中，尤其适合 web 开发。

以上是一个简单的回答，不过这是什么意思呢？请看如下例子：

示例 #1 一个介绍性的范例

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

            <?php
            echo "Hi, I'm a PHP script!";
            ?>

        </body>
    </html>

PHP 页面并不包含大量输出 HTML 的命令（如 C 或 Perl 中所示），而是包含嵌入代码的 HTML，这些代码可执行某些操作（在本例中为输出 Hi, I'm a PHP script!）。PHP 代码包含在特殊的开始和结束处理指令 `<?php` 和 `?>` 中，允许跳入和退出 PHP 模式。

和客户端的 JavaScript 不同的是，PHP 代码是运行在服务端的。如果在服务器上建立了如上例类似的代码，则在运行该脚本后，客户端就能接收到其结果，但无法得知底层代码是什么。甚至可以将 web 服务器设置成让 PHP 来处理所有的 HTML 文件，这么一来，用户就无法知道正在使用 PHP。

使用 PHP 的最大的好处是它对于初学者来说极其简单，同时也给专业的程序员提供了各种高级的特性。当看到 PHP 长长的特性列表时，请不要害怕。使用 PHP，几乎任何人都可以快速上手并编写简单的脚本。

尽管 PHP 的开发主要侧重于服务器端脚本，但它可以做很多事情。请继续阅读，并在PHP 能做什么？章节中了解更多内容，或者直接转到简明教程，直接学习 Web 编程。

# PHP 能做什么？

PHP 能做任何事。PHP 主要是用于服务端的脚本程序，因此可以用 PHP 来完成任何其它的 CGI 程序能够完成的工作，例如收集表单数据，生成动态网页，或者发送/接收 Cookies。但 PHP 的功能远不局限于此。

PHP 脚本主要用于以下两个领域：

- 服务器端脚本。这是 PHP 使用最广泛、最主要的目标领域。开展这项工作需要具备以下三点：PHP 解析器（CGI 或服务器模块）、Web 服务器和 Web 浏览器。所有这些都可以在本地机器上运行，以便尝试 PHP 编程。有关更多信息，请参阅安装说明部分。
- 命令行脚本。PHP 脚本无需任何服务器或浏览器即可运行，只需 PHP 解析器即可使用。这种方式非常适合使用 cron（在 Unix 或 macOS 上）或任务计划程序（在 Windows 上）定期执行的脚本。这些脚本还可用于简单的文本处理任务。有关更多信息，请参阅有关 PHP 的命令行用法的部分。

PHP 可用于所有主流操作系统，包括 Linux、许多 Unix 变体（包括 HP-UX、Solaris 和 OpenBSD）、Microsoft Windows、macOS、RISC OS 以及其他操作系统。PHP 还支持当今大多数 Web 服务器。这包括 Apache、IIS 和许多其他服务器。这包括任何可以使用 FastCGI PHP 二进制文件的 Web 服务器，如 lighttpd 和 nginx。PHP 既可以作为模块工作，也可以作为 CGI 处理器工作。

因此，使用 PHP，开发者可以自由地选择操作系统和 web 服务器。同时，还可以在开发时选择使用面向过程或者面向对象（OOP），或者两者的混合。

PHP 不仅限于输出 HTML。PHP 的功能包括输出丰富的文件类型，例如图像或 PDF 文件、加密数据和发送电子邮件。还可以轻松输出任何文本，例如 JSON 或 XML。PHP 可以自动生成这些文件，并将它们保存在文件系统中，而不是将其打印出来，从而形成动态内容的服务器端缓存。

PHP 最强大最显著的特性之一，是它支持很大范围的数据库。使用任何针对某数据库的扩展（例如 mysql）编写数据库支持的网页非常简单，或者使用抽象层如 PDO，或者通过 ODBC 扩展连接到任何支持 ODBC 标准的数据库。其它一些数据库也可能会用 cURL 或者 sockets，例如 CouchDB。

PHP 还支持使用 LDAP、IMAP、SNMP、NNTP、POP3、HTTP、COM（Windows 环境）等协议与其他服务通信，以及其他无数协议。还可以打开原始网络套接字并使用任何其他协议进行交互。PHP 支持几乎所有 web 开发语言之间的 WDDX 复杂数据交换。关于相互连接，PHP 已经支持了对 Java 对象的实例化，并且可以无缝的将其用作 PHP 对象。

PHP 具有极其有效的文本处理特性，包括 Perl 兼容正则表达式（PCRE）以及许多扩展和工具可用于解析和访问 XML 文档。PHP 将所有的 XML 功能标准化于坚实的 libxml2 扩展，并且还增加了 SimpleXML，XMLReader 以及 XMLWriter 支持以扩充其功能。

另外，还有很多其它有趣的扩展库，在此根据字母和分类归类列出。还有一些附加的 PECL 扩展 可能有也可能没有在 PHP 手册中列出，例如 » XDebug。

本页不足以列出 PHP 可以提供的所有功能和优点。请继续参阅安装以及函数参考有关章节以获取关于这里提到的扩展库更多的信息。

# 简明教程

## 目录

- 第一个 PHP 页面
- 实用的脚本
- 处理表单
- 下一步做什么？

本章将给出关于 PHP 的简明教程。虽然 PHP 的功能并不局限于生成动态的 web 页面，但本章的内容仅涉及于此。请查阅“PHP 能做什么”一节以获取更多信息。

使用了 PHP 的 web 页面将被和通常的 HTML 页面一样处理，可以用通常建立 HTML 页面的方法来建立和编辑它们。

# 第一个 PHP 页面

本教程假设 PHP 已经安装。安装说明可以在» 下载页面找到。

建立名为 hello.php 的文件，并带着如下内容：

示例 #1 第一个 PHP 脚本：hello.php

    <?php

    echo "Hello World!";

    ?>

通过终端导航至包含该文件的目录，并使用以下命令启动开发服务器：

    php -S localhost:8000

通过浏览器使用 Web 服务器的 URL 访问该文件，URL 以 `/hello.php` 文件名结尾。根据之前执行的命令，URL将是 `http://localhost:8000/hello.php`。如果所有配置均正确，该文件将由 PHP 解析，并在浏览器中显示“Hello World!”的输出内容。

PHP 可以嵌入到普通 HTML 网页中。这意味着可以在 HTML 文档中编写 PHP 语句，如下例所示：

    <!DOCTYPE html>
    <html>
        <head>
            <title>PHP Test</title>
        </head>
        <body>
            <?php echo '<p>Hello World</p>'; ?>
        </body>
    </html>

这会产生以下输出：

    <!DOCTYPE html>
    <html>
        <head>
            <title>PHP Test</title>
        </head>
        <body>
            <p>Hello World</p>
        </body>
    </html>

该程序非常的简单，它仅仅只是利用了 PHP 的 echo 语句显示了 `Hello World`。用户一定不会满足于此。请注意该文件无需被执行或以任何方式指定。服务器会找到该文件并提供给 PHP 进行解释，因为使用了“.php”的扩展名，服务器已被配置成自动传递有着“.php”扩展名的文件给 PHP。一个普通的 HTML 文件，加上了几个特别的标签，就可以做很多非常有趣的事情！

以上例子的目的是为了显示 PHP 特殊标识符的格式。在这个例子中，用 `<?php` 来表示 PHP 标识符的起始，然后放入 PHP 语句并通过加上一个终止标识符 `?>` 来退出 PHP 模式。可以根据自己的需要在 HTML 文件中像这样开启或关闭 PHP 模式。请参阅手册中“PHP 基本语法”以获取更多信息。

> 注意: 关于换行

> 尽管换行在 HTML 中的实际意义不是很大，但适当地使用换行可以使 HTML 代码易读且美观。PHP 会在输出时自动删除其结束符 `?>` 后的一个换行。该功能主要是针对在一个页面中嵌入多段 PHP 代码或者包含了无实质性输出的 PHP 文件而设计，与此同时也造成了一些疑惑。如果需要在 PHP 结束符 `?>` 之后输出换行的话，可以在其后加一个空格，或者在最后的一个 echo/print 语句中加入一个换行。

> 注意: 关于文本编辑器

> 有很多文本编辑器以及集成开发环境（IDE）可以被用来建立、编辑和管理 PHP 文件。这些工具中的一部分被列在 » PHP 编辑器列表中。如果希望推荐其它的编辑器，请访问以上页面，并要求该页面的维护者将你推荐的编辑器加入到该列表中。使用支持语法高亮功能的编辑器会给开发带来很多帮助。

> 注意: 关于文字处理器

> 诸如 StarOffice Writer、Microsoft Word 和 Abiword 的文字处理器不适合用来编辑 PHP 程序。如果希望用以上这些工具的某一种来处理脚本，必须保证将结果存成了纯文本格式，否则 PHP 将无法读取并运行这些脚本。

现在已经成功建立了一个简单的 PHP 脚本，那么再来建立一个最著名的 PHP 脚本！调用函数 phpinfo()，将会看到很多有关自己系统的有用信息，例如预定义变量、已经加载的 PHP 模块和配置信息。请花一些时间来查看这些重要的信息。

示例 #2 从 PHP 获取系统信息

    <?php

    phpinfo();

    ?>

# 实用的脚本

现在来编写一些更实用的脚本，比如检查浏览页面的访问者在用什么浏览器。要达到这个目的，需要检查用户的 agent 字符串，它是浏览器发送的 HTTP 请求的一部分。该信息被存储在一个变量中。在 PHP 中，变量总是以一个美元符开头。我们现在感兴趣的变量是 $_SERVER['HTTP_USER_AGENT']。

> 注意:

> $_SERVER 是一个特殊的 PHP 保留变量，它包含了 web 服务器提供的所有信息，被称为超全局变量。请查阅本手册“超全局变量”中的有关内容以获取更多信息。

要显示该变量，只需简单地进行如下操作：

示例 #1 打印变量（数组元素）

    <?php

    echo $_SERVER['HTTP_USER_AGENT'];

    ?>

该脚本的输出可能是：

    Mozilla/5.0 (Linux) Firefox/112.0

PHP 有多种不同类型的变量。以上例子是从 Array 变量中打印了一个元素。数组非常有用。

$_SERVER 只是 PHP 自动全局化的变量之一。可以查阅“预定义变量”一节来查看这些变量的列表，或者也可以通过上节例子中 phpinfo() 函数的输出来查看。

可以在一个 PHP 标识中加入多个 PHP 语句，也可以建立一个代码块来做比简单的 echo 更多的事情。例如，如果需要检测 Firefox，可以进行如下操作：

示例 #2 流程控制与函数的使用

    <?php

    if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {
        echo 'You are using Firefox.';
    }

    ?>

该脚本的输出可能是：

    You are using Firefox.

这里要介绍一些新的原理。上面用了一个 if 语句。如果用户对 C 语言的基本语法比较熟悉，则应该对此很熟悉，否则，可能需要拿起任何一本 PHP 介绍性的书籍并阅读前面的两三个章节，或者也可以阅读本手册的“语言参考”一章。

需要介绍的第二个原理，是对 str_contains() 函数的调用。str_contains() 是 PHP 的一个内置函数，其功能是确定指定字符串是否包含其它字符串。例如我们现在需要在 $_SERVER['HTTP_USER_AGENT']（即所谓的 haystack）变量中寻找 `'Firefox'`。如果在这个 haystack 中该字符串（即所谓的 needle）被找到（“草里寻针”），则函数返回 `true`；如果没有，则返回 `false`。如果返回 `true`，则 if 会将条件判断为 `true` 并运行其花括号 {} 内的代码；否则，则不运行这些代码。可以自己尝试利用 if，else 以及其它的函数如 strtoupper() 和 strlen() 来建立类似的脚本。在本手册中相关的页面也包含有范例。如果对如何使用函数不是很确定，可以阅读手册中有关“如何阅读函数的定义”和“函数”的有关章节。

以下我们进一步显示如何进出 PHP 模式，甚至是在一个 PHP 代码块的中间：

示例 #3 混合 HTML 和 PHP 模式

    <?php
    if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {
    ?>
    <h3>str_contains() returned true</h3>
    <p>You are using Firefox</p>
    <?php
    } else {
    ?>
    <h3>str_contains() returned false</h3>
    <p>You are not using Firefox</p>
    <?php
    }
    ?>

该脚本的输出可能是：

    <h3>str_contains() returned true</h3>
    <p>You are using Firefox</p>

和使用 PHP echo 语句输出不同的是，以上示例跳出了 PHP 模式直接发送 HTML。这里需要特别注意的一点是脚本的逻辑流保持不变。根据 str_contains() 的结果，只会有一个 HTML 块将发送给浏览者。换句话说，取决于是否找到字符串 `Firefox`。

# 处理表单

PHP 一个很有用的特点体现在它处理 HTML 表单的方式。需要理解的非常重要的原理，是表单的任何元素都在 PHP 脚本中自动生效。请参阅本手册中“PHP 的外部变量”以获取关于在 PHP 中使用表单的详细信息及范例。以下是 HTML 表单的范例：

示例 #1 一个简单的 HTML 表单

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

        <label for="age">Your age:</label>
        <input name="age" id="age" type="number">

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

该表单中并没有什么特殊的地方，其中没有使用任何特殊的标识符。当用户填写了该表单并点击了提交按钮，页面 action.php 将被调用。在该文件中，可以加入如下内容：

示例 #2 打印来自表单的数据

    Hi <?php echo htmlspecialchars($_POST['name']); ?>.
    You are <?php echo (int) $_POST['age']; ?> years old.

该脚本的输出可能是：

    Hi Joe. You are 22 years old.

除了htmlspecialchars() 和 `(int)` 部分，这段程序做什么用显而易见。htmlspecialchars() 使得 HTML 之中的特殊字符被正确的编码，从而不会被使用者在页面注入 HTML 标签或者 Javascript 代码。例如 age 字段，我们明确知道他是一个数值，因此我们将它转换为一个int来自动的消除任何不必要的字符。也可以使用 PHP 的 filter 扩展来自动完成该工作。PHP 将自动设置 $_POST['name'] 和 $_POST['age'] 变量。在这之前我们使用了超全局变量 $_SERVER，现在我们引入了超全局变量 $_POST，它包含了所有的 POST 数据。请注意我们的表单提交数据的方法（method）。如果使用了 GET 方法，那么表单中的信息将被储存到超全局变量 $_GET 中。如果并不关心请求数据的来源，也可以用超全局变量 $_REQUEST，它包含了所有 GET、POST 和 COOKIE 的数据。

# 下一步做什么？

用现在掌握的知识，应该能够理解本手册中的大部分内容以及其中各式各样的脚本范例。

请查阅 PHP Conference 资料网站 » http://talks.php.net/ 以观看更多幻灯片，这些幻灯片展示了许多 PHP 其它的功能。

- 简介 — PHP是什么并且可以做什么？
- 简明教程
  - 第一个 PHP 页面
  - 实用的脚本
  - 处理表单
  - 下一步做什么？

# 安装与配置

# 安装前需要考虑的事项

安装前，首先需要知道想用 PHP 来做什么。PHP 主要用在两个领域，分别在 PHP 能做什么 一节中进行了描述：

- 网站和 web 应用程序（服务器端脚本）
- 命令行脚本

在通常情况下，需要三样东西：PHP 自身、一个 web 服务器和一个 web 浏览器。通常你已经拥有了一个 web 浏览器，并且在你使用的操作系统中，也可能已经内置了 web 服务器（例如 Linux 和 macOS 下的 Apache；Windows 下的 IIS）。也许在某个公司租用了 web 空间（虚拟主机、VPS 等），这样，自己无需设置任何东西，仅需要编写 PHP 脚本，并上传到租用的空间中，然后在浏览器中查看结果。

如果需要自己配置服务器和 PHP，有两个方法将 PHP 连接到服务器上。对于很多服务器，PHP 均有一个直接的模块接口（也叫做 SAPI）。这些服务器包括 Apache、Microsoft Internet Information Server、Netscape 和 iPlanet 等服务器。如果你使用的 web 服务器不支持 PHP 模块接口，还可以将其作为 CGI 或 FastCGI 处理器来使用。这意味着可以使用 PHP 的 CGI 可执行程序来处理所有服务器上的 PHP 文件请求。

如果你对 PHP 命令行脚本感兴趣（例如在离线状态下，根据传递给脚本的参数，自动生成一些图片，或处理一些文本文件），可以参考 PHP 在命令行模式下的使用 章节。在这种情况下，不再需要 web 服务器和 web 浏览器支持。

本节开始介绍如何在 Unix 和 Windows 的 web 服务器中配置服务器模块接口和 CGI 可执行程序。也将在下面几节中了解到有关命令行可执行程序安装的信息。

PHP 源代码包和二进制包可以在以下链接获取 » https://www.php.net/downloads.php。

# 在 Unix 系统上安装 PHP

## 目录

- Debian GNU/Linux 及其相关发行版上从软件包中安装 PHP
- 在使用 DNF 的 GNU/Linux 发行版上通过软件包安装
- OpenBSD 上从软件包或者 ports 中安装 PHP
- 在 Unix 和 macOS 系统上以源码安装
- CGI 和命令行设置
- Unix 系统下的 Apache 2.x
- Unix 系统下的 Nginx 1.4.x
- Unix 平台的 Lighttpd 1.4
- Unix 系统下的 LiteSpeed、OpenLiteSpeed Web 服务器
- 针对 Solaris 的安装提示

大多数 Unix（和 Linux）操作系统和发行版都通过其打包系统提供 PHP 和扩展的打包版本。其中有部分章节介绍了使用这些系统安装 PHP 的基本信息。

对于某些发行版，还有第三方软件包存储库，通常包含更多可用的版本和扩展。

PHP 还可以作为某些第三方应用服务器的组件进行安装。

最后，PHP 始终可以从源码中安装，这样可以最大程度地灵活选择要启用的功能、扩展和服务器 API。其中有部分章节介绍了编译和配置 PHP 以及与不同的服务器 API 配合使用的信息。

## Debian GNU/Linux 及其相关发行版上从软件包中安装 PHP

虽然 PHP 可以从源码安装，但也可以通过 » Debian GNU/Linux 中的软件包获取。其他基于 Debian 的发行版也是如此，例如 Ubuntu、Kali Linux 和 Linux Mint。

警告

第三方提供的版本被视为非官方版本，不直接受 PHP 项目支持。 除非可以通过 » 官方下载区的构建版重现， 否则遇到的任何错误都应报告给这些非官方构建版的提供者。

可以使用 apt 或 aptitude 命令来安装软件包。本节中这两条命令可以互换。

### 使用 APT

首先，注意其它有关的包可能需要 `libapache-mod-php` 集成入 Apache 2，以及 PEAR 的 `php-pear`。

其次，在安装一个包之前，最好先确定该包是最新版。通常可以运行命令 apt update。

示例 #1 Debian 下将 PHP 安装入 Apache 2 的例子

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

APT 将自动安装 Apache 2 的 PHP 模块以及所有依赖的库并激活之。应重启动 Apache 以使更改生效，例如：

示例 #2 安装完 PHP 后停止并启动 Apache

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

### 更好地控制配置

上一节中 PHP 仅安装了核心模块。很可能还需要更多模块，例如 MySQL，cURL，GD 等。这些模块也可以通过 apt 命令安装。

示例 #3 取得 PHP 附加软件包的列表

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

软件包列表将包含大量软件包，其中包括基本 PHP 组件，比如 `php-cgi`、`php-cli` 和 `php-dev` 以及许多 PHP 扩展。安装扩展时，将根据需要自动安装其他软件包以满足这些软件包的依赖关系。

示例 #4 安装 PHP 的 MySQL 和 cURL 支持

    # apt install php-mysql php-curl

APT 会自动把适当的行添加到不同的 php.ini 相关文件中去，例如 /etc/php/7.4/php.ini，/etc/php/7.4/conf.d/*.ini 等，并且根据扩展，还会添加类似 `extension=foo.so` 的内容。不过还是需要重新启动 web 服务器（例如 Apache）以使这些改动生效。

### 常见问题

- 如果 PHP 脚本没有通过 web 服务器被解析，则有可能是 PHP 没有被加入到 web 服务器的配置文件中，在 Debian 中可能是 /etc/apache2/apache2.conf 或类似文件。具体内容参见 Debian 手册。
- 如果某扩展貌似已经安装，但其函数却又未定义，确保合适的 ini 文件已被加载并且 web 服务器在安装后重新启动过。

## 在使用 DNF 的 GNU/Linux 发行版上通过软件包安装

PHP 既可从源码安装，也可通过软件包在使用 DNF 的系统上安装，例如 Red Hat Enterprise Linux、OpenSUSE、Fedora、CentOS、Rocky Linux 和 Oracle Enterprise Linux。

警告

第三方提供的版本被视为非官方版本，不直接受 PHP 项目支持。 除非可以通过 » 官方下载区的构建版重现， 否则遇到的任何错误都应报告给这些非官方构建版的提供者。

这些软件包可通过 dnf 命令安装。

### 安装软件包

首先，注意可能还需要安装其他相关软件包，例如用于 » PEAR 的 `php-pear`，或用于 MySQL 扩展的 `php-mysqlnd`。

其次，在安装软件包前，建议确保软件包列表为最新状态。通常可通过运行 dnf update 命令完成此操作。

示例 #1 DNF 安装示例

    # dnf install php php-common

DNF 会自动为 Web 服务器安装 PHP 的配置，但可能需要重启 Web 服务器才能使更改生效。例如：

示例 #2 安装 PHP 后重启 Apache

    # sudo systemctl restart httpd

### 更精细的配置控制

上一节中仅安装了 PHP 的核心模块。通常还需要额外的模块，例如 MySQL, cURL, GD, 等，这些模块也可通过 dnf 命令进行安装。

示例 #3 列出额外 PHP 软件包的方法

    # dnf search php

软件包列表将包含大量基础 PHP 组件（如 `php-cli`、`php-fpm` 和 `php-devel`）以及众多 PHP 扩展。安装扩展时，系统会根据依赖关系自动安装所需的其他软件包。

示例 #4 安装 PHP 的 MySQL、GD 扩展

    # dnf install php-mysqlnd php-gd

DNF 会自动在不同的 php.ini 相关文件（如 /etc/php/8.3/php.ini、/etc/php/8.3/conf.d/*.ini 等）中添加相应的行，并根据扩展添加类似 `extension=foo.so` 的条目。但需重启 Web 服务器（如 Apache）后，这些更改才会生效。

## OpenBSD 上从软件包或者 ports 中安装 PHP

本章节的内容和提示仅限于将 PHP 安装到 » OpenBSD 系统上。

### 使用二进制包安装

使用二进制包安装 PHP 到 OpenBSD 系统上是被推荐的同时也是最简单的方法。PHP 核心包已经从其他模块中分离出来了并且每个模块可以被独立的安装／卸载而不影响其他模块。所有这些安装 PHP 需要的文件可以在 OpenBSD 光盘或者在 FTP 站点上找到。

需要安装的核心包是 php，它包含了基本的引擎（加上 fpm、gettext 和 iconv）并且可能有几个版本可供选择。其次，可能还需要安装一些模块包，如：php-mysqli 或 php-imap。需要使用命令 phpxs 去激活它，并且再通过修改 php.ini 文件来屏蔽他们。

示例 #1 在 OpenBSD 系统下的软件包的安装示例

    # pkg_add php
    # pkg_add php-apache
    # pkg_add php-mysqli
      （安装 PEAR 库）
    # pkg_add pear

      （按照每个包显示的说明操作！）

      (移除包)
    # pkg_delete php
    # pkg_delete php-apache
    # pkg_delete php-mysqli
    # pkg_delete pear

阅读用户手册中的 » packages(7) 部分，可以得到更多 OpenBSD 系统下有关二进制软件包的信息。

### 使用 Ports

同样可以使用 » ports tree 来编译 PHP 的源代码。然而，这样的安装方式仅仅是建议对 OpenBSD 非常熟悉的高级用户去做。PHP port 分为 core 和 extensions。其中 extensions 产生了所有 PHP 所支持的子模块。如果不希望创建并且使用这些模块中的某些模块，请使用 no_* FLAVOR。例如，如果希望跳过编译 imap 模块，设置 FLAVOR 为 no_imap 即可。

### 常见问题

- Apache 和 Nginx 不再是 OpenBSD 上的默认服务器，但他们都可以在 ports 和包中找到。 新的默认服务器也被称为 “httpd”。
- 默认安装的 httpd 运行于 » chroot(2) jail 内，将限制 PHP 脚本只能访问 /var/www下面的文件。需要建立 /var/www/tmp 目录来存放 PHP session 文件，或使用其它的 session 后端。此外，数据库套接字需要被放入 jail 或者侦听 localhost接口。如果使用网络函数，某些 /etc 下面的文件例如 /etc/resolv.conf 和 /etc/services 需要被移动到 /var/www/etc 中去。OpenBSD PEAR 包会自动安装到正确的 chroot 目录中。
- 对应于 » gd 扩展的 OpenBSD 包需要安装 Xorg。除非在基本安装时通过添加 xbase.tgz 文件集已经安装，否则可以在安装后添加（参见 » OpenBSD FAQ#4）。

## 在 Unix 和 macOS 系统上以源码安装

编译所需的前置软件：

- » GNU make
- C 编译器（自 PHP 8.0.0 起要求支持 C99 标准；自 PHP 8.4.0 起要求支持 C11 标准）
- Web 服务器
- 各模块所需的特定组件（例如 GD、PDF 库等）

直接从 Git 源码构建或进行自定义修改后，可能需要以下额外工具：

- » autoconf：
  - PHP 7.3 及其以后：2.68+
  - PHP 7.2：2.64+
  - PHP 7.1 及其更早：2.59+
- » re2c：
  - PHP 8.3 及其以后：1.0.3+
  - PHP 8.2 及其更早：0.13.4+
- » bison:
  - PHP 7.4 及其以后：3.0.0+
  - PHP 7.3 及其更早：2.4+（包含 Bison 3.x）

有关从源码编译 PHP 的详细步骤，请参见源码压缩包中的 » README.md 文件。

PHP 的初始设置和配置过程由 configure 脚本的命令行选项控制。运行 ./configure --help 可列出所有可用选项及其简要说明。本手册对各项选项分别进行了说明：核心选项位于附录中，各扩展的特有选项则在其对应的参考页面中描述。

配置脚本执行完成后，可使用 make 命令构建 PHP。常见问题解答中的安装部分提供了有关如何处理构建问题的更多信息。

> 注意: 某些 Unix 系统（如 OpenBSD 和 SELinux）出于安全原因，禁止同时将内存页映射为可写和可执行，这种机制称为 » PaX MPROTECT 或 » » W^X 违规保护。而 PCRE 的 JIT 需要此类内存映射，因此要么在构建 PHP 时禁用 PCRE 的 JIT 支持，要么通过系统提供的机制将 PHP 二进制文件加入白名单。

> 注意: 目前不支持使用 Android 工具链进行 ARM 交叉编译。

## CGI 和命令行设置

默认为将 PHP 编译为 CLI 和 CGI 程序。这将建立一个命令行解释器，可用于 CGI 处理或非 web 相关的 PHP 脚本。如果用户运行着一个 PHP 模块支持的 web 服务器，那通常为性能考虑应该使用模块方式。不过 CGI 版可以使 Apache 用户用不同的用户 ID 运行不同的 PHP 页面。

警告

服务器使用 CGI 方式进行部署可能存在几个公开的缺陷。请阅读 CGI 安全一章 以学习 如何抵御这些攻击。

### 测试

如果将 PHP 编译为 CGI 程序，可以通过键入 make test 来测试你的编译。测试一下编译永远是个好主意。这样就可以在你的平台上及早捕捉到 PHP 的问题而不是以后再费力的解决。

### 使用变量

某些服务器提供的环境变量没有定义在当前的 » CGI/1.1 标准中。只有下列变量定义在其中： 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 和 SERVER_SOFTWARE。其它的变量均作为“供应商扩展（vendor extensions）”来对待。

## Unix 系统下的 Apache 2.x

本节包括在 Unix 平台的 Apache 2.x 下安装 PHP 的说明和提示。

警告

不推荐在使用 Apache 2 的产品中使用线程化 MPM。应使用预分支 MPM，Apache 2.0 和 2.2 默认的 MPM。其原因见 FAQ 中的相关条目使用线程化 MPM 的 Apache2。

推荐阅读 » Apache 文档，了解一下 Apache 2.x 服务器，以及详细的安装参数。

可以从 » Apache 下载站点下载最新版本的Apache，并且根据上文选择合适版本的 PHP 下载。本向导仅包含最基础的内容，只能让 Apache 2.x 和 PHP 能够正常工作。更多信息请阅读 » Apache 文档。这里省略所有的版本号，以保证本文的正确性。需要将本文的“NN”替换为相应的版本号。

当前 Apache 2.x 有两个流行的版本 - 2.4 和 2.2。虽然选择某个版本会有种种原因，但是如果可以考虑的话，我们还是建议使用最新的 Apache 2.4 版本。当然，以下的介绍同样适合 Apache 2.4 和 2.2。请注意 Apache 2.2 已经不再被官方支持，并且不再发布新功能和补丁更新。

1. 从上面列出的地方获取 Apache 源码包，然后解压：

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

2. 同样，获取 PHP 源码包并解压：

       tar -xzf php-NN.tar.gz

3. 编译并安装 Apache。请参考 Apache 安装文档了解编译 Apache 的更多细节。

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

4. 现在已经将 Apache 2.x.NN 安装在 /usr/local/apache2。本安装支持可装载模块和标准的 MPM prefork。之后，可以使用如下命令启动 Apache 服务器：

       /usr/local/apache2/bin/apachectl start

   如果成功，可以停止 Apache 服务器并继续安装 PHP：

       /usr/local/apache2/bin/apachectl stop

5. 现在需要配置并编译 PHP。在这里可以用各种各样的参数来自定义 PHP，例如启动哪些扩展功能包的支持等。用 ./configure --help 命令可以列出当前可用的所有参数。在此例中，将给出一个在有 MySQL 支持的 Apache 2 上进行配置的范例。

   如果按照上面的说明从源代码编译了 Apache，下面的例子会正确匹配 apxs 的路径。如果通过其他方式安装了 Apache，需要相应的调整 apxs 的路径。注意，在有些发行版本中，可能将 apxs 更名为 apxs2。

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

   如果决定在安装后改变配置选项，只需重复最后的三步 configure，make，以及 make install，然后需要重新启动 Apache 使新模块生效。Apache 不需要重新编译。

   请注意，除非明确有提示，否则“make install”命令将安装 PEAR、各种 PHP 工具诸如 phpize，并安装 PHP CLI 等等。

6. 配置 php.ini。

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

   可以编辑 `.ini` 来设置 PHP 选项。如果想要把 php.ini 放到另外的位置，需要在步骤 5 使用 `--with-config-file-path=/some/path` 选项。

   如果选择了 php.ini-production，请务必阅读其中的变更列表，它们将如何影响 PHP 的行为。

7. 编辑 httpd.conf 文件以调用 PHP 模块。`LoadModule` 表达式右边的路径必须指向系统中的 PHP 模块。以上的 make install 命令可能已经完成了这些，但务必要检查。

   PHP 8 版本:

       LoadModule php_module modules/libphp.so

   PHP 7 版本:

       LoadModule php7_module modules/libphp7.so

8. 告知 Apache 将特定的扩展名解析成 PHP，例如，让 Apache 将扩展名 `.php` 解析成 PHP。为了避免潜在的危险，例如上传或者创建类似 exploit.php.jpg 的文件并被当做 PHP 执行，我们不再使用 Apache 的 `AddType` 指令来设置。参考下面的例子，你可以简单的将需要的扩展名解释为 PHP。 下面将添加 `.php` 来进行演示。

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

   或者也想将 `.php`、`.php2`、`.php3`、`.php4`、`.php5`、`.php6` 以及 `.phtml` 文件都当做 PHP 来运行，我们无需额外的设置，仅需按照下面这样来：

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

   然后，可以将 `.phps` 文件由 PHP 源码过滤器处理，使得其在显示时可以高亮源码，设置如下：

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

   `mod_rewrite` 也有助于将那些不需要运行的 `.php` 文件的源码高亮显示，而并不需要将他们更名为 `.phps` 文件：

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

   不要在正式生产运营的系统上启动 PHP 源码过滤器，因为这可能泄露系统机密或者嵌入的代码中的敏感信息。

9. 按照通常的方式启动 Apache 服务：

       /usr/local/apache2/bin/apachectl start

   或者

       service httpd restart

按照上面的步骤便可以使 Apache 2.ｘ 将 PHP 作为 `SAPI` 模块。当然 Apache 和 PHP 都还有很多配置选项，可以在相应的源代码目录中使用 ./configure --help 获得更多信息。

可以选择 worker MPM 而不是标准的 prefork MPM 来编译多线程版本的 Apache。只需在上面的第 3 步，将选项使用如下参数传递到 ./configure中：

    --with-mpm=worker

如果不是很明确这样做的后果并且大概理解其含义的话，最好不要进行这一步。更多信息请参考 Apache 文档中关于 » MPM-Modules 的部分。

> 注意:

> Apache MultiViews 常见问题中讨论了在 PHP 中使用 MultiViews。

> 注意:

> 要编译多线程版本的 Apache，系统必须支持多线程。这也意味着需要将 PHP 编译为 Zend 线程安全（ZTS）。在此配置下。并不是所有的扩展都可以使用。推荐设置是使用默认的 prefork MPM-Module 编译 Apache。

## Unix 系统下的 Nginx 1.4.x

本文档包括使用 PHP-FPM 为 Nginx 1.4.x HTTP 服务器安装和配置 PHP 的说明和提示。

本指南假定您已经从源代码成功构建 Nginx，并且其二进制文件和配置文件都位于 `/usr/local/nginx`。 如果您使用其他方式获取的 Nginx，请参考 » Nginx Wiki 并对照本文档完成安装。

本文档仅包含 Nginx 服务器的基本配置，它将通过 80 端口提供 PHP 应用的处理能力。 如果您需要超出本文档范围的安装配置指导，建议您查阅 Nginx 和 PHP-FPM 的文档。

需要注意的是，本文档一律使用 'x' 来表示版本号，请根据实际情况将 'x' 替换为对应的版本号。

1. 建议您访问 Nginx Wiki » 安装 页面以获取并在您的系统上安装 Nginx。

2. 获取并解压 PHP 源代码:

       tar zxf php-x.x.x

3. 配置并构建 PHP。在此步骤您可以使用很多选项自定义 PHP，例如启用某些扩展等。 运行 ./configure --help 命令来获得完整的可用选项清单。 在本示例中，我们仅进行包含 PHP-FPM 和 MySQL 支持的简单配置。

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

4. 创建配置文件，并将其复制到正确的位置。

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

5. 需要着重提醒的是，如果文件不存在，则阻止 Nginx 将请求发送到后端的 PHP-FPM 模块， 以避免遭受恶意脚本注入的攻击。

   将 php.ini 文件中的配置项 cgi.fix_pathinfo 设置为 `0` 。

   打开 php.ini:

       vim /usr/local/php/php.ini

   定位到 `cgi.fix_pathinfo=` 并将其修改为如下所示：

       cgi.fix_pathinfo=0

6. 在启动服务之前，需要修改 php-fpm.conf 配置文件，确保 php-fpm 模块使用 www-data 用户和 www-data 用户组的身份运行。

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

   找到以下内容并修改：

       ; 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

   然后启动 php-fpm 服务：

       /usr/local/bin/php-fpm

   本文档未涵盖对 php-fpm 进行进一步配置的信息，如果您需要更多信息，请查阅相关文档。

7. 配置 Nginx 使其支持 PHP 应用：

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

   修改默认的 location 块，使其支持 .php 文件：

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

   下一步配置来保证对于 .php 文件的请求将被传送到后端的 PHP-FPM 模块， 取消默认的 PHP 配置块的注释，并修改为下面的内容：

       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;
       }

   重启 Nginx。

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

8. 创建测试文件。

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

   打开浏览器，访问 http://localhost，将会显示 phpinfo() 。

通过以上步骤的配置，Nginx 服务器现在可以以 `FPM` `SAPI` 模块的方式支持 PHP 应用了。 当然，对于 Nginx 和 PHP 的配置，还有很多可用的选项， 请在对应的源代码目录执行 ./configure --help 来查阅更多配置选项。

## Unix 平台的 Lighttpd 1.4

本节包括在 Unix 平台的 Lighttpd 1.4 下安装 PHP 的说明和提示。

推荐阅读 » Lighttpd trac 了解一下正确安装 Lighttpd 然后继续。

推荐使用 FastCGI 作为 SAPI 模块来连接 PHP 和 Lighttpd。 在 php-cgi 中自动启用 FastCGI。

### 使 Lighttpd 产生 php 进程

要配置 Lighttpd 连接到 PHP 并产生 FastCGI 进程， 编辑 lighttpd.conf。 推荐使用套接字在本机连接 FastCGI 进程。

示例 #1 部分 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
      ))
    )

bin-path 指令允许 lighttpd 动态产生 FastCGI 进程。PHP 会根据 PHP_FCGI_CHILDREN 环境变量产生子进程。`bin-environment` 指令设定了所产生的进行的环境。PHP 会在达到 PHP_FCGI_MAX_REQUESTS 所指定的请求数目之后杀死一个子进程。在 PHP 中通常应避免 `min-procs` 和 `max-procs` 指令。PHP 自己管理其子进程，并且例如 APC 之类的 opcode 缓存仅在 PHP 管理下的子进程之间共享。如果 `min-procs` 被设定成某个大于 `1` 的值，则 PHP 应答器的总数目为该值乘以 PHP_FCGI_CHILDREN（如 min-procs 为 2，PHP_FCGI_CHILDREN 为 16 则会产生 32 个应答器）。

### 通过 spawn-fcgi 产生进程

Lighttpd 提供一个名为 spawn-fcgi 的程序来简化产生 FastCGI 进程的手续。

### 产生 php-cgi

有可能不通过 spawn-fcgi 来产生进程，但需要做些工作。设定 PHP_FCGI_CHILDREN 环境变量控制了 PHP 产生多少个子进程来处理请求。设定 PHP_FCGI_MAX_REQUESTS 将决定每个子进程存活多久（以请求数目决定）。 以下为一个简单的 bash 脚本来帮助产生 php 应答器。

示例 #2 产生 FastCGI 应答器

    #!/bin/sh

    # Location of the php-cgi binary
    PHP=/usr/local/bin/php-cgi

    # PID File location
    PHP_PID=/tmp/php.pid

    # Binding to an address
    #FCGI_BIND_ADDRESS=10.0.1.1:10000
    # Binding to a 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"

### 连接远程 FCGI 实例

FastCGI 实例可被产生于多个远程机器以分散应用程序。

示例 #3 连接远程 php-fastcgi 实例

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

## Unix 系统下的 LiteSpeed、OpenLiteSpeed Web 服务器

LiteSpeed PHP 是一个通过 LiteSpeed SAPI 方式和 LiteSpeed 协同工作的 PHP 优化编译器。LSPHP 有自己的进程和独立的二进制包，可用作简单的命令行二进制文件在命令行中执行 PHP 脚本。

LSAPI 是一个高度优化的 API，允许 LiteSpeed 与第三方 web 引擎之间进行通信。它的协议和 FCGI 很像，但更加高效。

本文档将包含安装和配置 PHP 的 LSAPI，并将 LSAPI 适用于 LiteSpeed Web 服务器和 OpenLiteSpeed Web 服务器。

本文档假设 LSWS 或者 OLS 使用默认路径和标记安装。这两个 web 服务器的默认路径为： /usr/local/lsws，并且都可以从 bin 子目录下运行。

请注意：本文档中对版本号使用 `x` 替代，以确保本文档在将来保持正确，请根据需要替换对应的版本号。

1. 要获取和安装 LiteSpeed Web 服务器或者 OpenLiteSpeed Web 服务器，请访问 LiteSpeed Web 服务器文档 » 安装页面 或者 OpenLiteSpeed 文档 » 安装页面.

2. 获取并且解压PHP源码：

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

3. 配置并构建 PHP。这里可以根据各种选项来定制 PHP，例如需要开启哪些扩展。运行 ./configure --help 可以获得可用的选项列表。在示例中，我们将使用 LiteSpeed Web 服务器默认推荐的配置选项：

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

4. 检查 LSPHP 是否安装

   检查 PHP 是否成功安装的一种最简单的方式是运行以下代码：

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

   它将会返回新构建的 PHP 信息：

       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

   注意括号中的 `litespeed`。这意味着构建的 PHP 支持 LSAPI。

按照上面的步骤，LiteSpeed / OpenLiteSpeed Web 服务器已经作为 PHP 的 SAPI 扩展来运行。LSWS / OLS 和 PHP 更多的配置选项，请查看 LiteSpeed 文档： » PHP。

从命令行使用 LSPHP：

LSPHP(LSAPI + PHP) 命令行模式，适用于远程服务器上没必要运行 web 服务， 但是又需要处理 PHP 程序的情况。它常用于本地独立的 web 服务器处理 PHP 程序。 这个设置适合将 PHP 的处理拆分到远程服务器上，具有良好的服务可伸缩性。

从远程服务器的命令行中启动 lsphp 服务： LSPHP 是可执行文件，可以手动启动，通过命令行选项 -b socket_address 来绑定到 IPv4，IPv6，或者 Unix 域套接字地址上。

例如：

LSPHP 绑定到所有 IPv4 和 IPv6 地址的 3000 端口：

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

LSPHP 绑定到所有 IPv4 地址的 3000 端口：

    /path/to/lsphp -b *:3000

LSPHP 绑定到 192.168.0.2:3000：

    /path/to/lsphp -b 192.168.0.2:3000

LSPHP 通过 Unix 域套接字`/tmp/lsphp_manual.sock` 接受请求：

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

在 LSPHP 执行前设置环境变量：

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

目前 LiteSpeed PHP 可适用于 LiteSpeed Web 服务器，OpenLiteSpeed Web 服务器和 Apache mod_lsapi 一起使用。有关服务器端的配置的步骤，请浏览相关的文档页面： » LiteSpeed Web 服务器 和 » OpenLiteSpeed。

LSPHP 也可以通过其它的方式来安装。

CentOS： 在 CentOS 系统中，LSPHP 可以从 LiteSpeed 存储库或 Remi 存储库中通过 » RPM 的方式安装。

Debian： 在 Debian 系统中，LSPHP 可以从 LiteSpeed 存储库中通过 » apt 的方式安装。

cPanel： 访问相应的» 文档页面了解如何通过 cPanel 和 LSWS/OLS 在 EasyApache4 中安装 LSPHP。

Plesk： Plesk 可以在 CentOS，CloudLinux，Debian 和 Ubuntu 上使用 LSPHP，想获取更多的信息，请参考对应的» 文档页面

## 针对 Solaris 的安装提示

本节包含了在 Solaris 系统上安装 PHP 的说明和提示。

### 需要的软件

默认安装的 Solaris 系统经常缺少 C 语言编译器和其相关工具。部分工具必须使用该工具的 GNU 版本，原因请阅读 FAQ。

要解压缩 PHP 发行包，需要：

- tar
- gzip 或
- bzip2

要编译 PHP，需要：

- gcc（推荐使用，其它 C 编译器也许也能用）
- make
- GNU sed

要编译更多扩展库或自行开发 PHP 代码，可能还需要：

- re2c
- bison
- m4
- autoconf
- automake

此外，还需要安装（甚至编译）针对自己的配置所需的软件，例如 Oracle 或 MySQL。

### 使用软件包

可以使用 pkgadd 来安装大部分需要的软件来简化 Solaris 安装过程。Solaris 11 Express 下的映像打包系统（Image Packaging System，IPS）也包含了大多数安装所需的部件，通过 pkg 命令。

# macOS 系统下的安装

## 目录

- 在 MacOS 上使用第三方包安装
- 在 macOS 下编译 PHP
- 使用 macOS Monterey 之前内置的 PHP

PHP 在 macOS 10 和 11 版本中与 macOS 捆绑在一起，但 macOS 12 (Monterey) 之后的版本中不再包含 PHP。在较新版本上安装需要使用来自第三方来源的软件包，或从源代码编译。

## 在 MacOS 上使用第三方包安装

macOS 下有几个预编译和打包的 PHP 版本。可以通过它使用标准的配置的 PHP，但是若需要不同的功能集（比如一个安全服务器，或者一个不同的数据库驱动程序），可能需要自己编译 PHP 和／或 web 服务器。如果不熟悉如何自己编译软件，可以试着找一下包含自己所需功能的 PHP 预编译版本。

在 macOS 上安装 PHP 的简单方法是使用 » Homebrew 包管理器。

1. 按照网站上的说明安装 Homebrew。

2. brew install php

下面可选资源提供了在 macOS 上易于安装的软件包和预编译的二进制 PHP。

- » MacPorts
- » Fink

## 在 macOS 下编译 PHP

参考 Unix 系统下的安装以在 macOS 下编译 PHP。

## 使用 macOS Monterey 之前内置的 PHP

PHP 从 macOS X（10.0.0）开始，到 macOS Monterey（12.0.0）之前内置到系统中。在默认的 web 服务器中启用 PHP，只需将 Apache 配置文件 httpd.conf 中的几行配置指令最前面的注释符号去掉，而 CGI 或 CLI 默认都可使用（可以很容易的被终端程序使用）。

按照以下的使用说明，可以快速的建立一个本地 PHP 开发环境。强烈建议将 PHP 升级到最新的版本。在大多数活跃的软件中， 新的版本会修复错误和添加新的功能，PHP 也是如此。请参见相应的 macOS 安装文档，以进一步了解详细的信息。以下的说明以初学者的角度来详细描述如何操作来得到一个缺省的运行环境。建议所有的用户都编译或者安装一个新的打包版本。

标准的安装类型为 mod_php，在 macOS 的 Apache web 服务器（默认 web 服务器，可以从系统设置中访问）中启用 PHP 包含以下的步骤：

1. 找到并打开Apache的配置文件。默认情况下，这个配置文件的位置是： /private/etc/apache2/httpd.conf。 使用 `Finder` 或者 `Spotlight` 来找到这个文件可能不是很容易的事情，因为在默认情况下它一般是 `root` 用户拥有所有权的私有文件。

   > 注意: 要打开这个文件，可以在命令行下面使用基于 Unix 的文本编辑器，例如 `nano`，因为他的属主是 `root`，所以我们需要使用 `sudo` 来打开（以 `root` 用户权限）。例如我们在 `Terminal` 程序中敲入下面的指令（操作后，会提示输入密码）：`sudo nano /private/etc/apache2/httpd.conf` 注意 nano 中的命令：`^w`（搜索），`^o`（保存），以及 `^x`（退出）。`^` 表示 Ctrl 键。

   > 注意: 在 Mac OS X 10.5之前的版本中捆绑的是旧版本的 PHP 和 Apache。因此在旧的计算机中 Apache 配置文件的位置可能是 /etc/httpd/httpd.conf。

2. 使用文本的编辑器取消注释（删除前面的 #）看起来类似于下面的行（这两行常常不在一起，需要在文件中找到这两行）：

       # LoadModule php5_module libexec/httpd/libphp5.so

       # AddModule mod_php5.c

   注意位置／路径。如果在以后重新编译了 PHP，以上文件应被更换或者注释掉。

3. 确保将所需要的文件扩展名解析为 PHP（例如：.php、.html 以及 .inc），否则不能正常运行。

   由于以下的配置已经写入 httpd.conf（自 Mac Panther 版起），一旦 PHP 被启用则 .php 文件会被自动解析为 PHP 脚本。

       <IfModule mod_php5.c>
           # If php is turned on, we respect .php and .phps files.
           AddType application/x-httpd-php .php
           AddType application/x-httpd-php-source .phps

           # Since most users will want index.php to work we
           # also automatically enable index.php
           <IfModule mod_dir.c>
               DirectoryIndex index.html index.php
           </IfModule>
       </IfModule>

   > 注意:

   > 在 Mac OS X 10.5（Leopard）以前版本中，捆绑的是 PHP 4 而不是 PHP 5，因此上面的配置指令稍有不同，需要将 5 更改为 4。

4. 确保 DirectoryIndex 加载了所需的默认索引文件。 这个也是在 httpd.conf 中设置的。 通常情况下使用 index.php 和 index.html 。默认情况下 index.php 会被启用，因为在我们上面的配置指令中写明了。根据实际情况可以做相应的调整。
5. 设置 php.ini 的位置或者使用默认的位置。 macOS 上通常默认的位置是 /usr/local/php/php.ini ，调用 phpinfo() 也可以得到此信息。如果没有使用 php.ini，PHP 将使用所有的默认值。参见常见问题中的寻找 php.ini。
6. 定位或者设置 `DocumentRoot`。 这是网站所有文件的根目录。此目录中的文件由 web 服务器提供服务，从而使得 PHP 文件将在输出到浏览器之前解析为 PHP 脚本。通常情况下默认的路径是 /Library/WebServer/Documents，但是可以根据需要在 httpd.conf中设置为任何其他目录。另外，用户自己的缺省 DocumentRoot 是 /Users/yourusername/Sites。
7. 创建一个 phpinfo() 文件。

   phpinfo() 将会显示PHP的相关系统信息。可以在 DocumentRoot 下创建一个 PHP 文件，其代码如下：

       <?php phpinfo(); ?>

8. 重启 Apache，然后从浏览器访问上面创建的文件。

   要重启Apache，可以在 shell 中执行 `sudo apachectl graceful`，也可以停止/启动 macOS 系统首选项中的“Personal Web Server”选项。默认情况下，从浏览器访问本地文件的 URL 一般类似于：http://localhost/info.php，或者使用：http://localhost/~yourusername/info.php 来访问用户自己 DocumentRoot 中的文件。

CLI（或者旧版本中的 CGI）一般文件名为 php ，其路径可能是 /usr/bin/php。打开一个终端，参考 PHP 手册中的 PHP 的命令行模式一章，然后执行 `php -v` 可以检查当前运行的 PHP 的版本。调用 phpinfo() 也会显示相关的信息。

# Windows 系统下的安装

## 目录

- Windows 系统下的推荐配置
- 手动安装预编译的二进制文件
- 在Windows系统上安装 Apache 2.x
- Windows 上与 IIS 安装
- 用于安装 PHP 的第三方工具
- 从源程序编译
- 在 Windows 系统的命令行上运行 PHP

建议在生产中使用 Windows 上的 PHP 官方版本，但也可以从源代码编译 PHP。

PHP 也可以安装在 Azure App Services（Azure 应用服务）（又名 Microsoft Azure、Windows Azure 或 (Windows) Azure Web Apps（Azure Web 应用））上。

常见问题解答的安装章节涵盖了可能遇到的常见安装和配置问题。

## Windows 系统下的推荐配置

### OpCache

强烈建议开启 OpCache。 此扩展默认已经包含到 PHP Windows 版本中。 它会自动编译和优化 PHP 脚本，并将它们缓存在内存中， 这样就不会在每次加载页面时动态编译它们。

在 php.ini 配置中，设置

示例 #1 推荐的 OpCache 配置

    opcache.enable=On
    opcache.enable_cli=On

然后重新启动你的 WEB 服务器。更多信息，请参阅：OpCache 配置章节。

### WinCache

WinCache 推荐在 IIS 下使用，尤其是在共享 Web 托管环境中或使用网络文件存储（NAS）时。 所有 PHP 应用程序都会自动受益于 WinCache 的文件缓存功能。文件系统操作缓存在内存中。 WinCache 还可以缓存用户对象到内存中，并在 php.exe 或 php-cgi.exe 进程之间共享它们（在请求之间共享对象）。许多主流的 Web 应用程序都有插件、扩展或配置选项来使用 WinCache 用户对象缓存。 如果需要高性能，应该在应用程序中使用对象缓存。 参阅：» https://pecl.php.net/package/WinCache 下载 WinCache DLL（或 WINCACHE_*.tgz）到 PHP 扩展目录（php.ini 中的 extension_dir）。 将 php.ini 设置为

示例 #2 推荐的 WinCache 配置

    extension=php_wincache.dll
    wincache.fcenabled=1
    wincache.ocenabled=1 ; 自 wincache 2.0.0.0 起移除

更多信息，请参阅 WinCache 配置

## 手动安装预编译的二进制文件

### 安装要求

PHP 仅适用于 32 位 x86 或 64 位 x64 系统，目前无法在 Windows RT 或 Windows on ARM 上运行。从 8.3.0 版本开始，PHP 需要 Windows 8 或 Windows Server 2012。7.2.0 之后的版本需要 Windows 2008 R2 或 Windows 7。7.2.0 之前的版本支持 Windows 2008 和 Vista。

PHP 需要 Visual C 运行时 (CRT)。许多其他应用程序也需要它，因此很可能已经安装了该运行时，但如果没有，Visual Studio 2022 的 Microsoft Visual C++ 可再发行程序包（Microsoft Visual C++ Redistributable for Visual Studio 2022）适用于所有 PHP 版本，可从 » Microsoft 下载。

必须下载 x86 CRT 才能与 PHP x86 版本一起使用，而 x64 CRT 则适用于 PHP x64 版本。如果已安装 CRT，安装程序将显示一条消息，表明已安装且不会进行任何更改。CRT 安装程序支持 /quiet 和 /norestart 命令行开关，因此可以编写安装脚本。

### 哪里可以下载 PHP 二进制文件

Windows 版本可从 » PHP Windows 网站下载。所有版本都经过优化 (PGO)，QA 和 GA 版本都经过全面测试。

### 预编译的 PECL 扩展

PECL 扩展的预编译 Windows 版本以 DLL 文件的形式分发在扩展的 PECL 页面上。

对于使用其他系统（如 Unix）的特定功能或依赖于在 Windows 上无效的扩展，二进制文件不可用。

### 编译类型

PHP 编译有四种类型：

- Thread-Safe (TS) - 线程安全，用于单进程 web 服务器，例如带有 mod_php 的 Apache

- Non-Thread-Safe (NTS) - 非线程安全，用于 IIS 和其他 FastCGI web 服务器（使用带有 mod_fastcgi 的 Apache），并且推荐命令行脚本也用此版本

- x86 - 用于 32 位系统。

- x64 - 用于 64 位系统。

## 在Windows系统上安装 Apache 2.x

本节包括在 Microsoft Windows 系统中针对 Apache 2.x 安装 PHP 的指导与说明。

> 注意:

> 请先阅读手工安装步骤！

强烈建议阅读 » Apache 文档 来加深对 Apache 2.x 服务器的基本理解。此外在继续下去之前考虑先阅读一下 Apache 2.x 的 » Windows 下使用说明。

下载最新版本的 » Apache 2.x 以及适合的 PHP 版本。先完成手工安装步骤后再回来继续将 PHP 集成入 Apache。

Windows 下有三种方法使 PHP 工作于 Apache 2.x 之中。可以以 handler、CGI、或者 FastCGI 方式运行 PHP。

> 注意: 记住当在 Windows 环境下的 Apache 配置文件中添加路径值时，所有的反斜线，如 c:\directory\file.ext，应转换为正斜线： c:/directory/file.ext。对目录来说，也必须由斜线结尾。

### 以 Apache handler 方式安装

> 注意: 在使用 apache2handler SAPI 时，必须使用线程安全 (TS) 版本的 PHP。

需要将以下几行加入到 Apache 的 httpd.conf 配置文件中以加载 Apache 2.x 的 PHP 模块：

示例 #1 PHP 在 Apache 2.x 中作为 handler

    # 在 PHP 8.0.0 之前，模块的名称是 php7_module
    LoadModule php_module "c:/php/php8apache2_4.dll"
    <FilesMatch \.php$>
        SetHandler application/x-httpd-php
    </FilesMatch>
    # 配置 php.ini 的路径
    PHPIniDir "C:/php"

> 注意: 必须使用实际的 PHP 路径替换掉上例中的 c:/php/。 确保在 `LoadModule` 指令中引用的文件位于所指定的位置。 PHP 7 使用 php7apache2_4.dll， PHP 8 使用 php8apache2_4.dll。

### 以 CGI 方式运行 PHP

要更好地理解在 Apache 下运行 CGI，请参阅 » Apache CGI 文档。

要将 PHP 以 CGI 方式运行，需要将 php-cgi 文件放入到用 ScriptAlias 指令所指定的 CGI 目录中。

然后需要给 PHP 文件中添加 `#!` 的一行来指明 PHP 可执行文件的位置：

示例 #2 Apache 2.x 下 CGI 方式的 PHP

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

警告

服务器使用 CGI 方式进行部署可能存在几个公开的缺陷。请阅读 CGI 安全一章 以学习 如何抵御这些攻击。

### 以 FastCGI 方式运行 PHP

以 FastCGI 方式运行 PHP 比起 CGI 方式有很多优点。设定的方式很直接：

从 » https://www.apachelounge.com 取得 `mod_fcgid`，该站点有 Win32 可执行文件的下载。按照下载文件中的指示安装此模块。

按以下方法配置 web 服务器，注意用自己系统上的路径替换其中相应的内容：

示例 #3 配置 Apache 以 FastCGI 方式运行 PHP

    LoadModule fcgid_module modules/mod_fcgid.so

    # php.ini 文件的位置
    FcgidInitialEnv PHPRC        "c:/php"

    <FilesMatch \.php$>
        SetHandler fcgid-script
    </FilesMatch>
    FcgidWrapper "c:/php/php-cgi.exe" .php

此时具有 `.php` 后缀的文件将被 PHP FastCGI 所解析执行。

## Windows 上与 IIS 安装

### 安装 IIS

Internet 信息服务 (IIS) 内置于 Windows 中。在 Windows Server 上，可以通过服务器管理器添加 IIS 角色。需要包含 CGI 角色功能。在 Windows 桌面上，必须通过控制面板的添加/删除程序添加 IIS。Microsoft 文档有» 关于启用 IIS 的详细说明。对于开发，也可以使用 » IIS/Express。

> 注意: 在 IIS 中使用 FastCGI 处理程序时，应安装 PHP 的非线程安全 (NTS) 版本。

### 使用 IIS 配置 PHP-CGI

在 IIS 管理器中，安装 FastCGI 模块并将 `.php` 的处理程序映射到 php-cgi.exe（而不是 php.exe）的路径

APPCMD 命令行工具可用于编写 IIS 配置脚本。

### 批处理脚本示例

示例 #1 命令行配置 IIS 和 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']"

## 用于安装 PHP 的第三方工具

警告

第三方提供的版本被视为非官方版本，不直接受 PHP 项目支持。 除非可以通过 » 官方下载区的构建版重现， 否则遇到的任何错误都应报告给这些非官方构建版的提供者。

» XAMPP、 » WampServer 和 » Bitnami 也会在 Windows 上使用 Apache 安装 PHP 应用程序。

## 从源程序编译

参阅 » 逐步构建说明 以使用 Visual Studio 进行编译。

## 在 Windows 系统的命令行上运行 PHP

本章包含有针对在 Windows 下以命令行运行 PHP 的说明与提示。

> 注意:

> 阅读 手工安装步骤！

要在命令行下运行 PHP，可以无需对 Windows 做任何改动。

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

但是有几个很容易的步骤可以使其更加简便。某些步骤可能已经在之前完成了，不过还是在这里重复说明以便提供一个完整的步骤序列。

> 注意:

> PATH 和 PATHEXT 都是在 Windows 下已有的重要环境变量，要留意不要覆盖了其内容，仅仅是向其中添加内容。

- 将 PHP 可执行文件（php.exe，php-win.exe 或者 php-cli.exe）的路径添加到 PATH 环境变量中去。如何将 PHP 目录添加到 PATH 中请参阅与之相关的常见问题。

- 将 `.PHP` 后缀添加到 PATHEXT 环境变量中去。可以在修改 PATH 环境变量时同时进行。跟常见问题中说明的步骤一样，要修改的是 PATHEXT 环境变量而不是 PATH 环境变量。

  > 注意:

  > 把 `.PHP` 放置到什么位置将决定具有相同文件名时运行的优先级。例如将 `.PHP` 放到 `.BAT` 之前将导致如果有同名的 PHP 脚本和批处理文件，则 PHP 脚本会运行。

- 将 `.PHP` 后缀关联为一种文件类型，用以下命令完成：

      assoc .php=phpfile

- 将 `phpfile` 文件类型关联到适当的 PHP 可执行文件，用以下命令完成：

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

按照以上步骤将使 PHP 脚本可以在任何目录下运行，不需要输入 PHP 可执行文件名以及 `.PHP` 后缀，并且所有参数都会被传递给脚本来处理。

以下例子说明了可以手工修改的注册表项目变化。

示例 #1 注册表变化

    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"

有了这些改变之后，本页顶端第一个例子中的命令可以写成这样：

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

或者如果 `"C:\PHP Scripts"` 目录位于 PATH 环境变量中的话：

    script -arg1 -arg2 -arg3

> 注意:

> 当打算使用这种技术作为命令行过滤器运行 PHP 脚本时，会出现一个小问题，例如以下例子：

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

> 或者

>     dir | script -arg1 -arg2 -arg3

> 脚本可能会直接挂起，没有任何输出。 要使其正常运行，需要对注册表进行另一项更改：

>     Windows Registry Editor Version 5.00

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

> 有关此问题的更多信息见» 微软知识库文章：321788。 从 Windows 10 开始，此设置似乎被颠倒，请参考以下链接 » Microsoft 论坛帖子。

# 云计算平台上的安装

## 目录

- Azure 应用服务
- Amazon EC2
- DigitalOcean

PHP 在云平台上的安装。进入 PHP 云世界！

## Azure 应用服务

PHP 经常用于 Azure 应用服务（又称 Microsoft Azure、Windows Azure、Azure Web 应用）。

Azure 应用服务通过管理 Windows Web 应用池来托管 web 应用程序，作为在你自己的 Azure 计算虚拟机或者其他服务器的 web 服务器管理的替代品。

在 Azure 应用服务中 PHP 将会自动启用。 在 Azure 门户，选择你的站点，选择要使用的 PHP 版本。可能希望选择比默认更高的版本。

因此，PHP 和扩展将跟在其他 Windows 服务器一样在 Azure 应用服务上运行。 然而，Azure 应用管理的管理界面是不同的：

- Azure 门户：创建，编辑设置和删除 web 站点。 » Azure 门户

- Kudu 仪表板：如果网站的 URL 是 `site_name.azurewebsites.net`，那么 Kudu 仪表板是 `https://site_name.scm.azurewebsites.net/`。 仪表板提供了调试功能，文件管理和站点扩展。 站点扩展是 Azure 机制，用于向网站添加额外的程序，如 PHP 预览版本。

- 你不能使用 IIS 管理器、服务器管理器、RDP。

还有 PHP SDK，支持用 PHP 代码调用许多 Azure 服务。参阅 » Azure SDK for PHP。

更多信息，参阅 » Azure PHP 开发人员中心

### WinCache

在 Azure 应用服务中默认启用了 WinCache ，并且推荐保持开启状态。 如果安装的是自己编译的 PHP，也应该启用 WinCache。

### 自定义编译 PHP

可以上传自己编译的 PHP 到 D:\Home (C:\ 不可写)。然后在 Azure 门户，为 .php 的 SCRIPT_PROCESSOR 设置为自己编译的 php-cgi.exe 文件的绝对路径。

## Amazon EC2

» EC2 云平台上 PHP 的安装。

参见 » AWS SDK for PHP。

## DigitalOcean

DigitalOcean 提供以下平台来安装 PHP， 并在其云托管基础架构上运行 Web 应用程序。

- » Cloudways： 一键部署主要的 PHP 应用程序： WordPress、Magento、Drupal、Laravel 等等。

- » Droplet： 使用虚拟机在 » Linux 服务器上安装 LAMP 堆栈 。

- » App Platform： 使用托管基础架构快速构建、部署和扩展应用程序。 了解 » 如何在应用平台上运行 PHP 应用程序 。

- » Functions： 无服务器平台允许开发人员在不预配或管理服务器的情况下运行代码。 PHP 被原生支持。 了解 » 如何使用 PHP 创建无服务器函数 。

# FastCGI 进程管理器（FPM）

## 目录

- 安装
- 配置

FPM（FastCGI 进程管理器）是 PHP FastCGI 的主要实现，包含大部分对高负载网站有用的功能。

它的功能包括：

- 支持平滑停止/启动的高级进程管理功能；

- 进程池可以工作于不同的 uid/gid/chroot 环境下，并监听不同的端口和使用不同的 php.ini 配置文件（可取代 safe_mode 的设置）；

- 可配置的 stdout 和 stderr 日志记录;

- 在发生意外情况的时候能够重新启动并缓存被破坏的 opcode;

- 文件上传优化支持;

- "慢日志" - 记录脚本（不仅记录文件名，还记录 PHP backtrace 信息，可以使用 ptrace 或者类似工具读取和分析远程进程的运行数据）运行所导致的异常缓慢;

- fastcgi_finish_request() - 特殊功能：用于在请求完成和刷新数据后，继续在后台执行耗时的工作（录入视频转换、统计处理等）；

- 动态（dynamic）/按需（ondemand）/静态（static）子进程产生；

- 基础和扩展运行状态信息（类似 Apache 的 mod_status），支持各种格式，如： json， xml 和 openmetrics；

- 基于 php.ini 的配置文件。

## 安装

### 从源代码编译

编译 PHP 时需要 `--enable-fpm` 配置选项来激活 FPM 支持。

以下为 FPM 编译的具体配置参数（全部为可选参数）：

- `--with-fpm-user` - 设置 FPM 运行的用户身份（默认 - nobody）。

- `--with-fpm-group` - 设置 FPM 运行时的用户组（默认 - nobody）。

- `--with-fpm-systemd` - 启用 systemd 集成 (默认 - no)。

- `--with-fpm-acl` - 使用 POSIX 访问控制列表 (默认 - no)。

- `--with-fpm-apparmor` - 激活 AppArmor 集成 (默认 - no)。

- `--with-fpm-selinux` - 激活 SELinux 集成（默认 - no）。

### 更新日志

版本 | 说明
--- | ---
8.2.0 | 新增 `--with-fpm-selinux` 选项。
8.0.0 | 新增 `--with-fpm-apparmor` 选项。

## 配置

FPM 使用类似 php.ini 语法的 php-fpm.conf 和进程池配置文件。

### php-fpm.conf 全局配置段

`pid` string

  PID 文件的位置。默认为空。

`error_log` string

  错误日志的位置。默认：`#INSTALL_PREFIX#/log/php-fpm.log`。 如果设置为 "syslog"，日志将不会写入本地文件，而是发送到 syslogd。

`log_level` string

  错误级别。可用级别为：alert（必须立即处理），error（错误情况），warning（警告情况），notice（一般重要信息），debug（调试信息）。默认：notice。

`log_limit` int

  日志记录行的限制，允许记录超过 1024 个字符的消息而不需要换行。 默认值：1024。 PHP 7.3.0 起可用。

`log_buffering` bool

  实验性：没有额外缓冲的日志记录。 默认值：yes。 PHP 7.3.0 后可用。

`syslog.facility` string

  设置何种程序记录消息，默认值：daemon。

`syslog.ident` string

  为每条信息添加前缀。 如果在同一台服务器上运行了多个 FPM 实例，可以修改此默认值来满足需求。默认值：php-fpm。

`emergency_restart_threshold` int

  如果子进程在 `emergency_restart_interval` 设定的时间内收到该参数设定次数的 SIGSEGV 或者 SIGBUS退出信息号，则FPM会重新启动。0 表示“关闭该功能”。默认值：0（关闭）。

`emergency_restart_interval` mixed

  `emergency_restart_interval` 用于设定平滑重启的间隔时间。这么做有助于解决加速器中共享内存的使用问题。可用单位：s（秒），m（分），h（小时）或者 d（天）。默认单位：s（秒）。默认值：0（关闭）。

`process_control_timeout` mixed

  设置子进程接受主进程复用信号的超时时间。可用单位：s（秒），m（分），h（小时）或者 d（天）。默认单位：s（秒）。默认值：0（关闭）。

`process.max` int

  Fork 的最大 FPM 进程数。使用动态管理进程数时，此设计可以控制在一个进程池内的全局进程数量。 使用需谨慎。默认值：0。

`process.priority` int

  设置 master 进程的 nice(2) 优先级（如果设置了此值）。 可以是 -19（最高优先级）到 20 （更低优先级）。 默认值：不设置。

`daemonize` bool

  设置 FPM 在后台运行。设置“no”将 FPM 保持在前台运行用于调试。默认值：yes。

`rlimit_files` int

  设置 master 进程的打开文件描述符 rlimit 数。 默认值：系统定义值。

`rlimit_core` int

  设置 master 进程最大 core 的 rlimit 尺寸。 默认值：0。

`events.mechanism` string

  设置 FPM 使用的事件机制。 可用以下选项：epoll、kqueue (*BSD)、port (Solaris)、poll、select。 默认值：不设置（自动检测，优先使用 epoll 和 kqueue）

`systemd_interval` int

  使用 systemd 集成的 FPM 时，设置间歇秒数，报告健在通知给 systemd。 设置为 0 表示禁用。默认值：10。

### 运行配置区段

在FPM中，可以使用不同的设置来运行多个进程池。 这些设置可以针对每个进程池单独设置。

`listen` string

  设置接受 FastCGI 请求的地址。可用格式为：'ip:port'，'port'，'/path/to/unix/socket'。每个进程池都需要设置。

`listen.backlog` int

  设置 listen(2) backlog 的值。在 BSD 系统上 `-1` 表示无限制。默认值：`-1`（FreeBSD 或 OpenBSD）或者 `511`（Linux 或其他平台）。

`listen.allowed_clients` string

  设置允许连接到 FastCGI 客户端的 IPv4 或 IPv6 地址列表。等同于 PHP FastCGI (5.2.2+) 中的 FCGI_WEB_SERVER_ADDRS 环境变量。仅对 TCP 监听起作用。每个地址是用逗号分隔，如果没有设置或者为空，则允许任何服务器请求连接。默认值：未设置（接受任何 IP 地址）。

`listen.owner` string

  如果使用了 Unix 套接字，表示它的权限。在 Linux 中必须设置读/写权限，以便用于 WEB 服务器连接。 在很多 BSD 派生的系统中可以忽略权限允许自由连接。 默认值：运行所使用的用户和组，权限为 0660。

`listen.group` string

  参见 `listen.owner`。

`listen.mode` string

  参见 `listen.owner`。

`listen.acl_users` string

  当系统支持 POSIX ACL（Access Control Lists）时，可以设置使用此选项。 当设置了的时候，将会忽略 `listen.owner` 和 `listen.group`。 值是逗号分割的用户名列表。

`listen.acl_groups` string

  参见 `listen.acl_users`。 值是逗号分割的用户组名称列表。

`listen.setfib` int

  设置关联的路由表（FIB）。仅适用于 FreeBSD。默认值 `-1`。自 PHP 8.2.0 起可用。

`user` string

  FPM 进程运行的Unix用户。必须设置。

`group` string

  FPM 进程运行的 Unix 用户组。如果不设置，就使用默认用户的用户组。

`pm` string

  设置进程管理器如何管理子进程。可用值：`static`，`ondemand`，`dynamic`。必须设置。

  `static` - 子进程的数量是固定的（`pm.max_children`）。

  `ondemand` - 进程在有需求时才产生（当请求时才启动。与 dynamic 相反，在服务启动时 `pm.start_servers` 就启动了。

  `dynamic` - 子进程的数量在下面配置的基础上动态设置：`pm.max_children`，`pm.start_servers`，`pm.min_spare_servers`，`pm.max_spare_servers`。

`pm.max_children` int

  `pm` 设置为 `static` 时表示创建的子进程的数量，`pm` 设置为 `dynamic` 时表示最大可创建的子进程的数量。必须设置。

  该选项设置可以同时提供服务的请求数限制。类似 Apache 的 mpm_prefork 中 MaxClients 的设置和 普通PHP FastCGI中的 PHP_FCGI_CHILDREN 环境变量。

`pm.start_servers` int

  设置启动时创建的子进程数目。仅在 `pm` 设置为 `dynamic` 时使用。默认值：(min_spare_servers + max_spare_servers) / 2。

`pm.min_spare_servers` int

  设置空闲服务进程的最低数目。仅在 `pm` 设置为 `dynamic` 时使用。必须设置。

`pm.max_spare_servers` int

  设置空闲服务进程的最大数目。仅在 `pm` 设置为 `dynamic` 时使用。必须设置。

`pm.max_spawn_rate` int

  同时生成子进程的速率。仅当 `pm` 设置为 `dynamic` 时使用。默认值： 32

`pm.process_idle_timeout` mixed

  秒数，多久之后结束空闲进程。 仅当设置 `pm` 为 `ondemand`。 可用单位：s（秒），m（分），h（小时）或者 d（天）。默认单位：10s。

`pm.max_requests` int

  设置每个子进程重生之前服务的请求数。对于可能存在内存泄漏的第三方模块来说是非常有用的。如果设置为 '0' 则一直接受请求，等同于 PHP_FCGI_MAX_REQUESTS 环境变量。默认值：0。

`pm.status_listen` string

  接受 FastCGI 状态请求的地址。会创建一个新不可见池用来独立处理请求。如果主池处理长时间运行的请求时很繁忙， 那么对长时间运行的请求结束之前能够获得 FPM 状态页面会非常有用。语法与 listen 指令相同。默认值：none。

`pm.status_path` string

  查看 FPM 状态页面的 URI。此值必须以斜线（/）开头。如果没有设置，则无法访问状态页面，默认值：无。

`ping.path` string

  FPM 监控页面的 ping 网址。如果没有设置，则无法访问 ping 页面。该页面用于外部检测 FPM 是否存活并且可以响应请求。请注意必须以斜线开头（/）。

`ping.response` string

  用于定义 ping 请求的返回响应。返回为 HTTP 200 的 text/plain 格式文本。默认值：pong。

`process.priority` int

  设置 worker 的 nice(2)优先级（如果设置了的话）。 该值从 -19（最高优先级） 到 20（更低优先级）。 默认值：不设置

`process.dumpable` bool

  即使进程用户或者组跟主进程用户是不同的，也设置进程可转储标志 (PR_SET_DUMPABLE prctl)。 它允许为用户池创建进程 core dump 和 ptrace 进程。 默认值：no。自 PHP 7.0.29、7.1.17 和 7.2.5 起可用。

`prefix` string

  检测路径时使用的前缀。

`request_terminate_timeout` mixed

  设置单个请求的超时中止时间。该选项可能会对 php.ini 设置中的 'max_execution_time' 因为某些特殊原因没有中止运行的脚本有用。设置为 '0' 表示 'Off'。可用单位：s（秒），m（分），h（小时）或者 d（天）。默认单位：s（秒）。默认值：0（关闭）。

`request_terminate_timeout_track_finished` bool

  在 fastcgi_finish_request 之后或当应用程序结束且调用内部关闭命令时，不会使用通过 request_terminate_timeout 设置的超时时间。但即使在这种情况下，该指令也可以无条件应用超时限制。默认值：no。自 PHP 7.3.0 启用。

`request_slowlog_timeout` mixed

  当一个请求该设置的超时时间后，就会将对应的 PHP 调用堆栈信息完整写入到慢日志中。设置为 '0' 表示 'Off'。可用单位：s（秒），m（分），h（小时）或者 d（天）。默认单位：s（秒）。默认值：0（关闭）。

`request_slowlog_trace_depth` int

  slowlog 日志堆栈追踪的深度。默认值：20。自 PHP 7.2.0 起可用。

`slowlog` string

  慢请求的记录日志。默认值：`#INSTALL_PREFIX#/log/php-fpm.log.slow`。

`rlimit_files` int

  设置文件打开描述符的 rlimit 限制。默认值：系统定义值。

`rlimit_core` int

  设置核心 rlimit 最大限制值。可用值：'unlimited'，0 或者正整数。默认值：系统定义值。

`chroot` string

  启动时的 Chroot 目录。所定义的目录需要是绝对路径。如果没有设置，则 chroot 不被使用。

`chdir` string

  设置启动目录，启动时会自动 Chdir 到该目录。所定义的目录需要是绝对路径。默认值：当前目录，或者根目录（chroot时）。

`catch_workers_output` bool

  重定向运行过程中的 stdout 和 stderr 到主要的错误日志文件中。如果没有设置，stdout 和 stderr 将会根据 FastCGI 的规则被重定向到 /dev/null。默认值：无。

`decorate_workers_output` bool

  当 catch_workers_output 启用时， 为 worker 输出启用输出装饰。 默认值：yes。 自 PHP 7.3.0 起可用。

`clear_env` bool

  为 FPM worker 进程清除环境变量。 在进程池配置文件里设置环境变量前，阻止任意系统的环境变量进入 FPM worker 进程。 默认值：Yes

`security.limit_extensions` string

  限制 FPM 允许解析的脚本扩展名。 此设置可以预防 web 服务器配置的错误。 应当限制 FPM 仅仅解析 .php 扩展名，阻止恶意用户使用其他扩展名运行 php 代码。 默认值： .php .phar

`apparmor_hat` string

  如果启用 AppArmor，允许更换帽子（hat）。 默认值：未设置

`access.log` string

  Access log 文件。 默认值：不设置

`access.format` string

  access log 的格式。 默认: `"%R - %u %t \"%m %r\" %s"`：

  可用选项
  占位符 | 描述
  --- | ---
  `%%` | `%` 字符
  `%C` | 请求使用的 %CPU。可以接受以下格式：`%{user}C` 仅表示用户 CPU，`%{system}C` 仅表示系统 CPU，`%{total}C` 表示用户 + 系统 CPU（默认）
  `%d` | 处理请求所花费的时间。可以接受以下格式以提高精度：`%{seconds}d`（默认）`%{milliseconds}d`、`%{microseconds}d`
  `%{name}e` | 环境变量（与 $_ENV 或 $_SERVER 相同）。必须在花括号内指定变量名称，以指定环境 env 的名称。例如，服务器详细信息（如 `%{REQUEST_METHOD}e` 或 `%{SERVER_PROTOCOL}e`）、HTTP header（如 `%{HTTP_HOST}e` 或 `%{HTTP_USER_AGENT}e`）
  `%f` | 脚本文件名
  `%l` | 请求的 `Content-Length`（仅适用于 HTTP POST 请求）
  `%m` | 请求 HTTP 方法
  `%M` | PHP 分配的内存峰值。可以接受以下格式：`%{bytes}M`（默认）、`%{kilobytes}M`、`%{kilo}M`、`%{megabytes}M`、`%{mega}M`
  `%n` | 进程池（pool）名称
  `%{name}o` | 输出 header。必须在花括号内指定 header 名称。例如 `%{Content-Type}o`、`%{X-Powered-By}o`、`%{Transfer-Encoding}o`
  `%p` | 为请求提供服务的子进程的 PID
  `%P` | 为请求提供服务的子进程的父进程 PID
  `%q` | 查询字符串
  `%Q` | 如果查询字符串存在，则为 `'?'` 字符，或 `%q` 和 `%r` 之间的连接字符
  `%r` | 不带查询字符串的请求 URI，参阅 `%q` 和 `%Q`
  `%R` | 远程 IP 地址
  `%s` | 状态（响应码）
  `%t` | 收到请求的服务器时间。可以接受 `strftime(3)` 格式 `%d/%b/%Y:%H:%M:%S %z`（默认）。`strftime(3)` 格式必须封装在 `%{<strftime_format>}t` 标签中，例如，对于 ISO8601 格式的时间字符串，使用 `%{%Y-%m-%dT%H:%M:%S%z}t`
  `%T` | 写入日志的时间（请求完成时）。可以接受 `strftime(3)` 格式 `%d/%b/%Y:%H:%M:%S %z`（默认）。`strftime(3)` 格式必须封装在 `%{<strftime_format>}T` 标签中，例如，对于 ISO8601 格式的时间字符串，使用 `%{%Y-%m-%dT%H:%M:%S%z}T`
  `%u` | 基本访问认证用户（如果在 `Authorization` header 中指定）

`access.suppress_path` array

  需要从访问日志中过滤掉的 request_uri 值列表。默认值：未设置。自 PHP 8.2.0 起可用。

还可以在为一个运行池传递附加的环境变量，或者更新 PHP 的配置值。可以在进程池配置文件中如下面的配置参数来做到：

示例 #1 给运行池传递环境变量和设置 PHP 的配置值

    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配置值通过 `php_value` 或者 `php_flag` 设置，并且会覆盖以前的值。请注意 disable_functions 或者 disable_classes 在 php.ini 之中定义的值不会被覆盖掉，但是会将新的设置附加在原有值的后面。

使用 `php_admin_value` 或者 `php_admin_flag` 定义的值，不能被 PHP 代码中的 ini_set() 覆盖。

可以通过 web 服务器设置 PHP 的设定。

示例 #2 在 nginx.conf 中设定 PHP

    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";

警告

由于这些设定是以 FastCGI 标头传递给 php-fpm，php-fpm 不应绑定到外部网可以访问的地址上，否则任何人都能修改 PHP 的配置选项了。参见 listen.allowed_clients。

> 注意: 进程池不是种安全机制，因为它们不会完全隔离；例如：所有的进程池会使用单个 Opcache 实例。

# PECL 扩展安装

## 目录

- PECL 安装介绍
- 下载 PECL 扩展库
- 在 Windows 上安装 PHP 扩展
- 用 PEAR 编译共享 PECL 扩展库
- 用 phpize 编译共享 PECL 扩展库
- php-config
- 将 PECL 扩展库静态编译入 PHP

## PECL 安装介绍

> 注意: PHP 扩展安装器 (PIE) 是一个新的工具，将取代 PECL。 我们建议使用 PIE 来安装扩展。在 » https://github.com/php/pie 了解更多。

» PECL 通过 » PEAR 打包系统来的 PHP 扩展库仓库，本章内容示范了怎样取得并安装 PECL 扩展。

以下指南中假设 `/path/to/php/src/dir` 是 PHP 源代码发布包的路径，`extname` 是 PECL 扩展库的名字。自己根据实际情况调整。此外还假设用户熟悉 » pear 命令。PEAR 手册里 pear 命令的信息同样适用于 pecl。

共享扩展库必须经过编译、安装和加载才能使用。以下说明的方法提供了怎样编译和安装扩展库的各种指导，但并不会自动加载它们。可以通过将其包括在 php.ini 中用 extension PHP 指令加载，或者 用 dl() 函数。

当编译 PHP 模块时，拥有各种工具（autoconf、automake、libtool 等）的已知好使的版本很重要。所需工具和所需版本的详情见» 匿名 Git 说明。

## 下载 PECL 扩展库

> 注意: PHP 扩展安装器 (PIE) 是一个新的工具，将取代 PECL。 我们建议使用 PIE 来安装扩展。在 » https://github.com/php/pie 了解更多。

下载 PECL 扩展库有几种方法，如：

- pecl install extname 命令会自动下载扩展代码，所以在这种情况下不需要再次下载。
- » https://pecl.php.net/ PECL 网站包括有 PHP 开发组提供的不同扩展库的信息。这里的信息包括：更新记录、版本说明、需求以及其它信息。
- pecl download extname PECL 网站中列出的 PECL 扩展库的发行版本可以用 » pear 命令 来下载和安装。也可以指定具体的修订版本。
- git Github 上有很多 PECL 扩展。
- SVN 部分 PECL 扩展库也在 SVN 中。其 web 页面见 » https://svn.php.net/pecl/。要直接从 SVN 中下载，用以下命令：

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

- Windows 下载 PHP 项目在 package 页面上编译并提供大多数 PECL 扩展的 Windows DLL 文件。

## 在 Windows 上安装 PHP 扩展

在 Windows 上有两种加载 PHP 扩展的方式：把扩展编译进 PHP，或者加载 DLL。加载预编译的扩展是更简单更被推荐的方式。

要加载扩展，需要在系统中有可用的 .dll 文件。所有扩展都会由 PHP 小组定期自动编译（如何下载见下节）。

要将扩展编译入 PHP，请参考从源程序编译文档。

要编译一个独立的扩展（即 DLL 文件），请参考从源程序编译文档。如果在 PHP 发行版和 PCEL 中都没有某 DLL 文件，那可能需要编译之后才能使用该扩展。

### 去哪里找扩展库？

PHP 扩展库通常称为 php_*.dll（其中星号代表具体某扩展的名字），位于 PHP\ext 目录下。

PHP 发行包中包括了大多数开发者最常用到的扩展库。称为捆绑扩展库。

不过，如果捆绑扩展没有提供所需的功能，可以在 » PECL 中找到满足需求的扩展。PHP 扩展社区库（PHP Extension Community Library 简称 PECL）是个 PHP 扩展的储存库，提供了对于所有已知扩展目录以及下载及开发 PHP 扩展的托管设施。

如果针对特定用途开发了扩展，则可以将其托管在 PECL 中以便于其他有相同需求的用户使用。这样做的好处就是可以得到其他用户的反馈、感谢、错误报告甚至修复/补丁。不过在向 PECL 提交扩展之前，请先阅读 » PECL 提交指南。

### 下载哪个扩展？

很多时候，每个 DLL 都有几个版本可供选择：

- 不同的版本号（至少前两个数字要一致）
- 不同的线程安全性设定
- 不同的处理器体系（x86，x64，...)
- 不同的排错设定
- `其它`

请记住，扩展设置应该与所使用的 PHP 可执行文件的设置相匹配。以下脚本可以显示所有 PHP 设置：

示例 #1 调用 phpinfo()

    <?php
    phpinfo();
    ?>

或者在命令行运行：

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

### 载入一个扩展

最常见的方式是在 php.ini 配置文件里包含一个 PHP 扩展。请注意很多扩展已经在 php.ini 里了，仅需要移除分号来激活它们。

需要注意，从 PHP 7.2.0 开始，可以直接用扩展的名称，来替代扩展的文件名。这样配置文件就跟操作系统解耦了，也更容易理解。推荐采用此方式加载扩展。为了与之前的版本保持兼容，直接写扩展名的方式会仍然支持。

    ;extension=php_extname.dll

    extension=php_extname.dll

    ; 自 PHP 7.2.0 起首选：
    extension=extname
    zend_extension=another_extension

不过呢，有些 web 服务器会搞混，因为其并不一定使用和 PHP 可执行文件处于同一目录下的 php.ini 文件。要搞清楚具体使用了哪一个 php.ini 文件，在 phpinfo() 的输出中查看：

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

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

激活一个扩展后，保存 php.ini 文件并重启动 web 服务器，然后用 phpinfo() 再次查看确定。新的扩展应该有其自己的一节。

### 解决问题

如果某扩展并未在 phpinfo() 中显示，应该查看日志以确定问题出在哪里。

如果是在命令行中（CLI）使用 PHP，扩展加载出错信息会直接在屏幕显示。

如果在 web 服务器中使用 PHP，则日志文件的位置与格式各不相同。请阅读所使用的 web 服务器之文档以确定日志文件的位置，这与 PHP 本身并无关系。

最常见的问题是 DLL 和 DLL 依赖的文件的位置，php.ini 中“extension_dir”设置的值，以及编译时的设置不匹配。

如果问题出在编译时设置不匹配，那可能所下载的 DLL 文件不对。可以尝试使用正确的设置重新下载扩展。此外，phpinfo() 可以起到很大帮助。

## 用 PEAR 编译共享 PECL 扩展库

PECL 使建立共享 PHP 扩展库更容易。用 » pecl 命令这样做：

    $ pecl install extname

这将下载 extname 的源代码，编译之，并将 extname.so 安装到 extension_dir 中。然后 extname.so 就可以通过 php.ini 加载了。

默认情况下，pecl 命令不会安装标记为 `alpha` 或 `beta` 状态的包。如果没有 `stable` 包可用，也可以用以下命令安装一个 `beta` 包：

    $ pecl install extname-beta

也可以用此命令安装一个指定的版本：

    $ pecl install extname-0.1

> 注意:

> 在 php.ini 中启用扩展之后，需要重新启动 web 服务以使更改生效。

## 用 phpize 编译共享 PECL 扩展库

有时候不能用 pecl 安装命令。这可能是因为存在防火墙，或者要安装的扩展不可用作 PECL 兼容的包，例如 Git 中尚未发布的扩展库。如果要编译这种扩展，可以用更底层的编译工具来手工进行编译。

phpize 命令是用来准备 PHP 扩展库的编译环境的。下面例子中，扩展库的源程序位于 extname 目录中：

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

成功的安装将创建 extname.so 并放置于 PHP 的扩展库目录中。需要调整 php.ini，加入 `extension=extname.so` 这一行之后才能使用此扩展库。

如果系统中没有 phpize 命令并且使用了预编译的包（例如 RPM），那要安装 PHP 包相应的开发版本，此版本通常包含了 phpize 命令以及用于编译 PHP 及其扩展库的正确头文件。

使用 phpize --help 命令可以显示此命令用法。

## php-config

php-config 是一个简单的命令行脚本用于获取所安装的 PHP 配置的信息。

在编译扩展时，如果安装有多个 PHP 版本，可以在配置时用 --with-php-config 选项来指定使用哪一个版本编译，设置相应 php-config 脚本的路径。

php-config 脚本在命令行所能使用的选项可以通过 -h 选项来查询：

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

命令行选项
选项 | 说明
--- | ---
--prefix | PHP 所安装的路径前缀，例如 /usr/local
--includes | 列出用 `-I` 选项包含的所有文件
--ldflags | PHP 编译时所使用的 `LD` flag
--libs | PHP 编译时所附加的库
--extension-dir | 扩展库的默认路径
--include-dir | 头文件的默认路径前缀
--php-binary | PHP CLI 或者 CGI 可执行文件的完整路径
--php-sapis | 列出所有可用的 SAPI 模块
--configure-options | 重现当前 PHP 在编译时的配置选项
--version | PHP 版本号
--vernum | PHP 版本号，以整数表示

## 将 PECL 扩展库静态编译入 PHP

可能需要将扩展库静态编译到 PHP 中。这需要将扩展库源码放入 /path/to/php/src/dir/ext/ 目录中，去使用 PHP 编译系统来重新生成其 configure 脚本。

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

这将产生以下目录：

    /path/to/php/src/dir/ext/extname

此时 PHP 需要强制重新生成配置脚本，然后正常编译 PHP：

    $ cd /path/to/php/src/dir
    $ rm configure
    $ ./buildconf --force
    $ ./configure --help
    $ ./configure --with-extname --enable-someotherext --with-foobar
    $ make
    $ make install

> 注意: 要运行 buildconf 脚本，需要 autoconf `2.68` 和 automake `1.4+`。更高版本的 autoconf 也许能工作，但不被支持。

是否用 --enable-extname 或 --with-extname 取决于扩展库。通常不需要外部库文件的扩展库使用 --enable。当然，在 buildconf 之后运行：

    $ ./configure --help | grep extname

# Composer 与第三方软件包的安装

## Composer 简介

» Composer 是 PHP 的依赖管理工具，可用于定义项目所使用的第三方代码包，并轻松完成安装与更新。它利用 PHP 内置的类自动加载功能、PHP 软件包仓库（如 » Packagist），以及通用的项目结构和编码规范。

例如，某个 PHP 应用或网站需要处理 UUID 值，可使用 » Ben Ramsey 开发的 `ramsey/uuid` 软件包，该包实现了 » RFC 4122 所定义的广泛使用和认可的 UUID 类型。

简而言之，这一过程通过在项目中创建 `composer.json` 文件，使用 Composer 安装该软件包的最新版本，并引入 Composer 的自动加载脚本以供代码使用。» Composer “基本用法”文档对此有更详细的说明。

示例 #1 `composer.json` 需要单个软件包

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

# 安装 PIE 与第三方扩展

## PIE 简介

» PIE 是 PHP 安装工具，可用于安装第三方 PHP 扩展，并支持便捷地进行安装与更新。它利用 » Packagist 中的 PHP 扩展仓库来查找扩展的源代码以进行构建，或在存在时下载 Windows 二进制文件。若下载的是源代码，该工具还能自动完成构建和安装过程。

在 » 安装所需依赖和 PIE 本身之后，可通过命令行运行以下命令安装 MongoDB 扩展。

示例 #1 使用 PIE 安装 MongoDB 扩展

    pie install mongodb/mongodb-extension

» “PIE 使用方法”文档对此有更详细的说明。

# 运行时配置

## 目录

- 配置文件
- .user.ini 文件
- 配置可被设定范围
- 怎样修改配置设定

## 配置文件

配置文件（php.ini）在 PHP 启动时被读取。对于服务器模块版本的 PHP，仅在 web 服务器启动时读取一次。对于 CGI 和 CLI 版本，每次调用都会读取。

php.ini 的搜索路径如下（按顺序）：

- SAPI 模块所指定的位置（Apache 2 中的 `PHPIniDir` 指令，CGI 和 CLI 中的 `-c` 命令行选项）。
- PHPRC 环境变量。
- 可以为不同版本的 PHP 指定不同的 `php.ini` 文件位置。注册表目录所在的位置取决于你的系统是 32 位还是 64 位。32-bit 的 PHP 运行在 32-bit 的系统或 64-bit 的 PHP 运行在 64-bit 系统时使用 `[(HKEY_LOCAL_MACHINE\SOFTWARE\PHP]` 32-bit 的 PHP 运行在 64-bit 的系统上时，则使用 `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]`] 替代。 系统版本跟 PHP 版本架构一致时，会按以下顺序依次进行检查： `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z]`， `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y]` 和 `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x]`，其中的 x，y 和 z 指的是 PHP 主版本号，次版本号和发行批次。 对于 32 bit 版本的 PHP 运行在 64 bit 系统上的情况，则会按以下顺序依次进行检查： `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y.z]`， `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y]` 和 `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x]`，其中的 x，y 和 z 指的是 PHP 主版本号，次版本号和发行批次。如果在其中任何目录下的 `IniFilePath` 有键值，则第一个值将被用作 `php.ini` 的位置（仅适用于 Windows）。
- `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]` 内 `IniFilePath` 的值（Windows 注册表位置）。
- 当前工作目录（对于 CLI）。
- web 服务器目录（对于 SAPI 模块）或 PHP 所在目录（Windows 下其它情况）。
- Windows 目录（C:\windows 或 C:\winnt），或 `--with-config-file-path` 编译时选项指定的位置。

如果存在 php-SAPI.ini（SAPI 是当前所用的 SAPI 名称，因此实际文件名为 php-cli.ini 或 php-apache.ini 等），则会用它替代 php.ini。SAPI 的名称可以用 php_sapi_name() 来测定。

> 注意:

> Apache web 服务器在启动时会把目录转到根目录，这将导致 PHP 尝试在根目录下读取 php.ini，如果存在的话。

可以在如下所示的 php.ini 配置值中引用环境变量。自 PHP 8.3.0 起，可以指定一个后备值，当引用的变量未定义时使用该值。

示例 #1 php.ini 中的环境变量

    ; PHP_MEMORY_LIMIT 来自于环境变量的值
    memory_limit = ${PHP_MEMORY_LIMIT}
    ; 如果 PHP_MAX_EXECUTION_TIME 未定义，将回退到 30
    max_execution_time = ${PHP_MAX_EXECUTION_TIME:-30}

由扩展库处理的 php.ini 指令，其文档分别在各扩展库的页面。内核配置选项见附录。不过也许不是所有的 PHP 指令都在手册中有文档说明。要得到自己的 PHP 版本中的配置指令完整列表，请阅读 php.ini 文件，其中都有注释。此外，也许从 Git 得到的» 最新版 php.ini 也有帮助。

示例 #2 php.ini 示例

    ; any text on a line after an unquoted semicolon (;) is ignored
    [php] ; section markers (text within square brackets) are also ignored
    ; Boolean values can be set to either:
    ;    true, on, yes
    ; or false, off, no, none
    register_globals = off
    track_errors = yes

    ; you can enclose strings in double-quotes
    include_path = ".:/usr/local/lib/php"

    ; backslashes are treated the same as any other character
    include_path = ".;c:\php\lib"

在 .ini 文件内可能会引用已存在的 .ini 变量。例如：`open_basedir = ${open_basedir} ":/new/dir"`。

### 扫描路径配置

可以通过配置，让 PHP 在读完 php.ini 后，扫描指定路径中的附加 .ini 配置文件。编译时通过 --with-config-file-scan-dir 参数来指定要扫描的目录。扫描路径也可以通过环境变量 PHP_INI_SCAN_DIR 来设置。

通过在扫描路径配置中加入特定系统的目录分隔符（Windows、NetWare 和 RISC OS 下是 `;`；其它操作系统下是 `:`；该值可以通过 PHP 常量 `PATH_SEPARATOR` 获取），还可以设置多个扫描路径。如果 PHP_INI_SCAN_DIR 为空，PHP 一样会扫描在编译时指定的 --with-config-file-scan-dir 此路径。

对于每个目录而言，PHP 会以首字符顺序为优先级，扫描该目录下所有的 `.ini` 结尾的配置文件。所有被截入的配置文件，可以通过 php_ini_scanned_files() 函数来获取列表，也可以通过 PHP 命令行加入 --ini 参数来查看。

    以下假设 PHP 配置为 --with-config-file-scan-dir=/etc/php.d
    并且目录分隔符为 :

    $ php
      PHP 会加载 /etc/php.d/*.ini 全部配置文件。

    $ PHP_INI_SCAN_DIR=/usr/local/etc/php.d php
      PHP 会加载 /usr/local/etc/php.d/*.ini 全部配置文件。

    $ PHP_INI_SCAN_DIR=:/usr/local/etc/php.d php
      PHP 会加载 /etc/php.d/*.ini 下的全部配置文件，然后加载
      /usr/local/etc/php.d/*.ini 下的全部配置文件。

    $ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php
      PHP 会加载 /usr/local/etc/php.d/*.ini 下的全部配置文件，然后加载
      /etc/php.d/*.ini 下的全部配置文件。

## .user.ini 文件

PHP 支持基于每个目录的 INI 文件配置。此类文件 仅被 CGI／FastCGI SAPI 处理。此功能使得 PECL 的 htscanner 扩展作废。如果你的 PHP 以模块化运行在 Apache 里，则用 .htaccess 文件有同样效果。

除了主 php.ini 之外，PHP 还会在每个目录下扫描 INI 文件，从被执行的 PHP 文件所在目录开始一直上升到 web 根目录（$_SERVER['DOCUMENT_ROOT'] 所指定的）。如果被执行的 PHP 文件在 web 根目录之外，则只扫描该目录。

在 .user.ini 风格的 INI 文件中只有具有 `INI_PERDIR` 和 `INI_USER` 模式的 INI 设置可被识别。

两个新的 INI 指令， user_ini.filename 和 user_ini.cache_ttl 控制着用户 INI 文件的使用。

user_ini.filename 设定了 PHP 会在每个目录下搜寻的文件名；如果设定为空字符串则 PHP 不会搜寻。默认值是 `.user.ini`。

user_ini.cache_ttl 控制着重新读取用户 INI 文件的间隔时间。默认是 300 秒（5 分钟）。

## 配置可被设定范围

这些模式决定着一个 PHP 的指令在何时何地，是否能够被设定。手册中的每个指令都有其所属的模式。例如有些指令可以在 PHP 脚本中用 ini_set() 来设定，而有些则只能在 php.ini 或 httpd.conf 中。

例如 output_buffering 指令是属于 `INI_PERDIR`，因而就不能用 ini_set() 来设定。但是 display_errors 指令是属于 `INI_ALL` 因而就可以在任何地方被设定，包括 ini_set()。

INI 模式常量
`INI_USER` (int)
  可以在用户脚本（如使用 ini_set()）或 Windows 注册表中设置条目。可以在 .user.ini 中设置条目
`INI_PERDIR` (int)
  可以在 php.ini、.htaccess、httpd.conf 或 .user.ini 中设置条目
`INI_SYSTEM` (int)
  可以在 php.ini 或 httpd.conf 中设置条目
`INI_ALL` (int)
  条目可以设置在任何地方

## 怎样修改配置设定

### PHP 运行于 Apache 模块方式

当使用 PHP 作为 Apache 模块时，也可以用 Apache 的配置文件（例如 httpd.conf）和 .htaccess 文件中的指令来修改 PHP 的配置设定。需要有“AllowOverride Options”或“AllowOverride All”权限才可以。

有几个 Apache 指令可以使用户在 Apache 配置文件内部修改 PHP 的配置。哪些指令属于 `INI_ALL`、`INI_PERDIR` 或 `INI_SYSTEM` 中的哪一个，请参考附录中的 php.ini 配置选项列表。

`php_value` `name` `value`

  设定指定的值。只能用于 `INI_ALL` 或 `INI_PERDIR` 类型的指令。要清除先前设定的值，把 value 设为 `none`。

  > 注意: 不要用 `php_value` 设定布尔值。应该用 `php_flag`（见下面）。

`php_flag` `name` `on|off`

  用来设定布尔值的配置指令。仅能用于 `INI_ALL` 和 `INI_PERDIR` 类型的指令。

`php_admin_value` `name` `value`

  设定指定的指令的值。不能用于 .htaccess 文件。任何用 `php_admin_value` 设定的指令都不能被 .htaccess 或 ini_set() 覆盖。要清除先前设定的值，把 value 设为 `none`。

`php_admin_flag` `name` `on|off`

  用来设定布尔值的配置指令。不能用于 .htaccess 文件。任何用 `php_admin_flag` 设定的指令都不能被 .htaccess 或 ini_set() 覆盖。

示例 #1 Apache 配置例子

    <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>

警告

PHP 常量不存在于 PHP 之外。例如在 httpd.conf 中不能使用 PHP 常量如 `E_ALL` 或 `E_NOTICE` 来设定 error_reporting 指令，因为其无意义，实际等于 0。应该用相应的掩码值来替代。这些常量可以在 php.ini 中使用。

### 通过 Windows 注册表修改 PHP 配置

在 Windows 下运行 PHP 时，可以用 Windows 注册表以目录为单位来修改配置。配置值存放于注册表项 `HKLM\SOFTWARE\PHP\Per Directory Values` 下面，子项对应于路径名。例如对于目录 `c:\inetpub\wwwroot` 的配置值会存放于 `HKLM\SOFTWARE\PHP\Per Directory Values\c\inetpub\wwwroot` 项下面。其中的设定对于任何位于此目录及其任何子目录的脚本都有效。项中的值的名称是 PHP 配置指令的名字，值的数据是字符串格式的指令值。值中的 PHP 常量不被解析。不过只有可修改范围是 `INI_USER` 的配置值可以用此方法设定，`INI_PERDIR` 的值就不行。因为这些配置对于每次请求来说是只读的。

### 其它接口下的 PHP

无论怎样运行 PHP，都可以在脚本中通过 ini_set() 而在运行时修改某个值。更多信息见手册中 ini_set() 的页面。

如果对自己系统中的配置设定及其当前值的完整列表感兴趣，可以运行 phpinfo() 函数并查看其结果的页面。也可以在运行时用 ini_get() 或 get_cfg_var() 取得个别配置指令的值。

- 安装前需要考虑的事项
- 在 Unix 系统上安装 PHP
  - Debian GNU/Linux 及其相关发行版上从软件包中安装 PHP
  - 在使用 DNF 的 GNU/Linux 发行版上通过软件包安装
  - OpenBSD 上从软件包或者 ports 中安装 PHP
  - 在 Unix 和 macOS 系统上以源码安装
  - CGI 和命令行设置
  - Unix 系统下的 Apache 2.x
  - Unix 系统下的 Nginx 1.4.x
  - Unix 平台的 Lighttpd 1.4
  - Unix 系统下的 LiteSpeed、OpenLiteSpeed Web 服务器
  - 针对 Solaris 的安装提示
- macOS 系统下的安装
  - 在 MacOS 上使用第三方包安装
  - 在 macOS 下编译 PHP
  - 使用 macOS Monterey 之前内置的 PHP
- Windows 系统下的安装
  - Windows 系统下的推荐配置
  - 手动安装预编译的二进制文件
  - 在Windows系统上安装 Apache 2.x
  - Windows 上与 IIS 安装
  - 用于安装 PHP 的第三方工具
  - 从源程序编译
  - 在 Windows 系统的命令行上运行 PHP
- 云计算平台上的安装
  - Azure 应用服务
  - Amazon EC2
  - DigitalOcean
- FastCGI 进程管理器（FPM）
  - 安装
  - 配置
- PECL 扩展安装
  - PECL 安装介绍
  - 下载 PECL 扩展库
  - 在 Windows 上安装 PHP 扩展
  - 用 PEAR 编译共享 PECL 扩展库
  - 用 phpize 编译共享 PECL 扩展库
  - php-config
  - 将 PECL 扩展库静态编译入 PHP
- Composer 简介
- PIE 简介
- 运行时配置
  - 配置文件
  - .user.ini 文件
  - 配置可被设定范围
  - 怎样修改配置设定

# 语言参考

# 基本语法

## 目录

- PHP 标签
- 从 HTML 中分离
- 指令分隔符
- 注释

## PHP 标签

当 PHP 处理文件时，通过识别起始和结束标签 `<?php` 和 `?>` 来定义 PHP 代码执行的边界。PHP 解析器会忽略这些标签之外的内容，从而使 PHP 能够无缝嵌入到各种文档类型中。

必须在 `<?php` 后跟随一个空白字符（空格、制表符或换行符），以确保正确的 token 分隔。省略此空白字符将导致语法错误。

PHP 还包含短输出标签 `<?=`，这是 `<?php echo` 的简写形式。

示例 #1 PHP 开始和结束标签

    1.  <?php echo 'if you want to serve PHP code in XHTML or XML documents,
                    use these tags'; ?>

    2.  You can use the short echo tag to <?= 'print this string' ?>.
        It's equivalent to <?php echo 'print this string' ?>.

    3.  <? echo 'this code is within short tags, but will only work '.
                'if short_open_tag is enabled'; ?>

短标签 (第三个示例) 是被默认开启的，但是也可以通过 short_open_tag php.ini 来直接禁用。如果 PHP 在被安装时使用了 --disable-short-tags 的配置，该功能则是被默认禁用的。

> 注意:

> 因为短标签可以被禁用，所以建议使用普通标签 (`<?php ?>` 和 `<?= ?>`) 来最大化兼容性。

如果文件以 PHP 代码结尾，最好在文件末尾删除 PHP 结束标签。这可以避免在 PHP 结束标签之后意外添加空白字符或者换行符，导致 PHP 开始输出缓冲，进而引发不必要的影响，而脚本中此时并无输出的意图。

示例 #2 仅包含 PHP 代码的文件

    <?php
    echo "Hello world\n";

    // ... 更多代码

    echo "Last statement\n";

    // 脚本在此结束，未使用 PHP 结束标签

## 从 HTML 中分离

PHP 解析器会忽略一对开始和结束标签之外的内容，这使得 PHP 文件可以具备混合内容。可以使 PHP 嵌入到 HTML 文档中去，例如创建模板。

示例 #1 HTML 中嵌入 PHP

    <p>This is going to be ignored by PHP and displayed by the browser.</p>
    <?php echo 'While this is going to be parsed.'; ?>
    <p>This will also be ignored by PHP and displayed by the browser.</p>

这将如预期中的运行，因为当 PHP 解释器碰到 ?> 结束标签时就简单地将其后内容原样输出（除非马上紧接换行 - 见 指令分隔符）直到碰到下一个开始标签；例外是处于条件语句中间时，此时 PHP 解释器会根据条件判断来决定哪些输出，哪些跳过。见下例。

使用条件结构：

示例 #2 使用条件的高级分离术

    <?php if ($expression == true): ?>
      This will show if the expression is true.
    <?php else: ?>
      Otherwise this will show.
    <?php endif; ?>

上例中 PHP 将跳过条件语句未达成的段落，即使该段落位于 PHP 开始和结束标签之外。由于 PHP 解释器会在条件未达成时直接跳过该段条件语句块，因此 PHP 会根据条件来忽略之。

要输出大段文本时，跳出 PHP 解析模式通常比将文本通过 echo 或 print 输出更有效率。

> 注意:

> 如果 PHP 嵌入到 XML 或 XHTML 中，必须使用标准的 PHP `<?php ?>` 标签以保持与标准的兼容性。

## 指令分隔符

同 C 或 Perl 一样，PHP 需要在每个语句后用分号结束指令。一段 PHP 代码中的结束标签隐含表示了一个分号；在一个 PHP 代码段中的最后一行可以不用分号结束。如果后面还有新行，则代码段的结束标签包含了行结束。

示例 #1 包含末尾换行符的结束标签的示例

    <?php echo "Some text"; ?>
    No newline
    <?= "But newline now" ?>

以上示例会输出：

    Some textNo newline
    But newline now

示例 #2 进入和退出 PHP 解析的示例

    <?php
        echo "This is a test\n";
    ?>

    <?php echo "This is a test\n" ?>

    <?php echo "We omitted the last closing tag\n";

> 注意:

> 文件末尾的 PHP 代码段结束标签可以不要，有些情况下当使用 include 或者 require 时省略掉会更好些，这样不期望的空白字符就不会出现在文件末尾，之后仍然可以输出响应 header。在使用输出缓冲时也很便利，就不会看到由包含文件生成的不期望的空白符。

## 注释

PHP 支持 C，C++ 和 Unix Shell 风格（Perl 风格）的注释。例如:

示例 #1 注释

    <?php
        echo "This is a test\n"; // 这是单行 c++ 样式注释
        /* 这是一条多行注释
           另一行也是注释 */
        echo "This is yet another test\n";
        echo "One Final Test\n"; # 这是单行 shell 风格的注释
    ?>

单行注释仅仅注释到行末或者当前的 PHP 代码块，视乎哪个首先出现。这意味着在 `// ... ?>` 或者 `# ... ?>` 之后的 HTML 代码将被显示出来：?> 跳出了 PHP 模式并返回了 HTML 模式，`//` 或 `#` 并不能影响到这一点。

示例 #2 单行注释

    <h1>This is an <?php # echo 'simple';?> example</h1>
    <p>The header above will say 'This is an  example'.</p>

C 风格的注释在碰到第一个 `*/` 时结束。要确保不要嵌套 C 风格的注释。试图注释掉一大块代码时很容易出现该错误。

    <?php
     /*
        echo 'This is a test'; /* 这个注释会引发问题 */
     */
    ?>

# 类型

## 目录

- 简介
- 类型系统
- NULL
- Boolean 布尔类型
- Integer 整型
- Float 浮点型
- String 字符串
- 数字字符串
- Array 数组
- Object 对象
- Enum 枚举
- Resource 资源类型
- Callable
- Mixed
- Void
- Never
- 相对类类型
- 单例类型
- Iterable 可迭代对象
- 类型声明
- 类型转换

## 简介

PHP 中的每个表达式都属于以下某个内置类型，具体取决于值：

- null
- bool
- int
- float（浮点数）
- string
- array
- object
- callable
- resource

PHP 是动态类型语言，这意味着默认不需要指定变量的类型，因为会在运行时确定。然而，可以通过使用类型声明对语言的一些方面进行类型静态化。可以在类型系统页面找到 PHP 类型系统支持的不同类型。

类型限制了可以对其执行的操作。然而，如果使用的表达式/变量不支持该操作，PHP 将尝试将该值类型转换为操作支持的类型。此过程取决于使用该值的上下文。更多信息参阅类型转换。

小技巧

类型比较表也很有用，因为存在不同类型之间的值的各种比较示例。

> 注意: 使用类型转换，强制将表达式的值转换为某种类型。还可以使用 settype() 函数就地对变量进行类型转换。

使用 var_dump() 函数检查表达式的值和类型。使用 get_debug_type() 检索表达式的值和类型。使用 `is_type` 检查表达式是否属于某种类型。

示例 #1 不同类型

    <?php
    $a_bool = true;   // a bool
    $a_str  = "foo";  // a string
    $a_str2 = 'foo';  // a string
    $an_int = 12;     // an int
    echo get_debug_type($a_bool), "\n";
    echo get_debug_type($a_str), "\n";

    // 如果是整型，就加上 4
    if (is_int($an_int)) {
        $an_int += 4;
    }
    var_dump($an_int);

    // 如果 $a_bool 是字符串，就打印出来
    if (is_string($a_bool)) {
        echo "String: $a_bool";
    }
    ?>

以上示例在 PHP 8 中的输出：

    bool
    string
    int(16)

> 注意: PHP 8.0.0 之前，get_debug_type() 无效，可以使用 gettype() 函数代替。但是没有使用规范的类型名称。

## 类型系统

PHP 采用名义类型系统，并具有强行为的子类型关系。子类型关系在编译时检查，而类型验证则在运行时动态进行。

PHP 的类型系统支持各种原子类型，可以组合在一起创建更加复杂的类型。其中一些类型可以写成类型声明。

### 原子类型

一些原子类型是内置类型，跟语言紧密集成，不能用用户定义类型重现（reproduced）。

基础类型列表是：

- 内置类型
  - 标量类型：
    - bool 类型
    - int 类型
    - float 类型
    - string 类型
  - array 类型
  - object 类型
  - resource 类型
  - never 类型
  - void 类型
  - 相对类类型：self、parent 和 static
  - 单例类型
    - false
    - true
  - 单值类型
    - null
- 用户定义的类型（通常称为类类型）
  - 接口
  - 类
  - 枚举
- callable 类型

#### 标量类型

如果值是 int、float、string 或 bool 类型，则视该值为标量。

#### 用户定义类型

可以使用 interface、类和枚举定义自定义类型。这些被视为用户定义类型或类类型。例如，可以定义名为 `Elephant` 的类，然后可以实例化 `Elephant` 类型的对象，并且函数可以请求 `Elephant` 类型的参数。

### 复合类型

可以将多个原子类型组合为复合类型。PHP 允许使用以下方式组合类型：

- 类类型（接口和类名）的交集。
- 类型联合。

#### 交集类型

交集类型接受满足多个类类型声明的值，而不是单个值。交集类型中的每个类型由 `&` 符号连接。因此，类型 `T`、`U` 和 `V` 组成的交集类型将写成 `T&U&V`。

#### 联合类型

联合类型接受多个不同类型的值，而不是单个类型。联合类型中的每个类型由 `|` 符号连接。因此类型 `T`、`U` 和 `V` 的联合类型写成 `T|U|V`。如果其中一种类型是交集类型，需要使用括号括起来，在 DNF 中写成：`T|(X&Y)`。

### 类型别名

PHP 支持两种类型别名 mixed 和 iterable，分别对应 `object|resource|array|string|float|int|bool|null` 和 `Traversable|array` 的联合类型。

> 注意: PHP 不支持用户定义类型别名。

## NULL

null 类型是 PHP 的原子类型（unit type），也就是说，它仅有一个值 `null`。

未定义和 unset() 的变量都将解析为值 `null`。

### 语法

`null` 类型只有一个值，就是不区分大小写的常量 `null`。

    <?php
    $var = NULL;
    ?>

### 转换到 `null`

警告

本特性自 PHP 7.2.0 起废弃，并且自 PHP 8.0.0 起被移除。 强烈建议不要使用本特性。

使用 `(unset) $var` 将一个变量转换为 null 将不会删除该变量或 unset 其值。仅是返回 `null` 值而已。

### 参见

- is_null()
- unset()

## Boolean 布尔类型

bool 仅有两个值，用于表达真（truth）值，不是 `true` 就是 `false`。

### 语法

要指定一个 bool，使用常量 `true` 或 `false`。两个都不区分大小写。

    <?php
    $foo = True; // 设置 $foo 为 TRUE
    ?>

通常运算符所返回的 bool 值结果会被传递给控制流程。

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

    // == 是一个操作符，它检测两个变量是否相等，并返回一个布尔值
    if ($action == "show_version") {
        echo "The version is 1.23";
    }

    // 这样做是不必要的...
    if ($show_separators == TRUE) {
        echo "<hr>\n";
    }

    // ...因为可以使用下面这种简单的方式：
    if ($show_separators) {
        echo "<hr>\n";
    }
    ?>

### 转换为布尔值

要明确地将值转换成 bool，可以用 `(bool)` 强制转换。通常这不是必需的，因为值在逻辑上下文中使用将会自动解释为 bool 类型的值。更多信息请阅读类型转换页面。

参见类型转换的判别。

当转换为 bool 时，以下值被认为是 `false`：

- 布尔值 `false` 本身
- 整型值 `0`（零）
- 浮点型值 `0.0`（零）`-0.0`（零）
- 空字符串 `""`，以及字符串 `"0"`
- 不包括任何元素的数组
- 原子类型 NULL（包括尚未赋值的变量）
- 内部对象的强制转换行为重载为 bool。例如：由不带属性的空元素创建的 SimpleXML 对象。

所有其它值都被认为是 `true`（包括 资源 和 `NAN`）。

警告

`-1` 和其它非零值（不论正负）一样，被认为是 `true`！

示例 #1 转换为布尔型

    <?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)
    ?>

## Integer 整型

int 是集合 ℤ = {..., -2, -1, 0, 1, 2, ...} 中的某个数。

### 参见

- 浮点数
- 任意精度/BCMath
- 任意长度整数/GMP

### 语法

Int 可以使用十进制，十六进制，八进制或二进制表示，前面可以加上可选的符号（- 或者 +）。 可以用负运算符 来表示一个负的 int。

要使用八进制表达，数字前必须加上 `0`（零）。 PHP 8.1.0 起，八进制表达也可以在前面加上 `0o` 或者 `0O` 。 要使用十六进制表达，数字前必须加上 `0x`。要使用二进制表达，数字前必须加上 `0b`。

从 PHP 7.4.0 开始，整型数值可能会包含下划线 (`_`)，为了更好的阅读体验，这些下划线在展示的时候，会被 PHP 过滤掉。

示例 #1 整数文字表达

    <?php
    $a = 1234; // 十进制数
    $a = 0123; // 八进制数 (等于十进制 83)
    $a = 0o123; // 八进制数 (PHP 8.1.0 起)
    $a = 0x1A; // 十六进制数 (等于十进制 26)
    $a = 0b11111111; // 二进制数字 (等于十进制 255)
    $a = 1_234_567; // 整型数值 (PHP 7.4.0 以后)
    ?>

int literal 的结构形式从 PHP 8.1.0 开始是（之前不允许使用 `0o` 或 `0O` 八进制前缀，并且 PHP 7.4.0 之前不允许使用下划线）：

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

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

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

    binary      : 0[bB][01]+(_[01]+)*

    integer     : decimal
                | hexadecimal
                | octal
                | binary

整型数 int 的字长和平台有关，尽管通常最大值是大约二十亿（32 位有符号）。64 位平台下的最大值通常是大约 9E18。 PHP 不支持无符号的 int。int 值的字长可以用常量 `PHP_INT_SIZE`来表示， 最大值可以用常量 `PHP_INT_MAX` 来表示， 最小值可以用常量 `PHP_INT_MIN` 表示。

### 整数溢出

如果给定的一个数超出了 int 的范围，将会被解释为 float。同样如果执行的运算结果超出了 int 范围，也会返回 float。

示例 #2 整数溢出

    <?php
    $large_number = 50000000000000000000;
    var_dump($large_number);         // float(5.0E+19)
    var_dump(PHP_INT_MAX + 1);       // 32 位系统：float(2147483648)
                                     // 64 位系统：float(9.2233720368548E+18)
    ?>

### 整数除法

PHP 没有 int 除法取整运算符，要使用 intdiv() 实现。 `1/2` 产生出 float `0.5`。 值可以舍弃小数部分，强制转换为 int，或者使用 round() 函数可以更好地进行四舍五入。

示例 #3 Divisions

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

### 转换为整型

要明确地将一个值转换为 int，用 `(int)` 强制转换。 不过大多数情况下都不需要强制转换，因为当运算符，函数或流程控制需要一个 int 参数时，值会自动转换。还可以通过函数 intval() 来将一个值转换成 int 整型。

将 resource 转换成 int 时， 结果会是 PHP 运行时为 resource 分配的唯一资源号。

参见：类型转换的判别。

#### 从布尔值转换

`false` 将产生出 `0`（零），`true` 将产生出 `1`（壹）。

#### 从浮点型转换

当从浮点数 float 转换成整数 int时，将向零取整。自 PHP 8.1.0 起，当将非整数类型的 float 转换为失去精度的 int 时，会发出弃用通知。

示例 #4 从浮点数转换

    <?php

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

    var_dump(foo(8.1)); // 自 PHP 8.1.0 起：“Deprecated: Implicit conversion from float 8.1 to int loses precision”
    var_dump(foo(8.1)); // PHP 8.1.0 之前为 8
    var_dump(foo(8.0)); // 均为 8

    var_dump((int) 8.1); // 均为 8
    var_dump(intval(8.1)); // 均为 8
    ?>

如果浮点数超出了 int 范围（32 位平台下通常为 `+/- 2.15e+9 = 2^31`，64 位平台下，通常为 `+/- 9.22e+18 = 2^63`），则结果为未定义， 因为没有足够的精度给出一个确切的 int 结果。 在此情况下没有警告，甚至没有任何通知！

> 注意:

> `NaN`、`Inf` 和 `-Inf` 在转换成 int 时是零。

警告

绝不要将未知的分数强制转换为 int，这样有时会导致不可预料的结果。

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

参见关于浮点数精度的警告。

#### 从字符串转换

如果 string 是 numeric 或者前导数字， 则将它解析为相应的 int 值，否则将转换为零（`0`）。

#### 从 NULL 转换

`null` 会转换为零（`0`）。

#### 从其它类型转换

警告

没有定义从其它类型转换为 int 的行为。 不要依赖任何现有的行为，因为它会未加通知地改变。

## Float 浮点型

浮点型（也叫浮点数 float，双精度数 double 或实数 real）可以用以下任一语法定义：

    <?php
    $a = 1.234;
    $b = 1.2e3;
    $c = 7E-10;
    $d = 1_234.567; // 从 PHP 7.4.0 开始支持
    ?>

浮点数的形式表示（PHP 7.4.0 之前不支持下划线）：

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

浮点数的字长和平台相关，尽管通常最大值是 1.8e308 并具有 14 位十进制数字的精度（64 位 IEEE 格式）。

警告

# 浮点数的精度

浮点数的精度有限。尽管取决于系统，PHP 通常使用 IEEE 754 双精度格式，则由于取整而导致的最大相对误差为 1.11e-16。非基本数学运算可能会给出更大误差，并且要考虑到进行复合运算时的误差传递。

此外，以十进制能够精确表示的有理数如 `0.1` 或 `0.7`，无论有多少尾数都不能被内部所使用的二进制精确表示，因此不能在不丢失一点点精度的情况下转换为二进制的格式。这就会造成混乱的结果：例如，`floor((0.1+0.7)*10)` 通常会返回 `7` 而不是预期中的 `8`，因为该结果内部的表示其实是类似 `7.9999999999999991118...`。

所以永远不要相信浮点数结果精确到了最后一位，也永远不要比较两个浮点数是否相等。如果确实需要更高的精度，应该使用任意精度数学函数或者 gmp 函数。

参见» 浮点数指南网页的简单解释。

### 转换为浮点数

#### 从 string 转换

如果 string 是 numeric 或者前导数字， 则将它解析为相应的 float 值，否则将转换为零（`0`）。

#### 从其他类型转换

对于其它类型的值，其情况类似于先将值转换成 int，然后再转换成 float。 请参阅“转换为整型”一节以获取更多信息。

> 注意:

> 某些类型在转换成 int 时有未定义行为，转换为 float 时也会如此。

### 比较浮点数

如上述警告信息所言，由于内部表达方式的原因，比较两个浮点数是否相等是有问题的。不过还是有迂回的方法来比较浮点数值的。

要测试浮点数是否相等，要使用一个仅比该数值大一丁点的最小误差值。该值也被称为机器极小值（epsilon）或最小单元取整数，是计算中所能接受的最小的差别值。

$a 和 $b 在小数点后五位精度内都是相等的。

示例 #1 浮点比较

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

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

### NaN

某些数学运算会产生一个由常量 `NAN` 所代表的结果。此结果代表着一个在浮点数运算中未定义或不可表述的值。任何拿此值与其它任何值（除了 `true`）进行的松散或严格比较的结果都是 `false`。

由于 `NAN` 代表着任何不同值，不应拿 `NAN` 去和其它值进行比较，包括其自身，应该用 is_nan() 来检查。

## String 字符串

一个字符串 string 就是由一系列的字符组成，其中每个字符等同于一个字节。这意味着 PHP 只能支持 256 的字符集，因此不支持 Unicode 。详见字符串类型详解。

> 注意: 在 32 位版本中，string 最大可以达到 2GB（最多 2147483647 字节）。

### 语法

一个字符串可以用 4 种方式表达：

- 单引号
- 双引号
- heredoc 语法结构
- nowdoc 语法结构

#### 单引号

定义一个字符串的最简单的方法是用单引号把它包围起来（字符 `'`）。

要表达一个单引号自身，需在它的前面加个反斜线（`\`）来转义。要表达一个反斜线自身，则用两个反斜线（`\\`）。其它任何方式的反斜线都会被当成反斜线本身：也就是说如果想使用其它转义序列例如 `\r` 或者 `\n`，并不代表任何特殊含义，就单纯是这两个字符本身。

> 注意: 不像双引号和 heredoc 语法结构，在单引号字符串中的变量和特殊字符的转义序列将不会被替换。

示例 #1 Syntax Variants

    <?php
    echo 'this is a simple string', PHP_EOL;

    // 可以录入多行
    echo 'You can also have embedded newlines in
    strings this way as it is
    okay to do', PHP_EOL;

    // 输出：Arnold once said: "I'll be back"
    echo 'Arnold once said: "I\'ll be back"', PHP_EOL;

    // 输出：You deleted C:\*.*?
    echo 'You deleted C:\\*.*?', PHP_EOL;

    // 输出：You deleted C:\*.*?
    echo 'You deleted C:\*.*?', PHP_EOL;

    // 输出：This will not expand: \n a newline
    echo 'This will not expand: \n a newline', PHP_EOL;

    // 输出：Variables do not $expand $either
    echo 'Variables do not $expand $either', PHP_EOL;
    ?>

#### 双引号

如果字符串是包围在双引号（`"`)）中， PHP 将对以下特殊的字符进行解析：

转义字符
序列 | 含义
--- | ---
`\n` | 换行（ASCII 字符集中的 LF 或 0x0A (10)）
`\r` | 回车（ASCII 字符集中的 CR 或 0x0D (13)）
`\t` | 水平制表符（ASCII 字符集中的 HT 或 0x09 (9)）
`\v` | 垂直制表符（ASCII 字符集中的 VT 或 0x0B (11)）
`\e` | Escape（ASCII 字符集中的 ESC 或 0x1B (27)）
`\f` | 换页（ASCII 字符集中的 FF 或 0x0C (12)）
`\\` | 反斜线
`\$` | 美元标记
`\"` | 双引号
`\[0-7]{1,3}` | 八进制：匹配正则表达式序列 `[0-7]{1,3}` 的是八进制表示法的字符序列（比如 `"\101" === "A"`），会静默溢出以适应一个字节（例如 `"\400" === "\000"`）
`\x[0-9A-Fa-f]{1,2}` | 十六进制：匹配正则表达式序列 `[0-9A-Fa-f]{1,2}` 的是十六进制表示法的一个字符（比如 `"\x41" === "A"`）
`\u{[0-9A-Fa-f]+}` | Unicode：匹配正则表达式 `[0-9A-Fa-f]+` 的字符序列是 unicode 码位，该码位能作为 UTF-8 的表达方式输出字符串。序列中必须包含大括号。例如 `"\u{41}" === "A"`

和单引号字符串一样，转义任何其它字符都会导致反斜线被显示出来。

用双引号定义的字符串最重要的特征是变量会被解析，详见变量插值。

#### Heredoc 结构

第三种表达字符串的方法是用 heredoc 句法结构：`<<<`。在该运算符之后要提供一个标识符，然后换行。接下来是字符串 string 本身，最后要用前面定义的标识符作为结束标志。

结束标识符可以使用空格或制表符（tab）缩进，此时文档字符串会删除所有缩进。 在 PHP 7.3.0 之前的版本中，结束时所引用的标识符必须在该行的第一列。

而且，标识符的命名也要像其它标签一样遵守 PHP 的规则：只能包含字母、数字和下划线，并且必须以字母和下划线作为开头。

示例 #2 PHP 7.3.0 之后的基础 Heredoc 示例

    <?php
    // 无缩进
    echo <<<END
          a
         b
        c
    \n
    END;
    // 4 空格缩进
    echo <<<END
          a
         b
        c
        END;

以上示例在 PHP 7.3 中的输出：

          a
         b
        c
      a
     b
    c

如果结束标识符的缩进超过内容的任何一行的缩进，则将抛出 ParseError 异常：

示例 #3 结束标识符的缩进不能超过正文的任何一行

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

以上示例在 PHP 7.3 中的输出：

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

制表符也可以缩进结束标识符，但是，关于缩进结束标识符和内容， 制表符和空格不能混合使用。在以上任何情况下， 将会抛出 ParseError 异常。 之所以包含这些空白限制，是因为混合制表符和空格来缩进不利于易读性。

示例 #4 内容（空白）和结束标识符的不同缩进

    <?php
    // 以下所有代码都不起作用。
    // 正文（空格）和结束标记（制表符），不同的缩进
    {
        echo <<<END
         a
            END;
    }
    // 在正文中混合空格和制表符
    {
        echo <<<END
            a
         END;
    }
    // 在结束标记中混合空格和制表符
    {
        echo <<<END
              a
             END;
    }

以上示例在 PHP 7.3 中的输出：

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

内容字符串的结束标识符后面不需要跟分号或者换行符。 例如，从 PHP 7.3.0 开始允许以下代码：

示例 #5 在结束标识符后继续表达式

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

以上示例在 PHP 7.3 中的输出：

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

警告

如果在某一行的开头找到了结束标识符，那么不管它是否是另外一个单词的一部分， 它都可能看作结束标识符并引起 ParseError。

示例 #6 字符串内容中的结束标识符往往会导致 ParseError

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

以上示例在 PHP 7.3 中的输出：

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

为了避免这个问题，遵循以下简单的规则较为安全： 不要选择一个出现在文本主体中的单词作为结束标识符。

警告

在 PHP 7.3.0 之前，请务必注意，带有结束标识符的行不能包含除 (`;`)外的任何其他字符。 这意味着标识符不能缩进，分号的前后也不能有任何空白或制表符。更重要的是结束标识符的前面必须是个被本地操作系统认可的换行，比如在 UNIX 和 macOS 系统中是 `\n`，而结束定界符之后也必须紧跟一个换行。

如果不遵守该规则导致结束标识不“干净”，PHP 将认为它不是结束标识符而继续寻找。如果在文件结束前也没有找到一个正确的结束标识符，PHP 将会在最后一行产生一个解析错误。

示例 #7 PHP 7.3.0 之前的错误示例

    <?php
    class foo {
        public $bar = <<<EOT
    bar
        EOT;
    }
    // 不能缩进标识符
    ?>

示例 #8 在 PHP 7.3.0 之前有效示例

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

Heredocs 结构不能用来初始化类的属性。

Heredoc 结构就象是没有双引号的 string，这就是说在 heredoc 结构中单引号不用被转义，但是上文中列出的转义序列还可以使用。变量将被替换，但在 heredoc 结构中含有复杂的变量时要像 string 一样格外小心。

示例 #9 Heredoc 结构的字符串示例

    <?php
    $str = <<<EOD
    Example of string
    spanning multiple lines
    using heredoc syntax.
    EOD;

    /* 含有变量的更复杂示例 */
    class foo
    {
        var $foo;
        var $bar;

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

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

    echo <<<EOT
    My name is "$name". I am printing some $foo->foo.
    Now, I am printing some {$foo->bar[1]}.
    This should print a capital 'A': \x41
    EOT;
    ?>

以上示例会输出：

    My name is "MyName". I am printing some Foo.
    Now, I am printing some Bar2.
    This should print a capital 'A': A

也可以把 Heredoc 结构用在函数参数中来传递数据：

示例 #10 Heredoc 结构在参数中的示例

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

可以用 Heredoc 结构来初始化静态变量和类的属性和常量：

示例 #11 使用 Heredoc 结构来初始化静态值

    <?php
    // 静态变量
    function foo()
    {
        static $bar = <<<LABEL
    Nothing in here...
    LABEL;
    }

    // 类的常量、属性
    class foo
    {
        const BAR = <<<FOOBAR
    Constant example
    FOOBAR;

        public $baz = <<<FOOBAR
    Property example
    FOOBAR;
    }
    ?>

还可以在 Heredoc 结构中用双引号来声明标识符：

示例 #12 在 heredoc 结构中使用双引号

    <?php
    echo <<<"FOOBAR"
    Hello World!
    FOOBAR;
    ?>

#### Nowdoc 结构

就象 heredoc 结构类似于双引号字符串，Nowdoc 结构是类似于单引号字符串的。Nowdoc 结构很象 heredoc 结构，但是 nowdoc 中不进行字符串插值。这种结构很适合用于嵌入 PHP 代码或其它大段文本而无需对其中的特殊字符进行转义。与 SGML 的 `<![CDATA[ ]]>` 结构是用来声明大段的不用解析的文本类似，nowdoc 结构也有相同的特征。

一个 nowdoc 结构也用和 heredocs 结构一样的标记 `<<<`， 但是跟在后面的标识符要用单引号括起来，即 `<<<'EOT'`。Heredoc 结构的所有规则也同样适用于 nowdoc 结构，尤其是结束标识符的规则。

示例 #13 Nowdoc 结构字符串示例

    <?php
    echo <<<'EOD'
    Example of string spanning multiple lines
    using nowdoc syntax. Backslashes are always treated literally,
    e.g. \\ and \'.
    EOD;

以上示例会输出：

    Example of string spanning multiple lines
    using nowdoc syntax. Backslashes are always treated literally,
    e.g. \\ and \'.

示例 #14 含变量引用的 Nowdoc 字符串示例

    <?php

    /* 含有变量的更复杂的示例 */
    class foo
    {
        public $foo;
        public $bar;

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

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

    echo <<<'EOT'
    My name is "$name". I am printing some $foo->foo.
    Now, I am printing some {$foo->bar[1]}.
    This should not print a capital 'A': \x41
    EOT;
    ?>

以上示例会输出：

    My name is "$name". I am printing some $foo->foo.
    Now, I am printing some {$foo->bar[1]}.
    This should not print a capital 'A': \x41

示例 #15 静态数据的示例

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

> 注意:

> Nowdoc 结构是在 PHP 5.3.0 中加入的。

#### 字符串插值

当字符串用双引号或 heredoc 结构定义时，其中的变量可以进行替换。

这里共有两种语法规则：一种基本规则，一种高级规则。基本的语法规则是最常用和最方便的，它可以用最少的代码在一个 string 中嵌入一个变量，一个 array 的值，或一个 object 的属性。

##### 基本语法

如果遇到一个美元符号（`$`），后面的字符会被解释为变量名，然后替换为变量的值。

示例 #16 String Interpolation

    <?php
    $juice = "apple";

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

    ?>

以上示例会输出：

    He drank some apple juice.

从形式上讲，基本变量替换语法的结构如下：

    string-variable::
         variable-name   (offset-or-property)?
       | ${   expression   }

    offset-or-property::
         offset-in-string
       | property-in-string

    offset-in-string::
         [   name   ]
       | [   variable-name   ]
       | [   integer-literal   ]

    property-in-string::
         ->  name

    variable-name::
         $   name

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

警告

`${ expression }` 语法从 PHP 8.2.0 开始被弃用，因为它可能被解释为 可变变量：

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

以上示例在 PHP 8.2 中的输出：

    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"

以上示例会输出：

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

高级 字符串插值语法应该被使用。

> 注意: 如果无法形成有效的变量名，美元符号会保持原样。

>     <?php
>     echo "No interpolation $  has happened\n";
>     echo "No interpolation $\n has happened\n";
>     echo "No interpolation $2 has happened\n";
>     ?>

> 以上示例会输出：

>     No interpolation $  has happened
>     No interpolation $
>      has happened
>     No interpolation $2 has happened

示例 #17 插值数组或属性的第一个维度值

    <?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 "Object value: $o->s.";
    ?>

以上示例会输出：

    He drank some apple juice.
    He drank some orange juice.
    He drank some purple juice.
    Object value: string.

> 注意: 数组键必须是无引号的，因此不能用基本语法将常量作为键来引用。使用 高级 语法代替。

从 PHP 7.1.0 起，还支持负数字索引。

示例 #18 负数索引

    <?php
    $string = 'string';
    echo "The character at index -2 is $string[-2].", PHP_EOL;
    $string[-3] = 'o';
    echo "Changing the character at index -3 to o gives $string.", PHP_EOL;
    ?>

以上示例会输出：

    The character at index -2 is n.
    Changing the character at index -3 to o gives strong.

对于更复杂的情况，可以使用 高级 语法。

##### 高级（大括号）语法

高级语法允许使用任意访问器对变量进行插值。

任何标量变量、数组元素或对象属性（static 或非 static）都可以通过这种语法进行插值。表达式的写法和 在string之外的写法一样，然后用大括号`{`和 `}`包围。由于`{`不能被转义，所以这种语法只有在 紧跟在`{`后面的`$`才会被识别。要得到一个字面的 `{$`，需要用`{\$`。以下是一些例子：

示例 #19 Curly Syntax

    <?php
    const DATA_KEY = 'const-key';
    $great = 'fantastic';
    $arr = [
        '1',
        '2',
        '3',
        [41, 42, 43],
        'key' => 'Indexed value',
        'const-key' => 'Key with minus sign',
        'foo' => ['foo1', 'foo2', 'foo3']
    ];

    // 无效，输出 This is { fantastic}
    echo "This is { $great}";

    // 有效，输出 This is fantastic
    echo "This is {$great}";

    class Square {
        public $width;

        public function __construct(int $width) { $this->width = $width; }
    }

    $square = new Square(5);

    // 有效
    echo "This square is {$square->width}00 centimeters wide.";

    // 有效，引用 key 仅使用花括号语法时有效
    echo "This works: {$arr['key']}";

    // 有效
    echo "This works: {$arr[3][2]}";

    echo "This works: {$arr[DATA_KEY]}";

    // 使用多维数组时，在字符串内部时，始终使用括号括住数组
    echo "This works: {$arr['foo'][2]}";

    echo "This works: {$obj->values[3]->name}";

    echo "This works: {$obj->$staticProp}";

    // 无效，输出 C:\directory\{fantastic}.txt
    echo "C:\directory\{$great}.txt";

    // 有效，输出 C:\directory\fantastic.txt
    echo "C:\\directory\\{$great}.txt";
    ?>

> 注意: 由于该语法允许任意表达式，因此可以在高级语法中使用 可变变量。

#### 存取和修改字符串中的字符

string 中的字符可以通过一个从 0 开始的下标，用类似 array 结构中的方括号包含对应的数字来访问和修改，比如 $str[42]。可以把 string 当成字符组成的 array。函数 substr() 和 substr_replace() 可用于操作多于一个字符的情况。

> 注意: 从 PHP 7.1.0 开始，还支持 string 负偏移量。从 string 尾部到指定位置的偏移量。 以前，负偏移量读取时（返回空 string）会发出 `E_NOTICE`， 写入时（string 保持不变）会发出 `E_WARNING`。

> 注意: PHP 8.0.0 之前, 出于同样的目的，可以使用大括号访问 string，例如 $str{42}。 从 PHP 7.4.0 起，此大括号语法被弃用，自 PHP 8.0.0 开始不再受支持。

警告

用超出字符串长度的下标写入将会拉长该字符串并以空格填充。非整数类型下标会被转换成整数。非法下标类型会产生一个 `E_WARNING` 级别错误。 写入时只用到了赋值字符串的第一个字符。 PHP 7.1.0 开始，用空字符串赋值会导致 fatal 错误；在之前赋给的值是 NULL 字符。

警告

PHP 的字符串在内部是字节组成的数组。因此用花括号访问或修改字符串对多字节字符集很不安全。仅应对单字节编码例如 ISO-8859-1 的字符串进行此类操作。

> 注意: 从 PHP 7.1.0 开始，对空字符串应用空索引运算符会引发致命错误。 以前是空字符串会被静默转为数组。

示例 #20 一些字符串示例

    <?php
    // 取得字符串的第一个字符
    $str = 'This is a test.';
    $first = $str[0];
    var_dump($first);

    // 取得字符串的第三个字符
    $third = $str[2];
    var_dump($third);

    // 取得字符串的最后一个字符
    $str = 'This is still a test.';
    $last = $str[strlen($str)-1];
    var_dump($last);

    // 修改字符串的最后一个字符
    $str = 'Look at the sea';
    $str[strlen($str)-1] = 'e';
    var_dump($str);
    ?>

字符串下标必须为整数或可转换为整数的字符串，否则会发出警告。之前类似 `"foo"` 的下标会无声地转换成 `0`。

示例 #21 字符串无效下标的例子

    <?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;
    }
    ?>

以上示例会输出：

    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"

> 注意:

> 用 `[]` 或 `{}` 访问任何其它类型（不包括数组或具有相应接口的对象实现）的变量只会无声地返回 `null`。

> 注意:

> 可以直接在字符串原型中用 `[]` 或 `{}` 访问字符。

> 注意:

> PHP 7.4 中弃用在字符串字面量中使用 `{}` 来访问字符。 PHP 8.0 已移除。

### 有用的函数和运算符

字符串可以用 '.'（点）运算符连接起来，注意 '+'（加号）运算符没有这个功能。更多信息参考字符串运算符。

对于 string 的操作有很多有用的函数。

可以参考字符串函数了解大部分函数，高级的查找与替换功能可以参考 Perl 兼容正则表达式函数。

另外还有 URL 字符串函数，也有加密／解密字符串的函数（Sodium 和 Hash）。

最后，可以参考字符类型函数。

### 转换成字符串

一个值可以通过在其前面加上 `(string)` 或用 strval() 函数来转变成字符串。在一个需要字符串的表达式中，会自动转换为 string。这发生在当使用 echo 或 print 函数，或当变量与 string 进行比较的时候。类型和类型转换可以更好的解释下面的事情，也可参考函数 settype()。

一个布尔值 bool 的 `true` 被转换成 string 的 `"1"`。bool 的 `false` 被转换成 `""`（空字符串）。这种转换可以在 bool 和 string 之间相互进行。

一个整数 int 或浮点数 float 被转换为数字的字面样式的 string（包括 float 中的指数部分）。使用指数计数法的浮点数（`4.1E+6`）也可转换。

> 注意:

> PHP 8.0.0 起，十进制小数点字符都是一个句号（`.`）。 而在此之前的版本，在脚本的区域（category LC_NUMERIC） 中定义了十进制小数点字符。参见 setlocale()。

数组 array 总是转换成字符串 `"Array"`，因此，echo 和 print 无法显示出该数组的内容。要显示某个单元，可以用 `echo $arr['foo']` 这种结构。要显示整个数组内容见下文。

必须使用魔术方法 __toString 才能将 object 转换为 string。

资源 Resource 总会被转变成 `"Resource id #1"` 这种结构的字符串，其中的 `1` 是 PHP 在运行时分配给该 resource 的资源数字。 虽然不应依赖此字符串的确切结构且该结构可能会更改，但在脚本执行的生命周期内（即一个 Web 请求或 CLI 进程），该字符串对于给定的资源始终是唯一的，且不会被重复使用。 要得到一个 resource 的类型，可以用函数 get_resource_type()。

`null` 总是被转变成空字符串。

如上面所说的，直接把 array，object 或 resource 转换成 string 不会得到除了其类型之外的任何有用信息。可以使用函数 print_r() 和 var_dump() 列出这些类型的内容。

大部分的 PHP 值可以转变成 string 来永久保存，这被称作串行化，可以用函数 serialize() 来实现。

### 字符串类型详解

PHP 中的 string 的实现方式是一个由字节组成的数组再加上一个整数指明缓冲区长度。并无如何将字节转换成字符的信息，由程序员来决定。字符串由什么值来组成并无限制；特别的，其值为 `0`（“NUL bytes”）的字节可以处于字符串任何位置（不过有几个函数，在本手册中被称为非“二进制安全”的，也许会把 NUL 字节之后的数据全都忽略）。

字符串类型的此特性解释了为什么 PHP 中没有单独的“byte”类型 - 已经用字符串来代替了。返回非文本值的函数 - 例如从网络套接字读取的任意数据 - 仍会返回字符串。

由于 PHP 并不特别指明字符串的编码，那字符串到底是怎样编码的呢？例如字符串 `"á"` 到底是等于 `"\xE1"`（ISO-8859-1），`"\xC3\xA1"`（UTF-8，C form），`"\x61\xCC\x81"`（UTF-8，D form）还是任何其它可能的表达呢？答案是字符串会被按照该脚本文件相同的编码方式来编码。因此如果一个脚本的编码是 ISO-8859-1，则其中的字符串也会被编码为 ISO-8859-1，以此类推。不过这并不适用于激活了 Zend Multibyte 时；此时脚本可以是以任何方式编码的（明确指定或被自动检测）然后被转换为某种内部编码，然后字符串将被用此方式编码。注意脚本的编码有一些约束（如果激活了 Zend Multibyte 则是其内部编码）- 这意味着此编码应该是 ASCII 的兼容超集，例如 UTF-8 或 ISO-8859-1。不过要注意，依赖状态的编码其中相同的字节值可以用于首字母和非首字母而转换状态，这可能会造成问题。

当然了，要做到有用，操作文本的函数必须假定字符串是如何编码的。不幸的是，PHP 关于此的函数有很多变种：

- 某些函数假定字符串是以单字节编码的，但并不需要将字节解释为特定的字符。例如 substr()，strpos()，strlen() 和 strcmp()。理解这些函数的另一种方法是它们作用于内存缓冲区，即按照字节和字节下标操作。
- 某些函数被传递入了字符串的编码方式，也可能会假定默认无此信息。例如 htmlentities() 和 mbstring 扩展中的大部分函数。
- 其它函数使用了当前区域（见 setlocale()），但是逐字节操作。
- 最后一些函数会假定字符串是使用某特定编码的，通常是 UTF-8。intl 扩展和 PCRE（上例中仅在使用了 `u` 修饰符时）扩展中的大部分函数都是这样。

最后，要书写能够正确使用 Unicode 的程序依赖于很小心地避免那些可能会损坏数据的函数。要使用来自于 intl 和 mbstring 扩展的函数。不过使用能处理 Unicode 编码的函数只是个开始。不管用何种语言提供的函数，最基本的还是了解 Unicode 规格。例如一个程序如果假定只有大写和小写，那可是大错特错。

## 数字字符串

如果一个 PHP string 可以被解释为 int 或 float 类型，则它被视为数字字符串。

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})

PHP 也有前导数字字符串的概念。 这只是一个字符串，其开头类似于数字字符串，后跟任何字符。

> 注意:

> 任何包含字母 `E` 周围是数字的字符串都将视为以科学计数法表示的数字。这会产生意想不到的效果。

> 示例 #1 科学记数法比较

>     <?php
>     var_dump("0D1" == "000"); // false，“0D1”不是科学计数法
>     var_dump("0E1" == "000"); // true，“0E1”是 0 * (10 ^ 1)，即 0
>     var_dump("2E1" == "020"); // true，“2E1”是 2 * (10 ^ 1)，即 20
>     ?>

### 在数字上下文中使用的字符串

当一个 string 需要被当作一个数字计算时，（例如：算术运算， int 类型声明等)，则采取以下步骤来确定结果：

1. 如果 string 是数字，当 string 是整数字符串并且符合 int 类型的范围限制（即是 PHP_INT_MAX 定义的值），则解析为 int ，否则解析为 float 。
2. 如果上下文允许前导数字和一个 string，如果 string 的前导部分是整数数字字符串且符合 int 类型限制（由 `PHP_INT_MAX` 定义），则解析为 int ，否则解析为 float 。 此外，还会导致 `E_WARNING` 级别的错误。
3. 如果 string 不是数字，则会抛出一个 TypeError 的异常。

### PHP 8.0.0 之前的行为

在 PHP 8.0.0 之前， 只有在前导空格的时候，string 才被认为是数字；如果它有尾随空格，则该字符串被视为是前导数字。

在 PHP 8.0.0 之前，当在数字上下文中使用字符串时，它将执行与上述相同的步骤，但有以下区别：

- 使用前导数字字符串将导致 `E_NOTICE` 而不是 `E_WARNING` 错误。
- 如果字符串不是数字，则会导致 `E_WARNING` 错误并返回 `0` 。

在 PHP 7.1.0 之前，则既不会导致 `E_NOTICE`，也不会导致 `E_WARNING`。

    <?php
    $foo = 1 + "10.5";                // $foo 是 float (11.5)
    $foo = 1 + "-1.3e3";              // $foo 是 float (-1299)
    $foo = 1 + "bob-1.3e3";           // PHP 8.0.0 起产生 TypeError；在此之前 $foo 是 integer (1)
    $foo = 1 + "bob3";                // PHP 8.0.0 起产生 TypeError；在此之前 $foo 是 integer (1)
    $foo = 1 + "10 Small Pigs";       // PHP 8.0.0 起，$foo 是 integer (11)，并且产生 E_WARNING；在此之前产生 E_NOTICE
    $foo = 4 + "10.2 Little Piggies"; // PHP 8.0.0 起，$foo 是 float (14.2)，并且产生 E_WARNING；在此之前产生 E_NOTICE
    $foo = "10.0 pigs " + 1;          // PHP 8.0.0 起，$foo 是 float (11)，并且产生 E_WARNING；在此之前产生 E_NOTICE
    $foo = "10.0 pigs " + 1.0;        // PHP 8.0.0 起，$foo 是 float (11)，并且产生 E_WARNING；在此之前产生 E_NOTICE
    ?>

## Array 数组

有关数组操作的更多信息，请参阅 数组函数 章节的文档。

PHP 中的 array 实际上是一个有序映射。映射是一种把 values 关联到 keys 的类型。此类型针对多种不同用途进行了优化； 它可以被视为数组、列表（向量）、哈希表（映射的实现）、字典、集合、堆栈、队列等等。 由于 array 的值可以是其它 array 所以树形结构和多维 array 也是允许的。

解释这些数据结构超出了本手册的范围，但对每种结构至少会提供一个例子。 要得到这些数据结构的更多信息，建议参考有关此广阔主题的其它文献。

### 语法

#### 定义数组 array()

可以用 array() 语言结构来新建一个 array。它接受任意数量用逗号分隔的 `键（key） => 值（value）` 对。

    array(
        key  => value,
        key2 => value2,
        key3 => value3,
        ...
    )

最后一个数组单元之后的逗号可以省略。通常用于单行数组定义中，例如常用 `array(1, 2)` 而不是 `array(1, 2, )`。对多行数组定义通常保留最后一个逗号，这样要添加一个新单元时更方便。

> 注意:

> 可以用短数组语法 `[]` 替代 `array()` 。

示例 #1 一个简单数组

    <?php
    $array1 = array(
        "foo" => "bar",
        "bar" => "foo",
    );

    // 使用短数组语法
    $array2 = [
        "foo" => "bar",
        "bar" => "foo",
    ];

    var_dump($array1, $array2);
    ?>

key 可以是 integer 或者 string。value 可以是任意类型。

此外 key 会有如下的强制转换：

- String 中包含有效的十进制 int，除非数字前面有一个 `+` 号，否则将被转换为 int 类型。例如键名 `"8"` 实际会被储存为 `8`。另外， `"08"` 不会被强制转换，因为它不是一个有效的十进制整数。
- Float 也会被转换为 int ，意味着其小数部分会被舍去。例如键名 `8.7` 实际会被储存为 `8`。
- Bool 也会被转换成 int。即键名 `true` 实际会被储存为 `1` 而键名 `false` 会被储存为 `0`。
- Null 会被转换为空字符串，即键名 `null` 实际会被储存为 `""`。
- Array 和 object 不能 被用为键名。坚持这么做会导致警告：`Illegal offset type`。

如果在数组定义时多个元素都使用相同键名，那么只有最后一个会被使用，其它的元素都会被覆盖。

示例 #2 类型转换与覆盖的示例

    <?php
    $array = array(
        1    => "a",
        "1"  => "b",
        1.5  => "c",
        true => "d",
    );
    var_dump($array);
    ?>

以上示例会输出：

    array(1) {
      [1]=>
      string(1) "d"
    }

上例中所有的键名都被强制转换为 `1`，则每一个新单元都会覆盖前一个的值，最后剩下的只有一个 `"d"`。

PHP 数组可以同时含有 int 和 string 类型的键名，因为 PHP 实际并不区分索引数组和关联数组。

示例 #3 混合 int 和 string 键名

    <?php
    $array = array(
        "foo" => "bar",
        "bar" => "foo",
        100   => -100,
        -100  => 100,
    );
    var_dump($array);
    ?>

以上示例会输出：

    array(4) {
      ["foo"]=>
      string(3) "bar"
      ["bar"]=>
      string(3) "foo"
      [100]=>
      int(-100)
      [-100]=>
      int(100)
    }

key 为可选项。如果未指定，PHP 将自动使用之前用过的最大 int 键名加上 1 作为新的键名。

示例 #4 没有键名的索引数组

    <?php
    $array = array("foo", "bar", "hello", "world");
    var_dump($array);
    ?>

以上示例会输出：

    array(4) {
      [0]=>
      string(3) "foo"
      [1]=>
      string(3) "bar"
      [2]=>
      string(5) "hello"
      [3]=>
      string(5) "world"
    }

还可以只对某些单元指定键名而对其它的空置：

示例 #5 仅对部分单元指定键名

    <?php
    $array = array(
             "a",
             "b",
        6 => "c",
             "d",
    );
    var_dump($array);
    ?>

以上示例会输出：

    array(4) {
      [0]=>
      string(1) "a"
      [1]=>
      string(1) "b"
      [6]=>
      string(1) "c"
      [7]=>
      string(1) "d"
    }

可以看到最后一个值 `"d"` 被自动赋予了键名 `7`。这是由于之前最大的整数键名是 `6`。

示例 #6 复杂类型转换和覆盖的例子

这个例子包括键名类型转换和元素覆盖的所有变化。

    <?php
    $array = array(
        1    => 'a',
        '1'  => 'b', // 值 "a" 会被 "b" 覆盖
        1.5  => 'c', // 值 "b" 会被 "c" 覆盖
        -1 => 'd',
        '01'  => 'e', // 由于这不是整数字符串，因此不会覆盖键名 1
        '1.5' => 'f', // 由于这不是整数字符串，因此不会覆盖键名 1
        true => 'g', // 值 "c" 会被 "g" 覆盖
        false => 'h',
        '' => 'i',
        null => 'j', // 值 "i" 会被 "j" 覆盖
        'k', // 值 “k” 的键名被分配为 2。这是因为之前最大的整数键是 1
        2 => 'l', // 值 "k" 会被 "l" 覆盖
    );

    var_dump($array);
    ?>

以上示例会输出：

    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"
    }

示例 #7 负数索引示例

当分配负整数 key `n` 时，PHP 会将下一个 key 分配给 `n+1`。

    <?php
    $array = [];

    $array[-5] = 1;
    $array[] = 2;

    var_dump($array);
    ?>

以上示例会输出：

    array(2) {
      [-5]=>
      int(1)
      [-4]=>
      int(2)
    }

警告

PHP 8.3.0 之前，分配负整数 key `n` 会将下一个 key 分配给 `0`，因此前面的示例将输出：

    array(2) {
      [-5]=>
      int(1)
      [0]=>
      int(2)
    }

#### 用方括号语法访问数组单元

数组单元可以通过 `array[key]` 语法来访问。

示例 #8 访问数组单元

    <?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"]);
    ?>

以上示例会输出：

    string(3) "bar"
    int(24)
    string(3) "foo"

> 注意:

> 在 PHP 8.0.0 之前，方括号和花括号可以互换使用来访问数组单元（例如 `$array[42]` 和 `$array{42}` 在上例中效果相同）。 花括号语法在 PHP 7.4.0 中已弃用，在 PHP 8.0.0 中不再支持。

示例 #9 数组解引用

    <?php
    function getArray() {
        return array(1, 2, 3);
    }

    $secondElement = getArray()[1];

    var_dump($secondElement);
    ?>

> 注意:

> 试图访问一个未定义的数组键名与访问任何未定义变量一样：会导致 `E_WARNING` 级别错误信息（在 PHP 8.0.0 之前是 `E_NOTICE` 级别），其结果为 `null`。

> 注意:

> 数组解引用非 string 的标量值会产生 `null`。 在 PHP 7.4.0 之前，它不会发出错误消息。 从 PHP 7.4.0 开始，这个问题产生 `E_NOTICE` ； 从 PHP 8.0.0 开始，这个问题产生 `E_WARNING` 。

#### 用方括号的语法新建／修改

可以通过明示地设定其中的值来修改现有的 array 。

这是通过在方括号内指定键名来给 array 赋值实现的。也可以省略键名，在这种情况下给变量名加上一对空的方括号（`[]`）。

    $arr[key] = value;
    $arr[] = value;
    // key 可以是 int 或 string
    // value 可以是任意类型的值

如果 $arr 不存在或者设置为 `null` 或者 `false`，将会新建它，这也是另一种创建 array 的方法。不过并不鼓励这样做，因为如果 $arr 已经包含有值（例如来自请求变量的 string）则此值会保留而 `[]` 实际上代表着字符串访问运算符。初始化变量的最好方式是直接给其赋值。

> 注意: 从 PHP 7.1.0 起，对字符串应用空索引操作符会抛出致命错误。以前，字符串被静默地转换为数组。

> 注意: 从 PHP 8.1.0 起，弃用从 `false` 值中创建一个新数组。 但仍然允许从 `null` 或者未定义的变量中创建新数组。

要修改某个值，通过其键名给该单元赋一个新值。要删除某键值对，对其调用 unset() 函数。

示例 #10 Using Square Brackets with Arrays

    <?php
    $arr = array(5 => 1, 12 => 2);

    $arr[] = 56;    // 这与 $arr[13] = 56 相同;
                    // 在脚本的这一点上

    $arr["x"] = 42; // 添加一个新元素
                    // 键名使用 "x"

    unset($arr[5]); // 从数组中删除元素

    unset($arr);    // 删除整个数组
    ?>

> 注意:

> 如上所述，如果给出方括号但没有指定键名，则取当前最大 int 索引值，新的键名将是该值加上 1（但是最小为 0）。如果当前还没有 int 索引，则键名将为 `0` 。

> 注意这里所使用的最大整数键名目前不需要存在于 array 中。 它只要在上次 array 重新生成索引后曾经存在于 array 就行了。以下面的例子来说明：

>     <?php
>     // 创建一个简单的数组
>     $array = array(1, 2, 3, 4, 5);
>     print_r($array);

>     // 现在删除其中的所有元素，但保持数组本身不变:
>     foreach ($array as $i => $value) {
>         unset($array[$i]);
>     }
>     print_r($array);

>     // 添加一个单元（注意新的键名是 5，而不是你可能以为的 0）
>     $array[] = 6;
>     print_r($array);

>     // 重新索引：
>     $array = array_values($array);
>     $array[] = 7;
>     print_r($array);
>     ?>

> 以上示例会输出：

>     Array
>     (
>         [0] => 1
>         [1] => 2
>         [2] => 3
>         [3] => 4
>         [4] => 5
>     )
>     Array
>     (
>     )
>     Array
>     (
>         [5] => 6
>     )
>     Array
>     (
>         [0] => 6
>         [1] => 7
>     )

#### 数组解包

可以使用 `[]`（自 PHP 7.1.0 起）或者 list() 语言结构解包数组。这些结构可用于将数组解包为不同的变量。

示例 #11 Array Destructuring

    <?php
    $source_array = ['foo', 'bar', 'baz'];

    [$foo, $bar, $baz] = $source_array;

    echo $foo, PHP_EOL;    // 打印 "foo"
    echo $bar, PHP_EOL;    // 打印 "bar"
    echo $baz, PHP_EOL;    // 打印 "baz"
    ?>

数组解包可用于 `foreach` 在迭代多维数组时对其进行解包。

示例 #12 Array Destructuring in Foreach

    <?php
    $source_array = [
        [1, 'John'],
        [2, 'Jane'],
    ];

    foreach ($source_array as [$id, $name]) {
        echo "{$id}: '{$name}'\n";
    }
    ?>

如果变量未提供，数组元素将会被忽略。数组解包始终从索引 `0` 开始。

示例 #13 Ignoring Elements

    <?php
    $source_array = ['foo', 'bar', 'baz'];

    // 将索引 2 的元素分配给变量 $baz
    [, , $baz] = $source_array;

    echo $baz;    // 打印 "baz"
    ?>

自 PHP 7.1.0 起，也可以解包关联数组。这在数字索引数组中更容易选择正确的元素，因为可以显式指定索引。

示例 #14 Destructuring Associative Arrays

    <?php
    $source_array = ['foo' => 1, 'bar' => 2, 'baz' => 3];

    // 将索引 'baz' 处的元素分配给变量 $three
    ['baz' => $three] = $source_array;

    echo $three, PHP_EOL;    // 打印 3

    $source_array = ['foo', 'bar', 'baz'];

    // 将索引 2 处的元素分配给变量 $baz
    [2 => $baz] = $source_array;

    echo $baz, PHP_EOL;    // 打印 "baz"
    ?>

数组解包可以方便的用于两个变量交换。

示例 #15 Swapping Two Variable

    <?php
    $a = 1;
    $b = 2;

    [$b, $a] = [$a, $b];

    echo $a, PHP_EOL;    // 打印 2
    echo $b, PHP_EOL;    // 打印 1
    ?>

> 注意:

> 分配时不支持展开运算符（`...`）。

> 注意:

> 尝试访问未定义的数组键与访问任何未定义的变量相同：都将发出 `E_WARNING` 级别的错误消息（PHP 8.0.0 之前是 `E_NOTICE` 级别），结果将是 `null`。

> 注意:

> 解构标量值会分配 `null` 到所有变量。

### 实用函数

有很多操作数组的函数，参见 数组函数 一节。

> 注意:

> unset() 函数允许删除 array 中的某个键。但要注意数组将不会重建索引。如果需要删除后重建索引，可以用 array_values() 函数重建 array 索引。

> 示例 #16 Unsetting Intermediate Elements

>     <?php
>     $a = array(1 => 'one', 2 => 'two', 3 => 'three');

>     /* 该数组将被定义为
>        $a = array(1 => 'one', 3 => 'three');
>        而不是
>        $a = array(1 => 'one', 2 =>'three');
>     */
>     unset($a[2]);
>     var_dump($a);

>     $b = array_values($a);
>     // Now $b is array(0 => 'one', 1 =>'three')
>     var_dump($b);
>     ?>

`foreach` 控制结构是专门用于 array 的。它提供了一个简单的方法来遍历 array。

### 数组做什么和不做什么

#### 为什么 `$foo[bar]` 错了？

应该始终在用字符串表示的数组索引上加上引号。例如用 `$foo['bar']` 而不是 `$foo[bar]`。但是为什么呢？可能在老的脚本中见过如下语法：

    <?php
    $foo[bar] = 'enemy';
    echo $foo[bar];
    // 及其它
    ?>

这样是错的，但可以正常运行。那么为什么错了呢？原因是此代码中有一个未定义的常量（ `bar` ）而不是 string（`'bar'`－注意引号）。而 PHP 可能会在以后定义此常量，不幸的是你的代码中有同样的名字。它能运行，是因为 PHP 自动将裸字符串（没有引号的 string 且不对应于任何已知符号）转换成一个其值为该裸 string 的 string。例如，如果没有常量定义为 `bar`，那么PHP 将在 string 中替代为 `'bar'` 并使用之。

警告

将未定义的常量当作裸字符串的回退会触发 `E_NOTICE` 级别错误。 从 PHP 7.2.0 起已废弃，并触发 `E_WARNING` 级别错误。 从 PHP 8.0.0 起被移除，并触发 Error 异常。

这并不意味着总是给键名加上引号。用不着给键名为 常量 或 变量 的加上引号，否则会使 PHP 不能解析它们。

示例 #17 Key Quoting

    <?php
    error_reporting(E_ALL);
    ini_set('display_errors', true);
    ini_set('html_errors', false);

    // 简单数组:
    $array = array(1, 2);
    $count = count($array);

    for ($i = 0; $i < $count; $i++) {
        echo "\n检查 $i: \n";
        echo "坏的: " . $array['$i'] . "\n";
        echo "好的: " . $array[$i] . "\n";
        echo "坏的: {$array['$i']}\n";
        echo "好的: {$array[$i]}\n";
    }
    ?>

以上示例会输出：

    检查 0:
    Notice: Undefined index:  $i in /path/to/script.html on line 9
    坏的:
    好的: 1
    Notice: Undefined index:  $i in /path/to/script.html on line 11
    坏的:
    好的: 1

    检查 1:
    Notice: Undefined index:  $i in /path/to/script.html on line 9
    坏的:
    好的: 2
    Notice: Undefined index:  $i in /path/to/script.html on line 11
    坏的:
    好的: 2

演示此行为的更多例子：

示例 #18 More Examples

    <?php
    // 显示所有错误
    error_reporting(E_ALL);

    $arr = array('fruit' => 'apple', 'veggie' => 'carrot');

    // 正确
    echo $arr['fruit'], PHP_EOL;  // apple
    echo $arr['veggie'], PHP_EOL; // carrot

    // 不正确。此操作无效，并会因未定义名为 fruit 的常量而抛出 PHP 错误
    //
    // Error: Undefined constant "fruit"
    try {
        echo $arr[fruit];
    } catch (Error $e) {
        echo get_class($e), ': ', $e->getMessage(), PHP_EOL;
    }

    // 此处定义了一个常量以说明其行为，将值 'veggie' 赋予名为 fruit 的常量
    define('fruit', 'veggie');

    // 注意现在不同
    echo $arr['fruit'], PHP_EOL;  // apple
    echo $arr[fruit], PHP_EOL;    // carrot

    // 以下写法是允许的，因为其位于字符串内部。常量在字符串中不会被查找，因此此处不会产生错误
    echo "Hello $arr[fruit]", PHP_EOL;      // Hello apple

    // 例外：字符串中用花括号包围的数组允许对常量进行解析
    echo "Hello {$arr[fruit]}", PHP_EOL;    // Hello carrot
    echo "Hello {$arr['fruit']}", PHP_EOL;  // Hello apple

    // 拼接是另一种选择
    echo "Hello " . $arr['fruit'], PHP_EOL; // Hello apple
    ?>

    // 这将不起作用，并会导致解析错误，例如：
    // Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING'
    // 这当然也适用于在字符串中使用超全局变量
    print "Hello $arr['fruit']";
    print "Hello $_GET['foo']";
    ?>

和在 语法 一节中规定的一样，在方括号（`[`” 和 “`]`”）之间必须有一个表达式。这意味着可以这样写：

    <?php
    echo $arr[somefunc($bar)];
    ?>

这是一个用函数返回值作为数组索引的例子。PHP 也可以用已知常量，可能之前已经见过：

    <?php
    $error_descriptions[E_ERROR]   = "A fatal error has occurred";
    $error_descriptions[E_WARNING] = "PHP issued a warning";
    $error_descriptions[E_NOTICE]  = "This is just an informal notice";
    ?>

注意 `E_ERROR` 也是个合法的标识符，就和第一个例子中的 `bar` 一样。但是上一个例子实际上和如下写法是一样的：

    <?php
    $error_descriptions[1] = "A fatal error has occurred";
    $error_descriptions[2] = "PHP issued a warning";
    $error_descriptions[8] = "This is just an informal notice";
    ?>

因为 `E_ERROR` 等于 `1`，等等。

##### 那么为什么这样做不好？

也许有一天，PHP 开发小组可能会想新增一个常量或者关键字，或者用户可能希望以后在自己的程序中引入新的常量，那就有麻烦了。例如已经不能这样用 `empty` 和 `default` 这两个词了，因为他们是 保留关键字。

> 注意: 重申一次，在双引号字符串中，不给索引加上引号是合法的因此 `"$foo[bar]"` 是合法的（“合法”的原文为 valid。在实际测试中，这么做确实可以访问数组的该元素，但是会报一个常量未定义的 notice。无论如何，强烈建议不要使用 $foo[bar]这样的写法，而要使用 $foo['bar'] 来访问数组中元素。--haohappy 注）。至于为什么参见以上的例子和 字符串中的变量解析 中的解释。

### 转换为数组

对于任意 int，float， string，bool 和 resource 类型，如果将一个值转换为 array，将得到一个仅有一个元素的数组，其下标为 0，该元素即为此标量的值。换句话说，`(array) $scalarValue` 与 `array($scalarValue)` 完全一样。

如果将 object 类型转换为 array，则结果为一个数组，其单元为该对象的属性。键名将为成员变量名，不过有几点例外：整数属性不可访问； 私有变量前会加上类名作前缀；保护变量前会加上一个 '*' 做前缀。这些前缀的前后都各有一个 `NUL` 字节。 未初始化的类型属性将会被丢弃。

示例 #19 转换为数组

    <?php

    class A {
        private $B;
        protected $C;
        public $D;
        function __construct()
        {
            $this->{1} = null;
        }
    }

    var_export((array) new A());
    ?>

以上示例会输出：

    array (
      '' . "\0" . 'A' . "\0" . 'B' => NULL,
      '' . "\0" . '*' . "\0" . 'C' => NULL,
      'D' => NULL,
      1 => NULL,
    )

这些 `NUL` 会导致一些意想不到的行为：

示例 #20 Casting an Object to an Array

    <?php

    class A {
        private $A; // 将变为 '\0A\0A'
    }

    class B extends A {
        private $A; // 将变为 '\0B\0A'
        public $AA; // 将变为 'AA'
    }

    var_dump((array) new B());
    ?>

以上示例会输出：

    array(3) {
      ["BA"]=>
      NULL
      ["AA"]=>
      NULL
      ["AA"]=>
      NULL
    }

上例会有两个键名为 'AA'，不过其中一个实际上是 '\0A\0A'。

将 `null` 转换为 array 会得到一个空的数组。

### 比较

可以用 array_diff() 函数和数组运算符来比较数组。

### 数组解包

在 array 定义时，用 `...` 前缀的一个 array 可以被展开到当前位置。 只有实现了 Traversable 的数组和对象才能被展开。 PHP 7.4.0 开始可以使用 `...` 解包 array。这也被称之为展开运算符。

它可以多次使用，在 `...` 操作符前后都可以添加常规元素：

示例 #21 简单的数组解包

    <?php
    // 使用简短的数组语法。
    // 亦可用于 array() 语法
    $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);
    ?>

`...` 操作符解包 array 时也遵守函数 array_merge() 的语义。 也就是说，key 为字符时，后面的字符键会覆盖之前的字符键；key 为 integer 时则会重新编号：

示例 #22 重复 key 的数组解包

    <?php
    // string key
    $arr1 = ["a" => 1];
    $arr2 = ["a" => 2];
    $arr3 = ["a" => 0, ...$arr1, ...$arr2];
    var_dump($arr3); // ["a" => 2]

    // integer key
    $arr4 = [1, 2, 3];
    $arr5 = [4, 5, 6];
    $arr6 = [...$arr4, ...$arr5];
    var_dump($arr6); // [1, 2, 3, 4, 5, 6]
    // 即 [0 => 1, 1 => 2, 2 => 3, 3 => 4, 4 => 5, 5 => 6]
    // 也就是原始的 integer key 不再保留
    ?>

> 注意:

> 既不是 integer 也不是 string 的 key 会抛出 TypeError。 这类 key 只能通过 Traversable 对象生成。

> 注意:

> 在 PHP 8.1 之前，带有 string 键的 array 无法解包：

>     <?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]
>     ?>

### 示例

PHP 中的数组类型有非常多的用途。以下是一些示例：

示例 #23 Array Versatility

    <?php
    // 这里：
    $a = array( 'color' => 'red',
                'taste' => 'sweet',
                'shape' => 'round',
                'name'  => 'apple',
                4        // 键名为 0
              );

    $b = array('a', 'b', 'c');

    var_dump($a, $b);

    // . . .完全等同于:
    $a = array();
    $a['color'] = 'red';
    $a['taste'] = 'sweet';
    $a['shape'] = 'round';
    $a['name']  = 'apple';
    $a[]        = 4;        // 键名为 0

    $b = array();
    $b[] = 'a';
    $b[] = 'b';
    $b[] = 'c';

    // 执行上述代码后，数组 $a 将是
    // array('color' => 'red', 'taste' => 'sweet', 'shape' => 'round',
    // 'name' => 'apple', 0 => 4)， 数组 $b 将是
    // array(0 => 'a', 1 => 'b', 2 => 'c'), 或简单的 array('a', 'b', 'c').
    ?>

示例 #24 使用 array()

    <?php
    // Array as (property-)map
    $map = array( 'version'    => 4,
                  'OS'         => 'Linux',
                  'lang'       => 'english',
                  'short_tags' => true
                );
    var_dump($map);

    // strictly numerical keys
    // this is the same as array(0 => 7, 1 => 8, ...)
    $array = array( 7,
                    8,
                    0,
                    156,
                    -10
                  );
    var_dump($array);

    $switching = array(         10, // key = 0
                        5    =>  6,
                        3    =>  7,
                        'a'  =>  4,
                                11, // key = 6 (整数索引的最大值为 5)
                        '8'  =>  2, // key = 8 (整数！)
                        '02' => 77, // key = '02'
                        0    => 12  // 值 10 被 12 覆盖
                      );
    var_dump($switching);

    // 空数组
    $empty = array();
    var_dump($empty);
    ?>

示例 #25 集合

    <?php
    $colors = array('red', 'blue', 'green', 'yellow');

    foreach ($colors as $color) {
        echo "Do you like $color?\n";
    }

    ?>

以上示例会输出：

    Do you like red?
    Do you like blue?
    Do you like green?
    Do you like yellow?

可以通过引用传递 array 的值来直接更改数组的值。

示例 #26 在循环中改变单元

    <?php
    $colors = array('red', 'blue', 'green', 'yellow');

    foreach ($colors as &$color) {
        $color = mb_strtoupper($color);
    }
    unset($color); /* 确保后面对
    $color 的写入不会修改最后一个数组元素 */

    print_r($colors);
    ?>

以上示例会输出：

    Array
    (
        [0] => RED
        [1] => BLUE
        [2] => GREEN
        [3] => YELLOW
    )

本例生成一个下标从 1 开始的数组。

示例 #27 下标从 1 开始的数组

    <?php
    $firstquarter = array(1 => 'January', 'February', 'March');
    print_r($firstquarter);
    ?>

以上示例会输出：

    Array
    (
        [1] => January
        [2] => February
        [3] => March
    )

示例 #28 填充数组

    <?php
    // 把指定目录中的所有项填充到数组
    $handle = opendir('.');
    while (false !== ($file = readdir($handle))) {
        $files[] = $file;
    }
    closedir($handle);

    var_dump($files);
    ?>

Array 是有序的。也可以使用不同的排序函数来改变顺序。更多信息参见 数组函数。可以用 count() 函数来统计出 array 中元素的个数。

示例 #29 数组排序

    <?php
    sort($files);
    print_r($files);
    ?>

因为 array 中的值可以为任意值，也可是另一个 array。这样可以产生递归或多维 array。

示例 #30 递归和多维数组

    <?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);

    // 处理上面数组中的值的一些例子
    echo $fruits["holes"][5];    // 打印 "second"
    echo $fruits["fruits"]["a"]; // 打印 "orange"
    unset($fruits["holes"][0]);  // 删除 "first"

    // 创建一个新的多维数组
    $juices["apple"]["green"] = "good";
    var_dump($juices);
    ?>

Array 的赋值总是会涉及到值的拷贝。使用 引用运算符 通过引用来拷贝 array。

示例 #31 Array Copying

    <?php
    $arr1 = array(2, 3);
    $arr2 = $arr1;
    $arr2[] = 4; // $arr2 已更改，
                 // $arr1 仍然是 array(2, 3)

    $arr3 = &$arr1;
    $arr3[] = 4; // 现在 $arr1 和 $arr3 是一样的

    var_dump($arr1, $arr2, $arr3);
    ?>

## Object 对象

### 对象初始化

要创建新的 object，使用 `new` 语句实例化类：

示例 #1 对象构造

    <?php
    class foo
    {
        function do_foo()
        {
            echo "Doing foo.";
        }
    }

    $bar = new foo;
    $bar->do_foo();
    ?>

详细讨论参见手册中类与对象章节。

### 转换为对象

如果将一个对象转换成对象，它将不会有任何变化。如果其它任何类型的值被转换成对象，将会创建一个内置类 stdClass 的实例。如果该值为 `null`，则新的实例为空。 array 转换成 object 将使键名成为属性名并具有相对应的值。注意：在这个例子里， 使用 PHP 7.2.0 之前的版本，数字键只能通过迭代访问。

示例 #2 转换为对象

    <?php
    $obj = (object) array('1' => 'foo');
    var_dump(isset($obj->{'1'})); // 输出 'bool(true)'

    // 自 PHP 8.1 起弃用
    var_dump(key($obj)); // 输出 'string(1) "1"'
    ?>

对于其他值，会包含进成员变量名 `scalar`。

示例 #3 `(object)` cast

    <?php
    $obj = (object) 'ciao';
    echo $obj->scalar;  // 输出 'ciao'
    ?>

## Enum 枚举

(PHP 8 >= 8.1.0)

### 枚举基础

枚举是在类、类常量基础上的约束层， 目标是提供一种能力：定义包含可能值的封闭集合类型。

    <?php
    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    function do_stuff(Suit $s)
    {
        // ...
    }

    do_stuff(Suit::Spades);
    ?>

详情参阅枚举章节。

### 类型转换

将 enum 转换为 object 不会有变化。 将 enum 转换为 array， 纯粹枚举会创建单个 `name` 键的数组； 回退枚举创建带 `name` 和 `value` 键的数组。 其他类型转换都会导致错误。

## Resource 资源类型

资源 resource 是一种特殊变量，保存了到外部资源的一个引用。资源是通过专门的函数来建立和使用的。所有这些函数及其相应资源类型见附录。

参见 get_resource_type()。

### 转换为资源

由于资源类型变量保存有为打开文件、数据库连接、图形画布区域等的特殊句柄，因此将其它类型的值转换为资源没有意义。

### 释放资源

引用计数系统是 Zend 引擎的一部分，可以自动检测到一个资源不再被引用了（和 Java 一样）。这种情况下此资源使用的所有外部资源都会被垃圾回收系统释放。因此，很少需要手工释放内存。

> 注意: 持久数据库连接比较特殊，它们不会被垃圾回收系统销毁。参见数据库永久连接一章。

## Callable

callable 是对函数或方法的引用，作为参数传递给其他函数，使用 callable 类型声明来表示。

    <?php
    function foo(callable $callback) {
        $callback();
    }
    ?>

一些函数接受回调函数作为参数，例如 array_map()、usort() 或 preg_replace_callback()。

### callable 的创建

callable 是一种表示可调用内容的类型。Callable 可作为参数传递给需要回调参数的函数或方法，也可直接调用。callable 类型不能用于类属性的类型声明，此时应使用 Closure 类型声明。

Callable 可通过多种方式创建：

- Closure 对象
- 包含函数名或方法名的 string
- 索引 0 为类名或者 object，索引 1 是方法名的 array
- 实现了 __invoke() 魔术方法的 object

Closure 对象可通过匿名函数语法、箭头函数语法、一级可调用语法，或 Closure::fromCallable() 方法创建。

> 注意: 一级可调用语法 仅自 PHP 8.1.0 起可用。

示例 #1 使用 Closure 的 Callback 示例

    <?php
    // 使用匿名函数语法
    $double1 = function ($a) {
        return $a * 2;
    };

    // 使用一级可调用语法
    function double_function($a) {
        return $a * 2;
    }
    $double2 = double_function(...);

    // 使用箭头函数语法
    $double3 = fn($a) => $a * 2;

    // 使用 Closure::fromCallable
    $double4 = Closure::fromCallable('double_function');

    // 此处使用 closure 作为回调，将范围内每个元素的值翻倍。
    $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);

    ?>

以上示例在 PHP 8.1 中的输出：

    2 4 6 8 10
    2 4 6 8 10
    2 4 6 8 10
    2 4 6 8 10

callable 也可以是包含函数名或静态方法名的字符串。除语言结构（如 array()、echo、empty()、eval()、isset()、list()、print 或 unset()）外，任何内置或用户自定义函数均可使用。

静态类方法可在不实例化该类 object 的情况下使用，方式包括：创建数组，其中索引 0 为类名，索引 1 为方法名；或使用作用域解析运算符 `::` 的特殊语法，例如 `'ClassName::methodName'`。

已实例化 object 的方法在以数组形式提供时可作为 callable，其中索引 0 为该 object，索引 1 为方法名。

Closure 对象与 callable 类型的主要区别在于，Closure 对象与作用域无关，始终可直接调用，而 callable 类型可能依赖于作用域，不一定能直接调用。创建 callable 时，推荐使用 Closure。

> 注意: Closure 对象绑定于其创建时所在的作用域，而以字符串或数组形式引用类方法的 callable 则在其被调用的作用域中解析。若需从 private 或 protected 方法创建可在类作用域外部调用的可调用项，应使用 Closure::fromCallable() 或一级可调用语法。

PHP 允许创建 callable，可用作回调参数，但无法直接调用。它们是上下文相关的 callable，引用类继承层次中的某个类方法，例如 `'parent::method'` 或 `["static", "method"]`。

> 注意: 自 PHP 8.2.0 起，已弃用上下文相关的 callable 。应通过将 `'parent::method'` 替换为 `parent::class . '::method'`，或使用一级可调用语法，以消除上下文依赖。

示例 #2 使用 call_user_function() 调用各类 callable

    <?php

    // callback 函数示例
    function my_callback_function() {
        echo 'hello world!', PHP_EOL;
    }

    // callback 方法示例
    class MyClass {
        static function myCallbackMethod() {
            echo 'Hello World!', PHP_EOL;
        }
    }

    // 类型 1：简单回调
    call_user_func('my_callback_function');

    // 类型2：静态类方法回调
    call_user_func(['MyClass', 'myCallbackMethod']);

    // 类型 3：对象方法回调
    $obj = new MyClass();
    call_user_func([$obj, 'myCallbackMethod']);

    // 类型 4：静态类方法回调
    call_user_func('MyClass::myCallbackMethod');

    // 类型 5：使用 ::class 关键字的静态类方法回调
    call_user_func([MyClass::class, 'myCallbackMethod']);

    // 类型 6：相对静态类方法调用
    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']); // 自 PHP 8.2.0 起弃用

    // 类型 7：实现 __invoke 的对象用于 callable
    class C {
        public function __invoke($name) {
            echo 'Hello ', $name;
        }
    }

    $c = new C();
    call_user_func($c, 'PHP!');
    ?>

以上示例会输出：

    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!

> 注意: 在函数中注册有多个回调内容时(如使用 call_user_func() 与 call_user_func_array())，如在前一个回调中有未捕获的异常，其后的将不再被调用。

## Mixed

mixed 类型接受每个值。等同于联合类型 `object|resource|array|string|float|int|bool|null`。自 PHP 8.0.0 起可用。

在类型理论中，mixed 是顶级类型。这意味着其它所有类型都是它的子类型。

## Void

void 是仅用于返回类型，表示函数不返回值，但该函数仍可能会终止。因此，它不能成为联合类型声明的一部分。自 PHP 7.1.0 起可用。

> 注意: 即使函数的返回类型是 void，但仍然可以返回值，但值只能始终为 `null`。

## Never

never 是仅用于返回的类型，表示函数不会终止。这意味着它要么调用 exit()，要么抛出异常，要么无限循环。因此，它不能是联合类型声明的一部分。自 PHP 8.1.0 起可用。

never 是类型理论中的最底层类型。这意味着它是其它所有类型的子类型，并在可以在继承期间替换其它任何返回类型。

## 相对类类型

这些类型声明只能在类中使用。

### self

该值必须是与类型声明所在类相同的类的 `instanceof` 实例。

### parent

值必须是 `instanceof` 使用了类型声明的父级类。

### static

static 是仅用于返回值的类型，要求返回的值必须是调用该方法的类的 `instanceof` 实例。自 PHP 8.0.0 起可用。

## 单例类型

单例类型（singleton type）是只允许单个值的类型。PHP 支持两种单例类型：false（自 PHP 8.0.0 起支持），true（自 PHP 8.2.0 起支持）。

警告

在 PHP 8.2.0 之前，false 类型只能用作联合类型的一部分。

> 注意: 无法定义自定义单例类型。建议改用枚举。

## Iterable 可迭代对象

Iterable 是内置编译时 `array|Traversable` 的类型别名。从 PHP 7.1.0 到 PHP 8.2.0 之间的描述来看，iterable 是内置伪类型，充当上述类型别名，也可以用于类型声明。iterable 类型可用于 `foreach` 或在生成器中使用 yield from。

> 注意:

> 将可迭代对象声明为返回类型的函数也可能是 生成器。

> 示例 #1 可迭代生成器返回类型的示例

>     <?php

>     function gen(): iterable {
>         yield 1;
>         yield 2;
>         yield 3;
>     }

>     foreach(gen() as $value) {
>         echo $value, "\n";
>     }
>     ?>

## 类型声明

类型声明可以用于函数的参数、返回值， PHP 7.4.0 起还可以用于类的属性， PHP 8.3.0 起还可以用于类的常量。 如果预期类型在调用时不匹配，则会抛出一个 TypeError 异常。

PHP 支持各种单一类型，除了 resource 之外，都可以用于用户级别类型声明。这个页面包含了不同类型间的可用性变更日志以及在类型声明中用法的文档。

> 注意:

> 当类实现了接口方法或者重新实现了父级类中定义的方法时，必须与上述定义兼容。如果方法遵循方差规则，则兼容该方法。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | 新增了对类、接口、trait 和枚举常量类型的支持。
8.2.0 | 新增对 DNF 类型的支持。
8.2.0 | 新增对 literal 类型 true 的支持。
8.2.0 | 现在可以单独使用 null 和 false。
8.1.0 | 新增对交集类型的支持。
8.1.0 | 弃用 void 函数通过引用返回。
8.1.0 | 新增对返回类型 never 的支持。
8.0.0 | 新增对 mixed 类型的支持。
8.0.0 | 新增对返回类型 static 的支持。
8.0.0 | 新增对联合类型的支持。
7.4.0 | 新增对类属性类型化的支持。
7.2.0 | 新增对 object 类型的支持。
7.1.0 | 新增对 iterable 类型的支持。
7.1.0 | 新增对 void 类型的支持。
7.1.0 | 新增对可为 null 类型的支持。

### 原子类型使用说明

原子类型具有直接明了的行为，但存在一些细微注意事项，本节对此进行了描述。

#### 标量类型

警告

标量类型（bool、int、float、string）不支持别名。别名反而会视为类或接口名。例如，使用 `boolean` 作为类型声明，将要求值是 `instanceof` 类或接口 `boolean`，而不是类型 bool。

    <?php
        function test(boolean $param) {}
        test(true);
    ?>

以上示例在 PHP 8 中的输出：

    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

> 注意:

> 从 PHP 8.1.0 起弃用 void 函数通过引用返回，因为这样的函数自相矛盾。在此之前调用时总是会发出如下 `E_NOTICE`：Only variable references should be returned by reference。

>     <?php
>     function &test(): void {}
>     ?>

#### Callable 类型

此类型不能用于类属性的类型声明。

> 注意: 无法指定函数的签名。

#### 通过引用传递的参数类型

如果通过引用传递的参数有类型声明，则变量的类型仅在调用函数时检查，返回时不会检查。这意味着函数可以改变引用变量的类型。

示例 #1 通过引用传递的参数类型

    <?php
    function array_baz(array &$param)
    {
        $param = 1;
    }
    $var = [];
    array_baz($var);
    var_dump($var);
    array_baz($var);
    ?>

以上示例的输出类似于：

    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

### 复合类型使用说明

复合类型声明有几个限制，并且在编译时执行冗余检查以避免简单的错误。

警告

在 PHP 8.2 之前，也就是没引入 DNF 之前，交集类型和联合类型不能组合使用。

#### 联合类型

警告

在一个联合类型中不能同时用两个单例类型 false 和 true。而是使用 bool 替代。

警告

在 PHP 8.2.0 之前，由于 false 和 null 不能作为独立的类型使用，因此不允许仅由这些类型组成联合类型。这还包括以下类型：false、`false|null`, 和 `?false`。

##### 可为 null 类型语法糖

单个基本类型声明可以通过在类型前添加问号（`?`）来标记可为 null。因此 `?T` 和 `T|null` 是相同的。

> 注意: 该语法自 PHP 7.1.0 起支持，且早于完整的（generalized）联合类型支持。

> 注意:

> 也可以通过设置参数的参数的默认值为 `null` 来实现允许为 null。但并不建议这么做，因为如果在子类中更改了默认值，会引发类型兼容冲突，需要将 null 类型添加到类型声明中。 此行为在 PHP 8.4 中也被弃用。

> 示例 #2 使参数可以为 null 的旧方法

>     <?php
>     class C {}

>     function f(C $c = null) {
>         var_dump($c);
>     }

>     f(new C);
>     f(null);
>     ?>

> 以上示例会输出：

>     object(C)#1 (0) {
>     }
>     NULL

#### 重复冗余的类型

为了能捕获复合类型声明中的简单错误，不需要类加载检测到的冗余类型将导致编译时错误。包含：

- 解析出来的类型只能出现一次。例如这样的类型 `int|string|INT` 或 `Countable&Traversable&COUNTABLE` 会导致错误。
- 使用 mixed 或 never 会导致错误。
- 对于联合类型：
  - 使用了 bool 时就不能再附带使用 false 或者 true。
  - 使用了 object 时就不能再附带使用 class 类型。
  - 使用了 iterable 时，不能再附带使用 array 和 Traversable。
- 对于交集类型：
  - 使用 class-type 以外的类型会导致错误。
  - 使用 self、parent 或 static 都会导致错误。
- DNF 类型：
  - 如果使用了更通用的类型，则更加严格的那个类型就是多余的。
  - 使用两个相同的交集类型。

> 注意: 不过它不能确保类型最小化，因为要达到这样的效果，还要加载使用类型的 class。

例如，假设 `A` 和 `B` 都是一个类的别名， 而 `A|B` 仍然是有效的，哪怕它可以被简化为 `A` 或 `B`。 同样的，如果 `B extends A {}`，那 `A|B` 仍然是有效的联合类型，尽管它可以被简化为 `A`。

    <?php
    function foo(): int|INT {} // 不允许
    function foo(): bool|false {} // 不允许
    function foo(): int&Traversable {} // 不允许
    function foo(): self&Traversable {} // 不允许

    use A as B;
    function foo(): A|B {} // 不允许 ("use" 是名称解析的一部分)
    function foo(): A&B {} // 不允许 ("use" 是名称解析的一部分)

    class_alias('X', 'Y');
    function foo(): X|Y {} // 允许 (运行时才能知道重复性)
    function foo(): X&Y {} // 允许 (运行时才能知道重复性)
    ?>

### 示例

示例 #3 基础类类型声明

    <?php
    class C {}
    class D extends C {}

    // 没有继承 C。
    class E {}

    function f(C $c) {
        echo get_class($c)."\n";
    }

    f(new C);
    f(new D);
    f(new E);
    ?>

以上示例在 PHP 8 中的输出：

    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

示例 #4 基础接口类型声明

    <?php
    interface I { public function f(); }
    class C implements I { public function f() {} }

    // 没有实现（implement）I。
    class E {}

    function f(I $i) {
        echo get_class($i)."\n";
    }

    f(new C);
    f(new E);
    ?>

以上示例在 PHP 8 中的输出：

    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

示例 #5 基础返回类型声明

    <?php
    function sum($a, $b): float {
        return $a + $b;
    }

    // Note that a float will be returned.
    var_dump(sum(1, 2));
    ?>

以上示例会输出：

    float(3)

示例 #6 返回对象

    <?php
    class C {}

    function getC(): C {
        return new C;
    }

    var_dump(getC());
    ?>

以上示例会输出：

    object(C)#1 (0) {
    }

示例 #7 可为 null 参数类型声明

    <?php
    class C {}

    function f(?C $c) {
        var_dump($c);
    }

    f(new C);
    f(null);
    ?>

以上示例会输出：

    object(C)#1 (0) {
    }
    NULL

示例 #8 可为 null 返回类型声明

    <?php
    function get_item(): ?string {
        if (isset($_GET['item'])) {
            return $_GET['item'];
        } else {
            return null;
        }
    }
    ?>

示例 #9 类属性类型化声明

    <?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;
        }
    }
    ?>

### 严格类型

默认如果可能，PHP 会强制转化不合适的类型为想要的标量类型。 比如，参数想要 string，传入的是 int， 则会获取 string 类型的变量。

可以按文件开启严格模式。 在严格模式下，只能接受完全匹配的类型，否则会抛出 TypeError。 唯一的例外是 int 值也可以传入声明为 float 的类型。

警告

通过内部函数调用函数时，不会受 `strict_types` 声明影响。

要开启严格模式，使用 `declare` 开启 `strict_types`：

> 注意:

> 文件开启严格类型后的内部调用函数将应用严格类型， 而不是在声明函数的文件内开启。 如果文件没有声明开启严格类型，而被调用的函数所在文件有严格类型声明， 那将遵循调用者的设置（开启类型强制转化）， 值也会强制转化。

> 注意:

> 只有为标量类型的声明开启严格类型。

示例 #10 参数值的严格类型

    <?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));
    ?>

以上示例在 PHP 8 中的输出：

    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

示例 #11 参数值的类型强制转化

    <?php
    function sum(int $a, int $b) {
        return $a + $b;
    }

    var_dump(sum(1, 2));

    // 以下会强制转化为整型，注意以下内容输出！
    var_dump(sum(1.5, 2.5));
    ?>

以上示例会输出：

    int(3)
    int(3)

示例 #12 返回值的严格类型

    <?php
    declare(strict_types=1);

    function sum($a, $b): int {
        return $a + $b;
    }

    var_dump(sum(1, 2));
    var_dump(sum(1, 2.5));
    ?>

以上示例会输出：

    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

## 类型转换

PHP 在变量声明时不需要定义类型。在这种情况下，变量的类型由存储的值决定。也就是说，如果 string 赋值给 $var，然后 $var 的类型就是 string。之后将 int 值赋值给 $var，它将是 int 类型。

PHP 可能会尝试在某些上下文中自动将值转换为另一种类型。不同的上下文有：

- 数字
- 字符串
- 逻辑
- 整数和字符串
- 比较
- 函数

> 注意: 当值需要解释为不同类型时，值本身不会改变类型。

强制将变量当做某种变量来求值，参见类型转换一节。要更改变量的类型，请参阅 settype() 函数。

### 数字上下文

使用算术运算符时的上下文。

在这种情况下，如果任一运算对象是 float（或者不能解释为 int），则两个运算对象都将解释为 float，结果也将是 float。否则，运算对象将解释为 int，结果也将是 int。自 PHP 8.0.0 起，如果无法解释其中一个运算对象，则会抛出 TypeError。

### 字符串上下文

使用 echo、print、字符串插值或者字符串连接运算符时的上下文。

这种情况下，值将会解释为 string。如果值无法解释，那么会抛出 TypeError。在 PHP 7.4.0 之前，会引发 `E_RECOVERABLE_ERROR`。

### 逻辑上下文

使用条件语句、三元运算符或逻辑运算符时的上下文。

在这种情况下，值将会解释为 bool。

### 整数和字符串上下文

使用位运算符时的上下文。

在这种情况下，如果所有的运算对象都是 string，则结果也将是 string。否则运算对象将解释为 int，结果也将是 int。如果其中一个运算对象无法解释，则会抛出 TypeError。

### 比较上下文

使用比较运算符时的上下文。

在此上下文中发生的类型转换在比较多种类型表中进行了说明。

### 函数上下文

将值传递给已声明类型的参数、属性，或从声明了返回类型的函数返回值时的上下文。

在此上下文中，值必须是类型值。但存在两个例外，第一个是如果值为 int，但声明的类型是 float，然后整数会转换为浮点数。第二个是如果声明的类型是 scalar 类型，值可转换为标量类型，并且强制类型模式处于活动状态（默认），值会转换为可接受的标量值。参见下文查看有关此行为的描述。

警告

内部函数自动将 `null` 转换为标量类型，此行为自 PHP 8.1.0 起弃用。

#### 使用简单类型声明的强制类型

- bool 类型声明：值将解释为 bool。
- int 类型声明：如果明确定义转换，则值将解释为 int。例如，字符串是数字。
- float 类型声明：如果明确定义转换，则值将解释为 float。例如，字符串是数字。
- string 类型声明：值将解释为 string。

#### 使用联合类型的强制类型

当未启用 `strict_types` 时，声明的标量类型会受到有限的隐式类型转换的影响。如果值的精确类型不是联合的一部分，然后会按照以下优先顺序选择目标类型：

1. int
2. float
3. string
4. bool

如果类型存在于 union 类型中，并且值可以根据 PHP 现有的类型检查语义转换为此类型，则选择该类型。否则，尝试下一个类型
警告

有个例外，如果值是字符串，并且 int 和 float 都是联合类型的一部分，首选类型则通过现有的数字字符串语义决定。例如 `"42"` 选择 int，`"42.0"` 选择 float。

> 注意:

> 不属于上述优先级列表的类型不会进行隐式转换。特别是，不会出现对 null、false 和 true 类型的隐式转换。

示例 #1 类型转换为 union 类型中的一个的示例

    <?php
    // int|string
    42    --> 42          // 具体类型
    "42"  --> "42"        // 具体类型
    new ObjectWithToString --> "Result of __toString()"
                          // 对象绝不会兼容 int，回退到 string
    42.0  --> 42          // int 兼容 float
    42.1  --> 42          // int 兼容 float
    1e100 --> "1.0E+100"  // float 对于 int 类型来说太大了，回退为 string
    INF   --> "INF"       // float 对于 int 类型来说太大了，回退为 string
    true  --> 1           // int 兼容 bool
    []    --> TypeError   // int 或 string 不兼容 array

    // int|float|bool
    "45"    --> 45        // int 数字 string
    "45.0"  --> 45.0      // float 数字 string

    "45X"   --> true      // 不是 numeric string，回退为 bool
    ""      --> false     // 不是 numeric string，回退为 bool
    "X"     --> true      // 不是 numeric string，回退为 bool
    []      --> TypeError // int、float 或 bool 不兼容 array
    ?>

### 类型转换

类型转换通过在值前面的括号中写入类型来将值转换指定的类型。

示例 #2 类型转换

    <?php
    $foo = 10;   // $foo 是 int
    $bar = (bool) $foo;   // $bar 是 bool

    var_dump($bar);
    ?>

允许的转换是：

- `(int)` ——转换为 int
- `(bool)` ——转换为 bool
- `(float)` ——转换为 float
- `(string)` ——转换为 string
- `(array)` ——转换为 array
- `(object)` ——转换为 object
- `(unset)` ——转换为 NULL

警告

`(integer)` 是 `(int)` 转换的别名。`(boolean)` 是 `(bool)` 转换的别名。`(binary)` 是 `(string)` 转换的别名。`(double)` 和 `(real)` 是 `(float)` 转换的别名。这些转换不使用标准的类型名称，自 PHP 8.5.0 起已弃用。

警告

自 PHP 7.4.0 起弃用 `(real)` 转换别名，并在 PHP 8.0.0 中移除。

警告

自 PHP 7.2.0 起弃用 `(unset)` 转换。注意 `(unset)` 转换等同于将值 NULL 通过赋值或者调用给变量。自 PHP 8.0.0 起移除 `unset` 转换。

警告

向前兼容 `(binary)` 转换和 `b` 前缀转换。注意 `(binary)` 转换和 `(string)` 相同，但是这可能会改变且不应依赖。

> 注意:

> 类型转换的括号中的空格将被忽略。 因此，以下两个转换是等价的：

>     <?php
>     $foo = (int) $bar;
>     $foo = ( int ) $bar;
>     ?>

将文字 string 和变量转换为二进制 string：

    <?php
    $binary = (binary) $string;
    $binary = b"binary string";
    ?>

除了将变量转换为 string 之外，还可以将变量放在双引号内。

示例 #3 不同的转换机制

    <?php
    $foo = 10;            // $foo 是 int
    $str = "$foo";        // $str 是 string
    $fst = (string) $foo; // $fst 也是 string

    // 打印出 "they are the same"
    if ($fst === $str) {
        echo "they are the same", PHP_EOL;
    }
    ?>

有时在类型之间转换时确切地会发生什么可能不是很明显。更多信息见如下不分：

- 转换为 bool
- 转换为 int
- 转换为 float
- 转换为 string
- 转换为 array
- 转换为 object
- 转换为 resource
- 转换为 NULL
- 类型比较表

> 注意: 因为 PHP 的 string 支持使用与 array 索引相同的语法，通过偏移量进行索引，所以以下示例适用于所有 PHP 版本：

> 示例 #4 使用字符串的数组偏移

>     <?php
>     $a    = 'car'; // $a 是 string
>     $a[0] = 'b';   // $a 依然是 string
>     echo $a;       // bar
>     ?>

> 请查看章节标题为存取和修改字符串中的字符获取更多信息。

# 变量

## 目录

- 基础
- 预定义变量
- 变量作用域
- 可变变量
- 来自 PHP 之外的变量

## 基础

PHP 中的变量用一个美元符号后面跟变量名来表示。变量名是区分大小写的。

有效的变量名由字母（`A-Z`、`a-z` 或 128 到 255 之间的字节）或者下划线开头，后面跟上任意数量的字母，数字，或者下划线。 按照正常的正则表达式，它将被表述为：`^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`。

> 注意: PHP 不支持 Unicode 变量名，但是，某些字符编码（例如 UTF-8）会以这样的方式对字符进行编码，即多字节字符的所有字节都在允许的范围内，从而使其成为有效的变量名。

> 注意: `$this` 是一个特殊的变量，它不能被赋值。PHP 7.1.0 之前，间接赋值（例如通过使用可变变量）是可能的。

小技巧

请参见用户空间命名指南。

示例 #1 有效变量名

    <?php
    $var = 'Bob';
    $Var = 'Joe';
    echo "$var, $Var";      // 输出 "Bob, Joe"

    $_4site = 'not yet';    // 合法变量名；以下划线开头
    $i站点is = 'mansikka';  // 合法变量名；可以用中文
    ?>

示例 #2 无效变量名

    <?php
    $4site = 'not yet';     // 非法变量名；以数字开头

PHP 接受任意字节序列作为变量名。不遵循上述命名规则的变量名只能在运行时动态访问。有关如何访问变量的信息，请参阅可变变量。

示例 #3 访问模糊的变量名

    <?php
    ${'invalid-name'} = 'bar';
    $name = 'invalid-name';
    echo ${'invalid-name'}, " ", $$name;
    ?>

以上示例会输出：

    bar bar

变量默认始终传值赋值。那也就是说，当表达式的值赋值给变量时，整个原始表达式的值被赋值到目标变量。这意味着，例如，当一个变量的值赋予另外一个变量时，改变其中一个变量的值，将不会影响到另外一个变量。有关这种类型的赋值操作，请参阅表达式一章。

PHP 也提供了另外一种方式给变量赋值：引用赋值。这意味着新的变量简单的引用（换言之，“成为其别名” 或者 “指向”）了原始变量。改动新的变量将影响到原始变量，反之亦然。

使用引用赋值，简单地将一个 & 符号加到将要赋值的变量前（源变量）。例如，下列代码片断将输出“My name is Bob”两次：

    <?php
    $foo = 'Bob';              // 将 'Bob' 赋给 $foo
    $bar = &$foo;              // 通过 $bar 引用 $foo
    $bar = "My name is $bar";  // 修改 $bar 变量
    echo $bar;
    echo $foo;                 // $foo 的值也被修改
    ?>

有一点重要事项必须指出，那就是只有变量才可以引用赋值。

    <?php
    $foo = 25;
    $bar = &$foo;      // 合法的赋值
    $bar = &(24 * 7);  // 非法; 引用没有名字的表达式

    function test()
    {
       return 25;
    }

    $bar = &test();    // 无效，因为 test() 没有通过引用返回变量。
    ?>

在 PHP 中声明变量不是必需的，但这是一种非常好的做法。访问未定义的变量将导致 `E_WARNING`（在 PHP 8.0.0 之前，为 `E_NOTICE`）。未定义的变量的默认值为 `null`。isset() 语言结构可用于检测变量是否已初始化。

示例 #4 未初始化变量的默认值

    <?php
    // 未设置和未引用（不使用上下文）的变量。
    var_dump($unset_var);
    ?>

以上示例会输出：

    Warning: Undefined variable $unset_var in ...
    NULL

PHP 允许从未定义的变量自动生成数组（自动创建新数组）。 将元素追加到未定义的变量将创建一个新数组，并且不会生成警告。

示例 #5 未定义变量自动生成数组

    <?php
    $unset_array[] = 'value'; // 不会生成警告。
    ?>

警告

当将一个文件包含在另一个使用相同变量名的文件中时，依赖未初始化变量的默认值是有问题的。

可以使用 unset() 语言结构来销毁变量。

有关变量相关函数的信息，请参阅变量函数参考。

## 预定义变量

PHP 提供了许多 预定义变量。PHP 提供了一套附加的预定数组，这些数组变量包含了来自 web 服务器（如果可用），运行环境，和用户输入的数据。这些数组在每个作用域内自动可用。因此通常被称为自动全局变量（autoglobals）或者超全局变量（superglobals）。（PHP 中没有用户自定义超全局变量的机制。）详情参阅超全局变量列表。

> 注意: 可变变量

> 超级全局变量不能被用作函数或类方法中的可变变量。

如果某些 variables_order 中的变量没有设定，它们的对应的 PHP 预定义数组也是空的。

## 变量作用域

变量的作用域是定义该变量的上下文。PHP 有函数作用域和全局作用域。在函数之外定义的任何变量都仅限于全局作用域。当包含文件时，该文件中的代码继承了包含语句所在行的变量作用域。

示例 #1 全局变量作用域示例

    <?php
    $a = 1;
    include 'b.inc'; // 变量 $a 将在 b.inc 内可用
    ?>

在命名函数或匿名函数内创建的任何变量都仅限于函数主体的作用域。然而，箭头函数会绑定父级作用域中的变量，使其在函数体内可用。如果在函数内部 include 文件，那么包含文件中的变量将如同在调用函数内部定义一样可用。

示例 #2 局部变量作用域的示例

    <?php
    $a = 1; // 全局作用域

    function test()
    {
        echo $a; // $a 变量 $a 未定义，因为它引用了 $a 的局部版本
    }
    ?>

下面的示例会生成未定义变量 `E_WARNING`（PHP 8.0.0 之前是 `E_NOTICE`）诊断提示。这是因为 echo 语句引用了局部版本的变量 $a，而且在这个作用域内，它并没有被赋值。注意这与 C 语言有一点点不同，因为 C 中的全局变量会自动提供给函数，除非被局部定义特别覆盖。这可能引起一些问题，有些人可能不小心就改变了一个全局变量。PHP 中全局变量在函数中使用时必须声明为 global。

### `global` 关键字

`global` 关键字用于将变量从全局作用域绑定到局部作用域。该关键字可以与变量列表或单个变量一起使用。将创建引用同名全局变量的局部变量。如果全局变量不存在，则将在全局作用域内创建该变量并赋值为 `null`。

示例 #3 使用 `global`

    <?php
    $a = 1;
    $b = 2;

    function Sum()
    {
        global $a, $b;

        $b = $a + $b;
    }

    Sum();
    echo $b;
    ?>

以上示例会输出：

    3

在函数中声明了全局变量 $a 和 $b 之后，对任一变量的所有引用都会指向其全局版本。对于一个函数能够声明的全局变量的最大个数，PHP 没有限制。

在全局作用域内访问变量的第二个办法，是用特殊的 PHP 自定义 $GLOBALS 数组。前面的例子可以写成：

示例 #4 使用 $GLOBALS 替代 global

    <?php
    $a = 1;
    $b = 2;

    function Sum()
    {
        $GLOBALS['b'] = $GLOBALS['a'] + $GLOBALS['b'];
    }

    Sum();
    echo $b;
    ?>

$GLOBALS 是一个关联数组，每一个变量为一个元素，键名对应变量名，值对应变量的内容。$GLOBALS 之所以在全局作用域内存在，是因为 $GLOBALS 是一个超全局变量。以下范例显示了超全局变量的用处：

示例 #5 演示超全局变量和作用域的例子

    <?php
    function test_superglobal()
    {
        echo $_POST['name'];
    }
    ?>

> 注意: 在函数外部使用 `global` 关键字不是错误。如果文件是从函数内部 include 的，则可以使用它。

### 使用 `static` 变量

变量作用域的另一个重要特性是 static 变量。静态变量仅在局部函数作用域中存在，但当程序执行离开此作用域时，其值并不丢失。看看下面的例子：

示例 #6 演示需要静态变量的例子

    <?php
    function Test()
    {
        $a = 0;
        echo $a;
        $a++;
    }
    ?>

本函数没什么用处，因为每次调用时都会将 $a 的值设为 `0` 并输出 `0`。将变量加一的 $a++ 没有作用，因为一旦退出本函数则变量 $a 就不存在了。要写一个不会丢失本次计数值的计数函数，要将变量 $a 定义为静态的：

示例 #7 使用静态变量的例子

    <?php
    function test()
    {
        static $a = 0;
        echo $a;
        $a++;
    }
    ?>

现在，变量 $a 仅在第一次调用 test() 函数时被初始化，之后每次调用 test() 函数都会输出 $a 的值并加一。

静态变量也提供了一种处理递归函数的方法。以下这个简单的函数递归计数到 10，使用静态变量 $count 来判断何时停止：

示例 #8 静态变量与递归函数

    <?php
    function test()
    {
        static $count = 0;

        $count++;
        echo $count;
        if ($count < 10) {
            test();
        }
        $count--;
    }
    ?>

在 PHP 8.3.0 之前，静态变量只能使用常量表达式进行初始化。自 PHP 8.3.0 起，还允许使用动态表达式（例如函数调用）：

示例 #9 声明静态变量

    <?php
    function foo(){
        static $int = 0;          // 正确
        static $int = 1+2;        // 正确
        static $int = sqrt(121);  // 自 PHP 8.3.0 起正确

        $int++;
        echo $int;
    }
    ?>

匿名函数内的静态变量仅在该特定函数实例中存在。如果每次调用时都重新创建匿名函数，则静态变量将重新初始化。

示例 #10 匿名函数内的静态变量

    <?php
    function exampleFunction($input) {
        $result = (static function () use ($input) {
            static $counter = 0;
            $counter++;
            return "Input: $input, Counter: $counter\n";
        });

        return $result();
    }

    // 调用 exampleFunction 将重新创建匿名函数，因此静态
    // 变量不会保留其值。
    echo exampleFunction('A'); // 输出：Input: A, Counter: 1
    echo exampleFunction('B'); // 输出：Input: B, Counter: 1
    ?>

从 PHP 8.1.0 开始，当继承（不是覆盖）使用有静态变量的方法时，继承的方法将会跟父级方法共享静态变量。这意味着方法中的静态变量现在跟静态属性有相同的行为。

自 PHP 8.3.0 起，可以使用任意表达式初始化静态变量。这意味着也说，像是方法调用可用于初始化静态变量。

示例 #11 在继承方法中使用静态变量

    <?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)，PHP 8.1.0 之前 int(1)
    var_dump(Bar::counter()); // int(4)，PHP 8.1.0 之前 int(2)
    ?>

### `global` 和 `static` 变量的引用

对于变量的 static 和 global 定义是以引用的方式实现的。例如，在一个函数作用域内部用 `global` 语句导入的一个真正的全局变量实际上是建立了一个到全局变量的引用。这有可能导致预料之外的行为，如以下例子所演示的：

    <?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);
    ?>

以上示例会输出：

    NULL
    object(stdClass)#1 (0) {
    }

类似的行为也适用于 `static` 语句。引用并不是静态地存储的：

    <?php
    function &get_instance_ref() {
        static $obj;

        echo 'Static object: ';
        var_dump($obj);
        if (!isset($obj)) {
            $new = new stdClass;
            // 将一个引用赋值给静态变量
            $obj = &$new;
        }
        if (!isset($obj->property)) {
            $obj->property = 1;
        } else {
            $obj->property++;
        }
        return $obj;
    }

    function &get_instance_noref() {
        static $obj;

        echo 'Static object: ';
        var_dump($obj);
        if (!isset($obj)) {
            $new = new stdClass;
            // 将一个对象赋值给静态变量
            $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();
    ?>

以上示例会输出：

    Static object: NULL
    Static object: NULL

    Static object: NULL
    Static object: object(stdClass)#3 (1) {
      ["property"]=>
      int(1)
    }

此示例说明，当把引用赋值给静态变量时，第二次调用 `&get_instance_ref()` 函数时不会记住该引用。

## 可变变量

有时候使用可变变量名是很方便的。就是说，一个变量的变量名可以动态的设置和使用。一个普通的变量通过声明来设置，例如：

    <?php
    $a = 'hello';
    ?>

一个可变变量获取了一个普通变量的值作为这个可变变量的变量名。在上面的例子中 hello 使用了两个美元符号（$）以后，就可以作为一个可变变量的变量了。例如：

    <?php
    $$a = 'world';
    ?>

这时，两个变量都被定义了：$a 的内容是“hello”并且 $hello 的内容是“world”。因此，以下语句：

    <?php
    echo "$a {$$a}";
    ?>

与以下语句输出完全相同的结果：

    <?php
    echo "$a $hello";
    ?>

它们都会输出：hello world。

要将可变变量用于数组，必须解决模棱两可的问题。也就是说，如果解析器看到 $$a[1]，那么解析器需要知道是将 $a[1] 作为变量，还是将 $$a 作为个变量并取出该变量中索引为 `[1]` 的值。解决此问题的语法是，对第一种情况用 ${$a[1]}，对第二种情况用 ${$a}[1]。

类的属性也可以通过可变属性名来访问。可变属性名将在该调用所处的作用域内被解析。例如，对于 $foo->$bar 表达式，则会在局部作用域来解析 $bar 并且其值将被用于 $foo 的属性名。对于 $bar 是数组单元时也是一样。

也可使用花括号来给属性名清晰定界。最有用是在属性位于数组中，或者属性名包含有多个部分或者属性名包含有非法字符时（例如来自 json_decode() 或 SimpleXML）。

示例 #1 可变属性示例

    <?php
    class Foo {
        public $bar = 'I am bar.';
        public $arr = ['I am A.', 'I am B.', 'I am C.'];
        public $r   = 'I am 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";

    ?>

以上示例会输出：

    I am bar.
    I am bar.
    I am bar.
    I am r.
    I am B.

警告

注意，在 PHP 的函数和类的方法中，超全局变量不能用作可变变量。`$this` 变量也是一个特殊变量，不能被动态引用。

## 来自 PHP 之外的变量

### HTML 表单（GET 和 POST）

当一个表单提交给 PHP 脚本时，表单中的信息会自动在脚本中可用。有几个方法访问此信息，例如：

示例 #1 一个简单的 HTML 表单

    <form action="foo.php" method="POST">
        Name:  <input type="text" name="username"><br />
        Email: <input type="text" name="email"><br />
        <input type="submit" name="submit" value="Submit me!" />
    </form>

只有两种方法可以访问 HTML 表单中的数据。以下列出了当前有效的方法：

示例 #2 从简单的 POST HTML 表单访问数据

    <?php
    echo $_POST['username'];
    echo $_REQUEST['username'];
    ?>

使用 GET 表单也类似，只不过要用适当的 GET 预定义变量。GET 也适用于 `QUERY_STRING`（URL 中在“?”之后的信息）。因此，举例说，`http://www.example.com/test.php?id=3` 包含有可用 $_GET['id'] 来访问的 GET 数据。参见 $_REQUEST。

> 注意:

> 变量名中的点和空格被转换成下划线。例如 `<input name="a.b" />` 变成了 `$_REQUEST["a_b"]`。

PHP 也理解表单变量上下文中的数组（参见相关常见问题）。例如可以将相关的变量编成组，或者用此功能从多选输入框中取得值。例如，将表单 POST 给自己并在提交时显示数据：

示例 #3 更复杂的表单变量

    <?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 />
        Email: <input type="text" name="personal[email]" /><br />
        Beer: <br />
        <select multiple name="beer[]">
            <option value="warthog">Warthog</option>
            <option value="guinness">Guinness</option>
            <option value="stuttgarter">Stuttgarter Schwabenbräu</option>
        </select><br />
        <input type="submit" value="submit me!" />
    </form>

> 注意: 如果外部变量名以有效的数组语法开头，则将会忽略尾随字符。例如，`<input name="foo[bar]baz">` 变为 `$_REQUEST['foo']['bar']`。

#### IMAGE SUBMIT 变量名

当提交表单时，可以用一幅图像代替标准的提交按钮，用类似这样的标记：

    <input type="image" src="image.gif" name="sub" />

当用户点击到图像中的某处时，相应的表单会被传送到服务器，并加上两个变量 sub_x 和 sub_y。它们包含了用户点击图像的坐标。有经验的用户可能会注意到被浏览器发送的实际变量名包含的是一个点而不是下划线（即 sub.x 和 sub.y），但 PHP 自动将点转换成了下划线。

### HTTP Cookie

PHP 透明地支持 » RFC 6265定义中的 HTTP cookies。Cookies 是一种在远端浏览器端存储数据并能追踪或识别再次访问的用户的机制。可以用 setcookie() 函数设定 cookies。Cookies 是 HTTP 信息头中的一部分，因此 SetCookie 函数必须在向浏览器发送任何输出之前调用。对于 header() 函数也有同样的限制。Cookie 数据会在相应的 cookie 数据数组中可用，例如 $_COOKIE 和 $_REQUEST。更多细节和例子见 setcookie() 手册页面。

> 注意: 自 PHP 7.2.34、7.3.23 和 7.4.11 起，出于安全原因，传入 cookie 的 name 不再进行 url 解码。

如果要将多个值赋给单个 cookie 变量，可以将其赋成数组。例如：

    <?php
      setcookie("MyCookie[foo]", 'Testing 1', time()+3600);
      setcookie("MyCookie[bar]", 'Testing 2', time()+3600);
    ?>

尽管 MyCookie 在脚本中是单个数组，这将会建立两个单独的 cookie。如果只需为一个 cookie 设定多个值，考虑先在值上使用 serialize() 或 explode()。

注意，除非路径或者域不同，cookie 将替换浏览器中先前的同名 cookie。因此对于购物车程序，可以保留一个计数器并一起传递，即

示例 #4 一个 setcookie() 的示例

    <?php
    if (isset($_COOKIE['count'])) {
        $count = $_COOKIE['count'] + 1;
    } else {
        $count = 1;
    }
    setcookie('count', $count, time()+3600);
    setcookie("Cart[$count]", $item, time()+3600);
    ?>

### 变量名中的点

通常，PHP 不会改变传递给脚本中的变量名。然而应该注意到点（句号）不是 PHP 变量名中的合法字符。至于原因，看看：

    <?php
    $varname.ext;  /* 非法变量名 */
    ?>

这时，解析器看到是一个名为 $varname 的变量，后面跟着一个字符串连接运算符，后面跟着一个裸字符串（即没有加引号的字符串，且不匹配任何已知的健名或保留字）'ext'。很明显这不是想要的结果。

出于此原因，要注意 PHP 将会自动将变量名中的点替换成下划线。

### 确定变量类型

因为 PHP 会判断变量类型并在需要时进行转换（通常情况下），因此在某一时刻给定的变量是何种类型并不明显。PHP 包括几个函数可以判断变量的类型，例如：gettype()，is_array()，is_float()，is_int()，is_object() 和 is_string()。参见类型一章。

HTTP 是一种文本协议，大多数（可能不是全部）超全局数组中的内容（如 $_POST 和 $_GET）将保留为字符串。PHP 不会尝试将值转换为特定类型。在下面的示例中，$_GET["var1"] 将包含字符串“null”，而 $_GET["var2"] 将包含字符串“123”。

    /index.php?var1=null&var2=123

### 更新日志

版本 | 说明
--- | ---
7.2.34, 7.3.23, 7.4.11 | 出于安全原因，传入 cookie 的 name 不再进行 URL 解码。

# 常量

## 目录

- 语法
- 预定义常量
- 魔术常量

常量是一个简单值的标识符（名字）。如同其名称所暗示的，在脚本执行期间该值不能改变（除了所谓的 魔术常量，它们其实不是常量）。常量大小写敏感。传统上常量标识符总是大写的。

> 注意:

> 在 PHP 8.0.0 之前，使用 define() 定义的常量可能不区分大小写。

常量名和其它任何 PHP 标签遵循同样的命名规则。合法的常量名以字母或下划线开始，后面跟着任何字母，数字或下划线。用正则表达式是这样表达的： `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`。

还可以使用 define() 函数来定义包含保留字或非常规名称的常量，这类常量可以通过 constant() 函数来获取名称，但是非常不推荐这种用法。

小技巧

请参见用户空间命名指南。

示例 #1 合法与非法的常量名

    <?php

    // 合法的常量名
    define("FOO",     "something");
    define("FOO2",    "something else");
    define("FOO_BAR", "something more");

    // 非法的常量名
    define("2FOO",    "something");

    // 下面的定义是合法的，但应该避免这样做：(自定义常量不要以__开头)
    // 也许将来有一天 PHP 会定义一个 __FOO__ 的魔术常量
    // 这样就会与你的代码相冲突
    define("__FOO__", "something");

    ?>

> 注意: 在这里，字母指的是 a-z，A-Z，以及从 128 到 255（0x80-0xff）的 ASCII 字符。

和 superglobals 一样，常量的范围是全局的。常量可以从脚本的任何地方被访问，而不考虑作用域。有关作用域的更多信息请阅读手册中的变量范围。

> 注意: 从 PHP 7.1.0 开始，类常量可以声明为 protected 或 private 的可见性， 使其只在其定义的类的层次范围内可用。

## 语法

可以使用 `const` 关键字或 define() 函数两种方法来定义一个常量。函数 define() 允许将常量定义为一个表达式，而 `const` 关键字有一些限制，具体可参见下述章节。一个常量一旦被定义，就不能再改变或者取消定义。

使用 `const` 关键字定义常量时，只能包含标量数据（bool、int、float 、string）。可以将常量定义为一个表达式，也可以定义为一个 array。还可以定义 resource 为常量，但应尽量避免，因为可能会造成不可预料的结果。

可以简单的通过指定其名字来取得常量的值，与变量不同，不应该在常量前面加上 `$` 符号。如果常量名是动态的，也可以用函数 constant() 来获取常量的值。用 get_defined_constants() 可以获得所有已定义的常量列表。

> 注意: 常量和（全局）变量在不同的名字空间中。这意味着例如 `true` 和 $TRUE 是不同的。

如果使用了一个未定义的常量，则会抛出 Error。 在 PHP 8.0.0 之前，调用未定义的常量会被解释为一个该常量的 字符串，即（CONSTANT 对应 "CONSTANT" ）。 此方法已在 PHP 7.2.0 中被废弃，会抛出一个 `E_WARNING` 级错误。（PHP 7.2.0 之前会发出一个 E_NOTICE 级的错误。）参见手册中为什么 $foo[bar] 是错误的（除非 `bar` 是一个常量）。这不适用于 (完全)限定的常量，如果未定义，将始终引发 Error 。

> 注意: 如果要检查是否定义了某常量，请使用 defined() 函数。

常量和变量有如下不同：

- 常量前面没有美元符号（`$`）；
- 常量可以不用理会变量的作用域而在任何地方定义和访问；
- 常量一旦定义就不能被重新定义或者取消定义；
- 常量只能计算标量值或数组。

示例 #1 定义常量

    <?php
    define("CONSTANT", "Hello world.");
    echo CONSTANT; // 输出 "Hello world."
    echo Constant; // 抛出错误：未定义的常量 "Constant"
                   // 在 PHP 8.0.0 之前，输出 "Constant" 并发出一个提示级别错误信息
    ?>

示例 #2 使用关键字 `const` 定义常量

    <?php
    // 简单的标量值
    const CONSTANT = 'Hello World';

    echo CONSTANT;

    // 标量表达式
    const ANOTHER_CONST = CONSTANT.'; Goodbye World';
    echo ANOTHER_CONST;

    const ANIMALS = array('dog', 'cat', 'bird');
    echo ANIMALS[1]; // 将输出 "cat"

    // 常量数组
    define('ANIMALS', array(
        'dog',
        'cat',
        'bird'
    ));
    echo ANIMALS[1]; // 将输出 "cat"
    ?>

    ?>

> 注意:

> 和使用 define() 来定义常量相反的是，使用 `const` 关键字定义常量必须处于最顶端的作用域，因为用此方法是在编译时定义的。这就意味着不能在函数内，循环内以及 `if` 或 `try`/`catch` 语句之内用 `const` 来定义常量。

### 参见

- 类常量

## 预定义常量

PHP 向它运行的任何脚本提供了大量的预定义常量。不过很多常量都是由不同的扩展库定义的，只有在加载了这些扩展库时才会出现，或者动态加载后，或者在编译时已经包括进去了。

## 魔术常量

一些魔术常量会根据使用位置而变化。例如 `__LINE__` 的值取决于它在脚本中使用的行。所有这些“魔术”常量都在编译时解析，而常规常量则在运行时解析。这些特殊的常量不区分大小写，如下：

PHP 的魔术常量
名字 | 说明
--- | ---
`__LINE__` | 文件中的当前行号。
`__FILE__` | 文件的完整路径和文件名。如果用在被包含文件中，则返回被包含的文件名。
`__DIR__` | 文件所在的目录。如果用在被包括文件中，则返回被包括的文件所在的目录。它等价于 `dirname(__FILE__)`。除非是根目录，否则目录中名不包括末尾的斜杠。
`__FUNCTION__` | 当前函数的名称。匿名函数则为 `{closure}`。
`__CLASS__` | 当前类的名称。类名包括其被声明的作用域（例如 `Foo\Bar`）。当用在 trait 方法中时，`__CLASS__` 是调用 trait 方法的类的名字。
`__TRAIT__` | Trait 的名字。Trait 名包括其被声明的作用域（例如 `Foo\Bar`）。
`__METHOD__` | 类的方法名。
`__PROPERTY__` | 仅在属性挂钩内有效。等同于属性的名称。
`__NAMESPACE__` | 当前命名空间的名称。
`ClassName::class` | 完整的类名。

### 参见

- ::class
- get_class()
- get_object_vars()
- file_exists()
- function_exists()

# 表达式

表达式是 PHP 最重要的构建部分。在 PHP 中，几乎所写的任何东西都是表达式。简单但却最精确的定义表达式的方式就是“任何有值的东西”。

最基本的表达式形式是常量和变量。当键入 `$a = 5`，即值 `5` 将分配给变量 $a。很明显，`5`的值为 5，换句话说 `5` 是一个值为 5 的表达式（在这里，`5` 是一个整型常量）。

赋值之后，期待 $a 的值为 5，因而如果写下 `$b = $a`，则期望其行为就像 `$b = 5` 一样。换句话说，$a 也是值为 5 的表达式。如果一切正确，那这正是将要发生的事情。

稍微复杂的表达式例子就是函数。例如，考虑以下函数：

    <?php
    function foo ()
    {
        return 5;
    }
    ?>

假如已经熟悉了函数的概念（如果没有，请查看函数的相关章节），那么本质上键入 `$c = foo()` 就如同写下 `$c = 5`，这是对的。函数是具有返回值的表达式。由于 `foo()` 返回 5，表达式“`foo()`”的值也是 5。通常函数不仅会返回静态值，还会计算一些东西。

当然，PHP 中的值并非都是整型的。PHP 支持四种标量值（标量值不能拆分为更小的单元，例如，和数组不同）类型：int 值、浮点数值（float）、string 值和 bool 值。PHP 也支持两种复合类型：数组和对象。这些值类型可以赋值给变量或者从函数返回。

PHP 和其它语言一样在表达式的道路上发展，但推进得更深远。PHP 是一种面向表达式的语言，从这一方面来讲几乎一切都是表达式。考虑刚才已经研究过的例子 `$a = 5`。很显然这里涉及到两个值，整数常量 `5` 的值以及变量 $a 的值，也被更新为 5。但事实是这里还涉及到一个额外的值，即附值语句本身的值。赋值语句本身求值为被赋的值，即 5。实际上这意味着 `$a = 5`，无论做什么，都是一个值为 5 的表达式。因此编写 `$b = ($a = 5)` 跟编写 `$a = 5; $b = 5;`（分号标志着语句的结束）是一样的。因为赋值操作的顺序是由右到左的，也可以写成 `$b = $a = 5`。

另外一个很好的面向表达式的例子就是前、后递增和递减。PHP 和多数其它语言的用户应该比较熟悉 `variable++` 和 `variable--` 符号。即递增和递减运算符。在 PHP 和 C 语言中，有两种类型的递增——前递增和后递增。本质上来讲，前递增和后递增均增加了变量的值，并且对于变量的影响是相同的。不同的是递增表达式的值。前递增，写做 `++$variable`，求增加后的值（PHP 在读取变量的值之前，增加变量的值，因而称之为“前递增”）。后递增，写做 `$variable++`，求 $variable 未递增之前的原始值（PHP 在读取变量的值之后，增加变量的值，因而叫做“后递增”）。

一个常用到的表达式类型是比较表达式。这些表达式求值 `false` 或 `true`。PHP 支持 >（大于）、>=（大于等于）、==（等于）、!=（不等于）、<（小于）、<= (小于等于)。PHP 还支持全等运算符 ===（值和类型均相同）和非全等运算符 !==（值或者类型不同）。这些表达式都是在条件判断语句，比如 `if`。

这里，将要研究的最后一个例子是组合的运算赋值表达式。已经知道如果想要为变量 $a 加 1，可以简单的写 `$a++` 或者 `++$a`。但是如果想为变量增加大于 1 的值，比如 3，该怎么做？可以写 `$a++` 多次，但这样明显不是一种高效舒适的方法，一个更加通用的做法是 `$a = $a + 3`。`$a + 3` 计算 $a 加上 3 的值，并将其赋予给 $a，于是 $a 的值增加了 3。在 PHP 及其它几种类似 C 的语言中，可以以一种更加简短的形式完成上述功能，随着时间的推移，会变得更加清晰、更容易理解。为 $a 的当前值加 3，可以这样写 `$a += 3`。这里的意思是“取变量 $a 的值，加 3，得到的结果再次分配给变量 $a”。除了更短和清楚外，也可以加快执行速度。`$a += 3` 的值，如同一个正常赋值操作的值，是赋值后的值。注意它不是 3，而是 $a 的值加上3 之后的值（此值将被赋给 $a）。任何二元运算符都可以用运算赋值模式，例如 `$a -= 5`（从变量 $a 的值中减去 5），`$b *= 7`（变量 $b 乘以 7），等等。

还有一个表达式，如果没有在别的语言中看到过的话，可能看上去很奇怪，即三元条件运算符：

    <?php
    $first ? $second : $third
    ?>

如果第一个子表达式的值是 `true`（非零），那么计算第二个子表达式的值，其值即为整个表达式的值。否则，将第三个子表达式的值作为整个表达式的值。

下面的例子有助于更好的理解前、后递增和表达式：

    <?php
    function double($i)
    {
        return $i*2;
    }
    $b = $a = 5;        /* 赋值 5 到变量 $a 和 $b */
    $c = $a++;          /* 后自增，将 $a（5）的原始值赋给 $c */
    $e = $d = ++$b;     /* 前自增，将 $b（6）的递增值赋给 $d 和 $e */

    /* 此时， $d 和 $e 都等于 6 */

    $f = double($d++);  /* 自增前将两倍值赋值给 $d ，即 2*6 = 12 赋值给 $f */
    $g = double(++$e);  /* 自增后将两倍值赋值给 $e ，即 2*7 = 14 赋值给 $g */
    $h = $g += 10;      /* 首先，$g 自增 10 后等于 24。然后将值（24）赋值给了 $h，
                           $h 的值也等于 24。 */
    ?>

一些表达式可以被当成语句。这时，一条语句的形式是 '`expr ;`'，即一个表达式加一个分号结尾。在 `$b = $a = 5;` 中，`$a = 5` 是一个有效的表达式，但它本身不是一条语句。`$b = $a = 5;` 是一条有效的语句。

最后一件值得提起的事情就是表达式的真假值。在许多事件中，主要是在条件执行和循环中，不要关心表达式中的具体值，反而要注意表达式的值是否是 `true` 或者 `false`。常量 `true` 和 `false`（大小写无关）是两种可能的 布尔值。必要时，表达式将自动转换为布尔值。参见类型强制转换获取详细信息。

PHP 提供了一套完整强大的表达式实现，并且完全纪录它超出了本手册的范围。上面的例子帮助了解了表达式的概念以及如何构建有用的表达式。在本手册的其余部分，将编写 expr 来指示任何有效的 PHP 表达式。

# 运算符

## 目录

- 运算符优先级
- 算术
- 递增/递减
- 赋值
- 位
- 比较
- 错误控制
- 执行
- 逻辑
- 字符串
- 数组
- 类型
- 函数式

运算符是可以通过给出的一或多个值（用编程行话来说，表达式）来产生另一个值（因而整个结构成为一个表达式）的东西。

运算符可按照其能接受几个值来分组。一元运算符只能接受一个值，例如 `!`（逻辑取反运算符）或 `++`（递增运算符）。 二元运算符可接受两个值，例如熟悉的算术运算符 `+`（加）和 `-`（减），大多数 PHP 运算符都是这种。最后是唯一的三元运算符 `? :`，可接受三个值；通常就简单称之为“三元运算符”（尽管称之为条件运算符可能更合适）。

PHP 的运算符完整列表见下节运算符优先级。该节也解释了运算符优先级和结合方向，这控制着在表达式包含有若干个不同运算符时究竟怎样对其求值。

## 运算符优先级

运算符优先级指定了两个表达式绑定得有多“紧密”。例如，表达式 `1 + 5 * 3` 的结果是 `16` 而不是 `18` 是因为乘号（“*”）的优先级比加号（“+”）高。必要时可以用括号来强制改变优先级。例如：`(1 + 5) * 3` 的值为 `18`。

如果运算符优先级相同，那运算符的结合方向决定了该如何运算。例如，"-"是左联的，那么 `1 - 2 - 3` 就等同于 `(1 - 2) - 3` 并且结果是 `-4`. 另外一方面，"="是右联的，所以 `$a = $b = $c` 等同于 `$a = ($b = $c)`。

没有结合的相同优先级的运算符不能连在一起使用，例如 `1 < 2 > 1` 在PHP是不合法的。但另外一方面表达式 `1 <= 1 == 1` 是合法的, 因为 `==` 的优先级低于 `<=`。

关联性仅对二（三）元操作符有意义。 一元操作符是前缀或者后缀，所以不适用该概念。 例如 `!!$a` 仅可分为 `!(!$a)`。

括号的使用，哪怕在不是必要的场合下，通过括号的配对来明确标明运算顺序，而非靠运算符优先级和结合性来决定，通常能够增加代码的可读性。

下表按照优先级从高到低列出了运算符。同一行中的运算符具有相同优先级，此时它们的结合方向决定求值顺序。

运算符优先级
结合方向 | 运算符 | 附加信息
--- | --- | ---
不适用 | `clone` `new` | clone 和 new
右 | `**` | 算术运算符
不适用 | `+` `-` `++` `--` `~` `(int)` `(float)` `(string)` `(array)` `(object)` `(bool)` `@` | 算术 (一元 `+` 和 `-`)，递增/递减，按位，类型转换和错误控制
左 | `instanceof` | 类型
不适用 | `!` | 逻辑运算符
左 | `*` `/` `%` | 算术运算符
左 | `+` `-` `.` | 算数 (二元 `+` 和 `-`)，array和string（`.` 自 PHP 8.0.0 前可用）
左 | `<<` `>>` | 位运算符
左 | `.` | string （PHP 8.0.0 起可用）
left | `|>` | 管道
无关联 | `<` `<=` `>` `>=` | 比较运算符
无关联 | `==` `!=` `===` `!==` `<>` `<=>` | 比较运算符
左 | `&` | 位运算符和引用
左 | `^` | 位运算符
左 | `|` | 位运算符
左 | `&&` | 逻辑运算符
左 | `||` | 逻辑运算符
右 | `??` | null 合并运算符
无关联 | `? :` | 三元运算符 (PHP 8.0.0 之前左联)
右 | `=` `+=` `-=` `*=` `**=` `/=` `.=` `%=` `&=` `|=` `^=` `<<=` `>>=` `??=` | 赋值运算符
不适用 | `yield from` | yield from
不适用 | `yield` | yield
不适用 | `print` | print
左 | `and` | 逻辑运算符
左 | `xor` | 逻辑运算符
左 | `or` | 逻辑运算符
(n/a) | `throw` | throw

示例 #1 结合方向

    <?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);
    ?>

三元运算符特别要求使用括号来消除优先级歧义。

示例 #2 明确优先级

    <?php
    $a = true ? 0 : (true ? 1 : 2);
    var_dump($a);

    // 自 PHP 8 起，这样不允许
    // $a = true ? 0 : true ? 1 : 2;
    ?>

运算符优先级和关联方式仅决定表达式如何分组，不指定计算顺序。 一般情况下， PHP 不指定表达式的计算顺序，并且代码避免指定假设执行顺序， 因为行为会在 PHP 版本间发生变化或者依赖于旁边的代码。

示例 #3 未定义执行顺序

    <?php
    $a = 1;
    echo $a + $a++; // 可能会输出 2 或 3

    $i = 1;
    $array[$i] = $i++; // 可能会设置索引 1 或 2
    ?>

示例 #4 `+`、`-` 和 `.` 优先级

    <?php
    $x = 4;
    // 这行可能会导致不可预料的输出：
    echo "x minus one equals " . $x-1 . ", or so I hope\n";

    // 通过使用括号执行所需的优先级：
    echo "x minus one equals " . ($x-1) . ", or so I hope\n";

    // 这样不允许，会抛出 TypeError：
    echo (("x minus one equals " . $x) - 1) . ", or so I hope\n";
    ?>

以上示例会输出：

    -1, or so I hope
    -1, or so I hope
    Fatal error: Uncaught TypeError: Unsupported operand types: string - int

示例 #5 PHP 8 之前，`+`、`-` 和 `.` 具有相同的优先级

    <?php
    $x = 4;
    // 此行可能会导致意想不到的输出：
    echo "x minus one equals " . $x-1 . ", or so I hope\n";

    // 因为它是这样计算的：（PHP 8.0.0 之前版本）
    echo (("x minus one equals " . $x) - 1) . ", or so I hope\n";

    // 可以使用括号来强制指定优先级：
    echo "x minus one equals " . ($x-1) . ", or so I hope\n";
    ?>

以上示例会输出：

    -1, or so I hope
    -1, or so I hope
    x minus one equals 3, or so I hope

> 注意:

> 尽管 `=` 比其它大多数的运算符的优先级低，PHP 仍旧允许类似如下的表达式：`if (!$a = foo())`，在此例中 `foo()` 的返回值被赋给了 $a。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在，字符串连接符（`.`）的优先级比算数加/减（`+` 和 `-`）、按位左/右移（`<<` 和 `>>`）更低。在此之前，它的优先级与 `+`、 `-` 相同，并且比 `<<`、 `>>` 更高。
8.0.0 | 三元运算符（`? :`）是现在是非关联的；以前它是左联的。
7.4.0 | 已弃用在无括号的表达式中依赖字符串连接（`.`）相对于算数加/减（`+` 或者 `-`）或者按位左/右移（`<<` 或者 `>>`）的优先级的使用方法。
7.4.0 | 不推荐使用三元运算符（`? :`）的左联。 即已弃用嵌套多个未带括号的三元运算符。

## 算术运算符

还记得学校里学到的基本数学知识吗？就和它们一样。

算术运算符
例子 | 名称 | 结果
--- | --- | ---
`+$a` | 标识 | 根据情况将 $a 转化为 int 或 float。
`-$a` | 取反 | $a 的负值。
`$a + $b` | 加法 | $a 和 $b 的和。
`$a - $b` | 减法 | $a 和 $b 的差。
`$a * $b` | 乘法 | $a 和 $b 的积。
`$a / $b` | 除法 | $a 除以 $b 的商。
`$a % $b` | 取模 | $a 除以 $b 的余数。
`$a ** $b` | 求幂 | $a 的 $b次方的值。

除法运算符 `/` 始终返回 float，除非两个操作数都是 int（或类型转换为 int 的 数字字符串）并且被除数是除数的倍数，这种情况下将返回整数。整数除法可参考 intdiv()。

取模运算符的操作数在运算之前都会转换成 int 。 浮点数取模可参考 fmod()。

取模运算符 `%` 的结果和被除数的符号（正负号）相同。即 `$a % $b` 的结果和 $a 的符号相同。例如：

示例 #1 取模运算符

    <?php
    var_dump(5 % 3);
    var_dump(5 % -3);
    var_dump(-5 % 3);
    var_dump(-5 % -3);
    ?>

以上示例会输出：

    int(2)
    int(2)
    int(-2)
    int(-2)

### 参见

- 数学函数

## 递增/递减运算符

PHP 支持前/后递增与递减运算符。这些一元运算符允许将值递增或递减 1。

递增/递减运算符
示例 | 名称 | 效果
--- | --- | ---
++$a | 前加 | $a 的值加一，然后返回 $a。
$a++ | 后加 | 返回 $a，然后将 $a 的值加一。
--$a | 前减 | $a 的值减一， 然后返回 $a。
$a-- | 后减 | 返回 $a，然后将 $a 的值减一。

示例 #1 递增/递减示例

    <?php
    echo 'Post-increment:', PHP_EOL;
    $a = 5;
    var_dump($a++);
    var_dump($a);

    echo 'Pre-increment:', PHP_EOL;
    $a = 5;
    var_dump(++$a);
    var_dump($a);

    echo 'Post-decrement:', PHP_EOL;
    $a = 5;
    var_dump($a--);
    var_dump($a);

    echo 'Pre-decrement:', PHP_EOL;
    $a = 5;
    var_dump(--$a);
    var_dump($a);
    ?>

以上示例会输出：

    Post-increment:
    int(5)
    int(6)
    Pre-increment:
    int(6)
    int(6)
    Post-decrement:
    int(5)
    int(4)
    Pre-decrement:
    int(4)
    int(4)

警告

递增和递减运算符对 bool 类型值没有影响。自 PHP 8.3.0 起，会发出 `E_WARNING`，因为将来会默认将该值转换为 int。

递减运算符对 null 类型的值没有影响。自 PHP 8.3.0 起，会发出 `E_WARNING`，因为将来会默认将该值转换为 int。

递减运算符对非数字字符串没有影响。自 PHP 8.3.0 起，会发出 `E_WARNING`，因为在将来会抛出 TypeError。

> 注意:

> 支持重载加/减法的内部对象也可以进行递增或递减。其中一个这样的内部对象是 GMP。

### PERL 字符串递增功能

警告

自 PHP 8.3.0 起，此功能已软弃用。应该使用 str_increment() 函数。

在 PHP 中，可以递增非数字字符串。该字符串必须是字母数字 ASCII 字符串。当到达字母 `Z` 且递增到下个字母时，将进位到左侧值。例如，`$a = 'Z'; $a++;`将 $a 变为 `'AA'`。

示例 #2 PERL 字符串递减功能

    <?php
    echo '== Alphabetic strings ==' . PHP_EOL;
    $s = 'W';
    for ($n=0; $n<6; $n++) {
        echo ++$s . PHP_EOL;
    }
    // 字母数字字符串的不同行为
    echo '== Alphanumeric strings ==' . 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;
    }
    ?>

以上示例会输出：

    == Alphabetic strings ==
    X
    Y
    Z
    AA
    AB
    AC
    == Alphanumeric strings ==
    A9
    B0
    B1
    B2
    B3
    B4
    A09
    A10
    A11
    A12
    A13
    A14

警告

如果数字字母字符串可以解释为数字字符串，则将转换为 int 或 float。这对于看起来像以指数形式写出的浮点数字符串来说尤其是一个问题。str_increment() 函数不会受到这些默认类型转换的影响。

示例 #3 数字字母字符串转换为浮点数

    <?php
    $s = "5d9";
    var_dump(++$s);
    var_dump(++$s);
    ?>

以上示例会输出：

    string(3) "5e0"
    float(6)

这是因为值 `"5e0"` 解释为 float，并在递增之前转换为 `5.0`。

## 赋值运算符

基本的赋值运算符是“=”。一开始可能会以为它是“等于”，其实不是的。它实际上意味着把右边表达式的值赋给左边的运算数。

赋值运算表达式的值也就是所赋的值。也就是说，“`$a = 3`”的值是 3。这样就可以做一些小技巧：

示例 #1 嵌套赋值

    <?php
    $a = ($b = 4) + 5; // $a 现在成了 9，而 $b 成了 4。
    var_dump($a);
    ?>

在基本赋值运算符之外，还有适合于所有二元算术，数组集合和字符串运算符的“组合运算符”，这样可以在一个表达式中使用它的值并把表达式的结果赋给它，例如：

示例 #2 组合赋值

    <?php
    $a = 3;
    $a += 5; // 设置 $a 为 8 ，之前说过： $a = $a + 5;
    $b = "Hello ";
    $b .= "There!"; // 设置 $b 为 "Hello There!"，就像 $b = $b . "There!";

    var_dump($a, $b);
    ?>

注意赋值运算将原变量的值拷贝到新变量中（传值赋值），所以改变其中一个并不影响另一个。这也适合于在密集循环中拷贝一些值例如大数组。

在 PHP 中普通的传值赋值行为有个例外就是碰到对象 object 时，在 PHP 5 中是以引用赋值的，除非明确使用了 clone 关键字来拷贝。

### 引用赋值

PHP 支持引用赋值，使用“$var = &$othervar;”语法。引用赋值意味着两个变量指向了同一个数据，没有拷贝任何东西。

示例 #3 引用赋值

    <?php
    $a = 3;
    $b = &$a; // $b 是 $a 的引用

    print "$a\n"; // 输出 3
    print "$b\n"; // 输出 3

    $a = 4; // 修改 $a

    print "$a\n"; // 输出 4
    print "$b\n"; // 也输出 4，因为 $b 是 $a 的引用，因此也被改变
    ?>

new 运算符自动返回一个引用，因此对 new 的结果进行引用赋值是错误的。

示例 #4 引用 new 运算符

    <?php
    class C {}

    $o = &new C;
    ?>

以上示例会输出：

    Parse error: syntax error, unexpected token ";", expecting "("

有关引用更多信息参见本手册中 引用的解释 一章。

### 算术赋值运算符

示例 | 等同于 | 操作
--- | --- | ---
$a += $b | $a = $a + $b | 加法
$a -= $b | $a = $a - $b | 减法
$a *= $b | $a = $a * $b | 乘法
$a /= $b | $a = $a / $b | 除法
$a %= $b | $a = $a % $b | 取模
$a **= $b | $a = $a ** $b | 指数

### 位赋值运算符

示例 | 等同于 | 操作
--- | --- | ---
$a &= $b | $a = $a & $b | 按位与
$a |= $b | $a = $a | $b | 按位或
$a ^= $b | $a = $a ^ $b | 按位异或
$a <<= $b | $a = $a << $b | 左移
$a >>= $b | $a = $a >> $b | 右移

### 其他赋值运算符

示例 | 等同于 | 操作
--- | --- | ---
$a .= $b | $a = $a . $b | 字符串拼接
$a ??= $b | $a = $a ?? $b | NULL 合并

### 参见

- 算术运算符
- 位运算符
- NULL 合并运算符

## 位运算符

位运算符允许对整型数中指定的位进行求值和操作。

位运算符
例子 | 名称 | 结果
--- | --- | ---
`$a & $b` | And（按位与） | 将把 $a 和 $b 中都为 1 的位设为 1。
`$a | $b` | Or（按位或） | 将把 $a 和 $b 中任何一个为 1 的位设为 1。
`$a ^ $b` | Xor（按位异或） | 将把 $a 和 $b 中一个为 1 另一个为 0 的位设为 1。
`~ $a` | Not（按位取反） | 将 $a 中为 0 的位设为 1，反之亦然。
`$a << $b` | Shift left（左移） | 将 $a 中的位向左移动 $b 次（每一次移动都表示“乘以 2”）。
`$a >> $b` | Shift right（右移） | 将 $a 中的位向右移动 $b 次（每一次移动都表示“除以 2”）。

位移在 PHP 中是数学运算。向任何方向移出去的位都被丢弃。左移时右侧以零填充，符号位被移走意味着正负号不被保留。右移时左侧以符号位填充，意味着正负号被保留。

要用括号确保想要的优先级。例如 `$a & $b == true` 先进行比较再进行按位与；而 `($a & $b) == true` 则先进行按位与再进行比较。

如果 `&`、 `|` 和 `^` 运算符的左右两个操作对象都是字符串，将对会组成字符串的字符 ASCII 值执行操作，结果也是一个字符串。除此之外，两个操作对象都将 转换为整数 ，结果也将会是整数。

如果 `~` 运算符的操作对象是字符串，则将对组成字符串的字符 ASCII 值进行操作， 结果将会是字符串，否则操作对象和结构都会是整数。

`<<` 和 `>>` 运算符的操作对象和结果始终都是整数。

PHP 的 ini 设定 error_reporting 使用了按位的值， 提供了关闭某个位的真实例子。要显示除了提示级别 之外的所有错误，php.ini 中是这样用的： `E_ALL & ~E_NOTICE`

         具体运作方式是先取得 E_ALL 的值：
         00000000000000000111011111111111
         再取得 E_NOTICE 的值：
         00000000000000000000000000001000
         然后通过 ~ 将其取反：
         11111111111111111111111111110111
         最后再用按位与 AND（&）得到两个值中都设定了（为 1）的位：
         00000000000000000111011111110111

另外一个方法是用按位异或 XOR（`^`）来取得只在 其中一个值中设定了的位 `E_ALL ^ E_NOTICE`

error_reporting 也可用来演示怎样置位。只显示错误和可恢复 错误的方法是： `E_ERROR | E_RECOVERABLE_ERROR`

         也就是将 E_ERROR
         00000000000000000000000000000001
         和 E_RECOVERABLE_ERROR
         00000000000000000001000000000000
         用按位或 OR（|）运算符来取得在任何一个值中被置位的结果：
         00000000000000000001000000000001

示例 #1 整数的 AND，OR 和 XOR 位运算符

    <?php
    /*
     * 忽略顶部，
     * 它只是为了使输出更加清晰而格式化。
     */

    $format = '(%1$2d = %1$04b) = (%2$2d = %2$04b)'
            . ' %3$s (%4$2d = %4$04b)' . "\n";

    echo <<<EOH
     ---------     ---------  -- ---------
     result        value      op test
     ---------     ---------  -- ---------
    EOH;

    /*
     * 这是示例。
     */

    $values = array(0, 1, 2, 4, 8);
    $test = 1 + 4;

    echo "\n Bitwise AND \n";
    foreach ($values as $value) {
        $result = $value & $test;
        printf($format, $result, $value, '&', $test);
    }

    echo "\n Bitwise Inclusive OR \n";
    foreach ($values as $value) {
        $result = $value | $test;
        printf($format, $result, $value, '|', $test);
    }

    echo "\n Bitwise Exclusive OR (XOR) \n";
    foreach ($values as $value) {
        $result = $value ^ $test;
        printf($format, $result, $value, '^', $test);
    }
    ?>

以上示例会输出：

     ---------     ---------  -- ---------
     result        value      op test
     ---------     ---------  -- ---------
     Bitwise 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)

     Bitwise Inclusive 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)

     Bitwise Exclusive 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)

示例 #2 字符串的 XOR 运算符

    <?php
    echo 12 ^ 9, PHP_EOL; // 输出 '5'

    echo "12" ^ "9", PHP_EOL; // 输出退格字符 (ascii 8)
                              // ('1' (ascii 49)) ^ ('9' (ascii 57)) = #8

    echo "hallo" ^ "hello", PHP_EOL; // 输出 ascii 值 #0 #4 #0 #0 #0
                                     // 'a' ^ 'e' = #4

    echo 2 ^ "3", PHP_EOL; // 输出 1
                           // 2 ^ ((int) "3") == 1

    echo "2" ^ 3, PHP_EOL; // 输出 1
                           // ((int) "2") ^ 3 == 1
    ?>

示例 #3 整数的位移

    <?php
    /*
     * 这是示例。
     */

    echo "\n--- BIT SHIFT RIGHT ON POSITIVE INTEGERS ---\n";

    $val = 4;
    $places = 1;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'copy of sign bit shifted into left side');

    $val = 4;
    $places = 2;
    $res = $val >> $places;
    p($res, $val, '>>', $places);

    $val = 4;
    $places = 3;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'bits shift out right side');

    $val = 4;
    $places = 4;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'same result as above; can not shift beyond 0');

    echo "\n--- BIT SHIFT RIGHT ON NEGATIVE INTEGERS ---\n";

    $val = -4;
    $places = 1;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'copy of sign bit shifted into left side');

    $val = -4;
    $places = 2;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'bits shift out right side');

    $val = -4;
    $places = 3;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'same result as above; can not shift beyond -1');

    echo "\n--- BIT SHIFT LEFT ON POSITIVE INTEGERS ---\n";

    $val = 4;
    $places = 1;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'zeros fill in right side');

    $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, 'sign bits get shifted out');

    $val = 4;
    $places = (PHP_INT_SIZE * 8) - 2;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'bits shift out left side');

    echo "\n--- BIT SHIFT LEFT ON NEGATIVE INTEGERS ---\n";

    $val = -4;
    $places = 1;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'zeros fill in right side');

    $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 shift out left side, including sign bit');

    /*
     * 忽略顶部，
     * 它只是为了使输出更加清晰而格式化。
     */

    function p($res, $val, $op, $places, $note = '') {
        $format = '%0' . (PHP_INT_SIZE * 8) . "b\n";

        printf("Expression: %d = %d %s %d\n", $res, $val, $op, $places);

        echo " Decimal:\n";
        printf("  val=%d\n", $val);
        printf("  res=%d\n", $res);

        echo " Binary:\n";
        printf('  val=' . $format, $val);
        printf('  res=' . $format, $res);

        if ($note) {
            echo " NOTE: $note\n";
        }

        echo "\n\n";
    }
    ?>

以上示例在 32 位机器上的输出:

    --- BIT SHIFT RIGHT ON POSITIVE INTEGERS ---
    Expression: 2 = 4 >> 1
     Decimal:
      val=4
      res=2
     Binary:
      val=00000000000000000000000000000100
      res=00000000000000000000000000000010
     NOTE: copy of sign bit shifted into left side

    Expression: 1 = 4 >> 2
     Decimal:
      val=4
      res=1
     Binary:
      val=00000000000000000000000000000100
      res=00000000000000000000000000000001

    Expression: 0 = 4 >> 3
     Decimal:
      val=4
      res=0
     Binary:
      val=00000000000000000000000000000100
      res=00000000000000000000000000000000
     NOTE: bits shift out right side

    Expression: 0 = 4 >> 4
     Decimal:
      val=4
      res=0
     Binary:
      val=00000000000000000000000000000100
      res=00000000000000000000000000000000
     NOTE: same result as above; can not shift beyond 0

    --- BIT SHIFT RIGHT ON NEGATIVE INTEGERS ---
    Expression: -2 = -4 >> 1
     Decimal:
      val=-4
      res=-2
     Binary:
      val=11111111111111111111111111111100
      res=11111111111111111111111111111110
     NOTE: copy of sign bit shifted into left side

    Expression: -1 = -4 >> 2
     Decimal:
      val=-4
      res=-1
     Binary:
      val=11111111111111111111111111111100
      res=11111111111111111111111111111111
     NOTE: bits shift out right side

    Expression: -1 = -4 >> 3
     Decimal:
      val=-4
      res=-1
     Binary:
      val=11111111111111111111111111111100
      res=11111111111111111111111111111111
     NOTE: same result as above; can not shift beyond -1

    --- BIT SHIFT LEFT ON POSITIVE INTEGERS ---
    Expression: 8 = 4 << 1
     Decimal:
      val=4
      res=8
     Binary:
      val=00000000000000000000000000000100
      res=00000000000000000000000000001000
     NOTE: zeros fill in right side

    Expression: 1073741824 = 4 << 28
     Decimal:
      val=4
      res=1073741824
     Binary:
      val=00000000000000000000000000000100
      res=01000000000000000000000000000000

    Expression: -2147483648 = 4 << 29
     Decimal:
      val=4
      res=-2147483648
     Binary:
      val=00000000000000000000000000000100
      res=10000000000000000000000000000000
     NOTE: sign bits get shifted out

    Expression: 0 = 4 << 30
     Decimal:
      val=4
      res=0
     Binary:
      val=00000000000000000000000000000100
      res=00000000000000000000000000000000
     NOTE: bits shift out left side

    --- BIT SHIFT LEFT ON NEGATIVE INTEGERS ---
    Expression: -8 = -4 << 1
     Decimal:
      val=-4
      res=-8
     Binary:
      val=11111111111111111111111111111100
      res=11111111111111111111111111111000
     NOTE: zeros fill in right side

    Expression: -2147483648 = -4 << 29
     Decimal:
      val=-4
      res=-2147483648
     Binary:
      val=11111111111111111111111111111100
      res=10000000000000000000000000000000

    Expression: 0 = -4 << 30
     Decimal:
      val=-4
      res=0
     Binary:
      val=11111111111111111111111111111100
      res=00000000000000000000000000000000
     NOTE: bits shift out left side, including sign bit

以上示例在 64 位机器上的输出:

    --- BIT SHIFT RIGHT ON POSITIVE INTEGERS ---
    Expression: 2 = 4 >> 1
     Decimal:
      val=4
      res=2
     Binary:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000010
     NOTE: copy of sign bit shifted into left side

    Expression: 1 = 4 >> 2
     Decimal:
      val=4
      res=1
     Binary:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000001

    Expression: 0 = 4 >> 3
     Decimal:
      val=4
      res=0
     Binary:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000000
     NOTE: bits shift out right side

    Expression: 0 = 4 >> 4
     Decimal:
      val=4
      res=0
     Binary:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000000
     NOTE: same result as above; can not shift beyond 0

    --- BIT SHIFT RIGHT ON NEGATIVE INTEGERS ---
    Expression: -2 = -4 >> 1
     Decimal:
      val=-4
      res=-2
     Binary:
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1111111111111111111111111111111111111111111111111111111111111110
     NOTE: copy of sign bit shifted into left side

    Expression: -1 = -4 >> 2
     Decimal:
      val=-4
      res=-1
     Binary:
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1111111111111111111111111111111111111111111111111111111111111111
     NOTE: bits shift out right side

    Expression: -1 = -4 >> 3
     Decimal:
      val=-4
      res=-1
     Binary:
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1111111111111111111111111111111111111111111111111111111111111111
     NOTE: same result as above; can not shift beyond -1

    --- BIT SHIFT LEFT ON POSITIVE INTEGERS ---
    Expression: 8 = 4 << 1
     Decimal:
      val=4
      res=8
     Binary:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000001000
     NOTE: zeros fill in right side

    Expression: 4611686018427387904 = 4 << 60
     Decimal:
      val=4
      res=4611686018427387904
     Binary:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0100000000000000000000000000000000000000000000000000000000000000

    Expression: -9223372036854775808 = 4 << 61
     Decimal:
      val=4
      res=-9223372036854775808
     Binary:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=1000000000000000000000000000000000000000000000000000000000000000
     NOTE: sign bits get shifted out

    Expression: 0 = 4 << 62
     Decimal:
      val=4
      res=0
     Binary:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000000
     NOTE: bits shift out left side

    --- BIT SHIFT LEFT ON NEGATIVE INTEGERS ---
    Expression: -8 = -4 << 1
     Decimal:
      val=-4
      res=-8
     Binary:
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1111111111111111111111111111111111111111111111111111111111111000
     NOTE: zeros fill in right side

    Expression: -9223372036854775808 = -4 << 61
     Decimal:
      val=-4
      res=-9223372036854775808
     Binary:
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1000000000000000000000000000000000000000000000000000000000000000

    Expression: 0 = -4 << 62
     Decimal:
      val=-4
      res=0
     Binary:
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=0000000000000000000000000000000000000000000000000000000000000000
     NOTE: bits shift out left side, including sign bit

警告

使用 gmp 扩展对超出 `PHP_INT_MAX` 的数值来进行位操作。

### 参见

- pack()
- unpack()
- gmp_and()
- gmp_or()
- gmp_xor()
- gmp_testbit()
- gmp_clrbit()

## 比较运算符

比较运算符，如同它们名称所暗示的，允许对两个值进行比较。还可以参考 PHP 类型比较表看不同类型相互比较的例子。

比较运算符
例子 | 名称 | 结果
--- | --- | ---
$a == $b | 等于 | `true`，如果类型转换后 $a 等于 $b。
$a === $b | 全等 | `true`，如果 $a 等于 $b，并且它们的类型也相同。
$a != $b | 不等 | `true`，如果类型转换后 $a 不等于 $b。
$a <> $b | 不等 | `true`，如果类型转换后 $a 不等于 $b。
$a !== $b | 不全等 | `true`，如果 $a 不等于 $b，或者它们的类型不同。
$a < $b | 小于 | `true`，如果 $a 严格小于 $b。
$a > $b | 大于 | `true`，如果 $a 严格大于 $b。
$a <= $b | 小于等于 | `true`，如果 $a 小于或者等于 $b。
$a >= $b | 大于等于 | `true`，如果 $a 大于或者等于 $b。
$a <=> $b | 太空船运算符（组合比较符） | 当$a小于、等于、大于 $b时 分别返回一个小于、等于、大于0的 int 值。

当两个操作对象都是 数字字符串， 或一个是数字另一个是 数字字符串， 就会自动按照数值进行比较。 此规则也适用于 switch 语句。 当比较时用的是 `===` 或 `!==`， 则不会进行类型转换——因为不仅要对比数值，还要对比类型。

警告

PHP 8.0.0 之前，如果 string 与数字或者数字字符串进行比较， 则在比较前会将 string 转化为数字。 在如下示例中会出现不可预料的结果：

    <?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;
    }
    ?>

以上示例在 PHP 7 中的输出：

    bool(true)
    bool(true)
    bool(true)
    bool(true)
    0

以上示例在 PHP 8 中的输出：

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    a

示例 #1 比较运算符

    <?php
    // 整数
    echo 1 <=> 1, ' '; // 0
    echo 1 <=> 2, ' '; // -1
    echo 2 <=> 1, ' '; // 1

    // 浮点数
    echo 1.5 <=> 1.5, ' '; // 0
    echo 1.5 <=> 2.5, ' '; // -1
    echo 2.5 <=> 1.5, ' '; // 1

    // 字符串
    echo "a" <=> "a", ' '; // 0
    echo "a" <=> "b", ' '; // -1
    echo "b" <=> "a", ' '; // 1

    echo "a" <=> "aa", ' ';  // -1
    echo "zz" <=> "aa", ' '; // 1

    // 数组
    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

    // 对象
    $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

    // 不仅仅比较值，而且也会匹配 key
    $a = (object) ["a" => "b"];
    $b = (object) ["b" => "b"];
    echo $a <=> $b, ' '; // 1

    ?>

对于多种类型，比较运算符根据下表比较（按顺序）。

比较多种类型
运算数 1 类型 | 运算数 2 类型 | 结果
--- | --- | ---
null 或 string | string | 将 `null` 转换为 ""，进行数字或词汇比较
bool 或 null | 任何其它类型 | 转换为 bool，`false` < `true`
object | object | 内置类可以定义自己的比较，不同类不能比较，相同的类查看对象比较
string、resource、int、float | string、resource、int、float | 将字符串和资源转换成数字，按普通数学比较
array | array | 成员越少的数组越小，如果运算数 1 中的键不存在于运算数 2 中则数组无法比较，否则挨个值比较（见下例）
object | 任何其它类型 | object 总是更大
array | 任何其它类型 | array 总是更大

示例 #2 Boolean/null comparison

    <?php
    // Bool 和 null 总是作为 bool 比较
    var_dump(1 == TRUE);  // TRUE——等同于 (bool) 1 == TRUE
    var_dump(0 == FALSE); // TRUE——等同于 (bool) 0 == FALSE
    var_dump(100 < TRUE); // FALSE——等同于 (bool) 100 < TRUE
    var_dump(-10 < FALSE);// FALSE——等同于 (bool) -10 < FALSE
    var_dump(min(-100, -10, NULL, 10, 100)); // NULL——(bool) NULL < (bool) -100 即 FALSE < TRUE
    ?>

示例 #3 标准数组比较代码

    <?php
    // 数组是用标准比较运算符或者太空船运算符进行比较的
    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
    }
    ?>

警告

# 比较浮点数

由于浮点数 float 的内部表达方式，不应比较两个浮点数float是否相等。

更多信息参见 float。

> 注意: 请注意，在比较不同类型的值时，类型转换并不总是很明显，尤其是比较 int 与 bool 或者 int 与 string。因此，在大多数情况下，通常建议使用 `===` 和 `!==` 进行比较而不是 `==` 和 `!=`。

### 不能比较的值

虽然恒等比较（`===` 和 `!==`）可以应用于任意值，其它比较运算符应该仅用于可比较的值。不能比较的值的比较的结果是不确定的，不应依赖。

### 参见

- strcasecmp()
- strcmp()
- 数组运算符
- 类型

### 三元运算符

另一个条件运算符是“?:”（或三元）运算符 。

示例 #4 赋默认值

    <?php
    // 三元运算符的例子
    $action = (empty($_POST['action'])) ? 'default' : $_POST['action'];

    // 以上等同于以下的  if/else 语句
    if (empty($_POST['action'])) {
        $action = 'default';
    } else {
        $action = $_POST['action'];
    }
    ?>

表达式 `(expr1) ? (expr2) : (expr3)` 在 expr1 求值为 `true` 时的值为 expr2，在 expr1 求值为 `false` 时的值为 expr3。

可以省略三元运算符中间那部分。表达式 `expr1 ?: expr3` 等同于如果 expr1 求值为 `true` 时返回 expr1 的结果，否则返回 expr3。expr1 在这里仅执行一次。

> 注意: 注意三元运算符是个语句，因此其求值不是变量，而是语句的结果。如果想通过引用返回一个变量这点就很重要。在一个通过引用返回的函数中语句 `return $var == 42 ? $a : $b;` 将不起作用，以后的 PHP 版本会为此发出一条警告。

> 注意:

> 建议避免将三元运算符堆积在一起使用。和其他语言相比， 当在单个表达式中使用多个未加括号的三元运算符时会造成 PHP 运算结果不清晰。 甚至在 PHP 8.0.0 之前，三元运算符是从左到右执行的， 而大多数其他编程语言是从右到左的。 自 PHP 7.4.0 起，弃用依靠左联。 PHP 8.0.0 起，三元运算符是非关联的。

> 示例 #5 不清晰的三元运算符行为

>     <?php
>     // 乍看起来下面的输出是 'true'
>     echo (true ? 'true' : false ? 't' : 'f');

>     // 然而，上面语句的实际输出是't'，因为在 PHP 8.0.0 之前三元运算符是左联的

>     // 下面是与上面等价的语句，但更清晰
>     echo ((true ? 'true' : 'false') ? 't' : 'f');

>     // 这里可以看到第一个表达式的计算结果是 “true”，第二个表达式的计算结果为 (bool) true，
>     // 因此返回第二个三元表达式的 true 分支。
>     ?>

> 注意:

> 然而，短三元运算符（`?:`）的链接是稳定且合理的。他将第一个参数进行求值，结果为非假值。注意，未定义的值将会引发警告。

> 示例 #6 Short-ternary chaining

>     <?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 合并运算符

另一个简略运算符是 "??" （NULL 合并）运算符。

示例 #7 设置默认值

    <?php
    // NULL 合并运算符的例子
    $action = $_POST['action'] ?? 'default';

    // 以上例子等同于于以下 if/else 语句
    if (isset($_POST['action'])) {
        $action = $_POST['action'];
    } else {
        $action = 'default';
    }
    ?>

当 expr1 为 `null`，表达式 `(expr1) ?? (expr2)` 等同于 expr2，否则为 expr1。

尤其要注意，当不存在左侧的值时，此运算符也和 isset() 一样不会产生警告。 对于 array 键尤其有用。

> 注意: 请注意：NULL 合并运算符是一个表达式，产生的也是表达式结果，而不是变量。 返回引用变量时需要强调这一点。 因此，在返回引用的函数里就无法使用这样的语句：`return $foo ?? $bar;`，还会提示警告。

> 注意:

> null 合并运算符的优先级较低。这意味着如果将它与其它运算符（比如字符串链接或者算术运算符）混合使用，可能需要括号。

>     <?php
>     // $name 未定义，引发警告。
>     print 'Mr. ' . $name ?? 'Anonymous';

>     // 打印 "Mr. Anonymous"
>     print 'Mr. ' . ($name ?? 'Anonymous');
>     ?>

> 注意:

> 请注意，NULL 合并运算符支持简单的嵌套：

> 示例 #8 嵌套 NULL 合并运算符

>     <?php

>     $foo = null;
>     $bar = null;
>     $baz = 1;
>     $qux = 2;

>     echo $foo ?? $bar ?? $baz ?? $qux; // 输出 1

>     ?>

## 错误控制运算符

PHP 支持一个错误控制运算符：`@`。当将其放置在一个 PHP 表达式之前，该表达式可能产生的任何错误诊断都被抑制。

如果用 set_error_handler() 设定了自定义的错误处理函数，即使诊断信息被抑制，也仍然会被调用。

警告

PHP 8.0.0 之前，如果错误被 `@` 运算符抑制，则在自定义错误处理程序中调用 error_reporting() 将始终返回 `0`。PHP 8.0.0 起，返回（按位）表达式的值：`E_ERROR | E_CORE_ERROR | E_COMPILE_ERROR | E_USER_ERROR | E_RECOVERABLE_ERROR | E_PARSE`。

error_get_last() 返回数组中的 `"message"` 元素储存了表达式产生的任意错误信息。 此函数的返回结果会随着每次错误的发生而相应变化，所以需要尽早检查。

示例 #1 故意文件错误

    <?php
    $my_file = @file ('non_existent_file') or
        die ("Failed opening file: error was '" . error_get_last()['message'] . "'");
    ?>

示例 #2 表达式抑制

    <?php
    // 这适用于所有表达式，而不仅仅是函数：
    $value = @$cache[$key];
    // 如果索引 $key 不存在，则不会发出通知。
    ?>

> 注意: `@` 运算符只对 表达式 有效。 对新手来说一个简单的规则就是：如果能从某处获得值，就能在它前面加上 `@` 运算符。例如，可以把它放在变量，函数调用，某些语言构造调用（例如 include ）等等之前。 不能把它放在函数或类的定义之前，也不能用于条件结构例如 `if` 和 `foreach` 等。

警告

PHP 8.0.0 之前，`@` 运算符会禁用导致脚本停止运行的严重错误。 例如在调用一个不存在的函数前添加 `@`，由于函数不可用或者输入错误， 将会导致脚本终止，而不会说明原因。

### 参见

- error_reporting()
- 错误处理与日志记录函数

## 执行运算符

PHP 支持一个执行运算符：反引号（````）。注意这不是单引号！PHP 将尝试将反引号中的内容作为 shell 命令来执行，并将其输出信息返回（即，可以赋给一个变量而不是简单地丢弃到标准输出）。使用反引号运算符“`”的效果与函数 shell_exec() 相同。

示例 #1 反引号运算符

    <?php
    $output = `ls -al`;
    echo "<pre>$output</pre>";
    ?>

> 注意:

> 关闭了 shell_exec() 时反引号运算符是无效的。

> 注意:

> 与其它某些语言不同，反引号不能在双引号字符串中使用。

### 更新日志

版本 | 说明
--- | ---
8.5.0 | 已弃用将反引号运算符作为 shell_exec() 的别名。

### 参见

- 程序执行函数
- popen()
- proc_open()
- PHP 的命令行模式

## 逻辑运算符

逻辑运算符
例子 | 名称 | 结果
--- | --- | ---
$a and $b | And（逻辑与） | `true`，如果 $a 和 $b 都为 `true`。
$a or $b | Or（逻辑或） | `true`，如果 $a 或 $b 任一为 `true`。
$a xor $b | Xor（逻辑异或） | `true`，如果 $a 或 $b 任一为 `true`，但不同时是。
! $a | Not（逻辑非） | `true`，如果 $a 不为 `true`。
$a && $b | And（逻辑与） | `true`，如果 $a 和 $b 都为 `true`。
$a || $b | Or（逻辑或） | `true`，如果 $a 或 $b 任一为 `true`。

“与”和“或”有两种不同形式运算符的原因是它们运算的优先级不同（见运算符优先级）。

示例 #1 逻辑运算符示例

    <?php

    // --------------------
    // foo() 根本没机会被调用，被运算符“短路”了

    $a = (false && foo());
    $b = (true  || foo());
    $c = (false and foo());
    $d = (true  or  foo());

    // --------------------
    // "||" 比 "or" 的优先级高

    // 表达式 (false || true) 的结果被赋给 $e
    // 等同于：($e = (false || true))
    $e = false || true;

    // 常量 false 被赋给 $f，true 被忽略
    // 等同于：(($f = false) or true)
    $f = false or true;

    var_dump($e, $f);

    // --------------------
    // "&&" 比 "and" 的优先级高

    // 表达式 (true && false) 的结果被赋给 $g
    // 等同于：($g = (true && false))
    $g = true && false;

    // 常量 true 被赋给 $h，false 被忽略
    // 等同于：(($h = true) and false)
    $h = true and false;

    var_dump($g, $h);
    ?>

以上示例的输出类似于：

    bool(true)
    bool(false)
    bool(false)
    bool(true)

## 字符串运算符

有两个字符串（string）运算符。第一个是连接运算符（“.”），它返回其左右参数连接后的字符串。第二个是连接赋值运算符（“`.=`”），它将右边参数附加到左边的参数之后。更多信息见赋值运算符。

示例 #1 字符串连接

    <?php
    $a = "Hello ";
    $b = $a . "World!"; // 现在 $b 包含 "Hello World!"
    var_dump($b);

    $a = "Hello ";
    $a .= "World!";     // 现在 $a 包含 "Hello World!"
    var_dump($a);
    ?>

### 参见

- 字符串类型
- 字符串函数

## 数组运算符

数组运算符
例子 | 名称 | 结果
--- | --- | ---
$a + $b | 联合 | $a 和 $b 的联合。
$a == $b | 相等 | 如果 $a 和 $b 具有相同的键／值对则为 `true`。
$a === $b | 全等 | 如果 $a 和 $b 具有相同的键／值对并且顺序和类型都相同则为 `true`。
$a != $b | 不等 | 如果 $a 不等于 $b 则为 `true`。
$a <> $b | 不等 | 如果 $a 不等于 $b 则为 `true`。
$a !== $b | 不全等 | 如果 $a 不全等于 $b 则为 `true`。

`+` 运算符把右边的数组元素附加到左边的数组后面，两个数组中都有的键名，则只用左边数组中的，右边的被忽略。

示例 #1 数组追加运算符

    <?php
    $a = array("a" => "apple", "b" => "banana");
    $b = array("a" => "pear", "b" => "strawberry", "c" => "cherry");

    $c = $a + $b; // $a 和 $b 的并集
    echo "Union of \$a and \$b: \n";
    var_dump($c);

    $c = $b + $a; // $b 和 $a 的并集
    echo "Union of \$b and \$a: \n";
    var_dump($c);

    $a += $b; //  $a += $b 的并集是 $a 和 $b
    echo "Union of \$a += \$b: \n";
    var_dump($a);
    ?>

以上示例会输出：

    Union of $a and $b:
    array(3) {
      ["a"]=>
      string(5) "apple"
      ["b"]=>
      string(6) "banana"
      ["c"]=>
      string(6) "cherry"
    }
    Union of $b and $a:
    array(3) {
      ["a"]=>
      string(4) "pear"
      ["b"]=>
      string(10) "strawberry"
      ["c"]=>
      string(6) "cherry"
    }
    Union of $a += $b:
    array(3) {
      ["a"]=>
      string(5) "apple"
      ["b"]=>
      string(6) "banana"
      ["c"]=>
      string(6) "cherry"
    }

数组中的单元如果具有相同的键名和值则比较时相等。

示例 #2 比较数组

    <?php
    $a = array("apple", "banana");
    $b = array(1 => "banana", "0" => "apple");

    var_dump($a == $b); // bool(true)
    var_dump($a === $b); // bool(false)
    ?>

### 参见

- 数组类型
- 数组函数

## 类型运算符

`instanceof` 用于确定一个 PHP 变量是否属于某一类 class 的实例：

示例 #1 对类使用 `instanceof`

    <?php
    class MyClass
    {
    }

    class NotMyClass
    {
    }
    $a = new MyClass;

    var_dump($a instanceof MyClass);
    var_dump($a instanceof NotMyClass);
    ?>

以上示例会输出：

    bool(true)
    bool(false)

`instanceof`也可用来确定一个变量是不是继承自某一父类的子类的实例：

示例 #2 对继承类使用 `instanceof`

    <?php
    class ParentClass
    {
    }

    class MyClass extends ParentClass
    {
    }

    $a = new MyClass;

    var_dump($a instanceof MyClass);
    var_dump($a instanceof ParentClass);
    ?>

以上示例会输出：

    bool(true)
    bool(true)

检查一个对象是否不是某个类的实例，可以使用逻辑运算符 `not`。

示例 #3 使用 `instanceof` 检查对象不是某个类的实例

    <?php
    class MyClass
    {
    }

    $a = new MyClass;
    var_dump(!($a instanceof stdClass));
    ?>

以上示例会输出：

    bool(true)

最后，`instanceof`也可用于确定一个变量是不是实现了某个接口的对象的实例:

示例 #4 对接口使用 `instanceof`

    <?php
    interface MyInterface
    {
    }

    class MyClass implements MyInterface
    {
    }

    $a = new MyClass;

    var_dump($a instanceof MyClass);
    var_dump($a instanceof MyInterface);
    ?>

以上示例会输出：

    bool(true)
    bool(true)

虽然 `instanceof` 通常直接与类名一起使用，但也可以使用对象或字符串变量：

示例 #5 对其它变量使用 `instanceof`

    <?php
    interface MyInterface
    {
    }

    class MyClass implements MyInterface
    {
    }

    $a = new MyClass;
    $b = new MyClass;
    $c = 'MyClass';
    $d = 'NotMyClass';

    var_dump($a instanceof $b); // $b 是 MyClass 类的对象
    var_dump($a instanceof $c); // $c 是字符串 'MyClass'
    var_dump($a instanceof $d); // $d 是字符串 'NotMyClass'
    ?>

以上示例会输出：

    bool(true)
    bool(true)
    bool(false)

如果被检测的变量不是对象，instanceof 并不发出任何错误信息而是返回 `false`。PHP 7.3.0 之前不允许用于检测常量。

示例 #6 用 `instanceof` 检测其它变量

    <?php
    $a = 1;
    $b = NULL;
    $c = fopen('/tmp/', 'r');
    var_dump($a instanceof stdClass); // $a 是整数
    var_dump($b instanceof stdClass); // $b 是 NULL
    var_dump($c instanceof stdClass); // $c 是资源
    var_dump(FALSE instanceof stdClass);
    ?>

以上示例会输出：

    bool(false)
    bool(false)
    bool(false)
    PHP Fatal error:  instanceof expects an object instance, constant given

PHP 7.3.0 起， `instanceof` 操作符的左侧可以放常量。

示例 #7 使用 `instanceof` 测试常量

    <?php
    var_dump(FALSE instanceof stdClass);
    ?>

以上示例在 PHP 7.3 中的输出：

    bool(false)

PHP 8.0.0 起， `instanceof` 可以与任何表达式一起使用。表达式必须使用括号括起来并且生成 string。

示例 #8 将 `instanceof` 与任意表达式一起使用

    <?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()));
    ?>

以上示例在 PHP 8 中的输出：

    bool(true)
    bool(true)
    bool(false)
    bool(true)

`instanceof` 在功能上有个 类似的变体 is_a()。

### 参见

- get_class()
- is_a()

## 函数式运算符

PHP 8.5 及更高版本支持可直接作用于可调用对象的操作符。`|>` 操作符（或称为“管道”），在右侧接受单个参数的可调用对象，并将左侧的值传递给它，最终返回该可调用对象的结果。右侧的可调用对象可以是任何有效的 PHP 可调用对象：Closure、一等可调用对象、实现了 __invoke() 方法的对象等。

这意味着以下两行在逻辑上是等价的。

示例 #1 使用 `|>`

    <?php
    $result = "Hello World" |> strlen(...);
    echo $result, PHP_EOL;

    $result = strlen("Hello World");
    echo $result, PHP_EOL;
    ?>

以上示例会输出：

    11
    11

对于单次调用，并不特别有用。当多个调用链式组合时，其作用才得以体现。也就是说，以下两段代码在逻辑上是等价的：

示例 #2 链式 |> 调用

    <?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);
    ?>

以上示例会输出：

    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
    )

管道的左侧可以是任何值或表达式。右侧可以是任何接受单个参数的有效 PHP 可调用对象，或是任何能够解析为这种可调用对象的表达式。不允许超过一个必需参数的函数，此类情况将如同普通调用时参数不足一样导致失败。不允许通过引用传递变量的函数。如果右侧无法解析为有效的可调用对象，则会抛出 Error。

> 注意:

> 需要注意，为了避免语法歧义，箭头函数在与管道操作符一起使用时必须用括号包裹，如上述示例所示。未遵循此要求将导致核心错误。

### 参见

- Closure

# 流程控制

## 目录

- 简介
- if
- else
- elseif/else if
- 流程控制的替代语法
- while
- do-while
- for
- foreach
- break
- continue
- switch
- match
- declare
- return
- require
- include
- require_once
- include_once
- goto

## 简介

任何 PHP 脚本都是由一系列语句构成的。一条语句可以是一个赋值语句，一个函数调用，一个循环，一个条件语句或者甚至是一个什么也不做的语句（空语句）。语句通常以分号结束。此外，还可以用花括号将一组语句封装成一个语句组。语句组本身可以当作是一行语句。本章介绍了各种语句类型。

### 参见

以下也被认为是语言结构，尽管在手册中它们是在函数下引用的。

- list()
- array()
- echo
- eval()
- print

## if

(PHP 4, PHP 5, PHP 7, PHP 8)

`if` 结构是很多语言包括 PHP 在内最重要的特性之一，它允许按照条件执行代码片段。PHP 的 `if` 结构和 C 语言相似：

    <?php
    if (expr)
      statement
    ?>

如同在表达式一章中定义的，expr 按照布尔求值。如果 expr 的值为 `true`，PHP 将执行 statement，如果值为 `false` ——将忽略 statement。有关哪些值被视为 `false` 的更多信息参见转换为布尔值一节。

如果 $a 大于 $b，则以下例子将显示 a is bigger than b：

    <?php
    if ($a > $b)
      echo "a is bigger than b";
    ?>

经常需要按照条件执行不止一条语句，当然并不需要给每条语句都加上一个 `if` 子句。可以将这些语句放入语句组中。例如，如果 $a 大于 $b，以下代码将显示 a is bigger than b 并且将 $a 的值赋给 $b：

    <?php
    if ($a > $b) {
      echo "a is bigger than b";
      $b = $a;
    }
    ?>

`if` 语句可以无限层地嵌套在其它 `if` 语句中，这给程序的不同部分的条件执行提供了充分的弹性。

## else

(PHP 4, PHP 5, PHP 7, PHP 8)

经常需要在满足某个条件时执行一条语句，而在不满足该条件时执行其它语句，这正是 `else` 的功能。`else` 延伸了 `if` 语句，可以在 `if` 语句中的表达式的值为 `false` 时执行语句。例如以下代码在 $a 大于 $b 时显示 a is bigger than b，反之则显示 a is NOT bigger than b：

    <?php
    if ($a > $b) {
      echo "a is greater than b";
    } else {
      echo "a is NOT greater than b";
    }
    ?>

`else` 语句仅在 `if` 以及 `elseif`（如果有的话）语句中的表达式的值为 `false` 时执行（参见 elseif）。

> 注意: 悬挂的 else

> 在多层嵌套 `if`-`else` 语句的情况下， `else` 总是与最近的 `if` 进行关联。

>     <?php
>     $a = false;
>     $b = true;
>     if ($a)
>         if ($b)
>             echo "b";
>     else
>         echo "c";
>     ?>

> 虽然存在缩进（对 PHP 来说，无关紧要）， 但是 `else` 还是与 `if ($b)` 进行关联，所以以上示例不会产生任何输出。虽然可以依赖此特性，但是推荐使用花括号，避免潜在的歧义问题。

## elseif/else if

(PHP 4, PHP 5, PHP 7, PHP 8)

`elseif`，和此名称暗示的一样，是 `if` 和 `else` 的组合。和 `else` 一样，它延伸了 `if` 语句，可以在原来的 `if` 表达式值为 `false` 时执行不同语句。但是和 `else` 不一样的是，它仅在 `elseif` 的条件表达式值为 `true` 时执行语句。例如以下代码将根据条件分别显示 a is bigger than b，a equal to b 或者 a is smaller than b：

    <?php
    if ($a > $b) {
        echo "a is bigger than b";
    } elseif ($a == $b) {
        echo "a is equal to b";
    } else {
        echo "a is smaller than b";
    }
    ?>

在一个 `if` 语句中可以有多个 `elseif`，其中将会执行第一个表达式值为 `true`（如果有的话）的 `elseif`。在 PHP 中，也可以写成 `else if`（两个单词），它和 `elseif`（一个单词）的行为完全一样。句法分析的含义有少许区别（行为与 C 相同），但是底线是两者会产生完全一样的行为。

`elseif` 的语句仅在之前的 `if` 和所有之前 `elseif` 的表达式值为 `false`，并且当前的 `elseif` 表达式值为 `true` 时执行。

> 注意: 必须要注意的是 `elseif` 与 `else if` 只有在类似上例中使用花括号的情况下才认为是完全相同。如果用冒号来定义 `if`/`elseif` 条件，必须在一个单词中使用 `elseif`。如果 `else if` 分割为两个单词，则 PHP 会产生解析错误。

    <?php

    /* 不正确的使用方法： */
    if ($a > $b):
        echo $a." is greater than ".$b;
    else if ($a == $b): // 将无法编译
        echo "The above line causes a parse error.";
    endif;

    <?php
    /* 正确的使用方法： */
    if ($a > $b):
        echo $a." is greater than ".$b;
    elseif ($a == $b): // 注意使用了一个单词的 elseif
        echo $a." equals ".$b;
    else:
        echo $a." is neither greater than or equal to ".$b;
    endif;

    ?>

## 流程控制的替代语法

(PHP 4, PHP 5, PHP 7, PHP 8)

PHP 提供了一些流程控制的替代语法，包括 `if`，`while`，`for`，`foreach` 和 `switch`。替代语法的基本形式是把左花括号（{）换成冒号（:），把右花括号（}）分别换成 `endif;`，`endwhile;`，`endfor;`，`endforeach;` 以及 `endswitch;`。

    <?php if ($a == 5): ?>
    A is equal to 5
    <?php endif; ?>

在上面的例子中，HTML 内容“A is equal to 5”用替代语法嵌套在 `if` 语句中。该 HTML 的内容仅在 $a 等于 5 时显示。

替代语法同样可以用在 `else` 和 `elseif` 中。下面是一个包括 `elseif` 和 `else` 的 `if` 结构用替代语法格式写的例子：

    <?php
    if ($a == 5):
        echo "a equals 5";
        echo "...";
    elseif ($a == 6):
        echo "a equals 6";
        echo "!!!";
    else:
        echo "a is neither 5 nor 6";
    endif;
    ?>

> 注意:

> 不支持在同一个控制块内混合使用两种语法。

警告

`switch` 和第一个 `case` 之间的任何输出（含空格）将导致语法错误。例如，这样是无效的：

    <?php switch ($foo): ?>
        <?php case 1: ?>
        // ...
    <?php endswitch; ?>

而这样是有效的，因为 `switch` 之后的换行符被认为是结束标记 `?>` 的一部分，所以在 `switch` 和 `case` 之间不能有任何输出：

    <?php switch ($foo): ?>
    <?php case 1: ?>
        ...
    <?php endswitch; ?>

更多例子参见 while，for 和 if。

## while

(PHP 4, PHP 5, PHP 7, PHP 8)

`while` 循环是 PHP 中最简单的循环类型。它和 C 语言中的 `while` 表现地一样。`while` 语句的基本格式是：

    while (expr)
        statement

`while` 语句的含意很简单，它告诉 PHP 只要 `while` 表达式的值为 `true` 就重复执行嵌套中的循环语句。表达式的值在每次开始循环时检查，所以即使这个值在循环语句中改变了，语句也不会停止执行，直到本次循环结束。 如果 `while` 表达式的值一开始就是 `false`，则循环语句一次都不会执行。

和 `if` 语句一样，可以在 `while` 循环中用花括号括起一个语句组，或者用替代语法：

    while (expr):
        statement
        ...
    endwhile;

下面两个例子完全一样，都显示数字 1 到 10：

    <?php
    /* 示例 1 */

    $i = 1;
    while ($i <= 10) {
        echo $i++;  /* 在自增前（后自增）打印的值将会是 $i */
    }

    /* 示例 2 */

    $i = 1;
    while ($i <= 10):
        print $i;
        $i++;
    endwhile;
    ?>

## do-while

(PHP 4, PHP 5, PHP 7, PHP 8)

`do-while` 循环和 `while` 循环非常相似，区别在于表达式的值是在每次循环结束时检查而不是开始时。和一般的 `while` 循环主要的区别是 `do-while` 的循环语句保证会执行一次（表达式的真值在每次循环结束后检查），然而在一般的 `while` 循环中就不一定了（表达式真值在循环开始时检查，如果一开始就为 `false` 则整个循环立即终止）。

`do-while` 循环只有一种语法：

    <?php
    $i = 0;
    do {
       echo $i;
    } while ($i > 0);
    ?>

以上循环将正好运行一次，因为经过第一次循环后，当检查表达式的真值时，其值为 `false`（$i 不大于 0）而导致循环终止。

资深的 C 语言用户可能熟悉另一种不同的 `do-while` 循环用法，把语句放在 `do-while`(0) 之中，在循环内部用 `break` 语句来结束执行循环。以下代码片段示范了此方法：

    <?php
    do {
        if ($i < 5) {
            echo "i is not big enough";
            break;
        }
        $i *= $factor;
        if ($i < $minimum_limit) {
            break;
        }
        echo "i is ok";

        /* 处理 i */

    } while(0);
    ?>

可以使用 `goto` 跳出循环，取代这种 hack 的方式。

## for

(PHP 4, PHP 5, PHP 7, PHP 8)

`for` 循环是 PHP 中最复杂的循环结构。它的行为和 C 语言的相似。 `for` 循环的语法是：

    for (expr1; expr2; expr3)
        statement

第一个表达式（expr1）在循环开始前无条件求值（并执行）一次。

expr2 在每次循环开始前求值。如果值为 `true`，则继续循环，执行嵌套的循环语句。如果值为 `false`，则终止循环。

expr3 在每次循环之后被求值（并执行）。

每个表达式都可以为空或包括逗号分隔的多个表达式。表达式 expr2 中，所有用逗号分隔的表达式都会计算，但只取最后一个结果。expr2 为空意味着将无限循环下去（和 C 一样，PHP 暗中认为其值为 `true`）。这可能不像想象中那样没有用，因为经常会希望用有条件的 `break` 语句来结束循环而不是用 `for` 的表达式真值判断。

考虑以下的例子，它们都显示数字 1 到 10：

    <?php
    /* 示例 1 */

    for ($i = 1; $i <= 10; $i++) {
        echo $i;
    }

    /* 示例 2 */

    for ($i = 1; ; $i++) {
        if ($i > 10) {
            break;
        }
        echo $i;
    }

    /* 示例 3 */

    $i = 1;
    for (;;) {
        if ($i > 10) {
            break;
        }
        echo $i;
        $i++;
    }

    /* 示例 4 */

    for ($i = 1, $j = 0; $i <= 10; $j += $i, print $i, $i++);
    ?>

当然，第一个例子看上去最简洁（或者有人认为是第四个），但用户可能会发现在 `for` 循环中用空的表达式在很多场合下会很方便。

PHP 也支持用冒号的 `for` 循环的替代语法。

    for (expr1; expr2; expr3):
        statement;
        ...
    endfor;

有时经常需要像下面这样例子一样对数组进行遍历：

    <?php
    /*
     * 此数组将在遍历的过程中改变其中某些单元的值
     */
    $people = Array(
            Array('name' => 'Kalle', 'salt' => 856412),
            Array('name' => 'Pierre', 'salt' => 215863)
            );

    for($i = 0; $i < count($people); ++$i)
    {
        $people[$i]['salt'] = rand(000000, 999999);
    }
    ?>

以上代码可能执行很慢，因为每次循环时都要计算一遍数组的长度。由于数组的长度始终不变，可以用一个中间变量来储存数组长度以优化而不是不停调用 count()：

    <?php
    $people = Array(
            Array('name' => 'Kalle', 'salt' => 856412),
            Array('name' => 'Pierre', 'salt' => 215863)
            );

    for($i = 0, $size = count($people); $i < $size; ++$i)
    {
        $people[$i]['salt'] = rand(000000, 999999);
    }
    ?>

## foreach

(PHP 4, PHP 5, PHP 7, PHP 8)

`foreach` 结构提供了一种遍历 array 和 Traversable object 的简便方式。当用于其他数据类型的变量，或未初始化的变量时，`foreach` 会触发错误。

`foreach` 可选择性的获取每个元素的 `key`：

    foreach (iterable_expression as $value) {
        statement_list
    }

    foreach (iterable_expression as $key => $value) {
        statement_list
    }

第一种格式遍历给定的 `iterable_expression` 迭代器。每次循环中，当前单元的值被赋给 `$value`。

第二种格式做同样的事，只除了当前单元的键名也会在每次循环中被赋给变量 `$key`。

注意 `foreach` 不会修改类似 current() 和 key() 函数所使用的数组内部指针。

还能够自定义遍历对象。

示例 #1 常见的 `foreach` 用法

    <?php

    /* 示例：仅有值 */
    $array = [1, 2, 3, 17];

    foreach ($array as $value) {
        echo "Current element of \$array: $value.\n";
    }

    /* 示例：key 和值 */
    $array = [
        "one" => 1,
        "two" => 2,
        "three" => 3,
        "seventeen" => 17
    ];

    foreach ($array as $key => $value) {
        echo "Key: $key => Value: $value\n";
    }

    /* 示例：多维 key-value 数组 */
    $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 "Value at position x=$x and y=$y: $value\n";
        }
    }

    /* 示例：动态数组 */
    foreach (range(1, 5) as $value) {
        echo "$value\n";
    }
    ?>

> 注意:

> `foreach` 不支持使用 `@` 运算符来抑制错误消息。

### 解包嵌套数组

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

可以通过遍历数组中的数组，在 value 的位置使用数组解构（`[]`）或 list() 语言结构将嵌套数组解包到循环变量中。

> 注意: 请注意，通过 `[]` 进行数组解构仅在 PHP 7.1.0 及以上版本中可用。

在以下两个示例中，将设 `$a` 为嵌套数组的第一个元素，`$b` 将包含第二个元素：

    <?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";
    }
    ?>

以上示例会输出：

    A: 1; B: 2
    A: 3; B: 4

当提供的变量数量少于数组中的元素数量时，将会忽略多余的元素。类似地，可通过使用逗号跳过某些元素：

    <?php
    $array = [
        [1, 2, 5],
        [3, 4, 6],
    ];

    foreach ($array as [$a, $b]) {
        // 注意此处没有 $c
        echo "$a $b\n";
    }

    foreach ($array as [, , $c]) {
        // 跳过 $a 和 $b
        echo "$c\n";
    }
    ?>

以上示例会输出：

    1 2
    3 4
    5
    6

如果数组元素数量不足以填充 list()，将生成一条 notice 级别的错误消息。

    <?php
    $array = [
        [1, 2],
        [3, 4],
    ];

    foreach ($array as [$a, $b, $c]) {
        echo "A: $a; B: $b; C: $c\n";
    }
    ?>

以上示例会输出：

    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 和引用

可以通过在 `$value` 前加上 `&`，就可以在循环中直接修改数组元素。此时，值将以引用的方式赋值。

    <?php
    $arr = [1, 2, 3, 4];
    foreach ($arr as &$value) {
        $value = $value * 2;
    }
    // $arr is now [2, 4, 6, 8]
    unset($value); // 断开与最后一个元素的引用
    ?>

警告

对数组最后一个元素的 `$value` 的引用在 `foreach` 循环结束后仍然存在。建议使用 unset() 将其销毁，否则将出现以下行为：

    <?php
    $arr = [1, 2, 3, 4];
    foreach ($arr as &$value) {
        $value = $value * 2;
    }
    // $arr 现在是 [2, 4, 6, 8]

    // 如果没有使用 unset(value)，$value 仍会引用最后一个元素：$arr[3]

    foreach ($arr as $key => $value) {
        // $arr[3] 会随着 $arr 中的每个值而更新……
        echo "{$key} => {$value} ";
        print_r($arr);
    }
    // ……最终会复制倒数第二个值到最后一个值上
    ?>

以上示例会输出：

    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 )

示例 #2 通过引用遍历常量数组的值

    <?php
    foreach ([1, 2, 3, 4] as &$value) {
        $value = $value * 2;
    }
    ?>

### 参见

- array
- Traversable
- iterable
- list()

## break

(PHP 4, PHP 5, PHP 7, PHP 8)

`break` 结束执行当前的 `for`、`foreach`、`while`、`do-while`、`switch` 结构。

`break` 接受一个数字的可选参数，决定跳出几重循环。 默认值是 `1`，仅仅跳出最近一层嵌套结构。

    <?php
    $arr = array('one', 'two', 'three', 'four', 'stop', 'five');
    foreach ($arr as $val) {
        if ($val == 'stop') {
            break;    /* 也可以在这里写 'break 1;'。 */
        }
        echo "$val<br />\n";
    }

    /* 使用可选参数 */

    $i = 0;
    while (++$i) {
        switch ($i) {
            case 5:
                echo "At 5<br />\n";
                break 1;  /* 只退出 switch. */
            case 10:
                echo "At 10; quitting<br />\n";
                break 2;  /* 退出 switch 和 while 循环 */
            default:
                break;
        }
    }
    ?>

## continue

(PHP 4, PHP 5, PHP 7, PHP 8)

`continue` 在循环结构用用来跳过本次循环中剩余的代码并在条件求值为真时开始执行下一次循环。

> 注意: 在 PHP 中 switch 语句被认为是可以使用 `continue` 的一种循环结构。 `continue` 的行为类似于没有传递参数的 `break` ，但会引发警告，因为这可能是一个错误。 如果 `switch` 在循环内， `continue 2` 将会外部循环中的下一个迭代中继续。

`continue` 接受一个可选的数字参数来决定跳过几重循环到循环结尾。默认值是 `1`，即跳到当前循环末尾。

    <?php
    $arr = ['zero', 'one', 'two', 'three', 'four', 'five', 'six'];
    foreach ($arr as $key => $value) {
        if (0 === ($key % 2)) { // 跳过偶数键的成员
            continue;
        }
        echo $value . "\n";
    }
    ?>

以上示例会输出：

    one
    three
    five

    <?php
    $i = 0;
    while ($i++ < 5) {
        echo "Outer\n";
        while (1) {
            echo "Middle\n";
            while (1) {
                echo "Inner\n";
                continue 3;
            }
            echo "This never gets output.\n";
        }
        echo "Neither does this.\n";
    }
    ?>

以上示例会输出：

    Outer
    Middle
    Inner
    Outer
    Middle
    Inner
    Outer
    Middle
    Inner
    Outer
    Middle
    Inner
    Outer
    Middle
    Inner

省略 `continue` 后面的分号会导致混淆。以下例子示意了不应该这样做。

    <?php
      for ($i = 0; $i < 5; ++$i) {
          if ($i == 2)
              continue
          print "$i\n";
      }
    ?>

希望得到的结果是：

    0
    1
    3
    4

`continue` 的更新记录
版本 | 说明
--- | ---
7.3.0 | 在 `switch` 中 `continue` 语句试图代替 `break` 语句将会触发 `E_WARNING` 。

## switch

(PHP 4, PHP 5, PHP 7, PHP 8)

`switch` 语句类似于具有同一个表达式的一系列 `if` 语句。很多场合下需要把同一个变量（或表达式）与很多不同的值比较，并根据它等于哪个值来执行不同的代码。这正是 `switch` 语句的用途。

> 注意: 注意和其它语言不同，continue 语句作用到 switch 上的作用类似于 `break`。如果在循环中有一个 switch 并希望 continue 到外层循环中的下一轮循环，用 `continue 2`。

> 注意:

> 注意 switch/case 作的是松散比较。

下面的例子使用不同方法实现同样的事。一个用一系列的 `if` 和 `elseif` 语句，另一个用 `switch` 语句。例子不同，但输出相同：

示例 #1 `switch` 结构

    // 这是 switch 语句

    switch ($i) {
        case 0:
            echo "i equals 0";
            break;
        case 1:
            echo "i equals 1";
            break;
        case 2:
            echo "i equals 2";
            break;
    }

    // 相当于：

    if ($i == 0) {
        echo "i equals 0";
    } elseif ($i == 1) {
        echo "i equals 1";
    } elseif ($i == 2) {
        echo "i equals 2";
    }
    ?>

为避免错误，理解 `switch` 是怎样执行的非常重要。`switch` 语句一行接一行地执行（实际上是语句接语句）。开始时没有代码被执行。仅当一个 `case` 语句中的值和 `switch` 表达式的值匹配时 PHP 才开始执行语句，直到 `switch` 的程序段结束或者遇到第一个 `break` 语句为止。如果不在 case 的语句段最后写上 `break` 的话，PHP 将继续执行下一个 case 中的语句段。例如：

    <?php
    switch ($i) {
        case 0:
            echo "i equals 0";
        case 1:
            echo "i equals 1";
        case 2:
            echo "i equals 2";
    }
    ?>

这里如果 $i 等于 0，PHP 将执行所有的 echo 语句！如果 $i 等于 1，PHP 将执行后面两条 echo 语句。只有当 $i 等于 2 时，才会得到“预期”的结果——只显示“i equals 2”。所以，别忘了 `break` 语句就很重要（即使在某些情况下故意想避免提供它们时）。

在 `switch` 语句中条件只求值一次并用来和每个 `case` 语句比较。在 `elseif` 语句中条件会再次求值。如果条件比一个简单的比较要复杂得多或者在一个很多次的循环中，那么用 `switch` 语句可能会快一些。

在一个 case 中的语句也可以为空，这样只不过将控制转移到了下一个 case 中的语句。

    <?php
    switch ($i) {
        case 0:
        case 1:
        case 2:
            echo "i is less than 3 but not negative";
            break;
        case 3:
            echo "i is 3";
    }
    ?>

一个 case 的特例是 `default`。它匹配了任何和其它 case 都不匹配的情况。例如：

    <?php
    switch ($i) {
        case 0:
            echo "i equals 0";
            break;
        case 1:
            echo "i equals 1";
            break;
        case 2:
            echo "i equals 2";
            break;
        default:
            echo "i is not equal to 0, 1 or 2";
    }
    ?>

> 注意: 如果有多个 default 将导致 `E_COMPILE_ERROR` 错误。

> 注意: 从技术上讲，`default` case 可以按照任何顺序列出。只有在没有匹配到其它的 case 时才会使用它。但是最好按照惯例，将其作为最后一个分支放在最后。

如果没有匹配到 `case` 分支且没有 `default` 分支，则不会执行任何代码，就像 `if` 不为 true 一样。

case 的值可以使用表达式。然而，该表达式将会自我求值，然后与 switch 的值进行松散比较。这意味着它不适合用于复杂的 switch 值求值。例如：

    <?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;
    }

    // 输出“B”
    ?>

对于更复杂的比较，值 `true` 可用于 switch 的值。或使用 `if`-`else` 代替 `switch`。

    <?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;
    }

    // 输出“B”
    ?>

`switch` 支持替代语法的流程控制。更多信息见流程控制的替代语法一节。

    <?php
    switch ($i):
        case 0:
            echo "i equals 0";
            break;
        case 1:
            echo "i equals 1";
            break;
        case 2:
            echo "i equals 2";
            break;
        default:
            echo "i is not equal to 0, 1 or 2";
    endswitch;
    ?>

允许使用分号代替 case 语句后的冒号，例如：

    <?php
    switch($beer)
    {
        case 'tuborg';
        case 'carlsberg';
        case 'stella';
        case 'heineken';
            echo 'Good choice';
            break;
        default;
            echo 'Please make a new selection...';
            break;
    }
    ?>

### 参见

- match

## match

(PHP 8)

`match` 表达式基于值的一致性进行分支计算。 `match`表达式和 `switch` 语句类似， 都有一个表达式主体，可以和多个可选项进行比较。 与 `switch` 不同点是，它会像三元表达式一样求值。 与 `switch` 另一个不同点，它的比较是严格比较（ `===`）而不是松散比较（`==`）。 Match 表达式从 PHP 8.0.0 起可用。

示例 #1 `match` 表达式结构

    <?php
    $return_value = match (subject_expression) {
        single_conditional_expression => return_expression,
        conditional_expression1, conditional_expression2 => return_expression,
    };
    ?>

示例 #2 `match` 的基础用法

    <?php
    $food = 'cake';

    $return_value = match ($food) {
        'apple' => 'This food is an apple',
        'bar' => 'This food is a bar',
        'cake' => 'This food is a cake',
    };

    var_dump($return_value);
    ?>

以上示例会输出：

    string(19) "This food is a cake"

示例 #3 使用 `match` 和比较运算符的示例

    <?php
    $age = 18;

    $output = match (true) {
        $age < 2 => "Baby",
        $age < 13 => "Child",
        $age <= 19 => "Teenager",
        $age >= 40 => "Old adult",
        $age > 19 => "Young adult",
    };

    var_dump($output);
    ?>

以上示例会输出：

    string(8) "Teenager"

> 注意: 不一定要使用 `match` 表达式的结果。

> 注意: 当 `match` 表达式用作独立表达式时，必须以分号 `;` 终止。

`match` 表达式跟 `switch` 语句相似，但是有以下关键区别：

- `match` 比较分支值，使用了严格比较 (`===`)， 而 switch 语句使用了松散比较。
- `match` 表达式会返回一个值。
- `match` 的分支不会像 `switch` 语句一样， 落空时执行下个 case。
- `match` 表达式必须彻底列举所有情况。

`match` 表达式和 `switch` 语句类似， 逐个检测匹配分支。一开始不会执行代码。 只有在所有之前的条件不匹配主体表达式时，才会执行剩下的条件表达式。 只会执行返回的表达式所对应的匹配条件表达式。 举例：

    <?php
    $result = match ($x) {
        foo() => 'value',
        $this->bar() => 'value', // 如果 foo() === $x，不会执行 $this->bar()
        $this->baz => beep(), // 只有 $x === $this->baz 时才会执行 beep()
        // 等等
    };
    ?>

`match` 表达式分支可以通过逗号分隔，包含多个表达式。 这是一个逻辑 OR，当多个分支表达式右侧相同时，就可以用这种缩写。

    <?php
    $result = match ($x) {
        // 匹配分支：
        $a, $b, $c => 5,
        // 等同于以下三个分支：
        $a => 5,
        $b => 5,
        $c => 5,
    };
    ?>

`default` 模式是个特殊的条件。 当之前的条件都不匹配时，会匹配到该模式。 For example:

    <?php
    $expressionResult = match ($condition) {
        1, 2 => foo(),
        3, 4 => bar(),
        default => baz(),
    };
    ?>

> 注意: 多个 default 模式将会触发 `E_FATAL_ERROR` 错误。

`match` 表达式必须详尽列出所有情况。 如果主体表达式不能被任意分支条件处理， 会抛出 UnhandledMatchError。

示例 #4 match 表达式存在未处理的示例

    <?php
    $condition = 5;

    try {
        match ($condition) {
            1, 2 => foo(),
            3, 4 => bar(),
        };
    } catch (\UnhandledMatchError $e) {
        var_dump($e);
    }
    ?>

以上示例会输出：

    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
    }

### 使用 match 表达式处理非一致性检查

可以使用 `match` 表达式将 `true` 作为主项表达式来处理非一致性条件的情况。

示例 #5 针对整数范围，使用宽泛的表达式匹配分支

    <?php

    $age = 23;

    $result = match (true) {
        $age >= 65 => 'senior',
        $age >= 25 => 'adult',
        $age >= 18 => 'young adult',
        default => 'kid',
    };

    var_dump($result);
    ?>

以上示例会输出：

    string(11) "young adult"

示例 #6 针对字符串内容，使用宽泛的表达式匹配分支

    <?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);
    ?>

以上示例会输出：

    string(2) "fr"

## declare

(PHP 4, PHP 5, PHP 7, PHP 8)

`declare` 结构用来设定一段代码的执行指令。`declare` 的语法和其它流程控制结构相似：

    declare (directive)
        statement

`directive` 部分允许设定 `declare` 代码段的行为。 目前只认识三个指令：

- `ticks`
- `encoding`
- `strict_types`

因为本指令是在文件编译时处理的，所以指令只接受字面量的值。 无法使用变量和常量。下面为你演示：

    <?php
    // 这样是有效的：
    declare(ticks=1);

    // 这样是无效的：
    const TICK_VALUE = 1;
    declare(ticks=TICK_VALUE);
    ?>

`declare` 代码段中的 `statement` 部分将被执行——怎样执行以及执行中有什么副作用出现取决于 `directive` 中设定的指令。

`declare` 结构也可用于全局范围，影响到其后的所有代码（但如果有 `declare` 结构的文件被其它文件包含，则对包含它的父文件不起作用）。

    <?php
    // 两者相等：

    // 可以这样用：
    declare(ticks=1) {
        // 这里写完整的脚本
    }

    // 也可以这样用：
    declare(ticks=1);
    // 这里写完整的脚本
    ?>

### Ticks

Tick（时钟周期）是一个在 `declare` 代码段中解释器每执行 N 条可计时的低级语句就会发生的事件。N 的值是在 `declare` 中的 `directive` 部分用 `ticks=N` 来指定的。

不是所有语句都可计时。通常条件表达式和参数表达式都不可计时。

在每个 tick 中出现的事件是由 register_tick_function() 来指定的。更多细节见下面的例子。注意每个 tick 中可以出现多个事件。

示例 #1 Tick 的用法示例

    <?php

    declare(ticks=1);

    // 每次 tick 事件都会调用该函数
    function tick_handler()
    {
        echo "tick_handler() called\n";
    }

    register_tick_function('tick_handler'); // 引起 tick 事件

    $a = 1; // 引起 tick 事件

    if ($a > 0) {
        $a += 2; // 引起 tick 事件
        print $a; // 引起 tick 事件
    }

    ?>

参见 register_tick_function() 和 unregister_tick_function()。

### Encoding

可以用 `encoding` 指令来对每段脚本指定其编码方式。

示例 #2 对脚本指定编码方式

    <?php
    declare(encoding='ISO-8859-1');
    // 在这里写代码
    ?>

警告

当和命名空间结合起来时 declare 的唯一合法语法是 `declare(encoding='...');`，其中 `...` 是编码的值。而 `declare(encoding='...') {}` 将在与命名空间结合时产生解析错误。

参见 zend.script_encoding。

## return

(PHP 4, PHP 5, PHP 7, PHP 8)

`return` 将程序控制返还给调用模块。 将在调用模块中执行的下一句表达式中继续。

如果在一个函数中调用 return 语句，将立即结束此函数的执行并将它的参数作为函数的值返回。return 也会终止 eval() 语句或者脚本文件的执行。

如果在全局范围中调用，则当前脚本文件中止运行。如果当前脚本文件是被 include 的或者 require 的，则控制交回调用文件。此外，如果当前脚本是被 include 的，则 return 的值会被当作 include 调用的返回值。如果在主脚本文件中调用 return，则脚本中止运行。如果当前脚本文件是在 php.ini 中的配置选项 auto_prepend_file 或者 auto_append_file 所指定的，则此脚本文件中止运行。

更多信息见返回值。

> 注意: 注意既然 return 是语言结构而不是函数，因此其参数没有必要用括号将其括起来，也不推荐这样用。

> 注意: 如果没有提供参数，则一定不能用括号，此时返回 `null`。如果调用 `return` 时加上了括号却又没有参数会导致解析错误。

自 PHP 7.1.0 起，如果函数中声明的返回类型是 void 而带了返回的参数，将导致 `E_COMPILE_ERROR`，相反声明了返回类型而未带参数也会同样导致该错误。

## require

(PHP 4, PHP 5, PHP 7, PHP 8)

`require` 跟 include 相同，只是在失败时还会产生 Error 异常（PHP 8.0.0 之前为 `E_COMPILE_ERROR` 级别错误），而 include 只会产生警告（`E_WARNING` 级别错误）。

参见 include 文档了解详情。

## include

(PHP 4, PHP 5, PHP 7, PHP 8)

`include` 表达式包含并运行指定文件。

以下文档也适用于 require。

被包含文件先按参数给出的路径寻找，如果没有给出目录（只有文件名）时则按照 include_path 指定的目录寻找。如果在 include_path 下没找到该文件则 `include` 最后才在调用脚本文件所在的目录和当前工作目录下寻找。如果最后仍未找到文件则 `include` 结构会发出一条 `E_WARNING` ；这一点和 require 不同，后者会发出一个 `E_ERROR` 。

注意如果文件无法访问， `include` 和 `require` 在分别发出最后的 `E_WARNING` 或 `E_ERROR` 之前，都会发出额外一条 `E_WARNING`。

如果定义了路径——不管是绝对路径（在 Windows 下以盘符或者 `\` 开头，在 Unix/Linux 下以 `/` 开头）还是当前目录的相对路径（以 `.` 或者 `..` 开头）——include_path 都会被完全忽略。例如一个文件以 `../` 开头，则解析器会在当前目录的父目录下寻找该文件。

有关 PHP 怎样处理包含文件和包含路径的更多信息参见 include_path 部分的文档。

当一个文件被包含时，其中所包含的代码继承了 include 所在行的变量范围。从该处开始，调用文件在该行处可用的任何变量在被调用的文件中也都可用。不过所有在包含文件中定义的函数和类都具有全局作用域。

示例 #1 基本的 `include` 例子

    vars.php
    <?php

    $color = 'green';
    $fruit = 'apple';

    ?>

    test.php
    <?php

    echo "A $color $fruit"; // A

    include 'vars.php';

    echo "A $color $fruit"; // A green apple

    ?>

如果 include 出现于调用文件中的一个函数里，则被调用的文件中所包含的所有代码将表现得如同它们是在该函数内部定义的一样。所以它将遵循该函数的变量范围。此规则的一个例外是魔术常量，它们是在发生包含之前就已被解析器处理的。

示例 #2 函数中的包含

    <?php

    function foo()
    {
        global $color;

        include 'vars.php';

        echo "A $color $fruit";
    }

    /* vars.php 在 foo() 范围内，所以 $fruit 在范围为不可用。 *
     * $color 能用是因为声明成全局变量。 */

    foo();                    // A green apple
    echo "A $color $fruit";   // A green

    ?>

当一个文件被包含时，语法解析器在目标文件的开头脱离 PHP 模式并进入 HTML 模式，到文件结尾处恢复。由于此原因，目标文件中需要作为 PHP 代码执行的任何代码都必须被包括在有效的 PHP 起始和结束标记之中。

如果“URL include wrappers”在 PHP 中被激活，可以用 URL（通过 HTTP 或者其它支持的封装协议——见支持的协议和封装协议）而不是本地文件来指定要被包含的文件。如果目标服务器将目标文件作为 PHP 代码解释，则可以用适用于 HTTP GET 的 URL 请求字符串来向被包括的文件传递变量。严格的说这和包含一个文件并继承父文件的变量空间并不是一回事；该脚本文件实际上已经在远程服务器上运行了，而本地脚本则包括了其结果。

示例 #3 通过 HTTP 进行的 `include`

    <?php

    /* 这个示例假定 www.example.com 配置为解析 .php 文件而不解析 .txt 文件。 *
     * 此外 “Works” 意味着 $foo 和 $bar 变量在包含的文件中是可用的。         */

    // 无法执行； file.txt 没有被 www.example.com 当作 PHP 处理。
    include 'http://www.example.com/file.txt?foo=1&bar=2';

    // 无法执行；在本地文件系统中查找名为 “file.php?foo=1&bar=2” 的文件。
    include 'file.php?foo=1&bar=2';

    // 正常。
    include 'http://www.example.com/file.php?foo=1&bar=2';
    ?>

警告

# 安全警告

远程文件可能会经远程服务器处理（根据文件后缀以及远程服务器是否在运行 PHP 而定），但必须产生出一个合法的 PHP 脚本，因为其将被本地服务器处理。如果来自远程服务器的文件应该在远端运行而只输出结果，那用 readfile() 函数更好。另外还要格外小心以确保远程的脚本产生出合法并且是所需的代码。

相关信息参见使用远程文件，fopen() 和 file()。

处理返回值：在失败时 `include` 返回 `FALSE` 并且发出警告。成功的包含则返回 `1`，除非在包含文件中另外给出了返回值。可以在被包括的文件中使用 return 语句来终止该文件中程序的执行并返回调用它的脚本。同样也可以从被包含的文件中返回值。可以像普通函数一样获得 include 调用的返回值。不过这在包含远程文件时却不行，除非远程文件的输出具有合法的 PHP 开始和结束标记（如同任何本地文件一样）。可以在标记内定义所需的变量，该变量在文件被包含的位置之后就可用了。

因为 `include` 是一个特殊的语言结构，其参数不需要括号。在比较其返回值时要注意。

示例 #4 比较 include 的返回值

    <?php
    // 不能运行，执行 include(('vars.php') == TRUE) 就等于执行 include('1')
    if (include('vars.php') == TRUE) {
        echo 'OK';
    }

    // 正常
    if ((include 'vars.php') == TRUE) {
        echo 'OK';
    }
    ?>

示例 #5 `include` 和 return 语句

    return.php
    <?php

    $var = 'PHP';

    return $var;

    ?>

    noreturn.php
    <?php

    $var = 'PHP';

    ?>

    testreturns.php
    <?php

    $foo = include 'return.php';

    echo $foo; // 打印 'PHP'

    $bar = include 'noreturn.php';

    echo $bar; // 打印 1

    ?>

`$bar` 的值为 `1` 是因为 include 成功运行了。注意以上例子中的区别。第一个在被包含的文件中用了 return 而另一个没有。如果文件不能被包含，则返回 `false` 并发出一个 `E_WARNING` 警告。

如果在包含文件中定义了函数，无论是在 return 之前还是之后，都可以独立在主文件（main）中使用。如果文件被包含两次，由于函数重复定义，PHP 会 发出致命错误（fatal error）。推荐使用 include_once 而不是检查文件是否已包含并在包含文件中有条件返回。

另一个将 PHP 文件“包含”到一个变量中的方法是用输出控制函数结合 include 来捕获其输出，例如：

示例 #6 使用输出缓冲来将 PHP 文件包含入一个字符串

    <?php
    $string = get_include_contents('somefile.php');

    function get_include_contents($filename) {
        if (is_file($filename)) {
            ob_start();
            include $filename;
            $contents = ob_get_contents();
            ob_end_clean();
            return $contents;
        }
        return false;
    }

    ?>

要在脚本中自动包含文件，参见 php.ini 中的 auto_prepend_file 和 auto_append_file 配置选项。

> 注意: 因为是语言构造器而不是函数，不能被 可变函数 或者 命名参数 调用。

参见 require、require_once、include_once、get_included_files()、readfile()、virtual()、include_path。

## require_once

(PHP 4, PHP 5, PHP 7, PHP 8)

`require_once` 表达式和 require 表达式完全相同，唯一区别是 PHP 会检查该文件是否已经被包含过，如果是则不会再次包含。

参见 include_once 的文档来理解 `_once` 的含义，并理解与没有 `_once` 时候有什么不同。

## include_once

(PHP 4, PHP 5, PHP 7, PHP 8)

`include_once` 表达在脚本执行期间包含并运行指定文件。此行为和 include 表达类似， 唯一区别是如果该文件中已经被包含过，则不会再次包含，且 include_once 会返回 `true`。 顾名思义，require_once，文件仅仅包含（require）一次。

`include_once` 可以用于在脚本执行期间同一个文件有可能被包含超过一次的情况下，想确保它只被包含一次以避免函数重定义，变量重新赋值等问题。

更多信息参见 include 文档。

## goto

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

此漫画鸣谢 » xkcd

`goto` 操作符可以用来跳转到程序中的另一位置。该目标位置可以用 区分大小写 的目标名称加上冒号来标记，而跳转指令是 `goto` 之后接上目标位置的标记。PHP 中的 `goto` 有一定限制，目标位置只能位于同一个文件和作用域，也就是说无法跳出一个函数或类方法，也无法跳入到另一个函数。也无法跳入到任何循环或者 switch 结构中。可以跳出循环或者 switch，通常的用法是用 `goto` 代替多层的 `break`。

示例 #1 `goto` 示例

    <?php

    goto a;
    echo 'Foo';

    a:
    echo 'Bar';

    ?>

以上示例会输出：

    Bar

示例 #2 `goto` 跳出循环示例

    <?php

    for ($i = 0, $j = 50; $i < 100; $i++) {
        while ($j--) {
            if ($j == 17) {
                goto end;
            }
        }
    }
    echo "i = $i";
    end:
    echo 'j hit 17';

    ?>

以上示例会输出：

    j hit 17

示例 #3 以下写法无效

    <?php

    goto loop;
    for ($i = 0, $j = 50; $i < 100; $i++) {
        while ($j--) {
            loop:
        }
    }
    echo "$i = $i";

    ?>

以上示例会输出：

    Fatal error: 'goto' into loop or switch statement is disallowed in
    script on line 2

# 函数

## 目录

- 用户自定义函数
- 函数的参数和参数值
- 返回值
- 可变函数
- 内部（内置）函数
- 匿名函数
- 箭头函数
- 一级可调用语法

## 用户自定义函数

函数的定义是通过使用 `function` 关键字、名称、由逗号（`,`）分隔并用圆括号括起来的参数列表（可能为空），后接包含使用大括号括起来的函数主体，例如以下形式：

示例 #1 声明名为 `foo` 的新函数

    <?php
    function foo($arg_1, $arg_2, /* ..., */ $arg_n)
    {
        echo "Example function.\n";
        return $retval;
    }
    ?>

> 注意:

> 自 PHP 8.0.0 起，参数列表可以包含尾随逗号：

>     <?php
>     function foo($arg_1, $arg_2,) { }
>     ?>

任何有效的 PHP 代码都有可能出现在函数主体，甚至包括其它函数和 class 定义。

函数名和 PHP 中的其它标识符命名规则相同。有效的函数名以字母或下划线打头，后面跟字母，数字或下划线。可以用正则表达式表示为 `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`。

小技巧

请参见用户空间命名指南。

函数无需在调用之前被定义，除非是下面两个例子中函数是有条件被定义时。

当一个函数是有条件被定义时，必须在调用函数之前定义。

示例 #2 有条件的函数

    <?php

    $makefoo = true;

    /* 不能在此处调用foo()函数，
       因为它还不存在，但可以调用bar()函数。*/

    bar();

    if ($makefoo) {
      function foo()
      {
        echo "I don't exist until program execution reaches me.\n";
      }
    }

    /* 现在可以安全调用函数 foo()
       因为 $makefoo 值为真 */

    if ($makefoo) foo();

    function bar()
    {
      echo "I exist immediately upon program start.\n";
    }

    ?>

示例 #3 函数中的函数

    <?php
    function foo()
    {
      function bar()
      {
        echo "I don't exist until foo() is called.\n";
      }
    }

    /* 现在还不能调用 bar() 函数，因为它还不存在 */

    foo();

    /* 现在可以调用 bar() 函数了，因为 foo() 函数
       的执行使得 bar() 函数变为已定义的函数 */

    bar();

    ?>

PHP 中的所有函数和类都具有全局作用域，可以定义在一个函数之内而在之外调用，反之亦然。

PHP 不支持函数重载，也不可能取消定义或者重定义已声明的函数。

> 注意: 从 `A` 到 `Z` 的 ASCII 函数名是大小写无关的，不过在调用函数的时候，使用其在定义时相同的形式是个好习惯。

函数支持 可变数量的参数 和 默认参数。参见 func_num_args()、func_get_arg() 和 func_get_args() 的函数参考以获取更多信息。

在 PHP 中可以调用递归函数。

示例 #4 递归函数

    <?php
    function recursion($a)
    {
        if ($a < 20) {
            echo "$a\n";
            recursion($a + 1);
        }
    }
    ?>

> 注意: 但是要避免递归函数／方法调用超过 100-200 层，因为可能会使堆栈崩溃从而使当前脚本终止。 无限递归可视为编程错误。

## 函数的参数和参数值

函数参数在函数签名中声明。通过参数值列表可以传递信息到函数，即以逗号作为分隔符的表达式列表。函数在实际调用之前，值参数是从左向右求值的（及早求值），并将结果赋值给函数的参数。

PHP 支持按值传递参数值（默认），通过引用传递参数以及默认参数。也支持可变长度参数列表和命名参数。

> 注意:

> 自 PHP 7.3.0 起，函数调用的参数列表中可以包含尾随逗号：

>     <?php
>     $v = foo(
>         $arg_1,
>         $arg_2,
>     );
>     ?>

自 PHP 8.0.0 起，函数参数列表可以包含一个尾部的逗号，这个逗号将被忽略。这在参数列表较长或包含较长的变量名的情况下特别有用，这样可以方便地垂直列出参数。

示例 #1 函数参数使用尾部逗号

    <?php
    function takes_many_args(
        $first_arg,
        $second_arg,
        $a_very_long_argument_name,
        $arg_with_default = 5,
        $again = 'a default string', // 在 8.0.0 之前，这个尾部的逗号是不允许的。
    )
    {
        // ...
    }
    ?>

### 通过引用传递参数值

默认情况下，函数参数值通过值传递（因而即使在函数内部改变参数值，它并不会改变函数外部的值）。如果希望允许函数修改它的参数值，必须通过引用传递。

如果想要函数的参数值始终通过引用传递，可以在函数定义中该参数的前面加上符号 &：

示例 #2 用引用传递函数参数值

    <?php
    function add_some_extra(&$string)
    {
        $string .= 'and something extra.';
    }
    $str = 'This is a string, ';
    add_some_extra($str);
    echo $str;    // 输出“This is a string, and something extra.”
    ?>

将常量表达式作为参数值传递给需要通过引用传递的参数是错误的。

### 默认参数的值

函数可以使用类似分配变量的语法定义参数的默认值。仅当参数未传递值时才使用默认值；注意传递 `null` 不会分配默认值。

示例 #3 在函数中使用默认参数

    <?php
    function makecoffee($type = "cappuccino")
    {
        return "Making a cup of $type.\n";
    }
    echo makecoffee();
    echo makecoffee(null);
    echo makecoffee("espresso");
    ?>

以上示例会输出：

    Making a cup of cappuccino.
    Making a cup of .
    Making a cup of espresso.

默认参数值可以是标量值、array、特殊类型 `null`，以及从 PHP 8.1.0 开始，使用 new ClassName() 语法的对象。

示例 #4 使用非标量类型作为默认参数

    <?php
    function makecoffee($types = array("cappuccino"), $coffeeMaker = NULL)
    {
        $device = is_null($coffeeMaker) ? "hands" : $coffeeMaker;
        return "Making a cup of ".join(", ", $types)." with $device.\n";
    }
    echo makecoffee();
    echo makecoffee(array("cappuccino", "lavazza"), "teapot");?>

以上示例会输出：

    Making a cup of cappuccino with hands.
    Making a cup of cappuccino, lavazza with teapot.

示例 #5 使用对象作为默认值（自 PHP 8.1.0 起）

    <?php
    class DefaultCoffeeMaker {
        public function brew() {
            return "Making coffee.\n";
        }
    }
    class FancyCoffeeMaker {
        public function brew() {
            return "Crafting a beautiful coffee just for you.\n";
        }
    }
    function makecoffee($coffeeMaker = new DefaultCoffeeMaker)
    {
        return $coffeeMaker->brew();
    }
    echo makecoffee();
    echo makecoffee(new FancyCoffeeMaker);
    ?>

以上示例会输出：

    Making coffee.
    Crafting a beautiful coffee just for you.

默认值必须是常量表达式，不能是诸如变量，类成员，或者函数调用等。

注意任何可选参数都应在强制参数之后指定，否则可选参数不能在调用时省略。考虑以下示例：

示例 #6 函数默认参数的不正确用法

    <?php
    function makeyogurt($container = "bowl", $flavour)
    {
        return "Making a $container of $flavour yogurt.\n";
    }

    echo makeyogurt("raspberry"); // "raspberry" 是 $container, 不是 $flavour
    ?>

以上示例会输出：

    Fatal error: Uncaught ArgumentCountError: Too few arguments
     to function makeyogurt(), 1 passed in example.php on line 42

现在，比较上面的例子和这个例子：

示例 #7 函数默认参数正确的用法

    <?php
    function makeyogurt($flavour, $container = "bowl")
    {
        return "Making a $container of $flavour yogurt.\n";
    }

    echo makeyogurt("raspberry"); // "raspberry" 是 $flavour
    ?>

以上示例会输出：

    Making a bowl of raspberry yogurt.

自 PHP 8.0.0 起，命名参数可用于跳过多个可选参数。

示例 #8 函数默认参数正确的用法

    <?php
    function makeyogurt($container = "bowl", $flavour = "raspberry", $style = "Greek")
    {
        return "Making a $container of $flavour $style yogurt.\n";
    }

    echo makeyogurt(style: "natural");
    ?>

以上示例会输出：

    Making a bowl of raspberry natural yogurt.

自 PHP 8.0.0 起，弃用在可选参数之后声明强制参数。这通常可以通过删除默认值来解决，因为它永远不会被使用。唯一的例外是 `Type $param = null` 类型的参数，其中默认 `null` 使得该类型可以隐式为 null。自 PHP 8.4.0 起，此用法已弃用，而应改用显式可为 null 类型。

示例 #9 强制参数后声明可选参数

    <?php

    function foo($a = [], $b) {}     // 默认不使用；自 PHP 8.0.0 起弃用
    function foo($a, $b) {}          // 功能相同，无弃用通知

    function bar(A $a = null, $b) {} // 自 PHP 8.1.0 起，$a 是隐式必需的
                                     // （因为其位于必需的参数之前），
                                     // 但隐式可为 null（自 PHP 8.4.0 起已弃用），
                                     // 因为默认参数值为 null
    function bar(?A $a, $b) {}       // 推荐

    ?>

> 注意: 自 PHP 7.1.0 起，省略未指定默认值的参数会原因引发 ArgumentCountError；在此之前的版本会引发警告。

> 注意: 期望通过引用传参的参数可以有默认值。

### 可变数量的参数值列表

PHP 在用户自定义函数中支持可变数量的参数值列表。由 `...` 语法实现。

参数列表可能包含 `...` 记号，表示该函数接受可变数量的参数值。参数值将作为 array 传递到指定变量中：

示例 #10 使用 `...` 来访问变量参数值

    <?php
    function sum(...$numbers) {
        $acc = 0;
        foreach ($numbers as $n) {
            $acc += $n;
        }
        return $acc;
    }

    echo sum(1, 2, 3, 4);
    ?>

以上示例会输出：

    10

`...` 也可以在调用函数时将 array 或 Traversable 变量或文字解包到参数值列表中使用：

示例 #11 使用 `...` 来传递参数

    <?php
    function add($a, $b) {
        return $a + $b;
    }

    echo add(...[1, 2])."\n";

    $a = [1, 2];
    echo add(...$a);
    ?>

以上示例会输出：

    3
    3

可以在 `...` 前指定正常的位置参数。在这种情况下，只有不符合位置参数的尾部参数才会被添加到 `...` 生成的数组中。

也可以在 `...` 标记前添加 类型声明。如果存在这种情况，那么 `...` 捕获的所有参数都必须匹配参数类型。

示例 #12 输入提示的变量参数

    <?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';

    // 这将会失败，因为 null 不是 DateInterval 对象。
    echo total_intervals('d', null);
    ?>

以上示例会输出：

    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

最后，可变参数值也可以通过在 `...` 前面加上 `&` 来通过引用传递。

### 命名参数

PHP 8.0.0 开始引入了命名参数作为现有位置参数的扩展。命名参数允许根据参数名而不是参数位置向函数传参。这使得参数的含义自成体系，参数与顺序无关，并允许任意跳过默认值。

命名参数通过在参数名前加上冒号来传递。允许使用保留关键字作为参数名。参数名必须是一个标识符，不允许动态指定。

示例 #13 命名参数的语法

    <?php
    myFunction(paramName: $value);
    array_foobar(array: $value);

    // 不支持。
    function_name($variableStoringParamName: $value);
    ?>

示例 #14 通过位置传参与命名参数的对比

    <?php
    // 使用顺序传递参数：
    array_fill(0, 100, 50);

    // 使用命名参数：
    array_fill(start_index: 0, count: 100, value: 50);
    ?>

指定参数的传递顺序并不重要。

示例 #15 参数顺序不同的示例（同上例）

    <?php
    array_fill(value: 50, count: 100, start_index: 0);
    ?>

命名参数也可以与位置参数相结合使用。此种情况下，命名参数必须在位置参数之后。也可以只指定一个函数的部分可选参数，而不考虑它们的顺序。

示例 #16 命名参数与位置参数结合使用

    <?php
    htmlspecialchars($string, double_encode: false);
    // 等价于
    htmlspecialchars($string, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, 'UTF-8', false);
    ?>

传递多个参数值给同一个命名参数会导致 Error 异常。

示例 #17 传递多个参数值到相同命名参数将会导致抛出 Error

    <?php

    function foo($param) { ... }

    foo(param: 1, param: 2);
    // 错误：命名参数 $param 覆盖了之前的参数

    foo(1, param: 2);
    // 错误：命名参数 $param 覆盖了之前的参数

    ?>

自 PHP 8.1.0 起，可以在解包参数后面使用命名参数。命名参数不能覆盖已解包的参数。

示例 #18 解包后使用命名参数

    <?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)); // Fatal error。命名参数 $b 覆盖之前的参数
    ?>

## 返回值

值通过使用可选的返回语句返回。可以返回包括数组和对象的任意类型。返回语句会立即中止函数的运行，并且将控制权交回调用该函数的代码行。更多信息见 return。

> 注意:

> 如果省略了 return，则返回值为 `null`。

### return 的使用

示例 #1 return 的使用

    <?php
    function square($num)
    {
        return $num * $num;
    }
    echo square(4);   // 输出 '16'。
    ?>

函数不能返回多个值，但可以通过返回一个数组来得到类似的效果。

示例 #2 返回一个数组以得到多个返回值

    <?php
    function small_numbers()
    {
        return [0, 1, 2];
    }
    // 使用短数组语法将数组中的值赋给一组变量
    [$zero, $one, $two] = small_numbers();

    // 在 7.1.0 之前，唯一相等的选择是使用 list() 结构
    list($zero, $one, $two) = small_numbers();
    ?>

从函数返回一个引用，必须在函数声明和指派返回值给一个变量时都使用引用运算符 &：

示例 #3 从函数返回一个引用

    <?php
    function &returns_reference()
    {
        return $someref;
    }

    $newref =& returns_reference();
    ?>

有关引用的更多信息, 请查看 引用的解释。

## 可变函数

PHP 支持可变函数的概念。这意味着如果一个变量名后有圆括号，PHP 将寻找与变量的值同名的函数，并且尝试执行它。可变函数可以用来实现包括回调函数，函数表在内的一些用途。

可变函数不能用于例如 echo，print，unset()，isset()，empty()，include，require 以及类似的语言结构。需要使用自己的包装函数来将这些结构用作可变函数。

示例 #1 可变函数示例

    <?php
    function foo() {
        echo "In foo()<br />\n";
    }

    function bar($arg = '')
    {
        echo "In bar(); argument was '$arg'.<br />\n";
    }

    // 使用 echo 的包装函数
    function echoit($string)
    {
        echo $string;
    }

    $func = 'foo';
    $func();        // 调用 foo()

    $func = 'bar';
    $func('test');  // 调用 bar()

    $func = 'echoit';
    $func('test');  // 调用 echoit()
    ?>

也可以用可变函数的语法来调用一个对象的方法。

示例 #2 可变方法范例

    <?php
    class Foo
    {
        function Variable()
        {
            $name = 'Bar';
            $this->$name(); // 调用 Bar() 方法
        }

        function Bar()
        {
            echo "This is Bar";
        }
    }

    $foo = new Foo();
    $funcname = "Variable";
    $foo->$funcname();  // 调用 $foo->Variable()

    ?>

当调用静态方法时，函数调用要比静态属性优先：

示例 #3 Variable 方法和静态属性示例

    <?php
    class Foo
    {
        static $variable = 'static property';
        static function Variable()
        {
            echo 'Method Variable called';
        }
    }

    echo Foo::$variable; // 打印 'static property'。在该作用域中需要 $variable。
    $variable = "Variable";
    Foo::$variable();  // 在该作用域中读取 $variable 调用 $foo->Variable()。

    ?>

示例 #4 复杂调用

    <?php
    class Foo
    {
        static function bar()
        {
            echo "bar\n";
        }
        function baz()
        {
            echo "baz\n";
        }
    }

    $func = array("Foo", "bar");
    $func(); // 打印 "bar"
    $func = array(new Foo, "baz");
    $func(); // 打印 "baz"
    $func = "Foo::bar";
    $func(); // 打印 "bar"
    ?>

### 参见

- is_callable()
- call_user_func()
- function_exists()
- 可变变量

## 内部（内置）函数

PHP 有很多标准的函数和结构。还有一些函数需要和特定地 PHP 扩展模块一起编译，否则在使用它们的时候就会得到一个致命的“未定义函数”错误。例如，要使用 image 函数中的 imagecreatetruecolor()，需要在编译 PHP 的时候加上 GD 的支持。或者，要使用 mysqli_connect() 函数，就需要在编译 PHP 的时候加上 MySQLi 支持。有很多核心函数已包含在每个版本的 PHP 中如字符串和变量函数。调用 phpinfo() 或者 get_loaded_extensions() 可以得知 PHP 加载了那些扩展库。同时还应该注意，很多扩展库默认就是有效的。PHP 手册按照不同的扩展库组织了它们的文档。请参阅配置，安装以及各自的扩展库章节以获取有关如何设置 PHP 的信息。

手册中如何阅读函数原型讲解了如何阅读和理解一个函数的原型。确认一个函数将返回什么，或者函数是否直接作用于传递的参数是很重要的。例如，str_replace() 函数将返回修改过的字符串，而 usort() 却直接作用于传递的参数变量本身。手册中，每一个函数的页面中都有关于函数参数、行为改变、成功与否的返回值以及使用条件等信息。了解这些重要的（常常是细微的）差别是编写正确的 PHP 代码的关键。

> 注意: 如果传递给函数的参数类型与实际的类型不一致，例如将一个 array 传递给一个 string 类型的变量，那么函数的返回值是不确定的。在这种情况下，通常函数会返回 `null`。但这仅仅是一个惯例，并不一定如此。从 PHP 8.0.0 起，这种情况下应抛出 TypeError 异常。

> 注意:

> 在强制模式下内置函数的标量类型默认可以为 null。自 PHP 8.1.0 起，弃用传递 `null` 到声明为非 null 的内部函数参数，并在强制类型下发出弃用通知，与用户定义函数的行为保持一致，其中标量类型需要显式标记为可以为 null。

> 例如，strlen() 函数接受参数 `$string` 为非 null 的 string。由于历史原因，在强制模式下 PHP 允许此参数接受 `null`，并将参数隐式转化为 string，从而产生 `""` 值。相比之下，严格模式会抛出 TypeError。

>     <?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)
>     ?>

### 参见

- function_exists()
- 函数参考
- get_extension_funcs()
- dl()

## 匿名函数

匿名函数（Anonymous functions），也叫闭包函数（`closures`），允许 临时创建一个没有指定名称的函数。最经常用作回调函数 callable参数的值。当然，也有其它应用的情况。

匿名函数目前是通过 Closure 类来实现的。

示例 #1 匿名函数示例

    <?php
    echo preg_replace_callback('~-([a-z])~', function ($match) {
        return strtoupper($match[1]);
    }, 'hello-world');
    // 输出 helloWorld
    ?>

闭包函数也可以作为变量的值来使用。PHP 会自动把此种表达式转换成内置类 Closure 的对象实例。把一个 closure 对象赋值给一个变量的方式与普通变量赋值的语法是一样的，最后也要加上分号：

示例 #2 匿名函数变量赋值示例

    <?php
    $greet = function($name) {
        printf("Hello %s\r\n", $name);
    };

    $greet('World');
    $greet('PHP');
    ?>

闭包可以从父作用域中继承变量。 任何此类变量都应该用 `use` 语言结构传递进去。 PHP 7.1 起，不能传入此类变量： superglobals、 $this 或者和参数重名。 返回类型声明必须放在 `use` 子句的 后面 。

示例 #3 从父作用域继承变量

    <?php
    $message = 'hello';

    // 没有 "use"
    $example = function () {
        var_dump($message);
    };
    $example();

    // 继承 $message
    $example = function () use ($message) {
        var_dump($message);
    };
    $example();

    // 当函数被定义而不是被调用的时候继承变量的值
    $message = 'world';
    $example();

    // 重置 message
    $message = 'hello';

    // 通过引用继承
    $example = function () use (&$message) {
        var_dump($message);
    };
    $example();

    // 父级作用域改变的值反映在函数调用中
    $message = 'world';
    $example();

    // 闭包函数也可以接受常规参数
    $example = function ($arg) use ($message) {
        var_dump($arg . ' ' . $message);
    };
    $example("hello");

    // 返回类型在 use 子句的后面
    $example = function () use ($message): string {
        return "hello $message";
    };
    var_dump($example());
    ?>

以上示例的输出类似于：

    Notice: Undefined variable: message in /example.php on line 6
    NULL
    string(5) "hello"
    string(5) "hello"
    string(5) "hello"
    string(5) "world"
    string(11) "hello world"
    string(11) "hello world"

从 PHP 8.0.0 开始，作用域继承的变量列表可能包含一个尾部的逗号，这个逗号将被忽略。

这些变量都必须在函数或类的头部声明。 从父作用域中继承变量与使用全局变量是不同的。全局变量存在于一个全局的范围，无论当前在执行的是哪个函数。而 闭包的父作用域是定义该闭包的函数（不一定是调用它的函数）。示例如下：

示例 #4 Closures 和作用域

    <?php
    // 一个基本的购物车，包括一些已经添加的商品和每种商品的数量。
    // 其中有一个方法用来计算购物车中所有商品的总价格，该方法使
    // 用了一个 closure 作为回调函数。
    class Cart
    {
        const PRICE_BUTTER  = 1.00;
        const PRICE_MILK    = 3.00;
        const PRICE_EGGS    = 6.95;

        protected $products = array();

        public function add($product, $quantity)
        {
            $this->products[$product] = $quantity;
        }

        public function getQuantity($product)
        {
            return isset($this->products[$product]) ? $this->products[$product] :
                   FALSE;
        }

        public function getTotal($tax)
        {
            $total = 0.00;

            $callback =
                function ($quantity, $product) use ($tax, &$total)
                {
                    $pricePerItem = constant(__CLASS__ . "::PRICE_" .
                        strtoupper($product));
                    $total += ($pricePerItem * $quantity) * ($tax + 1.0);
                };

            array_walk($this->products, $callback);
            return round($total, 2);
        }
    }

    $my_cart = new Cart;

    // 往购物车里添加条目
    $my_cart->add('butter', 1);
    $my_cart->add('milk', 3);
    $my_cart->add('eggs', 6);

    // 打出出总价格，其中有 5% 的销售税.
    print $my_cart->getTotal(0.05) . "\n";
    // 最后结果是 54.29
    ?>

示例 #5 自动绑定 `$this`

    <?php

    class Test
    {
        public function testing()
        {
            return function() {
                var_dump($this);
            };
        }
    }

    $object = new Test;
    $function = $object->testing();
    $function();

    ?>

以上示例会输出：

    object(Test)#1 (0) {
    }

当在类的上下文中声明时，当前的类会自动与之绑定，使得 `$this` 在函数的作用域中可用。如果不需要当前类的自动绑定，可以使用 静态匿名函数 替代。

### 静态匿名函数

匿名函数允许被定义为静态化。这样可以防止当前类自动绑定到它们身上，对象在运行时也可能不会被绑定到它们上面。

示例 #6 试图在静态匿名函数中使用 `$this`

    <?php

    class Foo
    {
        function __construct()
        {
            $func = static function() {
                var_dump($this);
            };
            $func();
        }
    };
    new Foo();

    ?>

以上示例会输出：

    Notice: Undefined variable: this in %s on line %d
    NULL

示例 #7 试图将对象绑定到静态匿名函数

    <?php

    $func = static function() {
        // function body
    };
    $func = $func->bindTo(new stdClass);
    $func();

    ?>

以上示例会输出：

    Warning: Cannot bind an instance to a static closure in %s on line %d

### 更新日志

版本 | 说明
--- | ---
8.3.0 | 通过魔术方法创建的闭包可以接受命名参数。
7.1.0 | 匿名函数不能用 use 包含 superglobals 、$this 、 跟参数同名的变量。

### 注释

> 注意: 可以在闭包中使用 func_num_args()，func_get_arg() 和 func_get_args()。

## 箭头函数

箭头函数是 PHP 7.4 的新语法，是一种更简洁的 匿名函数 写法。

匿名函数和箭头函数都是 Closure 类的实现。

箭头函数的基本语法为 `fn (argument_list) => expr`。

箭头函数支持与 匿名函数 相同的功能，只是其父作用域的变量总是自动的。

当表达式中使用的变量是在父作用域中定义的，它将被隐式地按值捕获。在下面的例子中，函数 $fn1 和 $fn2 的行为是一样的。

示例 #1 箭头函数自动捕捉变量的值

    <?php

    $y = 1;

    $fn1 = fn($x) => $x + $y;
    // 相当于通过 value 使用 $y：
    $fn2 = function ($x) use ($y) {
        return $x + $y;
    };

    var_export($fn1(3));
    ?>

以上示例会输出：

    4

在箭头函数嵌套的情况下同样有效。

示例 #2 箭头函数自动捕捉变量的值，即使在嵌套的情况下

    <?php

    $z = 1;
    $fn = fn($x) => fn($y) => $x * $y + $z;
    // 输出 51
    var_export($fn(5)(10));
    ?>

和匿名函数一样，箭头函数语法同样允许标准的函数声明，包括参数和返回类型、缺省值、变量，以及通过引用传递和返回。以下都是箭头函数的有效例子。

示例 #3 合法的箭头函数例子

    <?php

    fn(array $x) => $x;
    static fn($x): int => $x;
    fn($x = 42) => $x;
    fn(&$x) => $x;
    fn&($x) => $x;
    fn($x, ...$rest) => $rest;

    ?>

箭头函数会自动绑定上下文变量，这相当于对箭头函数内部使用的每一个变量 $x 执行了一个 `use($x)`。这意味着不可能修改外部作用域的任何值，若要实现对值的修改，可以使用 匿名函数 来替代。

示例 #4 来自外部范围的值不能在箭头函数内修改

    <?php

    $x = 1;
    $fn = fn() => $x++; // 不会影响 x 的值
    $fn();
    var_export($x);  // 输出 1

    ?>

### 更新日志

版本 | 说明
--- | ---
7.4.0 | 新增箭头函数语法。

### 注释

> 注意: 可以对箭头函数使用 func_num_args(), func_get_arg(), 和 func_get_args() 函数。

## 一级可调用语法

从 PHP 8.1.0 开始引入一级可调用语法，作为从 callable 创建匿名函数的一种方法。其取代了使用字符串和数组的现有 callable 语法。这种语法的优点是可以进行静态分析，并使用获得可调用对象的作用域。

`CallableExpr(...)` 语法用于从 callable 创建 Closure。`CallableExpr` 接受任何可以在 PHP 语法中直接调用的表达式：

示例 #1 简单的一级可调用语法

    <?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(...);  // 可调用对象
    $f3 = $obj->method(...);
    $f4 = $obj->$methodStr(...);
    $f5 = Foo::staticmethod(...);
    $f6 = $classStr::$staticmethodStr(...);

    // traditional callable using string, array
    $f7 = 'strlen'(...);
    $f8 = [$obj, 'method'](...);
    $f9 = [Foo::class, 'staticmethod'](...);
    ?>

> 注意:

> `...` 是语法的一部分，不是遗漏。

`CallableExpr(...)` 与 Closure::fromCallable() 语义相同。也就是说，与使用字符串和数组的 callable 不同，`CallableExpr(...)` 尊重其创建时的作用域：

示例 #2 `CallableExpr(...)` 与传统 callable 的作用域比较

    <?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
    // 这是因为调用是在 Foo 外部执行的，并且将从此时检查可见性。

    class Foo1 {
        public function getPrivateMethod() {
            // Uses the scope where the callable is acquired.
            return $this->privateMethod(...); // identical to Closure::fromCallable([$this, 'privateMethod']);
        }

        private function privateMethod() {
            echo __METHOD__, "\n";
        }
    }

    $foo1 = new Foo1;
    $privateMethod = $foo1->getPrivateMethod();
    $privateMethod();  // Foo1::privateMethod
    ?>

> 注意:

> 不支持通过此语法（例如 `new Foo(...)`）创建对象，因为不会视 `new Foo()` 语法为调用。

> 注意:

> 一级可调用语法不能与 nullsafe 运算符结合使用。以下两种情况都会导致编译时错误：

>     <?php
>     $obj?->method(...);
>     $obj?->prop->method(...);
>     ?>

# 类与对象

## 目录

- 简介
- 基本概念
- 属性
- 属性挂钩
- 类常量
- 类的自动加载
- 构造函数和析构函数
- 访问控制（可见性）
- 对象继承
- 范围解析操作符 （::）
- 静态（static）关键字
- 抽象类
- 对象接口
- Trait
- 匿名类
- 重载
- 遍历对象
- 魔术方法
- Final 关键字
- 对象复制
- 对象比较
- 后期静态绑定
- 对象和引用
- 对象序列化
- 协变与逆变
- 延迟对象
- OOP 变更日志

## 简介

PHP 具有完整的对象模型。特性包括： 访问控制，抽象类和 final 类与方法，附加的魔术方法，接口，对象复制。

PHP 对待对象的方式等同于引用或句柄，即每个变量都持有对象的引用，而不是整个对象的复制。参见 对象和引用。

小技巧

请参见用户空间命名指南。

## 基本概念

### class

每个类的定义都以关键字 `class` 开头，后面跟着类名，后面跟着一对花括号，里面包含有类的属性与方法的定义。

类名可以是任何不是 PHP 保留字 的有效标签。自 PHP 8.4.0 起，弃用使用单个下划线 `_` 作为类名。有效类名以字母或下划线开头，后面跟着若干字母、数字或下划线。以正则表达式表示为 `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`。

一个类可以包含有属于自己的 常量，变量（称为“属性”）以及函数（称为“方法”）。

示例 #1 简单的类定义

    <?php
    class SimpleClass
    {
        // 声明属性
        public $var = 'a default value';

        // 声明方法
        public function displayVar() {
            echo $this->var;
        }
    }
    ?>

当一个方法在类定义内部被调用时，有一个可用的伪变量 $this。$this 是一个到当前对象的引用。

警告

以静态方式去调用一个非静态方法，将会抛出一个 Error。 在 PHP 8.0.0 之前版本中，将会产生一个废弃通知，同时 $this 将会被声明为未定义。

示例 #2 使用 $this 伪变量的示例

    <?php
    class A
    {
        function foo()
        {
            if (isset($this)) {
                echo '$this is defined (';
                echo get_class($this);
                echo ")\n";
            } else {
                echo "\$this is not defined.\n";
            }
        }
    }

    class B
    {
        function bar()
        {
            A::foo();
        }
    }

    $a = new A();
    $a->foo();

    A::foo();

    $b = new B();
    $b->bar();

    B::bar();
    ?>

以上示例在 PHP 7 中的输出：

    $this is defined (A)

    Deprecated: Non-static method A::foo() should not be called statically in %s  on line 27
    $this is not defined.

    Deprecated: Non-static method A::foo() should not be called statically in %s  on line 20
    $this is not defined.

    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 is not defined.

以上示例在 PHP 8 中的输出：

    $this is defined (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

#### 只读类

自 PHP 8.2.0 起，可以使用 readonly 修饰符来标记类。将类标记为 readonly 只会向每个声明的属性添加 readonly 修饰符并禁止创建动态属性。此外，不能通过使用 AllowDynamicProperties 注解来添加对后者的支持。尝试这样做会触发编译错误。

    <?php
    #[\AllowDynamicProperties]
    readonly class Foo {
    }

    // Fatal error: Cannot apply #[AllowDynamicProperties] to readonly class Foo
    ?>

由于无类型的属性和静态属性不能用 `readonly` 修饰符，所以 readonly 也不会对其声明：

    <?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
    ?>

仅当子类也是 readonly 类时，才可以继承 readonly 类。

### new

要创建一个类的实例，必须使用 `new` 关键字。当创建新对象时该对象总是被赋值，除非该对象定义了 构造函数 并且在出错时抛出了一个 异常。类应在被实例化之前定义（某些情况下则必须这样）。

如果一个变量包含一个类名的 string 和 `new` 时，将创建该类的一个新实例。 如果该类属于一个命名空间，则必须使用其完整名称。

> 注意:

> 如果没有参数要传递给类的构造函数，类名后的括号则可以省略掉。

示例 #3 创建实例

    <?php
    class SimpleClass {
    }

    $instance = new SimpleClass();
    var_dump($instance);

    // 也可以这样做：
    $className = 'SimpleClass';
    $instance = new $className(); // new SimpleClass()
    var_dump($instance);
    ?>

PHP 8.0.0 起，支持任意表达式中使用 `new`。如果表达式生成一个 string，这将允许更复杂的实例化。表达式必须使用括号括起来。

示例 #4 使用任意表达式创建实例

在下列示例中，我们展示了多个生成类名的任意有效表达式的示例。展示了函数调用，string 连接和 `::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));
    ?>

以上示例在 PHP 8 中的输出：

    object(ClassA)#1 (0) {
    }
    object(ClassB)#1 (0) {
    }
    object(ClassC)#1 (0) {
    }
    object(ClassD)#1 (0) {
    }

在类定义内部，可以用 `new self` 和 `new parent` 创建新对象。

当把一个对象已经创建的实例赋给一个新变量时，新变量会访问同一个实例，就和用该对象赋值一样。此行为和给函数传递入实例时一样。可以用 克隆 给一个已创建的对象建立一个新实例。

示例 #5 对象赋值

    <?php
    class SimpleClass {
        public string $var;
    }

    $instance = new SimpleClass();

    $assigned   =  $instance;
    $reference  =& $instance;

    $instance->var = '$assigned will have this value';

    $instance = null; // $instance 和 $reference 变为 null

    var_dump($instance);
    var_dump($reference);
    var_dump($assigned);
    ?>

以上示例会输出：

    NULL
    NULL
    object(SimpleClass)#1 (1) {
       ["var"]=>
         string(30) "$assigned will have this value"
    }

有几种方法可以创建一个对象的实例。

示例 #6 创建新对象

    <?php

    class Test
    {
        public static function getNew()
        {
            return new static();
        }
    }

    class Child extends Test {}

    $obj1 = new Test(); // 通过类名
    $obj2 = new $obj1(); // 通过包含对象的变量
    var_dump($obj1 !== $obj2);

    $obj3 = Test::getNew(); // 通过类方法
    var_dump($obj3 instanceof Test);

    $obj4 = Child::getNew(); // 通过子类方法
    var_dump($obj4 instanceof Child);

    ?>

以上示例会输出：

    bool(true)
    bool(true)
    bool(true)

可以通过一个表达式来访问新创建对象的成员：

示例 #7 访问新创建对象的成员

    <?php
    echo (new DateTime())->format('Y'), PHP_EOL;

    // 从 PHP 8.4.0 起，周围的括号是可选的
    echo new DateTime()->format('Y'), PHP_EOL;
    ?>

以上示例的输出类似于：

    2025
    2025

> 注意: 在 PHP 7.1 之前，如果类没有定义构造函数，则不对参数进行执行。

### 属性和方法

类的属性和方法存在于不同的“命名空间”中，这意味着同一个类的属性和方法可以使用同样的名字。 在类中访问属性和调用方法使用同样的操作符，具体是访问一个属性还是调用一个方法，取决于你的上下文，即用法是变量访问还是函数调用。

示例 #8 访问类属性 vs. 调用类方法

    <?php
    class Foo
    {
        public $bar = 'property';

        public function bar() {
            return 'method';
        }
    }

    $obj = new Foo();
    echo $obj->bar, PHP_EOL, $obj->bar(), PHP_EOL;

以上示例会输出：

    property
    method

这意味着，如果你的类属性被分配给一个 匿名函数 你将无法直接调用它。因为访问类属性的优先级要更高，在此场景下需要用括号包裹起来调用。

示例 #9 类属性被赋值为匿名函数时的调用示例

    <?php
    class Foo
    {
        public $bar;

        public function __construct() {
            $this->bar = function() {
                return 42;
            };
        }
    }

    $obj = new Foo();

    echo ($obj->bar)(), PHP_EOL;

以上示例会输出：

    42

### extends

一个类可以在声明中用 `extends` 关键字继承另一个类的方法和属性。PHP 不支持多重继承，一个类只能继承一个基类。

被继承的方法和属性可以通过用同样的名字重新声明被覆盖。但是如果父类定义方法或者常量时使用了 final，则不可被覆盖。可以通过 parent:: 来访问被覆盖的方法或属性。

> 注意: 从 PHP 8.1.0 起，常量可以声明为 final。

示例 #10 简单的类继承

    <?php
    class SimpleClass
    {
        function displayVar()
        {
            echo "Parent class\n";
        }
    }

    class ExtendClass extends SimpleClass
    {
        // 同样名称的方法，将会覆盖父类的方法
        function displayVar()
        {
            echo "Extending class\n";
            parent::displayVar();
        }
    }

    $extended = new ExtendClass();
    $extended->displayVar();
    ?>

以上示例会输出：

    Extending class
    Parent Class

#### 签名兼容性规则

当覆盖（override）方法时，签名必须兼容父类方法。否则会导致 Fatal 错误，PHP 8.0.0 之前是 `E_WARNING` 级错误。 兼容签名是指：遵守协变与逆变规则；强制参数可以改为可选参数；添加的新参数只能是可选；放宽可见性而不是继续限制。这就是著名的里氏替换原则（Liskov Substitution Principle），简称 LSP。不过构造方法和私有（`private`）方法不需要遵循签名兼容规则，哪怕签名不匹配也不会导致 Fatal 错误。

示例 #11 兼容子类方法

    <?php

    class Base
    {
        public function foo(int $a) {
            echo "Valid\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);

以上示例会输出：

    Valid
    Valid

下面演示子类与父类方法不兼容的例子：通过移除参数、修改可选参数为必填参数。

示例 #12 子类方法移除参数后，导致 Fatal 错误

    <?php

    class Base
    {
        public function foo(int $a = 5) {
            echo "Valid\n";
        }
    }

    class Extend extends Base
    {
        function foo()
        {
            parent::foo(1);
        }
    }

以上示例在 PHP 8 中的输出类似于：

    Fatal error: Declaration of Extend::foo() must be compatible with Base::foo(int $a = 5) in /in/evtlq on line 13

示例 #13 子类方法把可选参数改成强制参数，导致 Fatal 错误

    <?php

    class Base
    {
        public function foo(int $a = 5) {
            echo "Valid\n";
        }
    }

    class Extend extends Base
    {
        function foo(int $a)
        {
            parent::foo($a);
        }
    }

以上示例在 PHP 8 中的输出类似于：

    Fatal error: Declaration of Extend::foo(int $a) must be compatible with Base::foo(int $a = 5) in /in/qJXVC on line 13

警告

重命名子类方法的参数名称也是签名兼容的。 然而我们不建议这样做，因为使用命名参数时， 这种做法会导致运行时的 Error。

示例 #14 在子类中重命一个命名参数，导致 Error

    <?php

    class A {
        public function test($foo, $bar) {}
    }

    class B extends A {
        public function test($a, $b) {}
    }

    $obj = new B;

    // 按 A::test() 的签名约定传入参数
    $obj->test(foo: "foo", bar: "bar"); // ERROR!

以上示例的输出类似于：

    Fatal error: Uncaught Error: Unknown named parameter $foo in /in/XaaeN:14
    Stack trace:
    #0 {main}
      thrown in /in/XaaeN on line 14

### ::class

关键词 `class` 也可用于类名的解析。使用 `ClassName::class` 可以获取包含类 `ClassName` 的完全限定名称。这对使用了 命名空间 的类尤其有用。

示例 #15 类名的解析

    <?php
    namespace NS {
        class ClassName {
        }

        echo ClassName::class;
    }
    ?>

以上示例会输出：

    NS\ClassName

> 注意:

> 使用 `::class` 解析类名操作会在底层编译时进行。这意味着在执行该操作时，类还没有被加载。 因此，即使要调用的类不存在，类名也会被展示。在此种场景下，并不会发生错误。

> 示例 #16 解析不存在的类名

>     <?php
>     print Does\Not\Exist::class;
>     ?>

> 以上示例会输出：

>     Does\Not\Exist

自 PHP 8.0.0 起，`::class` 也可用于对象。 与上述情况不同，此时解析将会在运行时进行。此操作的运行结果和在对象上调用 get_class() 相同。

示例 #17 类名解析

    <?php
    namespace NS {
        class ClassName {
        }

        $c = new ClassName();
        print $c::class;
    }
    ?>

以上示例会输出：

    NS\ClassName

### Nullsafe 方法和属性

自 PHP 8.0.0 起，类属性和方法可以通过 "nullsafe" 操作符访问： `?->`。 除了一处不同，nullsafe 操作符和以上原来的属性、方法访问是一致的： 对象引用解析（dereference）为 `null` 时不抛出异常，而是返回 `null`。 并且如果是链式调用中的一部分，剩余链条会直接跳过。

此操作的结果，类似于在每次访问前使用 is_null() 函数判断方法和属性是否存在，但更加简洁。

示例 #18 Nullsafe 操作符

    <?php

    // 自 PHP 8.0.0 起可用
    $result = $repository?->getUser(5)?->name;

    // 上边那行代码等价于以下代码
    if (is_null($repository)) {
        $result = null;
    } else {
        $user = $repository->getUser(5);
        if (is_null($user)) {
            $result = null;
        } else {
            $result = $user->name;
        }
    }
    ?>

> 注意:

> 仅当 null 被认为是属性或方法返回的有效和预期的可能值时，才推荐使用 nullsafe 操作符。如果业务中需要明确指示错误，抛出异常会是更好的处理方式。

## 属性

类的变量成员叫做属性，或者叫字段，在本文档统一称为属性。 属性开头至少使用一个修饰符（比如 访问控制（可见性）、静态（static）关键字或者自 PHP 8.1.0 起支持的 readonly）， 除了 `readonly` 属性之外都是可选的，然后自 PHP 7.4 起可以跟一个类型声明，然后跟一个普通的变量声明来组成。属性中的变量可以初始化，但是初始化的值必须是 常量值。

> 注意:

> 另一种过时的声明类属性的方法是使用 `var` 关键字，而不是使用修饰符。

> 注意: 没有声明 访问控制（可见性） 修饰符的属性将默认声明为 `public`。

在类的成员方法里面，可以用 `->`（对象运算符）：$this->property（其中 `property` 是该属性名）这种方式来访问非静态属性。静态属性则是用 `::`（双冒号）：self::$property 来访问。更多静态属性与非静态属性的区别参见 静态（static）关键字。

当一个方法在类定义内部被调用时，有一个可用的伪变量 $this。$this 是一个到主叫对象的引用（通常是该方法所从属的对象，但如果是从第二个对象静态调用时也可能是另一个对象）。

示例 #1 属性声明

    <?php
    class SimpleClass
    {
       public $var1 = 'hello ' . 'world';
       public $var2 = <<<EOD
    hello world
    EOD;
       public $var3 = 1+2;
       // 错误的属性声明
       public $var4 = self::myStaticMethod();
       public $var5 = $myVar;

       // 正确的属性声明
       public $var6 = myConstant;
       public $var7 = array(true, false);

       public $var8 = <<<'EOD'
    hello world
    EOD;

       // 没有访问控制修饰符：
       static $var9;
       readonly int $var10;
    }
    ?>

> 注意:

> 更多关于类／对象的处理函数，请查看类／对象函数。

### 类型声明

从 PHP 7.4.0 开始，属性定义可以包含类型声明，但 callable 除外。

示例 #2 类型声明的示例

    <?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);

    ?>

以上示例会输出：

    int(1234)
    NULL

类型属性必须在访问前初始化，否则会抛出 Error 。

示例 #3 访问属性

    <?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());
    ?>

以上示例会输出：

    string(8) "triangle"
    int(3)
    string(6) "circle"

    Fatal error: Uncaught Error: Typed property Shape::$numberOfSides must not be accessed before initialization

### 只读属性

自 PHP 8.1.0 起，可以使用 `readonly` 修饰符声明属性，防止初始化后修改属性。 在 PHP 8.4.0 之前，`readonly` 属性是隐式的私有设置，只能从同一类写入。 从 PHP 8.4.0 开始，`readonly` 属性是隐式的 `protected(set)`， 因此可以从子类设置。如果需要，可以显式覆盖。

示例 #4 只读属性示例

    <?php
    class Test {
       public readonly string $prop;
       public function __construct(string $prop) {
           // 初始化正常。
           $this->prop = $prop;
       }
    }
    $test = new Test("foobar");
    // 读取正常。
    var_dump($test->prop); // string(6) "foobar"
    // 再赋值异常。分配的值是否相同并不重要。
    $test->prop = "foobar";
    // Error: Cannot modify readonly property Test::$prop
    ?>

> 注意:

> readonly 修饰符只能应用于类型化属性。可以使用 Mixed 类型创建没有类型约束的只读属性。

> 注意:

> 不支持对静态属性只读。

只读属性只能初始化一次，并且只能从声明它的作用域内初始化。对属性的任何赋值和修改都会导致 Error 异常。

示例 #5 初始化只读属性异常

    <?php
    class Test1 {
        public readonly string $prop;
    }
    $test1 = new Test1;
    // 私有作用域之外异常初始化。
    $test1->prop = "foobar";
    // Error: Cannot initialize readonly property Test1::$prop from global scope
    ?>

> 注意:

> 禁止在只读属性上指定默认值，因为具有默认值的只读属性等同于常量，因此不是特别有用。

>     <?php

>     class Test {
>         // Fatal error: Readonly property Test::$prop cannot have default value
>         public readonly int $prop = 42;
>     }
>     ?>

> 注意:

> 只读属性一旦初始化就不能 unset()。但可以在初始化之前从声明属性的作用域中取消只读属性。

修改不一定是简单的赋值，以下所有行为也会导致 Error 异常：

    <?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);
    ?>

然而，只读属性并不会妨碍内部可变性。存储在只读属性中的对象（或资源）仍然可以在内部修改：

    <?php
    class Test {
        public function __construct(public readonly object $obj) {}
    }
    $test = new Test(new stdClass);
    // 内部可变正常。
    $test->obj->foo = 1;
    // 赋值异常。
    $test->obj = new stdClass;
    ?>

自 PHP 8.3.0 起，使用 __clone() 方法克隆对象时可以重新初始化 readonly 属性。

示例 #6 readonly 属性和克隆

    <?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
    ?>

### 动态属性

如果尝试在 object 上赋值不存在的属性，PHP 将会自动创建相应的属性。动态创建的属性将仅能在此类实例上使用。

警告

自 PHP 8.2.0 起弃用动态属性。建议更改为属性声明。要处理任意属性名称，类应该实现魔术方法 __get() 和 __set()。最后可以使用 `#[\AllowDynamicProperties]` 注解标记此类。

## 属性挂钩

属性挂钩在某些其他语言中也被称为"属性访问器"，是一种拦截和覆盖属性读写行为的方式。此功能有两个用途：

1. 允许直接使用属性，而不需要 get 和 set 方法，同时保留在未来添加额外行为的可能性。这使得大多数样板式的 get/set 方法变得不再必要，即使不使用挂钩也是如此。
2. 允许属性描述对象而不需要直接存储值。

非静态属性有两个可用的挂钩：`get` 和 `set`，分别用于覆盖属性的读取和写入行为。挂钩可用于有类型和无类型的属性。

属性可以是"backed"（有后备存储）或"virtual"（虚拟的）。backed 属性是实际存储值的属性，任何没有挂钩的属性都是 backed 属性。虚拟属性是具有挂钩且这些挂钩不与属性本身交互的属性。在这种情况下，挂钩实际上等同于方法，对象不会为该属性使用任何内存空间来存储值。

属性挂钩与 `readonly` 属性不兼容。如果需要在更改行为的同时限制对 `get` 或 `set` 操作的访问，请使用非对称属性可见性。

> 注意: 版本信息
> 属性挂钩在 PHP 8.4 中引入。

### 基本挂钩语法

声明挂钩的通用语法如下。

示例 #1 属性挂钩（完整版本）

    <?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;
    ?>

$foo 属性以 `{}` 结尾，而不是分号，这表示存在挂钩。同时定义了 `get` 和 `set` 挂钩，但也允许只定义其中一个。两个挂钩都有一个由 `{}` 表示的主体，可以包含任意代码。

`set` 挂钩还允许使用与方法相同的语法指定传入值的类型和名称。类型必须与属性的类型相同，或者对其逆变（更宽泛）。例如，string 类型的属性可以有一个接受 string|Stringable 的 `set` 挂钩，但不能有一个仅接受 array 的挂钩。

至少有一个挂钩引用了 `$this->foo`，即属性本身。这意味着该属性将是"backed"的。当调用 `$example->foo = 'changed'` 时，提供的字符串将首先被转换为小写，然后保存到后备值中。当读取属性时，之前保存的值可能会有条件地附加额外的文本。

还有许多简写语法变体可用于处理常见情况。

如果 `get` 挂钩是单个表达式，则可以省略 `{}`，替换为箭头表达式。

示例 #2 属性 get 表达式

此示例与前一个等价。

    <?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;
            }
        }
    }
    ?>

如果 `set` 挂钩的参数类型与属性类型相同（通常如此），则可以省略。在这种情况下，要设置的值会自动命名为 $value。

示例 #3 属性 set 默认值

此示例与前一个等价。

    <?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;
            }
        }
    }
    ?>

如果 `set` 挂钩只是设置传入值的修改版本，那么也可以将其简化为箭头表达式。表达式求值的结果将被设置到后备值上。

示例 #4 属性 set 表达式

    <?php
    class Example
    {
        public string $foo = 'default value' {
            get => $this->foo . ($this->modified ? ' (modified)' : '');
            set => strtolower($value);
        }
    }
    ?>

此示例与前一个并不完全等价，因为它没有修改 `$this->modified`。如果 set 挂钩主体中需要多条语句，请使用大括号版本。

属性可以根据需要实现零个、一个或两个挂钩。所有简写版本都是相互独立的。也就是说，使用简写 get 搭配完整 set，或者使用简写 set 搭配显式类型，等等都是合法的。

对于 backed 属性，省略 `get` 或 `set` 挂钩意味着将使用默认的读取或写入行为。

> 注意: 挂钩可以在使用构造函数属性提升时定义。但是，这样做时，提供给构造函数的值必须与属性关联的类型匹配，无论 `set` 挂钩允许什么。 考虑以下示例：

>     <?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;
>                 }
>             },
>         ) {
>         }
>     }

> 引擎内部会将其分解为以下形式：

>     <?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;
>         }
>     }

> 在构造函数之外设置属性时，将允许 string 或 DateTimeInterface 值，但构造函数只接受 DateTimeInterface。这是因为属性定义的类型（DateTimeInterface）被用作构造函数签名中的参数类型，无论 `set` 挂钩允许什么。 如果需要在构造函数中实现这种行为，则不能使用构造函数属性提升。

### 虚拟属性

虚拟属性是没有后备值的属性。如果属性的 `get` 和 `set` 挂钩都没有使用精确语法引用属性本身，则该属性就是虚拟的。也就是说，名为 `$foo` 的属性如果其挂钩中包含 `$this->foo`，则是 backed 属性。但以下不是 backed 属性，将会报错：

示例 #5 无效的虚拟属性

    <?php
    class Example
    {
        public string $foo {
            get {
                $temp = __PROPERTY__;
                return $this->$temp; // Doesn't refer to $this->foo, so it doesn't count.
            }
        }
    }
    ?>

对于虚拟属性，如果省略了某个挂钩，那么该操作就不存在，尝试使用它将产生错误。虚拟属性不占用对象中的内存空间。虚拟属性适用于"派生"属性，例如由其他两个属性组合而成的属性。

示例 #6 虚拟属性

    <?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.
    ?>

在虚拟属性上同时定义 `get` 和 `set` 挂钩也是允许的。

### 作用域

所有挂钩都在被修改对象的作用域内运行。这意味着它们可以访问对象的所有 public、private 或 protected 方法，以及所有 public、private 或 protected 属性，包括可能有自己属性挂钩的属性。从挂钩中访问另一个属性不会绕过该属性上定义的挂钩。

最值得注意的含义是，非简单的挂钩可以根据需要调用任意复杂的方法。

示例 #7 从挂钩中调用方法

    <?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;
        }
    }
    ?>

### 引用

由于挂钩的存在会拦截属性的读写过程，因此在获取属性的引用或进行间接修改（如 `$this->arrayProp['key'] = 'value';`）时会产生问题。这是因为任何通过引用修改值的尝试都会绕过 set 挂钩（如果定义了的话）。

在极少数需要获取定义了挂钩的属性的引用的情况下，可以在 `get` 挂钩前加上 `&` 前缀，使其按引用返回。在同一属性上同时定义 `get` 和 `&get` 是语法错误。

不允许在 backed 属性上同时定义 `&get` 和 `set` 挂钩。如上所述，通过引用写入返回的值会绕过 `set` 挂钩。在虚拟属性上，两个挂钩之间没有必然共享的值，因此允许同时定义两者。

写入数组属性的索引也涉及隐式引用。因此，只有在仅定义了 `&get` 挂钩的情况下，才允许写入带有挂钩的 backed 数组属性。在虚拟属性上，写入从 `get` 或 `&get` 返回的数组是合法的，但这是否对对象产生影响取决于挂钩的实现。

覆盖整个数组属性是可以的，行为与其他任何属性相同。只有操作数组元素时需要特别注意。

### 继承

#### Final 挂钩

挂钩也可以声明为 final，在这种情况下不能被覆盖。

示例 #8 Final 挂钩

    <?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);
        }
    }
    ?>

属性也可以声明为 final。final 属性不能被子类以任何方式重新声明，这包括修改挂钩或扩大其访问权限。

在声明为 final 的属性上将挂钩声明为 final 是多余的，会被静默忽略。这与 final 方法的行为一致。

子类可以通过重新声明属性并只定义要覆盖的挂钩来定义或重新定义各个挂钩。子类也可以向之前没有挂钩的属性添加挂钩。这本质上与挂钩是方法时的行为相同。

示例 #9 挂钩继承

    <?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;
            }
        }
    }
    ?>

每个挂钩独立于其他挂钩覆盖父类的实现。如果子类添加了挂钩，属性上设置的任何默认值都会被移除，必须重新声明。这与无挂钩属性的继承方式一致。

#### 访问父类挂钩

子类中的挂钩可以使用 `parent::$prop` 关键字后跟所需的挂钩来访问父类的属性。例如，`parent::$propName::get()`。可以理解为"访问父类中定义的 prop，然后运行其 get 操作"（或 set 操作，视情况而定）。

如果不以这种方式访问，父类的挂钩将被忽略。这一行为与所有方法的工作方式一致。这也提供了一种访问父类存储（如果有的话）的方式。如果父属性上没有挂钩，则会使用其默认的 get/set 行为。挂钩不能访问除自身属性上的父挂钩之外的任何其他挂钩。

上面的示例可以重写如下，这将允许 `Point` 类在未来添加自己的 `set` 挂钩而不会产生问题（在前面的示例中，添加到父类的挂钩会在子类中被忽略）。

示例 #10 访问父类挂钩（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);
            }
        }
    }
    ?>

仅覆盖 get 挂钩的示例如下：

示例 #11 访问父类挂钩（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());
        }
    }
    ?>

### 序列化

PHP 有多种不同的方式可以序列化对象，用于公共使用或调试目的。挂钩的行为因使用场景而异。在某些情况下，会使用属性的原始后备值，绕过所有挂钩。在其他情况下，属性将"通过"挂钩进行读取或写入，就像任何其他正常的读写操作一样。

- var_dump()：使用原始值
- serialize()：使用原始值
- unserialize()：使用原始值
- __serialize()/__unserialize()：自定义逻辑，使用 get/set 挂钩
- 数组转换：使用原始值
- var_export()：使用 get 挂钩
- json_encode()：使用 get 挂钩
- JsonSerializable：自定义逻辑，使用 get 挂钩
- get_object_vars()：使用 get 挂钩
- get_mangled_object_vars()：使用原始值

## 类常量

可以把在类中始终保持不变的值定义为 常量 。 类常量的默认可见性是 `public` 。

> 注意:

> 类常量可以通过子类重新定义。PHP 8.1.0 起，如果类常量定义为 final，则不能被子类重新定义。

接口（interface）中也可以定义常量。更多示例见文档中的接口部分。

可以用一个变量来动态调用类。但该变量的值不能为关键字（如 `self` ， `parent` 或 `static`）。

注意，类常量只为每个类分配一次，而不是为每个类的实例分配。

自 PHP 8.3.0 起，类常量可以具有标量类型，例如 `bool`、`int`、`float`、`string`，甚至是 `array`。使用 `array` 时，其内容只能包含其他标量类型。

示例 #1 定义和使用类常量

    <?php
    class MyClass
    {
        const CONSTANT = 'constant value';

        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";
    ?>

特殊的 `::class` 允许在编译时进行完全限定的类名解析， 这在命名空间类中非常有用。

示例 #2 命名空间的 ::class 示例

    <?php
    namespace foo {
        class bar {
        }

        echo bar::class; // foo\bar
    }
    ?>

示例 #3 类常量表达式示例

    <?php
    const ONE = 1;
    class foo {
        const TWO = ONE * 2;
        const THREE = ONE + self::TWO;
        const SENTENCE = 'The value of THREE is '.self::THREE;
    }
    ?>

示例 #4 自 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;
    ?>

以上示例在 PHP 7.1 中的输出：

    bar

    Fatal error: Uncaught Error: Cannot access private const Foo::BAZ in …

> 注意:

> 自 PHP 7.1.0 起，类常量允许使用可见性修饰符。

示例 #5 自 PHP 8.3.0 起，类常量可见性不一致检查

    <?php

    interface MyInterface
    {
        public const VALUE = 42;
    }

    class MyClass implements MyInterface
    {
        protected const VALUE = 42;
    }
    ?>

以上示例在 PHP 8.3 中的输出：

    Fatal error: Access level to MyClass::VALUE must be public (as in interface MyInterface) …

> 注意: 自 PHP 8.3.0 起，可见性差异检查要更加严格。在此版本之前，类常量的可见性可能与实现的接口中常量的可见性不同。

示例 #6 自 PHP 8.3.0 起获取类常量语法

    <?php
    class Foo {
        public const BAR = 'bar';
        private const BAZ = 'baz';
    }

    $name = 'BAR';
    echo Foo::{$name}, PHP_EOL; // bar
    ?>

> 注意:

> 自 PHP 8.3.0 起，可以使用变量动态获取类常量。

示例 #7 自 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);
    ?>

以上示例在 PHP 8.3 中的输出：

    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"
    }

## 类的自动加载

在编写面向对象（OOP）程序时，很多开发者为每个类新建一个 PHP 文件。 这会带来一个烦恼：每个脚本的开头，都需要包含（include）一个长长的列表（每个类都有个文件）。

spl_autoload_register() 函数可以注册任意数量的自动加载器，当使用尚未被定义的类（class）和接口（interface）时自动去加载。通过注册自动加载器，脚本引擎在 PHP 出错失败前有了最后一个机会加载所需的类。

像 class 一样的结构都可以以相同方式自动加载。包括类、接口、trait 和枚举。

警告

PHP 8.0.0 之前，可以使用 __autoload() 自动加载类和接口。然而，它是 spl_autoload_register() 的一种不太灵活的替代方法，并且 __autoload() 在 PHP 7.2.0 起弃用，在 PHP 8.0.0 起移除。

> 注意:

> spl_autoload_register() 可以多次调用以便注册多个自动加载器。但从自动加载函数中抛出异常会中断该过程并且禁止继续执行。因此强烈建议不要从自动加载函数中抛出异常。

示例 #1 自动加载示例

本例尝试分别从 MyClass1.php 和 MyClass2.php 文件中加载 `MyClass1` 和 `MyClass2` 类。

    <?php
    spl_autoload_register(function ($class_name) {
        require_once $class_name . '.php';
    });

    $obj  = new MyClass1();
    $obj2 = new MyClass2();
    ?>

示例 #2 另一个例子

本例尝试加载接口 `ITest`。

    <?php

    spl_autoload_register(function ($name) {
        var_dump($name);
    });

    class Foo implements ITest {
    }

    /*
    string(5) "ITest"

    Fatal error: Interface 'ITest' not found in ...
    */
    ?>

示例 #3 使用 Composer 的自动加载器

Composer 会生成 `vendor/autoload.php` 文件，用于自动加载 Composer 管理的软件包。通过 include 此文件，无需任何额外工作即可使用这些软件包。

    <?php
    require __DIR__ . '/vendor/autoload.php';

    $uuid = Ramsey\Uuid\Uuid::uuid7();

    echo "Generated new UUID -> ", $uuid->toString(), "\n";
    ?>

### 参见

- unserialize()
- unserialize_callback_func
- unserialize_max_depth
- spl_autoload_register()
- spl_autoload()
- __autoload()

## 构造函数和析构函数

### 构造函数

function __construct(mixed `...$values` = ""): void

PHP 允许开发者在一个类中定义一个方法作为构造函数。具有构造函数的类会在每次创建新对象时先调用此方法，所以非常适合在使用对象之前做一些初始化工作。

> 注意: 如果子类中定义了构造函数则不会隐式调用其父类的构造函数。要执行父类的构造函数，需要在子类的构造函数中调用 parent::__construct()。如果子类没有定义构造函数则会如同一个普通的类方法一样从父类继承（假如没有被定义为 private 的话）。

示例 #1 继承中的构造函数

    <?php
    class BaseClass {
        function __construct() {
            print "In BaseClass constructor\n";
        }
    }

    class SubClass extends BaseClass {
        function __construct() {
            parent::__construct();
            print "In SubClass constructor\n";
        }
    }

    class OtherSubClass extends BaseClass {
        // 继承 BaseClass 的构造函数
    }

    // In BaseClass constructor
    $obj = new BaseClass();

    // In BaseClass constructor
    // In SubClass constructor
    $obj = new SubClass();

    // In BaseClass constructor
    $obj = new OtherSubClass();
    ?>

与其它方法不同， __construct() 在继承时不受签名兼容性规则的约束。

自 PHP 5.3.3 起，在命名空间中，与类名同名的方法不再作为构造函数。不使用命名空间中的类则不受影响。 构造函数是一个普通的方法，在对应对象实例化时自动被调用。 因此可以定义任何数量的参数，可以是必选、可以有类型、可以有默认值。 构造器的参数放在类名后的括号里调用。

示例 #2 使用构造器参数

    <?php
    class Point {
        protected int $x;
        protected int $y;

        public function __construct(int $x, int $y = 0) {
            $this->x = $x;
            $this->y = $y;
        }
    }

    // 两个参数都传入
    $p1 = new Point(4, 5);
    // 仅传入必填的参数。 $y 会默认取值 0。
    $p2 = new Point(4);
    // 使用命名参数（PHP 8.0 起）:
    $p3 = new Point(y: 5, x: 4);
    ?>

如果一个类没有构造函数，以及构造函数的参数不是必填项时，括号就可以省略。

#### 旧式风格的构造器

PHP 8.0.0 之前，全局命名空间内的类如果有一个同名的方法，则会解析为旧式风格的构造器。 虽然函数能被当作构造器，但该语法已被废弃，并会导致 `E_DEPRECATED` 错误。 如果 __construct() 和同名方法同时存在时， 会调用 __construct()。

以下两种情况时，与类同名的方法不再有特殊意义：命名空间中的类、PHP 8.0.0 起的任何类。

新代码中要使用 __construct()。

#### 构造器属性提升

PHP 8.0.0 起，构造器的参数也可以相应提升为类的属性。 构造器的参数赋值给类属性的行为很普遍，否则无法操作。 而构造器提升的功能则为这种场景提供了便利。 因此上面的例子可以用以下方式重写：

示例 #3 使用构造器属性提升

    <?php
    class Point {
        public function __construct(protected int $x, protected int $y = 0) {
        }
    }

当构造器参数带修饰符时，PHP 会同时把它当作对象属性和构造器参数， 并赋值到属性。 构造器可以是空的，或者包含其他语句。 参数值赋值到相应属性后执行正文中额外的代码语句。

并非所有参数都需要提升。可以混合提升或不提升参数作为属性，也不需要按顺序。 提升后的参数不影响构造器内代码调用。

> 注意:

> 使用可见性修饰符（`public`、`protected` 或 `private`）是应用属性提升的最有可能的方式，但其它任何单个修饰符（例如 `readonly`）将产生相同的效果。

> 注意:

> 对象属性的类型不能为 callable 以避免为引擎带来混淆。 因此提升的参数也不能是 callable。 其他任意 类型声明 是允许的。

> 注意:

> 由于属性升级为属性和函数参数，因此属性和参数的所有命名限制都适用。

> 注意:

> 放在构造方法提升参数里的属性会同时复制为属性和参数。提升的构造方法的参数默认值将仅复制到参数并且不会复制到属性。

#### 初始化新功能

自 PHP 8.1.0 起，对象可以用于默认参数值，静态变量，全局常量，以及属性参数。define() 现在也接受对象。

> 注意:

> 禁止使用动态类名、非字符串类名以及匿名类。禁止使用参数解包。禁止使用不支持的表达式作为参数。

示例 #4 初始化中使用 new

    <?php

    // 全部允许：
    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,
        ) {}
    }

    // 全部禁止（编译时错误）:
    function test(
        $a = new (CLASS_NAME_CONSTANT)(), // 动态类名
        $b = new class {}, // 匿名类
        $c = new A(...[]), // 参数解包
        $d = new B($abc), // 不支持的常量表达式
    ) {}
    ?>

#### Static 创造方法

在 PHP 中每个 class 只能有一个构造器。 然而有些情况下，需要用不同的输入实现不同的方式构造对象。 这种情况下推荐使用 static 方法包装构造。

示例 #5 使用 static 创造方法

    <?php
    $some_json_string = '{ "id": 1004, "name": "Elephpant" }';
    $some_xml_string = "<animal><id>1005</id><name>Elephpant</name></animal>";

    class Product {

        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 {
            $new = new static($id, $name);
            return $new;
        }

        public static function fromJson(string $json): static {
            $data = json_decode($json, true);
            return new static($data['id'], $data['name']);
        }

        public static function fromXml(string $xml): static {
            $data = simplexml_load_string($xml);
            $new = new static();
            $new->id = (int) $data->id;
            $new->name = $data->name;
            return $new;
        }
    }

    $p1 = Product::fromBasicData(5, 'Widget');
    $p2 = Product::fromJson($some_json_string);
    $p3 = Product::fromXml($some_xml_string);

    var_dump($p1, $p2, $p3);

可以设置构造器为 private 或 protected，防止自行额外调用。 这时只有 static 方法可以实例化一个类。 由于它们位于同一个定义的 class 因此可以访问私有方法，也不需要在同一个对象实例中。 当然构造器不一定要设置为 private，是否合理取决于实际情况。

三个 static 方法展示了对象以不同方式的实例化方式。

- `fromBasicData()` 把所需的全部参数传入构造器，创建对象并返回结果。
- `fromJson()` 接受 JSON 字符串，，预处理成构造器所需的格式，然后返回新的对象。
- `fromXml()` 接受 XML 字符串并解析，然后创建一个单纯的对象。 由于参数都是可选的，使得可以忽略所有参数去调用构造器。然后为对象的属性赋值后返回结果。

在以上三个例子中，`static` 关键词会被翻译成代码所在类的类名。 这个例子中是 `Product`。

### 析构函数

function __destruct(): void

PHP 有析构函数的概念，这类似于其它面向对象的语言，如 C++。析构函数会在到某个对象的所有引用都被删除或者当对象被显式销毁时执行。

示例 #6 析构函数示例

    <?php

    class MyDestructableClass
    {
        function __construct() {
            print "In constructor\n";
        }

        function __destruct() {
            print "Destroying " . __CLASS__ . "\n";
        }
    }

    $obj = new MyDestructableClass();

和构造函数一样，父类的析构函数不会被引擎暗中调用。要执行父类的析构函数，必须在子类的析构函数体中显式调用 parent::__destruct()。此外也和构造函数一样，子类如果自己没有定义析构函数则会继承父类的。

析构函数即使在使用 exit() 终止脚本运行时也会被调用。在析构函数中调用 exit() 将会中止其余关闭操作的运行。

如果析构方法为其对象创建了新的引用，则当引用计数再次达到零或在关闭序列期间将不会再次调用该函数。

自 PHP 8.4.0 起，当在 Fiber 执行期间发生垃圾回收时，计划回收的对象析构方法将在单独的 Fiber（称为 `gc_destructor_fiber`）中执行。如果挂起此 Fiber，则会创建新的 Fiber 来执行任何剩余的析构方法。垃圾回收器将不会引用之前的 `gc_destructor_fiber`，并且如果其他地方没有引用它，则可能会被回收。已挂起的析构方法在对象中在析构方法返回或 Fiber 本身被回收之前不会被回收。

> 注意:

> 析构函数在脚本关闭时调用，此时所有的 HTTP 头信息已经发出。脚本关闭时的工作目录有可能和在 SAPI（如 apache）中时不同。

> 注意:

> 试图在析构函数（在脚本终止时被调用）中抛出一个异常会导致致命错误。

## 访问控制（可见性）

对属性或方法的访问控制（PHP 7.1.0 以后支持常量），是通过在前面添加关键字 `public`（公有），`protected`（受保护）或 `private`（私有）来实现的。被定义为公有的类成员可以在任何地方被访问。 被定义为受保护的类成员则可以被其自身以及其子类和父类访问。被定义为私有的类成员则只能被其定义所在的类访问。

### 属性的访问控制

类属性可以定义为public， private 或者 protected。在没有任何访问控制关键字的情况下，属性声明为 public。

示例 #1 属性声明

    <?php
    /**
     * Define 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; // 这行能被正常执行
    echo $obj->protected; // 这行会产生一个致命错误
    echo $obj->private; // 这行也会产生一个致命错误
    $obj->printHello(); // 输出 Public、Protected 和 Private

    /**
     * Define MyClass2
     */
    class MyClass2 extends MyClass
    {
        // 可以对 public 和 protected 进行重定义，但 private 而不能
        public $public = 'Public2';
        protected $protected = 'Protected2';

        function printHello()
        {
            echo $this->public;
            echo $this->protected;
            echo $this->private;
        }
    }

    $obj2 = new MyClass2();
    echo $obj2->public; // 这行能被正常执行
    echo $obj2->protected; // 这行会产生一个致命错误
    echo $obj2->private; // 未定义 private
    $obj2->printHello(); // 输出 Public2、Protected2 和 Undefined

    ?>

#### 不对称属性可见性

从 PHP 8.4 开始，对象属性也可以设置不对称的可见性，读取（`get`） 和写入（`set`）可以有不同的范围。 具体来说，可以单独指定`set`可见性，只要它不比默认可见性更宽。

示例 #2 不对称属性可见性

    <?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; // Fatal Error
        }
    }

    $b = new Book('How to PHP', 'Peter H. Peterson', 2024);

    echo $b->title; // Works
    echo $b->author; // Works
    echo $b->pubYear; // Fatal Error

    $b->title = 'How not to PHP'; // Fatal Error
    $b->author = 'Pedro H. Peterson'; // Fatal Error
    $b->pubYear = 2023; // Fatal Error
    ?>

从 PHP 8.5 开始，`set` 可见性也可以应用于类的静态属性。

示例 #3 不对称静态属性可见性

    <?php
    class Manager
    {
        public private(set) static int $calls = 0;

        public function doAThing(): string
        {
            self::$calls++;
            // Do other stuff.
            return "some string";
        }
    }

    $m = new Manager();

    $m->doAThing(); // Works
    echo Manager::$calls; // Works
    Manager::$calls = 5; // Fatal error
    ?>

以上示例会输出：

    1
    Fatal error: Uncaught Error: Cannot modify private(set) property Manager::$calls from global scope in /some/file.php

关于不对称可见性有一些注意事项：

- 只有声明了类型的属性才能有单独的`set`可见性。
- `set` 可见性必须和 `get` 可见性相同或更严格。 也就是说，`public protected(set)` 和 `protected protected(set)` 是允许的，但是 `protected public(set)` 会导致语法错误。
- 如果一个属性是 `public`，那么主要可见性可能被省略。 也就是说，`public private(set)` 和 `private(set)` 会有相同的结果。
- 一个属性的 `private(set)` 可见性会自动变为 `final`， 并且不能在子类中重新声明。
- 读取属性的引用遵循 `set` 可见性，而不是 `get`。 这是因为引用可能用于修改属性值。
- 同样，试图写入数组属性会涉及到内部的 `get` 和 `set` 操作， 因此会遵循 `set` 可见性，因为这总是更严格的。

> 注意: 设置访问控制时，声明中不允许有空格。`private(set)` 是正确的。`private( set )` 是不正确的，将导致解析错误。

当一个类继承另一个类时，子类可以重新定义任何不是 `final` 的属性。 这样做时，可以扩大主要可见性或 `set` 可见性，只要新的可见性和父类相同或更宽。 但是要注意，如果一个 `private` 属性被重写，它实际上并没有改变父类的属性， 而是创建了一个具有不同内部名称的新属性。

示例 #4 不对称属性继承

    <?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, as reading is wider and writing the same.
        public string $author; // OK, as reading is the same and writing is wider.
        public protected(set) int $pubYear; // Fatal Error. private(set) properties are final.
    }
    ?>

### 方法的访问控制

类中的方法可以被定义为 public、private 或 protected。如果没有设置这些关键字，则该方法默认为 public。

示例 #5 方法声明

    <?php
    /**
     * Define MyClass
     */
    class MyClass
    {
        // 声明一个公有的构造函数
        public function __construct() { }

        // 声明一个公有的方法
        public function MyPublic() { }

        // 声明一个受保护的方法
        protected function MyProtected() { }

        // 声明一个私有的方法
        private function MyPrivate() { }

        // 此方法为公有
        function Foo()
        {
            $this->MyPublic();
            $this->MyProtected();
            $this->MyPrivate();
        }
    }

    $myclass = new MyClass;
    $myclass->MyPublic(); // 这行能被正常执行
    $myclass->MyProtected(); // 这行会产生一个致命错误
    $myclass->MyPrivate(); // 这行会产生一个致命错误
    $myclass->Foo(); // 公有，受保护，私有都可以执行

    /**
     * Define MyClass2
     */
    class MyClass2 extends MyClass
    {
        // 此方法为公有
        function Foo2()
        {
            $this->MyPublic();
            $this->MyProtected();
            $this->MyPrivate(); // 这行会产生一个致命错误
        }
    }

    $myclass2 = new MyClass2;
    $myclass2->MyPublic(); // 这行能被正常执行
    $myclass2->Foo2(); // 公有的和受保护的都可执行，但私有的不行

    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
    ?>

### 常量的控制访问

PHP 7.1.0 开始，类的常量可以定义为 public、private 或 protected。如果没有设置这些关键字，则该常量默认为 public。

示例 #6 PHP 7.1.0 中的常量声明

    <?php
    /**
    * Define MyClass
    */
    class MyClass
    {
       // 公有常量
       public const MY_PUBLIC = 'public';

       // 受保护的常量
       protected const MY_PROTECTED = 'protected';

       // 私有常量
       private const MY_PRIVATE = 'private';

       public function foo()
       {
           echo self::MY_PUBLIC;
           echo self::MY_PROTECTED;
           echo self::MY_PRIVATE;
       }
    }

    $myclass = new MyClass();
    MyClass::MY_PUBLIC; // 这行可以正常执行
    MyClass::MY_PROTECTED; // 这行会产生一个致命错误
    MyClass::MY_PRIVATE; // 这行会产生一个致命错误
    $myclass->foo(); // 将会输出：Public Protected Private

    /**
    * Define MyClass2
    */
    class MyClass2 extends MyClass
    {
       // This is public
       function foo2()
       {
           echo self::MY_PUBLIC;
           echo self::MY_PROTECTED;
           echo self::MY_PRIVATE; // 这行会产生一个致命错误
       }
    }

    $myclass2 = new MyClass2;
    echo MyClass2::MY_PUBLIC; // 这行可以正常执行
    $myclass2->foo2(); // 将会输出：Public Protected，MY_PRIVATE 是私有常量，无法输出
    ?>

### 其它对象的访问控制

同一个类的对象即使不是同一个实例也可以互相访问对方的 private 与 protected 成员。 这是由于在这些对象的内部具体实现的细节都是已知的。

示例 #7 访问同一个对象类型的 private 成员

    <?php
    class Test
    {
        private $foo;

        public function __construct($foo)
        {
            $this->foo = $foo;
        }

        private function bar()
        {
            echo 'Accessed the private method.';
        }

        public function baz(Test $other)
        {
            // 我们可以改变 private 属性：
            $other->foo = 'hello';
            var_dump($other->foo);

            // 我们也可以调用 private 方法：
            $other->bar();
        }
    }

    $test = new Test('test');

    $test->baz(new Test('other'));
    ?>

以上示例会输出：

    string(5) "hello"
    Accessed the private method.

## 对象继承

继承已为大家所熟知的一个程序设计特性，PHP 的对象模型也使用了继承。继承将会影响到类与类，对象与对象之间的关系。

比如，当扩展一个类，子类就会继承父类所有 public 和 protected 的方法，属性和常量。除非子类覆盖了父类的方法，被继承的方法都会保留其原有功能。

继承有助于功能的设计和抽象，在实现类似的对象、增加新功能时，无须重复编写这些公用的功能。

子类无法访问父类的私有方法。因此，子类无需考虑正常的继承规则而重新实现私有方法。 然而，在 PHP 8.0.0 之前， `final` 和 `static` 的限制会应用于 private 方法。 从 PHP 8.0.0 开始，仅 `private final` 的构造器是唯一受限的 private 方法； 想要“禁用”构造器，我们通常用静态工厂方法作为代替。

方法，属性和常量的 可见性 可以放宽，例如 `protected` 方法可以标记为 `public`， 但不能增加限制，例如标记 `public` 属性为 `private`。有个例外是构造方法，可以限制其可见性，例如 `public` 构造方法可以在子类中标记为 `private`。

> 注意:

> 除非使用了自动加载，否则一个类必须在使用之前被定义。如果一个类扩展了另一个，则父类必须在子类之前被声明。此规则适用于类继承其它类与接口。

> 注意:

> 不允许使用只读属性覆盖可读写属性，反之亦然。

>     <?php

>     class A {
>         public int $prop;
>     }
>     class B extends A {
>         // Illegal: read-write -> readonly
>         public readonly int $prop;
>     }
>     ?>

示例 #1 继承示例

    <?php

    class Foo
    {
        public function printItem($string)
        {
            echo 'Foo: ' . $string . PHP_EOL;
        }

        public function printPHP()
        {
            echo 'PHP is great.' . PHP_EOL;
        }
    }

    class Bar extends Foo
    {
        public function printItem($string)
        {
            echo 'Bar: ' . $string . PHP_EOL;
        }
    }

    $foo = new Foo();
    $bar = new Bar();
    $foo->printItem('baz'); // 输出: 'Foo: baz'
    $foo->printPHP();       // 输出: 'PHP is great'
    $bar->printItem('baz'); // 输出: 'Bar: baz'
    $bar->printPHP();       // 输出: 'PHP is great'

    ?>

### 返回类型与内部类兼容

PHP 8.1 之前，大多数内部类或方法没有声明其返回类型，并且在继承它们时允许返回任何类型。

自 PHP 8.1.0 起，大多数内部方法开始“暂时”声明其返回类型，在这种情况下，方法的返回类型应该与继承的父级方法兼容；否则，将发出弃用通知。注意，没有指定返回声明也会视为签名不匹配，从而导致弃用通知。

如果由于 PHP 跨版本兼容性问题而无法为重写方法声明返回类型，则可以添加 ReturnTypeWillChange 注解来消除弃用通知。

示例 #2 重写方法未声明任何返回类型

    <?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
    ?>

示例 #3 重写方法声明了错误的返回类型

    <?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
    ?>

示例 #4 重写方法声明了错误的返回类型但没有弃用通知

    <?php
    class MyDateTime extends DateTime
    {
        /**
         * @return DateTime|false
         */
        #[\ReturnTypeWillChange]
        public function modify(string $modifier) { return false; }
    }

    // No notice is triggered
    ?>

## 范围解析操作符 （::）

范围解析运算符（也称作 Paamayim Nekudotayim）或更简单地说是双冒号，是一种允许访问类或其中一个父类的常量、static 属性或 static 方法的标记。此外，静态属性或方法也可以通过后期静态绑定来覆盖。

当在类定义之外引用到这些项目时，要使用类名。

可以通过变量来引用类，该变量的值不能是关键字（如 `self`，`parent` 和 `static`）。

把 Paamayim Nekudotayim 选作双冒号操作符的名字似乎有些奇怪。然而，这是 Zend 开发小组在写 Zend Engine 0.5（被用于 PHP 3 中）时所作出的决定。事实上这个词在希伯莱文就是双冒号的意思。

示例 #1 在类的外部使用 :: 操作符

    <?php
    class MyClass {
        const CONST_VALUE = 'A constant value';
    }

    $classname = 'MyClass';
    echo $classname::CONST_VALUE;

    echo MyClass::CONST_VALUE;
    ?>

self，parent 和 static 这三个特殊的关键字是用于在类定义的内部对其属性或方法进行访问的。

示例 #2 在类定义内部使用 ::

    <?php
    class MyClass {
        const CONST_VALUE = 'A constant value';
    }

    class OtherClass extends MyClass
    {
        public static $my_static = 'static var';

        public static function doubleColon() {
            echo parent::CONST_VALUE . "\n";
            echo self::$my_static . "\n";
        }
    }

    $classname = 'OtherClass';
    $classname::doubleColon();

    OtherClass::doubleColon();
    ?>

当一个子类覆盖其父类中的方法时，PHP 不会调用父类中已被覆盖的方法。是否调用父类的方法取决于子类。这种机制也作用于构造函数和析构函数，重载以及魔术方法。

示例 #3 调用父类的方法

    <?php
    class MyClass
    {
        protected function myFunc() {
            echo "MyClass::myFunc()\n";
        }
    }

    class OtherClass extends MyClass
    {
        // 覆盖了父类的定义
        public function myFunc()
        {
            // 但还是可以调用父类中被覆盖的方法
            parent::myFunc();
            echo "OtherClass::myFunc()\n";
        }
    }

    $class = new OtherClass();
    $class->myFunc();
    ?>

参见 伪变量的示例。

## 静态（static）关键字

小技巧

本页说明了用 `static` 关键字来定义静态方法和属性。`static` 也可用于定义静态变量， 静态匿名函数 以及后期静态绑定。参见上述页面了解 `static` 在其中的用法。

声明类属性或方法为静态，就可以不实例化类而直接访问。可以在实例化的类对象中通过静态访问。

### 静态方法

由于静态方法不需要通过对象即可调用，所以伪变量 $this 在静态方法中不可用。

警告

用静态方式调用一个非静态方法会抛出 Error。

在 PHP 8.0.0 之前，通过静态方式调用一个非静态方法这种用法已经被废弃，并且会导致一个 `E_DEPRECATED` 级别的警告。

示例 #1 静态方法示例

    <?php
    class Foo {
        public static function aStaticMethod() {
            // ...
        }
    }

    Foo::aStaticMethod();
    $classname = 'Foo';
    $classname::aStaticMethod();
    ?>

### 静态属性

静态属性使用 范围解析操作符 （ `::` ）访问，不能通过对象操作符（ `->` ）访问。

通过变量来引用一个类是可行的，但这个变量的值不能是一个保留字 （例如`self`，`parent`和 `static`）

示例 #2 静态属性示例

    <?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";      // 未定义的 "属性" 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";
    ?>

以上示例在 PHP 8 中的输出类似于：

    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

## 抽象类

PHP 有抽象类、抽象方法和抽象属性。定义为抽象的类无法实例化。任何一个类，如果它里面有一个方法或者属性是声明为抽象，那么这个类就必须被声明为抽象。定义为抽象的方法仅声明方法的签名以及它是 public 还是 protected；但无法定义实现。定义为抽象的属性可以声明 `get` 或 `set` 行为的要求，并且可以为一个（但不是全部）操作提供实现。

继承一个抽象类的时候，子类必须定义父类中的所有抽象方法， 并遵循常规的 继承 签名兼容性 规则。

自 PHP 8.4 起，抽象类可以声明抽象属性，可以是 public，也可以是 protected。protected 抽象属性可以从 protected 或 public 作用域读取/写入的属性满足。

抽象属性可以由标准属性或挂钩属性来满足，与所需的操作相对应。

示例 #1 抽象方法示例

    <?php

    abstract class AbstractClass
    {
        // 强制要求子类定义这些方法
        abstract protected function getValue();
        abstract protected function prefixValue($prefix);

        // 普通方法（非抽象方法）
        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";

    ?>

以上示例会输出：

    ConcreteClass1
    FOO_ConcreteClass1
    ConcreteClass2
    FOO_ConcreteClass2

示例 #2 抽象方法示例

    <?php

    abstract class AbstractClass
    {
        // 抽象方法仅需要定义需要的参数
        abstract protected function prefixName($name);
    }

    class ConcreteClass extends AbstractClass
    {
        // 子类可以定义父类签名中不存在的可选参数
        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";

    ?>

以上示例会输出：

    Mr. Pacman
    Mrs. Pacwoman

示例 #3 抽象属性示例

    <?php

    abstract class A
    {
        // 继承类必须具有可 public get 的属性
        abstract public string $readable {
            get;
        }

        // 继承类必须具有 protected 或 public set 的属性
        abstract protected string $writeable {
            set;
        }

        // 继承类必须具有 protected 或 public 的对称属性。
        abstract protected string $both {
            get;
            set;
        }
    }

    class C extends A
    {
        // 这满足了要求，也使其可 set，这是有效的
        public string $readable;

        // 这不能满足要求，因为它不能 public 可读
        protected string $readable;

        // 这正好满足要求，所以足够了。
        // 它只能被写入，并且只能从 protected 作用域进行写入。
        protected string $writeable {
            set => $value;
        }

        // 这将访问控制从 protected 继承为 public，这很好
        public string $both;
    }

    ?>

抽象类上的抽象属性可以为任何挂钩提供实现，必须声明 `get` 或 `set` 但是没有定义（如上例所示）。

示例 #4 带有挂钩的抽象属性示例

    <?php

    abstract class A
    {
        // 这提供了默认（但可覆盖）set 实现，
        // 并要求子类提供 get 实现
        abstract public string $foo {
            get;

            set {
                $this->foo = $value;
            }
        }
    }

    ?>

## 对象接口

使用接口（interface），可以指定某个类必须实现哪些方法和属性，但不需要定义这些方法或属性的具体内容。 由于接口（interface）和类（class）、trait 共享了命名空间，所以它们不能重名。

接口就像定义一个标准的类一样，通过 `interface` 关键字替换掉 `class` 关键字来定义，但其中所有的方法都是空的。

接口中定义的所有方法都必须是 public ，这是接口的特性。

在实践中，往往出于两个辅助目的使用接口：

- 因为实现了同一个接口，所以开发者创建的对象虽然源自不同的类，但可能可以交换使用。 常用于多个数据库的服务访问、多个支付网关、不同的缓存策略等。 可能不需要任何代码修改，就能切换不同的实现方式。
- 能够让函数与方法接受一个符合接口的参数，而不需要关心对象如何做、如何实现。 这些接口常常命名成类似 `Iterable`、`Cacheable`、`Renderable`， 以便于体现出功能的含义。

接口可以定义魔术方法，以便要求类（class）实现这些方法。

> 注意:

> 虽然没有禁止，但是强烈建议不要在接口中使用 构造器。 因为这样在对象实现接口时，会大幅降低灵活性。 此外，也不能强制确保构造器遵守继承规则，将导致不可预料的行为结果。

### 实现（`implements`）

要实现一个接口，使用 `implements` 操作符。类中必须实现接口中定义的所有方法，否则会报一个致命错误。 类可以实现多个接口，用逗号来分隔多个接口的名称。

警告

实现接口的时候，class 中的参数名称不必和接口完全一致。 然而， PHP 8.0 起语法开始支持命名参数， 也就是说调用方会依赖接口中参数的名称。 因此，强烈建议开发者的参数的命名，在类和接口中保持一致。

> 注意:

> 接口也可以通过 extends 操作符扩展。

> 注意:

> 类实现接口时，必须以兼容的签名定义接口中所有方法。类可以实现多个声明了相同方法名称的接口。在这种情况下，实现必须遵循所有接口的签名兼容性规则。因此可以应用协变和逆变。

### 常量

接口中也可以定义常量。接口常量和类常量的使用完全相同， 在 PHP 8.1.0 之前 不能被子类或子接口所覆盖。

### 属性

自 PHP 8.4.0 起，接口也可以声明属性。如果声明了属性，则必须指定属性是可读、可写还是可读可写。接口声明仅适用于 public 读写访问。

类可以通过多种方式满足接口属性。可以定义 public 属性。可以定义仅实现相应挂钩的 public 虚拟属性。或者属性读取可以由 `readonly` 属性满足。但是可 set 的接口属性可能不是 `readonly`。

示例 #1 接口属性示例

    <?php
    interface I
    {
        // 实现的类必须具有 public get 的属性，
        // 但是否可以 public set 则不受限制。
        public string $readable { get; }

        // 实现的类必须具有 public set 的属性，
        // 但是不是 public get 则不受限制。
        public string $writeable { set; }

        // 实现的类必须具有 public get 和 public set 的属性。
        public string $both { get; set; }
    }

    // 此类将所有三个属性实现为传统的非挂钩属性。这是完全有效的。
    class C1 implements I
    {
        public string $readable;

        public string $writeable;

        public string $both;
    }

    // 此类仅使用请求的挂钩即可实现所有三个属性。这也是完全有效的。
    class C2 implements I
    {
        private string $written = '';
        private string $all = '';

        // 仅使用 get 挂钩来创建虚拟属性。
        // 这满足了“public get”要求。
        // 它不可写，但这不是接口所要求的。
        public string $readable { get => strtoupper($this->writeable); }

        // 该接口仅要求属性可 set，
        // 但包含 get 操作也是完全有效的。
        // 此示例创建了虚拟属性，这很好。
        public string $writeable {
            get => $this->written;
            set {
                $this->written = $value;
            }
        }

        // 此属性要求读取和写入均可，
        // 因此需要实现两者，或者允许它具有默认行为。
        public string $both {
            get => $this->all;
            set {
                $this->all = strtoupper($value);
            }
        }
    }
    ?>

### 示例

示例 #2 接口示例

    <?php

    // 声明一个'Template'接口
    interface Template
    {
        public function setVariable($name, $var);
        public function getHtml($template);
    }

    // 实现接口
    // 下面的写法是正确的
    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;
        }
    }

    // 下面的写法是错误的，会报错，因为没有实现 getHtml()：
    // 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;
        }
    }
    ?>

示例 #3 可扩充的接口

    <?php
    interface A
    {
        public function foo();
    }

    interface B extends A
    {
        public function baz(Baz $baz);
    }

    // 正确写法
    class C implements B
    {
        public function foo()
        {
        }

        public function baz(Baz $baz)
        {
        }
    }

    // 错误写法会导致一个致命错误
    class D implements B
    {
        public function foo()
        {
        }

        public function baz(Foo $foo)
        {
        }
    }
    ?>

示例 #4 多接口的差异兼容性

    <?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();
        }
    }
    ?>

示例 #5 扩展多个接口

    <?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()
        {
        }
    }
    ?>

示例 #6 使用接口常量

    <?php
    interface A
    {
        const B = 'Interface constant';
    }

    // 输出接口常量
    echo A::B;

    // 错误写法，因为常量不能被覆盖。接口常量的概念和类常量是一样的。
    class B implements A
    {
        const B = 'Class constant';
    }

    // 输出： Class constant
    // 在 PHP 8.1.0 之前，不能正常运行
    // 因为之前还不允许覆盖类常量。
    echo B::B;
    ?>

示例 #7 抽象（abstract）类的接口使用

    <?php
    interface A
    {
        public function foo(string $s): string;

        public function bar(int $i): int;
    }

    // 抽象类可能仅实现了接口的一部分。
    // 扩展该抽象类时必须实现剩余部分。
    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;
        }
    }
    ?>

示例 #8 同时使用扩展和实现

    <?php

    class One
    {
        /* ... */
    }

    interface Usable
    {
        /* ... */
    }

    interface Updatable
    {
        /* ... */
    }

    // 关键词顺序至关重要： 'extends' 必须在前面
    class Two extends One implements Usable, Updatable
    {
        /* ... */
    }
    ?>

接口加上类型约束，提供了一种很好的方式来确保某个对象包含有某些方法。参见 instanceof 操作符和类型声明。

## Trait

PHP 实现了一种代码复用的方法，称为 trait。

Trait 是为类似 PHP 的单继承语言而准备的一种代码复用机制。Trait 为了减少单继承语言的限制，使开发人员能够自由地在不同层次结构内独立的类中复用 method。Trait 和 Class 组合的语义定义了一种减少复杂性的方式，避免传统多继承和 Mixin 类相关典型问题。

Trait 和 Class 相似，但仅仅旨在用细粒度和一致的方式来组合功能。 无法通过 trait 自身来实例化。它为传统继承增加了水平特性的组合；也就是说，应用的几个 Class 之间不需要继承。

示例 #1 Trait 示例

    <?php

    trait TraitA {
        public function sayHello() {
            echo 'Hello';
        }
    }

    trait TraitB {
        public function sayWorld() {
            echo 'World';
        }
    }

    class MyHelloWorld
    {
        use TraitA, TraitB; // A class can use multiple traits

        public function sayHelloWorld() {
            $this->sayHello();
            echo ' ';
            $this->sayWorld();
            echo "!\n";
        }
    }

    $myHelloWorld = new MyHelloWorld();
    $myHelloWorld->sayHelloWorld();

    ?>

以上示例会输出：

    Hello World!

### 优先级

从基类继承的成员会被 trait 插入的成员所覆盖。优先顺序是来自当前类的成员覆盖了 trait 的方法，而 trait 则覆盖了被继承的方法。

示例 #2 优先顺序示例

从基类继承的成员被插入的 SayWorld Trait 中的 MyHelloWorld 方法所覆盖。其行为 MyHelloWorld 类中定义的方法一致。优先顺序是当前类中的方法会覆盖 trait 方法，而 trait 方法又覆盖了基类中的方法。

    <?php
    class Base {
        public function sayHello() {
            echo 'Hello ';
        }
    }

    trait SayWorld {
        public function sayHello() {
            parent::sayHello();
            echo 'World!';
        }
    }

    class MyHelloWorld extends Base {
        use SayWorld;
    }

    $o = new MyHelloWorld();
    $o->sayHello();
    ?>

以上示例会输出：

    Hello World!

示例 #3 另一个优先级顺序的例子

    <?php
    trait HelloWorld {
        public function sayHello() {
            echo 'Hello World!';
        }
    }

    class TheWorldIsNotEnough {
        use HelloWorld;
        public function sayHello() {
            echo 'Hello Universe!';
        }
    }

    $o = new TheWorldIsNotEnough();
    $o->sayHello();
    ?>

以上示例会输出：

    Hello Universe!

### 多个 trait

通过逗号分隔，在 `use` 声明列出多个 trait，可以都插入到一个类中。

示例 #4 多个 trait 的用法

    <?php
    trait Hello {
        public function sayHello() {
            echo 'Hello ';
        }
    }

    trait World {
        public function sayWorld() {
            echo 'World';
        }
    }

    class MyHelloWorld {
        use Hello, World;
        public function sayExclamationMark() {
            echo '!';
        }
    }

    $o = new MyHelloWorld();
    $o->sayHello();
    $o->sayWorld();
    $o->sayExclamationMark();
    ?>

以上示例会输出：

    Hello World!

### 冲突的解决

如果两个 trait 都插入了一个同名的方法，如果没有明确解决冲突将会产生一个致命错误。

为了解决多个 trait 在同一个类中的命名冲突，需要使用 `insteadof` 操作符来明确指定使用冲突方法中的哪一个。

以上方式仅允许排除掉其它方法，`as` 操作符可以 为某个方法引入别名。 注意，`as` 操作符不会对方法进行重命名，也不会影响其方法。

示例 #5 冲突的解决

在本例中 Talker 使用了 trait A 和 B。由于 A 和 B 有冲突的方法，其定义了使用 trait B 中的 smallTalk 以及 trait A 中的 bigTalk。

Aliased_Talker 使用了 `as` 操作符来定义了 `talk` 来作为 B 的 bigTalk 的别名。

    <?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;
        }
    }
    ?>

### 修改方法的访问控制

使用 `as` 语法还可以用来调整方法的访问控制。

示例 #6 修改方法的访问控制

    <?php
    trait HelloWorld {
        public function sayHello() {
            echo 'Hello World!';
        }
    }

    // 修改 sayHello 的访问控制
    class MyClass1 {
        use HelloWorld { sayHello as protected; }
    }

    // 给方法一个改变了访问控制的别名
    // 原版 sayHello 的访问控制则没有发生变化
    class MyClass2 {
        use HelloWorld { sayHello as private myPrivateHello; }
    }
    ?>

### 从 trait 来组成 trait

正如 class 能够使用 trait 一样，其它 trait 也能够使用 trait。在 trait 定义时通过使用一个或多个 trait，能够组合其它 trait 中的部分或全部成员。

示例 #7 从 trait 来组成 trait

    <?php
    trait Hello {
        public function sayHello() {
            echo 'Hello ';
        }
    }

    trait World {
        public function sayWorld() {
            echo 'World!';
        }
    }

    trait HelloWorld {
        use Hello, World;
    }

    class MyHelloWorld {
        use HelloWorld;
    }

    $o = new MyHelloWorld();
    $o->sayHello();
    $o->sayWorld();
    ?>

以上示例会输出：

    Hello World!

### Trait 的抽象成员

为了对使用的类施加强制要求，trait 支持抽象方法的使用。 支持 public 、protected 和 private 方法。PHP 8.0.0 之前， 仅支持 public 和 protected 抽象方法。

警告

自 PHP 8.0.0 起，具体方法的签名必须遵循签名兼容性规则。以前，其签名可能有所不同。

示例 #8 表示通过抽象方法来进行强制要求

    <?php
    trait Hello {
        public function sayHelloWorld() {
            echo 'Hello'.$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;
        }
    }
    ?>

### Trait 的静态成员

Traits 可以定义静态变量、静态方法和静态属性。

> 注意:

> 自 PHP 8.1.0 起，弃用直接在 trait 上调用静态方法或者访问静态属性。 静态方法和属性应该仅在使用了 trait 的 class 中访问。

示例 #9 静态变量

    <?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();

    ?>

以上示例会输出：

    1
    1

示例 #10 静态方法

    <?php

    trait StaticExample
    {
        public static function doSomething()
        {
            return 'Doing something';
        }
    }

    class Example
    {
        use StaticExample;
    }

    echo Example::doSomething();

    ?>

以上示例会输出：

    Doing something

示例 #11 静态属性

警告

PHP 8.3.0 之前，trait 中定义的静态属性会在使用该 trait 的同一继承层次结构中的所有类之间共享。自 PHP 8.3.0 起，如果子类使用具有静态属性的 trait，将视为与父类中定义的 trait 不同。

    <?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";

    ?>

以上示例在 PHP 8.3 中的输出：

    2
    1

### 属性

Trait 同样可以定义属性。

示例 #12 定义属性

    <?php

    trait PropertiesTrait
    {
        public $x = 1;
    }

    class PropertiesExample
    {
        use PropertiesTrait;
    }

    $example = new PropertiesExample();
    $example->x;

    ?>

Trait 定义了一个属性后，类就不能定义同样名称的属性，否则会产生 fatal error。 有种情况例外：属性是兼容的（同样的访问可见度、类型、readonly 修饰符和初始默认值）。

示例 #13 解决冲突

    <?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
    }
    ?>

### 常量

自 PHP 8.2.0 起，trait 也可以定义常量。

示例 #14 定义常量

    <?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;
    ?>

以上示例会输出：

    1

如果 trait 定义了常量，然后类不能定义相同名称的常量，除非两者兼容（相同的可见性、初始化值和 final），否则会发出 fatal error。

示例 #15 解决冲突

    <?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
    }
    ?>

### final 方法

自 PHP 8.3.0 起，final 修饰符可以应用于使用 `as` 操作符从 trait 导入的方法。这可用于防止子类覆盖该方法。但是，使用该 trait 的类仍然可以覆盖该方法。

示例 #16 将来自 trait 的方法定义为 `final`

    <?php

    trait CommonTrait
    {
        public function method()
        {
            echo 'Hello';
        }
    }

    class FinalExampleA
    {
        use CommonTrait {
            CommonTrait::method as final; // 'final' 防止子类覆盖方法
        }
    }

    class FinalExampleB extends FinalExampleA
    {
        public function method() {}
    }

    ?>

以上示例的输出类似于：

    Fatal error: Cannot override final method FinalExampleA::method() in ...

## 匿名类

匿名类很有用，可以创建一次性的简单对象。

    <?php

    // 使用显性类
    class Logger
    {
        public function log($msg)
        {
            echo $msg;
        }
    }

    $util->setLogger(new Logger());

    // 使用匿名类
    $util->setLogger(new class {
        public function log($msg)
        {
            echo $msg;
        }
    });

可以传递参数到匿名类的构造器，也可以继承其他类、实现接口（implement interface），以及像其他普通的类一样使用 trait：

    <?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;
    });

以上示例会输出：

    object(class@anonymous)#1 (1) {
      ["Command line code0x104c5b612":"class@anonymous":private]=>
      int(10)
    }

匿名类被嵌套进普通 Class 后，不能访问这个外部类（Outer class）的 private（私有）、protected（受保护）方法或者属性。 为了访问外部类（Outer class）protected 属性或方法，匿名类可以 extend（扩展）此外部类。 为了使用外部类（Outer class）的 private 属性，必须通过构造器传进来：

    <?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();

以上示例会输出：

    6

声明的同一个匿名类，所创建的对象都是这个类的实例。

    <?php
    function anonymous_class()
    {
        return new class {};
    }

    if (get_class(anonymous_class()) === get_class(anonymous_class())) {
        echo 'same class';
    } else {
        echo 'different class';
    }

以上示例会输出：

    same class

> 注意:

> 注意，匿名类的名称是通过引擎赋予的，如下例所示。 由于实现的细节，不应该去依赖这个类名。

>     <?php
>     echo get_class(new class {});

> 以上示例的输出类似于：

>     class@anonymous/in/oNi1A0x7f8636ad2021

### 只读匿名类

自 PHP 8.3.0 起，`readonly` 修饰符可应用于匿名类。

示例 #1 定义 readonly 匿名类

    <?php
    // 使用匿名类
    var_dump(new readonly class('[DEBUG]') {
        public function __construct(private string $prefix)
        {
        }

        public function log($msg)
        {
            echo $this->prefix . ' ' . $msg;
        }
    });

## 重载

PHP所提供的重载（overloading）是指动态地创建类属性和方法。我们是通过魔术方法（magic methods）来实现的。

当调用当前环境下未定义或不可见的类属性或方法时，重载方法会被调用。本节后面将使用不可访问属性（inaccessible properties）和不可访问方法（inaccessible methods）来称呼这些未定义或不可见的类属性或方法。

所有的重载方法都必须被声明为 `public`。

> 注意:

> 这些魔术方法的参数都不能通过引用传递。

> 注意:

> PHP中的重载与其它绝大多数面向对象语言不同。传统的重载是用于提供多个同名的类方法，但各方法的参数类型和个数不同。

### 属性重载

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

在给不可访问（protected 或 private）或不存在的属性赋值时，__set() 会被调用。

读取不可访问（protected 或 private）或不存在的属性的值时，__get() 会被调用。

当对不可访问（protected 或 private）或不存在的属性调用 isset() 或 empty() 时，__isset() 会被调用。

当对不可访问（protected 或 private）或不存在的属性调用 unset() 时，__unset() 会被调用。

参数 $name 是指要操作的变量名称。__set() 方法的 $value 参数指定了 $name 变量的值。

属性重载只能在对象中进行。在静态方法中，这些魔术方法将不会被调用。所以这些方法都不能被 声明为 static。将这些魔术方法定义为 `static` 会产生一个警告。

> 注意:

> 因为 PHP 处理赋值运算的方式，__set() 的返回值将被忽略。类似的, 在下面这样的链式赋值中，__get() 不会被调用：``

>      $a = $obj->b = 8;

> 注意:

> PHP 不会在重载方法中再次调用本身。这意味着如果没有定义 `foo` 属性，在 __get() 中执行 `return $this->foo` 将会返回 `null` 并引发 `E_WARNING`，而不是再次调用 __get()。然而，重载方法可能会隐式调用其它重载方法（比如调用 __set() 触发 __get()）。

示例 #1 使用 __get()，__set()，__isset() 和 __unset() 进行属性重载

    <?php
    class PropertyTest {
         /**  被重载的数据保存在此  */
        private $data = array();

         /**  重载不能被用在已经定义的属性  */
        public $declared = 1;

         /**  只有从类外部访问这个属性时，重载才会发生 */
        private $hidden = 2;

        public function __set($name, $value)
        {
            echo "Setting '$name' to '$value'\n";
            $this->data[$name] = $value;
        }

        public function __get($name)
        {
            echo "Getting '$name'\n";
            if (array_key_exists($name, $this->data)) {
                return $this->data[$name];
            }

            $trace = debug_backtrace();
            trigger_error(
                'Undefined property via __get(): ' . $name .
                ' in ' . $trace[0]['file'] .
                ' on line ' . $trace[0]['line'],
                E_USER_NOTICE);
            return null;
        }

        public function __isset($name)
        {
            echo "Is '$name' set?\n";
            return isset($this->data[$name]);
        }

        public function __unset($name)
        {
            echo "Unsetting '$name'\n";
            unset($this->data[$name]);
        }

        /**  非魔术方法  */
        public function getHidden()
        {
            return $this->hidden;
        }
    }

    $obj = new PropertyTest;

    $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 "Let's experiment with the private property named 'hidden':\n";
    echo "Privates are visible inside the class, so __get() not used...\n";
    echo $obj->getHidden() . "\n";
    echo "Privates not visible outside of class, so __get() is used...\n";
    echo $obj->hidden . "\n";
    ?>

以上示例会输出：

    Setting 'a' to '1'
    Getting 'a'
    1

    Is 'a' set?
    bool(true)
    Unsetting 'a'
    Is 'a' set?
    bool(false)

    1

    Let's experiment with the private property named 'hidden':
    Privates are visible inside the class, so __get() not used...
    2
    Privates not visible outside of class, so __get() is used...
    Getting 'hidden'

    Notice:  Undefined property via __get(): hidden in <file> on line 70 in <file> on line 29

### 方法重载

public function __call(string `$name`, array `$arguments`): mixed
public static function __callStatic(string `$name`, array `$arguments`): mixed

在对象中调用一个不可访问方法时，__call() 会被调用。

在静态上下文中调用一个不可访问方法时，__callStatic() 会被调用。

$name 参数是要调用的方法名称。$arguments 参数是一个枚举数组，包含着要传递给方法 $name 的参数。

示例 #2 使用 __call() 和 __callStatic() 对方法重载

    <?php
    class MethodTest
    {
        public function __call($name, $arguments)
        {
            // 注意: $name 的值区分大小写
            echo "Calling object method '$name' "
                 . implode(', ', $arguments). "\n";
        }

        public static function __callStatic($name, $arguments)
        {
            // 注意: $name 的值区分大小写
            echo "Calling static method '$name' "
                 . implode(', ', $arguments). "\n";
        }
    }

    $obj = new MethodTest;
    $obj->runTest('in object context');

    MethodTest::runTest('in static context');
    ?>

以上示例会输出：

    Calling object method 'runTest' in object context
    Calling static method 'runTest' in static context

## 遍历对象

PHP 提供了一种定义对象的方法使其可以通过单元列表来遍历，例如用 `foreach` 语句。默认情况下，所有可见属性都将被用于遍历。

示例 #1 简单的对象遍历

    <?php
    class MyClass
    {
        public $var1 = 'value 1';
        public $var2 = 'value 2';
        public $var3 = 'value 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();

    ?>

以上示例会输出：

    var1 => value 1
    var2 => value 2
    var3 => value 3

    MyClass::iterateVisible:
    var1 => value 1
    var2 => value 2
    var3 => value 3
    protected => protected var
    private => private var

如上所示，`foreach` 遍历了所有其能够访问的可见属性。

### 参见

- 生成器
- Iterator
- IteratorAggregate
- SPL 迭代器

## 魔术方法

魔术方法是一种特殊的方法，当对对象执行某些操作时会覆盖 PHP 的默认操作。

警告

PHP 保留所有以 `__` 开头的方法名称。 因此，除非覆盖 PHP 的行为，否则不建议使用此类方法名称。

下列方法名被认为是魔术方法： __construct()、 __destruct()、 __call()、 __callStatic()、 __get()、 __set()、 __isset()、 __unset()、 __sleep()、 __wakeup()、 __serialize()、 __unserialize()、 __toString()、 __invoke()、 __set_state()、 __clone()、 __debugInfo()。

警告

除了 __construct()、 __destruct() 和 __clone() 之外的所有魔术方法都必须声明为 `public`， 否则会发出 `E_WARNING`。 在 PHP 8.0.0 之前没有为魔术方法 __sleep()、__wakeup()、__serialize()、__unserialize()、__set_state() 发出诊断信息。

警告

如果定义魔术方法时使用类型声明，它们必须与本文档中描述的签名相同，否则会发出致命错误。 在 PHP 8.0.0 之前，不会发出诊断信息。 然而，__construct() 和 __destruct() 不能声明返回类型， 否则会发出致命错误。

### __sleep() 和 __wakeup()

public function __sleep(): array
public function __wakeup(): void

serialize() 函数会检查类中是否存在一个魔术方法 __sleep()。如果存在，该方法会先被调用，然后才执行序列化操作。此功能可以用于清理对象，并返回一个包含对象中所有应被序列化的变量名称的数组。 如果该方法未返回任何内容，则 `null` 被序列化，并产生一个 `E_NOTICE` 级别的错误。

> 注意:

> __sleep() 不能返回父类的私有成员的名字。这样做会产生一个 `E_NOTICE` 级别的错误。使用 __serialize() 接口替代。

> 注意:

> 自 PHP 8.0.0 起，__sleep() 的返回值不是数组会生成 warning。之前生成 notice。

__sleep() 方法常用于提交未提交的数据，或类似的清理操作。同时，如果有一些很大的对象，但不需要全部保存，这个功能就很好用。

与之相反，unserialize() 会检查是否存在一个 __wakeup() 方法。如果存在，则会先调用 `__wakeup` 方法，预先准备对象需要的资源。

__wakeup() 经常用在反序列化操作中，例如重新建立数据库连接，或执行其它初始化操作。

示例 #1 Sleep 和 wakeup

    <?php
    class Connection
    {
        protected $link;
        private $server, $username, $password, $db;

        public function __construct($server, $username, $password, $db)
        {
            $this->server = $server;
            $this->username = $username;
            $this->password = $password;
            $this->db = $db;
            $this->connect();
        }

        private function connect()
        {
            $this->link = mysql_connect($this->server, $this->username, $this->password);
            mysql_select_db($this->db, $this->link);
        }

        public function __sleep()
        {
            return array('server', 'username', 'password', 'db');
        }

        public function __wakeup()
        {
            $this->connect();
        }
    }
    ?>

### __serialize() 和 __unserialize()

public function __serialize(): array
public function __unserialize(array `$data`): void

serialize() 函数会检查类中是否存在一个魔术方法 __serialize() 。如果存在，该方法将在任何序列化之前优先执行。它必须以一个代表对象序列化形式的 键/值 成对的关联数组形式来返回，如果没有返回数组，将会抛出一个 TypeError 错误。

> 注意:

> 如果类中同时定义了 __serialize() 和 __sleep() 两个魔术方法，则只有 __serialize() 方法会被调用。 __sleep() 方法会被忽略掉。如果对象实现了 Serializable 接口，接口的 `serialize()` 方法会被忽略，做为代替类中的 __serialize() 方法会被调用。

__serialize() 的预期用途是定义对象序列化友好的任意表示。 数组的元素可能对应对象的属性，但是这并不是必须的。

相反，unserialize() 检查是否存在具有名为 __unserialize() 的魔术方法。此函数将会传递从 __serialize() 返回的恢复数组。然后它可以根据需要从该数组中恢复对象的属性。

> 注意:

> 如果类中同时定义了 __unserialize() 和 __wakeup() 两个魔术方法，则只有 __unserialize() 方法会生效，__wakeup() 方法会被忽略。

> 注意:

> 此特性自 PHP 7.4.0 起可用。

示例 #2 序列化和反序列化

    <?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();
        }
    }?>

### __toString()

public function __toString(): string

__toString() 方法用于一个类被当成字符串时应怎样回应。例如 `echo $obj;` 应该显示些什么。

警告

从 PHP 8.0.0 起，返回值遵循标准的 PHP 类型语义， 这意味着如果禁用 严格类型 ，它将会强制转换为字符串。

如果启用严格类型，则声明的 string 类型将不会接受 Stringable 对象。如果需要这种行为，类型声明必须接受 Stringable 和 string 的联合类型。

从 PHP 8.0.0 起，任何包含 __toString() 方法的类都将隐性实现 Stringable 接口， 因此将通过该接口的类型检查。推荐无论如何应显式实现该接口。

在 PHP 7.4 中，返回值 必须 是 string ，否则会抛出 Error 。

在 PHP 7.4.0 之前，返回值 必须 是 string ，否则会抛出致命错误 `E_RECOVERABLE_ERROR` 。

警告

在 PHP 7.4.0 之前不能在 __toString() 方法中抛出异常。这么做会导致致命错误。

示例 #3 简单示例

    <?php
    // 声明一个简单的类
    class TestClass
    {
        public $foo;

        public function __construct($foo)
        {
            $this->foo = $foo;
        }

        public function __toString() {
            return $this->foo;
        }
    }

    $class = new TestClass('Hello');
    echo $class;
    ?>

以上示例会输出：

    Hello

### __invoke()

function __invoke( `...$values`): mixed

当尝试以调用函数的方式调用一个对象时，__invoke() 方法会被自动调用。

示例 #4 使用 __invoke()

    <?php
    class CallableClass
    {
        function __invoke($x) {
            var_dump($x);
        }
    }
    $obj = new CallableClass;
    $obj(5);
    var_dump(is_callable($obj));
    ?>

以上示例会输出：

    int(5)
    bool(true)

示例 #5 使用 __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']
    ];
    // sort customers by first name
    usort($customers, new Sort('first_name'));
    print_r($customers);
    // sort customers by last name
    usort($customers, new Sort('last_name'));
    print_r($customers);
    ?>

以上示例会输出：

    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

当调用 var_export() 导出类时，此静态 方法会被调用。

本方法的唯一参数是一个数组，其中包含按 `['property' => value, ...]` 格式排列的类属性。

示例 #6 使用 __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);
    var_dump($b);

    ?>

以上示例会输出：

    string(60) "A::__set_state(array(
       'var1' => 5,
       'var2' => 'foo',
    ))"
    object(A)#2 (2) {
      ["var1"]=>
      int(5)
      ["var2"]=>
      string(3) "foo"
    }

> 注意: 导出对象时，var_export() 不会检查对象类是否实现了 __set_state() ， 所以如果 __set_state() 没有实现， 重新导入对象会触发 Error 异常。特别是这会影响内部(内置)类。 程序员有责任验证要重新导入的类是否实现了 __set_state() 。

### __debugInfo()

function __debugInfo(): array

当通过 var_dump() 转储对象，获取应该要显示的属性的时候， 该函数就会被调用。如果对象中没有定义该方法，那么将会展示所有的公有、受保护和私有的属性。

示例 #7 使用 __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));
    ?>

以上示例会输出：

    object(C)#1 (1) {
      ["propSquared"]=>
      int(1764)
    }

## Final 关键字

final 关键字通过在定义方法、属性和常量之前加上 `final` 来防止被子类覆盖。 如果一个类被声明为 final，则不能被继承。

示例 #1 Final 方法示例

    <?php
    class BaseClass {
       public function test() {
           echo "BaseClass::test() called\n";
       }

       final public function moreTesting() {
           echo "BaseClass::moreTesting() called\n";
       }
    }

    class ChildClass extends BaseClass {
       public function moreTesting() {
           echo "ChildClass::moreTesting() called\n";
       }
    }
    // 产生 Fatal error: Cannot override final method BaseClass::moreTesting()
    ?>

示例 #2 Final 类示例

    <?php
    final class BaseClass {
       public function test() {
           echo "BaseClass::test() called\n";
       }

       // 由于类已经是 final，所以 final 关键字是多余的
       final public function moreTesting() {
           echo "BaseClass::moreTesting() called\n";
       }
    }

    class ChildClass extends BaseClass {
    }
    // 产生 Fatal error: Class ChildClass may not inherit from final class (BaseClass)
    ?>

示例 #3 PHP 8.4.0 起可用的 final 属性示例

    <?php
    class BaseClass {
       final protected string $test;
    }

    class ChildClass extends BaseClass {
        public string $test;
    }
    // Results in Fatal error: Cannot override final property BaseClass::$test
    ?>

示例 #4 PHP 8.1.0 起可用的 final 常量示例

    <?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
    ?>

> 注意: 从 PHP 8.0.0 起，除了构造函数之外，私有方法也不能声明为 final 。 声明为 `private(set)` 的属性是隐式的 `final`。

## 对象复制

在多数情况下，我们并不需要完全复制一个对象来获得其中属性。但有一个情况下确实需要：如果你有一个 GTK 窗口对象，该对象持有窗口相关的资源。你可能会想复制一个新的窗口，保持所有属性与原来的窗口相同，但必须是一个新的对象（因为如果不是新的对象，那么一个窗口中的改变就会影响到另一个窗口）。还有一种情况：如果对象 A 中保存着对象 B 的引用，当你复制对象 A 时，你想其中使用的对象不再是对象 B 而是 B 的一个副本，那么你必须得到对象 A 的一个副本。

对象复制可以通过 `clone` 关键字来完成（如果可能，这将调用对象的 __clone() 方法）。

    $copy_of_object = clone $object;

当对象被复制后，PHP 会对对象的所有属性执行一个浅复制（shallow copy）。所有的引用属性 仍然会是一个指向原来的变量的引用。

function __clone(): void

当复制完成时，如果定义了 __clone() 方法，则新创建的对象（复制生成的对象）中的 __clone() 方法会被调用，可用于修改属性的值（如果有必要的话）。

示例 #1 复制一个对象

    <?php
    class SubObject
    {
        static $instances = 0;
        public $instance;

        public function __construct() {
            $this->instance = ++self::$instances;
        }

        public function __clone() {
            $this->instance = ++self::$instances;
        }
    }

    class MyCloneable
    {
        public $object1;
        public $object2;

        function __clone()
        {

            // 强制复制一份this->object， 否则仍然指向同一个对象
            $this->object1 = clone $this->object1;
        }
    }

    $obj = new MyCloneable();

    $obj->object1 = new SubObject();
    $obj->object2 = new SubObject();

    $obj2 = clone $obj;

    print "Original Object:\n";
    print_r($obj);

    print "Cloned Object:\n";
    print_r($obj2);

    ?>

以上示例会输出：

    Original Object:
    MyCloneable Object
    (
        [object1] => SubObject Object
            (
                [instance] => 1
            )

        [object2] => SubObject Object
            (
                [instance] => 2
            )

    )
    Cloned Object:
    MyCloneable Object
    (
        [object1] => SubObject Object
            (
                [instance] => 3
            )

        [object2] => SubObject Object
            (
                [instance] => 2
            )

    )

可以在单个表达式中访问刚刚克隆的对象的成员：

示例 #2 访问新克隆的对象的成员

    <?php
    $dateTime = new DateTime();
    echo (clone $dateTime)->format('Y');
    ?>

以上示例的输出类似于：

    2016

## 对象比较

当使用比较运算符（`==`）比较两个对象变量时，比较的原则是：如果两个对象的属性和属性值 （值使用 `==` 对比）都相等，而且两个对象是同一个类的实例，那么这两个对象变量相等。

而如果使用全等运算符（`===`），这两个对象变量一定要指向某个类的同一个实例（即同一个对象）。

通过下面的示例可以理解以上原则。

示例 #1 对象比较的例子

    <?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 "Two instances of the same class\n";
    compareObjects($o, $p);

    echo "\nTwo references to the same instance\n";
    compareObjects($o, $q);

    echo "\nInstances of two different classes\n";
    compareObjects($o, $r);
    ?>

以上示例会输出：

    Two instances of the same class
    o1 == o2 : TRUE
    o1 != o2 : FALSE
    o1 === o2 : FALSE
    o1 !== o2 : TRUE

    Two references to the same instance
    o1 == o2 : TRUE
    o1 != o2 : FALSE
    o1 === o2 : TRUE
    o1 !== o2 : FALSE

    Instances of two different classes
    o1 == o2 : FALSE
    o1 != o2 : TRUE
    o1 === o2 : FALSE
    o1 !== o2 : TRUE

> 注意:

> PHP 扩展中可以自行定义对象比较（`==`）的原则。

## 后期静态绑定

PHP 增加了一个叫做后期静态绑定的功能，用于在继承范围内引用静态调用的类。

准确说，后期静态绑定工作原理是存储了在上一个“非转发调用”（non-forwarding call）的类名。当进行静态方法调用时，该类名即为明确指定的那个（通常在 `::` 运算符左侧部分）；当进行非静态方法调用时，即为该对象所属的类。所谓的“转发调用”（forwarding call）指的是通过以下几种方式进行的静态调用：`self::`，`parent::`，`static::` 以及 forward_static_call()。可用 get_called_class() 函数来得到被调用的方法所在的类名，`static::` 则指出了其范围。

该功能从语言内部角度考虑被命名为“后期静态绑定”。“后期绑定”的意思是说，`static::` 不再被解析为定义当前方法所在的类，而是在实际运行时计算的。也可以称之为“静态绑定”，因为它可以用于（但不限于）静态方法的调用。

### `self::` 的限制

使用 `self::` 或者 `__CLASS__` 对当前类的静态引用，取决于定义当前方法所在的类：

示例 #1 `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();

    ?>

以上示例会输出：

    A

### 后期静态绑定的用法

后期静态绑定本想通过引入一个新的关键字表示运行时最初调用的类来绕过限制。简单地说，这个关键字能在上述例子中调用 `test()` 时引用的类是 `B` 而不是 `A`。最终决定不引入新的关键字，而是使用已经预留的 `static` 关键字。

示例 #2 `static::` 简单用法

    <?php

    class A
    {
        public static function who()
        {
            echo __CLASS__;
        }

        public static function test()
        {
            static::who(); // 接下来是延迟静态绑定
        }
    }

    class B extends A
    {
        public static function who()
        {
            echo __CLASS__;
        }
    }

    B::test();

    ?>

以上示例会输出：

    B

> 注意:

> 在非静态环境下，所调用的类即为该对象实例所属的类。由于 `$this->` 会在同一作用范围内尝试调用私有方法，而 `static::` 则可能给出不同结果。另一个区别是 `static::` 只能用于静态属性。

示例 #3 非静态环境下使用 `static::`

    <?php

    class A
    {
        private function foo()
        {
            echo "Success!\n";
        }

        public function test()
        {
            $this->foo();
            static::foo();
        }
    }

    class B extends A
    {
        /* foo() 将被复制到 B，因此其作用域仍为 A，调用也会成功 */
    }

    class C extends A
    {
        private function foo()
        {
            /* 已替换原始方法，新方法的作用域为 C*/
        }
    }

    $b = new B();
    $b->test();

    $c = new C();
    try {
        $c->test();
    } catch (Error $e) {
        echo $e->getMessage();
    }

    ?>

以上示例会输出：

    Success!
    Success!
    Success!
    Call to private method C::foo() from scope A

> 注意:

> 后期静态绑定的解析会一直到取得一个完全解析了的静态调用为止。另一方面，如果静态调用使用 `parent::` 或者 `self::` 将转发调用信息。

> 示例 #4 转发和非转发调用

>     <?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();

>     ?>

> 以上示例会输出：

>     A
>     C
>     C

## 对象和引用

在 PHP 对象编程经常提到的一个关键点是“默认情况下对象是通过引用传递的”。但其实这不是完全正确的。下面通过一些例子来说明。

PHP 的引用是别名，就是两个不同的变量名字指向相同的内容。在 PHP 中，一个对象变量不再保存整个对象的值。只是保存一个标识符来访问真正的对象内容。 当对象作为参数传递，作为结果返回，或者赋值给另外一个变量，另外一个变量跟原来的不是引用的关系，只是他们都保存着同一个标识符的拷贝，这个标识符指向同一个对象的真正内容。

示例 #1 引用和对象

    <?php
    class A {
        public $foo = 1;
    }

    $a = new A;
    $b = $a;     // $a ,$b都是同一个标识符的拷贝
                 // ($a) = ($b) = <id>
    $b->foo = 2;
    echo $a->foo."\n";

    $c = new A;
    $d = &$c;    // $c ,$d是引用
                 // ($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";

    ?>

以上示例会输出：

    2
    2
    2

## 序列化对象 - 在会话中存放对象

所有 PHP 里面的值都可以使用函数 serialize() 来返回一个包含字节流的字符串来表示。unserialize() 函数能够重新把字符串变回 PHP 原来的值。序列化一个对象将会保存对象的所有变量，但是不会保存对象的方法，只会保存类的名字。

为了能够 unserialize() 一个对象，这个对象的类必须已经定义过。如果序列化类 A 的一个对象，将会返回一个跟类 A 相关，而且包含了对象所有变量值的字符串。 如果要想在另外一个文件中反序列化一个对象，这个对象的类必须在反序列化之前定义，可以通过包含一个定义该类的文件或使用函数 spl_autoload_register() 来实现。

    <?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保存起来以便文件page2.php能够读到
      file_put_contents('store', $s);

    // page2.php:

      // 要正确反序列化，必须包含下面一个文件
      include "A.php";

      $s = file_get_contents('store');
      $a = unserialize($s);

      // 现在可以使用对象$a里面的函数 show_one()
      $a->show_one();
    ?>

在应用程序中序列化对象以便在之后使用，强烈推荐在整个应用程序都包含对象的类的定义。 不然有可能出现在反序列化对象的时候，没有找到该对象的类的定义，从而把没有方法的类 __PHP_Incomplete_Class_Name 作为该对象的类，导致返回一个没有用的对象。

所以在上面的例子中，通过在 $_SESSION 超全局数组中添加新的键，把变量 $a 放在会话里之后，需要在每个页面都包含文件 `A.php`， 而不是只有文件 page1.php 和 page2.php。

除了以上建议，可以在对象上使用 __sleep() 和 __wakeup() 方法对序列化/反序列化事件挂载钩子。 使用 __sleep() 也能够让你仅序列化对象的某些属性。

## 协变与逆变

在 PHP 7.2.0 里，通过对子类方法里参数的类型放宽限制，实现对逆变的部分支持。 自 PHP 7.4.0 起开始支持完整的协变和逆变。

协变使子类比父类方法能返回更具体的类型；逆变使子类比父类方法参数类型能接受更模糊的类型。

在以下情况下，类型声明被认为更具体：

- 在 联合类型 中删除类型
- 在 交集类型 中添加类型
- 类类型（class type）修改为子类类型
- iterable 修改为 array 或者 Traversable

如果情况相反，则类型类被认为是模糊的。

### 协变

创建一个名为 Animal 的简单的抽象父类，用于演示什么是协变。 两个子类：Cat 和 Dog 扩展（extended）了 Animal。

    <?php

    abstract class Animal
    {
        protected string $name;

        public function __construct(string $name)
        {
            $this->name = $name;
        }

        abstract public function speak();
    }

    class Dog extends Animal
    {
        public function speak()
        {
            echo $this->name . " barks";
        }
    }

    class Cat extends Animal
    {
        public function speak()
        {
            echo $this->name . " meows";
        }
    }

注意：在这个例子中，没有方法返回了值。 将通过添加个别工厂方法，创建并返回 Animal、Cat、Dog 类型的新对象。

    <?php

    interface AnimalShelter
    {
        public function adopt(string $name): Animal;
    }

    class CatShelter implements AnimalShelter
    {
        public function adopt(string $name): Cat // 返回类的类型不仅限于 Animal，还可以是 Cat 类型
        {
            return new Cat($name);
        }
    }

    class DogShelter implements AnimalShelter
    {
        public function adopt(string $name): Dog // 返回类的类型不仅限于 Animal，还可以是 Dog 类型
        {
            return new Dog($name);
        }
    }

    $kitty = (new CatShelter)->adopt("Ricky");
    $kitty->speak();
    echo "\n";

    $doggy = (new DogShelter)->adopt("Mavrick");
    $doggy->speak();

以上示例会输出：

    Ricky meows
    Mavrick barks

### 逆变

继续上一个例子，除了 Animal、 Cat、Dog，我们还添加了 Food、AnimalFood 类， 同时为抽象类 Animal 添加了一个 eat(AnimalFood $food) 方法。

    <?php

    class Food {}

    class AnimalFood extends Food {}

    abstract class Animal
    {
        protected string $name;

        public function __construct(string $name)
        {
            $this->name = $name;
        }

        public function eat(AnimalFood $food)
        {
            echo $this->name . " eats " . get_class($food);
        }
    }

为了演示什么是逆变，Dog 类重写（overridden）了 eat 方法， 允许传入任意 Food 类型的对象。 而 Cat 类保持不变。

    <?php

    class Dog extends Animal
    {
        public function eat(Food $food) {
            echo $this->name . " eats " . get_class($food);
        }
    }

下面的例子展示了逆变。

    <?php

    $kitty = (new CatShelter)->adopt("Ricky");
    $catFood = new AnimalFood();
    $kitty->eat($catFood);
    echo "\n";

    $doggy = (new DogShelter)->adopt("Mavrick");
    $banana = new Food();
    $doggy->eat($banana);

以上示例会输出：

    Ricky eats AnimalFood
    Mavrick eats Food

但 $kitty 若尝试 eat() $banana 会发生什么呢？

    $kitty->eat($banana);

以上示例会输出：

    Fatal error: Uncaught TypeError: Argument 1 passed to Animal::eat() must be an instance of AnimalFood, instance of Food given

### 属性差异

默认情况下，属性既不是协变也不是逆变，因此是不变的。也就是说，它们的类型在子类中可能根本不会改变。原因是“get”操作必须是协变的，而“set”操作必须是逆变的。属性满足这两个要求的唯一方法是不变的。

自 PHP 8.4.0 起，随着抽象属性（在接口或抽象类上）和虚拟属性的增加，可以声明仅具有 get 或 set 操作的属性。因此，仅需“get”操作的抽象属性或虚拟属性可能是协变的。同样，仅需“set”操作的抽象属性或虚拟属性可能是逆变的。

然而，一旦属性同时具有 get 和 set 操作，就不再是协变或逆变的了，无法进一步扩展。也就是说，现在是不变的。

示例 #1 属性类型差异

    <?php
    class Animal {}
    class Dog extends Animal {}
    class Poodle extends Dog {}

    interface PetOwner
    {
        // 只需要 get 操作，因此这可能是协变的。
        public Animal $pet { get; }
    }

    class DogOwner implements PetOwner
    {
        // 这可能是一个更严格的类型，
        // 因为“get”端仍返回 Animal。但是，作为原生属性，
        // 此类的子类可能无法再更改类型。
        public Dog $pet;
    }

    class PoodleOwner extends DogOwner
    {
        // 这是不允许的，因为 DogOwner::$pet
        // 已经定义并要求 get 和 set 操作。
        public Poodle $pet;
    }
    ?>

## 延迟对象

延迟对象是指其初始化推迟到状态被观察或修改时才进行的对象。一些用例示例包括依赖项注入组件（仅在需要时提供完全初始化的延迟服务）、ORM（提供仅在访问时才从数据库获取数据的延迟实体）或 JSON 解析器（延迟解析直到访问元素）。

支持两种延迟对象策略：幽灵对象（Ghost Object）和虚拟代理（Virtual Proxies），以下称为"延迟幽灵"和"延迟代理"。 在这两种策略中，延迟对象都附加到初始化程序或工厂，当第一次观察或修改其状态时会自动调用。从抽象的角度来看，延迟幽灵对象与非延迟幽灵对象没有区别：都可以在不知道自己是延迟的情况下使用，从而允许将其传递给不知道延迟的代码并由其使用。延迟代理同样是透明的，但在使用它们的标识（identity）时必须小心，因为代理和其真实实例具有不同的标识。

> 注意: 版本信息
> 延迟对象在 PHP 8.4 中引入。

### 创建延迟对象

可以创建任何用户定义类或 stdClass 类的延迟实例（不支持其他内部类），或重置这些类的实例以使其成为延迟实例。创建延迟对象的入口点是 ReflectionClass::newLazyGhost() 和 ReflectionClass::newLazyProxy() 方法。

这两种方法都接受函数，在对象需要初始化时调用该函数。该函数的预期行为因所使用的策略而异，如每种方法的参考文档中所述。

示例 #1 创建延迟幽灵

    <?php
    class Example
    {
        public function __construct(public int $prop)
        {
            echo __METHOD__, "\n";
        }
    }

    $reflector = new ReflectionClass(Example::class);
    $lazyObject = $reflector->newLazyGhost(function (Example $object) {
        // 在这里初始化对象
        $object->__construct(1);
    });

    var_dump($lazyObject);
    var_dump(get_class($lazyObject));

    // 触发初始化
    var_dump($lazyObject->prop);
    ?>

以上示例会输出：

    lazy ghost object(Example)#3 (0) {
    ["prop"]=>
    uninitialized(int)
    }
    string(7) "Example"
    Example::__construct
    int(1)

示例 #2 创建延迟代理

    <?php
    class Example
    {
        public function __construct(public int $prop)
        {
            echo __METHOD__, "\n";
        }
    }

    $reflector = new ReflectionClass(Example::class);
    $lazyObject = $reflector->newLazyProxy(function (Example $object) {
        // 创建并返回真实实例
        return new Example(1);
    });

    var_dump($lazyObject);
    var_dump(get_class($lazyObject));

    // 触发器初始化
    var_dump($lazyObject->prop);
    ?>

以上示例会输出：

    lazy proxy object(Example)#3 (0) {
      ["prop"]=>
      uninitialized(int)
    }
    string(7) "Example"
    Example::__construct
    int(1)

对延迟对象属性的任何访问都会触发其初始化（包括通过 ReflectionProperty 访问）。但是，某些属性可能是预先知道的，并且在访问时不应触发初始化：

示例 #3 立即初始化属性

    <?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']);
    });

    // 如果没有这行，下面调用 ReflectionProperty::setValue() 时将触发初始化
    $reflector->getProperty('id')->skipLazyInitialization($post);
    $reflector->getProperty('id')->setValue($post, 123);

    // 或者直接使用它：
    $reflector->getProperty('id')->setRawValueWithoutLazyInitialization($post, 123);

    // 无需触发初始化即可访问 id 属性
    var_dump($post->id);
    ?>

ReflectionProperty::skipLazyInitialization() 和 ReflectionProperty::setRawValueWithoutLazyInitialization() 方法提供了在访问属性时绕过延迟初始化的方法。

### 关于延迟对象策略

延迟幽灵，就地初始化的对象，并且一旦初始化，就跟从未延迟化的对象没有区别。当需要控制对象的实例化和初始化时，此策略是合适的，如果是其中任何一个由另一方管理，则不适合。

延迟代理一旦初始化，便充当真实实例的代理：对已初始化延迟代理的任何操作都将转发给真实实例。真实实例的创建可以委托给另一方，这使得此策略在延迟幽灵不适合的情况下非常有用。尽管延迟代理几乎与延迟幽灵一样透明，但在使用其身份时需要谨慎，因为代理和真实实例具有不同的身份。

### 延迟对象的生命周期

对象可以使用 ReflectionClass::newLazyGhost() 或 ReflectionClass::newLazyProxy() 在实例化时设置为延迟，或者使用 ReflectionClass::resetAsLazyGhost() 或 ReflectionClass::resetAsLazyProxy() 在实例化后设置为延迟。之后可以通过下列操作之一初始化延迟对象：

- 以触发自动初始化的方式与对象进行交互。参阅初始化触发器。
- 使用 ReflectionProperty::skipLazyInitialization() 或 ReflectionProperty::setRawValueWithoutLazyInitialization() 将其所有属性标注为非延迟。
- 明确调用 ReflectionClass::initializeLazyObject() 或 ReflectionClass::markLazyObjectAsInitialized()。

由于延迟对象在所有属性均标记为非惰性时才会初始化，因此如果没有属性可以标记为延迟，则上述方法不会将对象标记为延迟。

### 初始化触发器

延迟对象设计为对其使用者完全透明，因此观察或修改对象状态的常规操作将在执行操作之前自动触发初始化。这包括但不限于以下操作：

- 读取或写入属性。
- 测试属性是否已设置或已清除。
- 通过 ReflectionProperty::getValue()、ReflectionProperty::getRawValue()、ReflectionProperty::setValue(), 或 ReflectionProperty::setRawValue() 访问或修改属性。
- 使用 ReflectionObject::getProperties()、ReflectionObject::getProperty()、get_object_vars() 列出属性。
- 使用 foreach 迭代未实现 Iterator 或 IteratorAggregate 的对象属性。
- 使用 serialize()、json_encode() 等序列化对象。
- 克隆对象。

方法调用不访问对象状态的话不会触发初始化。同样，如果这些方法或函数不访问对象的状态，则调用魔术方法或挂钩函数与对象的交互也不会触发初始化。

#### 非触发操作

以下特定方法或低级操作允许访问或修改延迟对象而无需触发初始化：

- 使用 ReflectionProperty::skipLazyInitialization() 或 ReflectionProperty::setRawValueWithoutLazyInitialization() 将属性标注为非延迟。
- 使用 get_mangled_object_vars() 或将对象转换为数组来检索属性的内部表示。
- 当设置了 `ReflectionClass::SKIP_INITIALIZATION_ON_SERIALIZE` 时使用 serialize()，除非使用 __serialize() 或 __sleep() 触发初始化。
- 调用 ReflectionObject::__toString()。
- 使用 var_dump() 或 debug_zval_dump()，除非使用 __debugInfo() 触发初始化。

### 初始化序列

本节概述了根据所使用的执行策略触发初始化时的操作顺序。

#### 幽灵对象

- 对象标记为非延迟。
- 没有使用 ReflectionProperty::skipLazyInitialization() 或 ReflectionProperty::setRawValueWithoutLazyInitialization() 初始化的属性将设置为他们的默认值（如果有）。在此阶段，该对象类似于使用 ReflectionClass::newInstanceWithoutConstructor() 创建的对象，但排除已初始化的属性。
- 然后，将对象作为第一个参数调用其初始化函数。该函数需要（但不是必须）初始化对象状态，并且必须返回 `null` 或没有值。此时对象不再是延迟，因此该函数可以直接访问其属性。

初始化后，该对象与从未延迟过的对象没有区别。

#### 代理对象

- 对象标记为非延迟。
- 与幽灵对象不同，在此阶段不会修改对象的属性。
- 会将对象作为工厂函数的第一个参数进行调用，并且必须返回兼容类的非延迟实例（参见 ReflectionClass::newLazyProxy()）。
- 返回的实例称为真实实例，并附加到代理对象上。
- 会丢弃代理对象的属性值，如同调用了 unset()。

初始化后，访问代理对象上的任何属性将得到与访问真实实例上对应属性相同的结果；访问代理对象上的所有属性都会转发到真实实例，包括已声明、动态、不存在的属性，或使用 ReflectionProperty::skipLazyInitialization() 或 ReflectionProperty::setRawValueWithoutLazyInitialization() 标记的属性。

代理对象本身不会替换（replaced）或替代（substituted）为真实实例。

虽然工厂函数会将代理对象作为第一个参数接收，但并不期望对代理对象进行修改（尽管允许修改，但在最终初始化步骤中这些修改将会丢失）。不过，代理对象可以用于根据已初始化属性的值、类、对象本身或其标识来做出决策。例如，在创建真实实例时，初始化程序可能会使用某个已初始化属性的值。

#### 通用行为

初始化程序或工厂函数的作用域和 $this 上下文保持不变，同时适用常规的可见性约束。

初始化成功后，对象将不再引用初始化程序或工厂函数，如果它没有其他引用，就可以将对象释放。

如果初始化程序抛出异常，对象状态将恢复到初始化前的状态，并且该对象再次被标记为延迟初始化。换句话说，对象自身的所有影响都将会撤销。其他副作用（例如对其他对象的影响），则不会撤销。这可防止在出现故障的情况下暴露部分初始化的实例。

### 克隆

克隆延迟对象会在创建克隆之前触发其初始化，从而产生已初始化的对象。

对于代理对象，代理及其真实实例都会克隆，并返回代理的克隆。`__clone` 方法会在真实实例上调用，而不是在代理上调用。克隆的代理和真实实例在初始化时会保持连接，因此对代理克隆的访问将转发到克隆的真实实例。

此行为可确保克隆对象和原始对象保持不同的状态。克隆后对原始对象或其初始化程序状态的更改不会影响克隆。克隆代理及其真实实例（而不是仅返回真实实例的克隆），可确保克隆操作始终返回同一类的对象。

### 析构方法

对于延迟幽灵，只有对象初始化后才会调用析构方法。对于延迟代理，只有存在真实实例时才会调用析构方法。

ReflectionClass::resetAsLazyGhost() 和 ReflectionClass::resetAsLazyProxy() 方法可能会调用已重置对象的析构方法。

## OOP 变更日志

这里只记录了 PHP OOP 模型的变更记录。有关变更功能的具体描述与其他相关注意事项，可以到具体的 OOP 文档链接中查看。

版本 | 说明
--- | ---
8.4.0 | 新增：支持属性挂钩。
8.4.0 | 添加：支持 延迟对象。
8.1.0 | 添加：支持类常量的 final 修饰符。此外，接口常量默认可覆盖。
8.0.0 | 添加：支持 nullsafe 操作符 ?-> 来访问可能为空的对象中的属性和方法。
7.4.0 | 已变更：可以通过 __toString() 抛出异常。
7.4.0 | 增加：支持限制返回类型协变与参数类型逆变。 如果使用自动加载，则完整的差异支持可用。 在一个文件内，只有非循环类型引用是可能的。
7.4.0 | 增加：可以给类属性增加类型。
7.3.0 | 不兼容：不再支持对使用非 int 键的 Traversable 进行参数解包。该功能不是有意设计的，因此被删除。
7.3.0 | 不兼容：在以前的版本中，可以通过分配一个引用来分离静态属性，这一特性已被移除。
7.3.0 | 已变更： instanceof 运算符允许将字面量作为第一个操作数，在这种情况下，结果始终是 `false` 。
7.2.0 | 废弃：__autoload() 方法已被废弃，请使用 spl_autoload_register() 代替。
7.2.0 | 已变更：`object` 做为保留关键字，不允许做为 classes、interfaces、traits 的名称。
7.2.0 | 已变更：分组引入命名空间时，允许行尾添加多余的逗号分隔符。
7.2.0 | 已变更：参数类型扩展。 现在可以省略来自重写方法和从接口实现的参数类型。
7.2.0 | 已变更：当一个抽象类（abstract class）继承另一个抽象类时，抽象的方法现在可以被覆写。
7.1.0 | 已变更：增加系统保留关键字 `void` 和 `iterable`，不允许做为 classes、interfaces、traits 的名称。
7.1.0 | 增加：类常量增加了 访问控制（可见性）。
7.0.0 | 废弃：对未声明为静态的方法（Static）的静态调用。
7.0.0 | 废弃：PHP 4 风格的构造函数 constructor 已被废弃。
7.0.0 | 增加： use 组声明：同一个命名空间导入的类、函数、常量现在可以组合在一个 use 语句中。
7.0.0 | 增加：使用 `new class` 语法来支持 匿名类。
7.0.0 | 不兼容：遍历非 Traversable object 将跟遍历引用 array 具有相同的行为。
7.0.0 | 已变更：traits 里定义兼容的属性不再产生错误信息。
5.6.0 | 增加: __debugInfo() 方法。
5.5.0 | 增加: ::class 魔法常量。
5.5.0 | 增加: finally 来处理异常。
5.4.0 | 增加： traits。
5.4.0 | 已变更：如果一个抽象 类定义了 构造函数 的签名，它将必须被实现。
5.3.3 | 已变更： 命名空间 中和类同名的方法不再被作为 构造函数。这个变更不影响非命名空间中的类。
5.3.0 | 已变更：类实现接口的方法所具有的默认值不再需要和接口的默认值一致。
5.3.0 | 已变更： 现在它也能够通过一个变量来引用一个类（例如，`echo $classname::constant;`）。 这个变量的值不能是一个保留关键词（比如，`self`、`parent` 或 `static`）。
5.3.0 | 已变更： 如果重载方法被定义为 static 将导致一个 `E_WARNING` 级别的错误。 同时它也需要强制使用 public 的可见性。
5.3.0 | 已变更： 在 5.3.0 之前的版本，__autoload() 函数里抛出的异常不能被 catch 块结构捕获，并会导致一个致命错误。 现在在一个前提下 catch 块能够捕获 __autoload 函数中抛出的错误。如果抛出一个自定义异常，这个自定义异常的类必须是可用的。否则 __autoload 函数可能递归自动加载这个自定义异常类。
5.3.0 | 新增： __callStatic 方法。
5.3.0 | 新增： heredoc 和 nowdoc 支持类的 常量 和属性的定义。 注意：heredoc 值必须和双引号字符串遵循同样的规则（比如，变量将被替换）。
5.3.0 | 新增： 后期静态绑定。
5.3.0 | 新增： __invoke 方法。
5.2.0 | 已变更：__toString 方法仅在直接与 echo 或 print 使用时被调用。但是现在它能在任何字符串上下文被调用（比如在 printf() 中使用 `%s` ），但不是在其他类型的上下文被调用（例如 `%d` 修饰符）。 自 PHP 5.2.0 起，将不具有 __toString 方法的对象转化为字符串将导致一个 `E_RECOVERABLE_ERROR` 级别的错误。
5.1.3 | 已变更：在 PHP 5 之前的版本，`var` 的使用已被废弃，并将产生一个 `E_STRICT` 级别的错误。现在它不再被废弃，因此也不会产生错误。
5.1.0 | 已变更：现在 __set_state 静态方法在 var_export() 导出类时会被调用。
5.1.0 | 新增：__isset 和 __unset 方法。

# 命名空间概述

## 目录

- 命名空间概述
- 命名空间
- 子命名空间
- 在一个文件中定义多个命名空间
- 基础
- 命名空间和动态语言特征
- namespace 关键字和 __NAMESPACE__
- 别名和导入
- 全局空间
- 回退到全局空间
- 名称解析规则
- FAQ

## 命名空间概述

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

什么是命名空间？从广义上来说，命名空间是一种封装事物的方法。在很多地方都可以见到这种抽象概念。例如，在操作系统中目录用来将相关文件分组，对于目录中的文件来说，它就扮演了命名空间的角色。具体举个例子，文件 `foo.txt` 可以同时在目录 `/home/greg` 和 `/home/other` 中存在，但在同一个目录中不能存在两个 `foo.txt` 文件。另外，在目录 `/home/greg` 外访问 `foo.txt` 文件时，我们必须将目录名以及目录分隔符放在文件名之前得到 `/home/greg/foo.txt`。这个原理应用到程序设计领域就是命名空间的概念。

在 PHP 中，命名空间用来解决在编写类库或应用程序时创建可重用的代码如类或函数时碰到的两类问题：

1. 用户编写的代码与PHP内部的类/函数/常量或第三方类/函数/常量之间的名字冲突。
2. 为很长的标识符名称(通常是为了缓解第一类问题而定义的)创建一个别名（或简短）的名称，提高源代码的可读性。

PHP 命名空间提供了一种将相关的类、函数和常量组合到一起的途径。下面是一个说明 PHP 命名空间语法的示例：

示例 #1 命名空间语法示例

    <?php
    namespace my\name; // 参考 "定义命名空间" 小节

    class MyClass {}
    function myfunction() {}
    const MYCONST = 1;

    $a = new MyClass;
    $c = new \my\name\MyClass; // 参考 "全局空间" 小节

    $a = strlen('hi'); // 参考 "使用命名空间：后备全局函数/常量" 小节

    $d = namespace\MYCONST; // 参考 "namespace操作符和__NAMESPACE__常量” 小节

    $d = __NAMESPACE__ . '\MYCONST';
    echo constant($d); // 参考 "命名空间和动态语言特征" 小节
    ?>

> 注意: 命名空间名称大小写不敏感。

> 注意:

> 名为 `PHP` 的命名空间，以及以这些名字开头的命名空间 （例如 `PHP\Classes`）被保留用作语言内核使用， 而不应该在用户空间的代码中使用。

## 定义命名空间

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

虽然任意合法的 PHP 代码都可以包含在命名空间中，但只有以下类型的代码受命名空间的影响，它们是：类（包括抽象类、trait 和枚举）、接口、函数和常量。

命名空间通过关键字 `namespace` 来声明。如果一个文件中包含命名空间，它必须在其它所有代码之前声明命名空间，除了一个以外：declare关键字。

示例 #1 声明单个命名空间

    <?php
    namespace MyProject;

    const CONNECT_OK = 1;
    class Connection { /* ... */ }
    function connect() { /* ... */  }

    ?>

> 注意: 完全限定名称（就是以反斜杠开头的名称）不能用于命名空间的声明。 因为该结构会解析成相对命名空间表达式。

在声明命名空间之前唯一合法的代码是用于定义源文件编码方式的 `declare` 语句。另外，所有非 PHP 代码包括空白符都不能出现在命名空间的声明之前：

示例 #2 声明单个命名空间

    <html>
    <?php
    namespace MyProject; // 致命错误 -　命名空间必须是程序脚本的第一条语句
    ?>

另外，与 PHP 其它的语言特征不同，同一个命名空间可以定义在多个文件中，即允许将同一个命名空间的内容分割存放在不同的文件中。

## 定义子命名空间

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

与目录和文件的关系很象，PHP 命名空间也允许指定层次化的命名空间的名称。因此，命名空间的名字可以使用分层次的方式定义：

示例 #1 声明分层次的单个命名空间

    <?php
    namespace MyProject\Sub\Level;

    const CONNECT_OK = 1;
    class Connection { /* ... */ }
    function connect() { /* ... */  }

    ?>

上面的例子创建了常量 `MyProject\Sub\Level\CONNECT_OK`，类 `MyProject\Sub\Level\Connection` 和函数 `MyProject\Sub\Level\connect`。

## 在同一个文件中定义多个命名空间

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

也可以在同一个文件中定义多个命名空间。在同一个文件中定义多个命名空间有两种语法形式。

示例 #1 定义多个命名空间，简单组合语法

    <?php
    namespace MyProject;

    const CONNECT_OK = 1;
    class Connection { /* ... */ }
    function connect() { /* ... */  }

    namespace AnotherProject;

    const CONNECT_OK = 1;
    class Connection { /* ... */ }
    function connect() { /* ... */  }
    ?>

不建议使用这种语法在单个文件中定义多个命名空间。建议使用下面的大括号形式的语法。

示例 #2 定义多个命名空间，大括号语法

    <?php
    namespace MyProject {

    const CONNECT_OK = 1;
    class Connection { /* ... */ }
    function connect() { /* ... */  }
    }

    namespace AnotherProject {

    const CONNECT_OK = 1;
    class Connection { /* ... */ }
    function connect() { /* ... */  }
    }
    ?>

在实际的编程实践中，非常不提倡在同一个文件中定义多个命名空间。这种方式的主要用于将多个 PHP 脚本合并在同一个文件中。

将全局的非命名空间中的代码与命名空间中的代码组合在一起，只能使用大括号形式的语法。全局代码必须用一个不带名称的 namespace 语句加上大括号括起来，例如：

示例 #3 定义多个命名空间和不包含在命名空间中的代码

    <?php
    namespace MyProject {

    const CONNECT_OK = 1;
    class Connection { /* ... */ }
    function connect() { /* ... */  }
    }

    namespace { // 全局代码
    session_start();
    $a = MyProject\connect();
    echo MyProject\Connection::start();
    }
    ?>

除了开始的 declare 语句外，命名空间的括号外不得有任何 PHP 代码。

示例 #4 定义多个命名空间和不包含在命名空间中的代码

    <?php
    declare(encoding='UTF-8');
    namespace MyProject {

    const CONNECT_OK = 1;
    class Connection { /* ... */ }
    function connect() { /* ... */  }
    }

    namespace { // 全局代码
    session_start();
    $a = MyProject\connect();
    echo MyProject\Connection::start();
    }
    ?>

## 使用命名空间：基础

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

在讨论如何使用命名空间之前，必须了解 PHP 是如何知道要使用哪一个命名空间中的元素的。可以将 PHP 命名空间与文件系统作一个简单的类比。在文件系统中访问一个文件有三种方式：

1. 相对文件名形式如 `foo.txt`。它会被解析为 `currentdirectory/foo.txt`，其中 `currentdirectory` 表示当前目录。因此如果当前目录是 `/home/foo`，则该文件名被解析为 `/home/foo/foo.txt`。
2. 相对路径名形式如 `subdirectory/foo.txt`。它会被解析为 `currentdirectory/subdirectory/foo.txt`。
3. 绝对路径名形式如 `/main/foo.txt`。它会被解析为 `/main/foo.txt`。

PHP 命名空间中的元素使用同样的原理。例如，类名可以通过三种方式引用：

1. 非限定名称，或不包含前缀的类名称，例如 `$a=new foo();` 或 `foo::staticmethod();`。如果当前命名空间是 `currentnamespace`，foo 将被解析为 `currentnamespace\foo`。如果使用 foo 的代码是全局的，不包含在任何命名空间中的代码，则 foo 会被解析为 `foo`。 警告：如果命名空间中的函数或常量未定义，则该非限定的函数名称或常量名称会被解析为全局函数名称或常量名称。详情参见 使用命名空间：后备全局函数名称/常量名称。
2. 限定名称,或包含前缀的名称，例如 `$a = new subnamespace\foo();` 或 `subnamespace\foo::staticmethod();`。如果当前的命名空间是 `currentnamespace`，则 foo 会被解析为 `currentnamespace\subnamespace\foo`。如果使用 foo 的代码是全局的，不包含在任何命名空间中的代码，foo 会被解析为 `subnamespace\foo`。
3. 完全限定名称，或包含了全局前缀操作符的名称，例如， `$a = new \currentnamespace\foo();` 或 `\currentnamespace\foo::staticmethod();`。在这种情况下，foo 总是被解析为代码中的文字名(literal name)`currentnamespace\foo`。

下面是一个使用这三种方式的实例：

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() {}
    }

    /* 非限定名称 */
    foo(); // 解析为函数 Foo\Bar\foo
    foo::staticmethod(); // 解析为类 Foo\Bar\foo 的静态方法 staticmethod
    echo FOO; // 解析为常量 Foo\Bar\FOO

    /* 限定名称 */
    subnamespace\foo(); // 解析为函数 Foo\Bar\subnamespace\foo
    subnamespace\foo::staticmethod(); // 解析为类 Foo\Bar\subnamespace\foo,
                                      // 以及类的方法 staticmethod
    echo subnamespace\FOO; // 解析为常量 Foo\Bar\subnamespace\FOO

    /* 完全限定名称 */
    \Foo\Bar\foo(); // 解析为函数 Foo\Bar\foo
    \Foo\Bar\foo::staticmethod(); // 解析为类 Foo\Bar\foo, 以及类的方法 staticmethod
    echo \Foo\Bar\FOO; // 解析为常量 Foo\Bar\FOO
    ?>

注意访问任意全局类、函数或常量，都可以使用完全限定名称，例如 \strlen() 或 \Exception 或 \`INI_ALL`。

示例 #1 在命名空间内部访问全局类、函数和常量

    <?php
    namespace Foo;

    function strlen() {}
    const INI_ALL = 3;
    class Exception {}

    $a = \strlen('hi'); // 调用全局函数strlen
    $b = \INI_ALL; // 访问全局常量 INI_ALL
    $c = new \Exception('error'); // 实例化全局类 Exception
    ?>

## 命名空间和动态语言特征

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

PHP 命名空间的实现受到其语言自身的动态特征的影响。因此，如果要将下面的代码转换到命名空间中：

示例 #1 动态访问元素

example1.php:

    <?php
    class classname
    {
        function __construct()
        {
            echo __METHOD__,"\n";
        }
    }
    function funcname()
    {
        echo __FUNCTION__,"\n";
    }
    const constname = "global";

    $a = 'classname';
    $obj = new $a; // 输出 classname::__construct
    $b = 'funcname';
    $b(); // 输出 funcname
    echo constant('constname'), "\n"; // 输出 global
    ?>

必须使用完全限定名称（包括命名空间前缀的类名称）。注意因为在动态的类名称、函数名称或常量名称中，限定名称和完全限定名称没有区别，因此其前导的反斜杠是不必要的。

示例 #2 动态访问命名空间的元素

    <?php
    namespace namespacename;
    class classname
    {
        function __construct()
        {
            echo __METHOD__,"\n";
        }
    }
    function funcname()
    {
        echo __FUNCTION__,"\n";
    }
    const constname = "namespaced";

    /* 注意，如果使用双引号，要这样写 "\\namespacename\\classname" */
    $a = '\namespacename\classname';
    $obj = new $a; // 输出 namespacename\classname::__construct
    $a = 'namespacename\classname';
    $obj = new $a; // 也会输出 namespacename\classname::__construct
    $b = 'namespacename\funcname';
    $b(); // 输出 namespacename\funcname
    $b = '\namespacename\funcname';
    $b(); // 也会输出 namespacename\funcname
    echo constant('\namespacename\constname'), "\n"; // 输出 namespaced
    echo constant('namespacename\constname'), "\n"; // 也会输出 namespaced
    ?>

请一定别忘了阅读 对字符串中的命名空间名称转义的注解.

## namespace 关键字和 __NAMESPACE__ 魔术常量

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

PHP支持两种抽象的访问当前命名空间内部元素的方法，`__NAMESPACE__` 魔术常量和 `namespace` 关键字。

常量 `__NAMESPACE__` 的值是包含当前命名空间名称的字符串。在全局的，不包括在任何命名空间中的代码，它包含一个空的字符串。

示例 #1 __NAMESPACE__ 示例, 在命名空间中的代码

    <?php
    namespace MyProject;

    echo '"', __NAMESPACE__, '"'; // 输出 "MyProject"
    ?>

示例 #2 __NAMESPACE__ 示例，全局代码

    <?php

    echo '"', __NAMESPACE__, '"'; // 输出 ""
    ?>

常量 `__NAMESPACE__` 在动态创建名称时很有用，例如：

示例 #3 使用 __NAMESPACE__ 动态创建名称

    <?php
    namespace MyProject;

    function get($classname)
    {
        $a = __NAMESPACE__ . '\\' . $classname;
        return new $a;
    }
    ?>

关键字 `namespace` 可用来显式访问当前命名空间或子命名空间中的元素。它等价于类中的 `self` 操作符。

示例 #4 namespace 操作符，命名空间中的代码

    <?php
    namespace MyProject;

    use blah\blah as mine; // 参考 "使用命名空间：别名/导入"

    blah\mine(); // 调用函数 MyProject\blah\mine()
    namespace\blah\mine(); // 调用函数 MyProject\blah\mine()

    namespace\func(); // 调用函数 MyProject\func()
    namespace\sub\func(); // 调用函数 MyProject\sub\func()
    namespace\cname::method(); // 调用 class MyProject\cname 的静态方法 "method"
    $a = new namespace\sub\cname(); // class MyProject\sub\cname 的实例对象
    $b = namespace\CONSTANT; // 设置 $b 的值为常量 MyProject\CONSTANT
    ?>

示例 #5 namespace 操作符, 全局代码

    <?php

    namespace\func(); // 调用函数 func()
    namespace\sub\func(); // 调用函数 sub\func()
    namespace\cname::method(); // 调用 class cname 的静态方法 "method"
    $a = new namespace\sub\cname(); // class sub\cname 的实例对象
    $b = namespace\CONSTANT; // 设置 $b 的值为常量 CONSTANT
    ?>

## 使用命名空间：别名/导入

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

允许通过别名引用或导入外部的完全限定名称，是命名空间的一个重要特征。这有点类似于在类 unix 文件系统中可以创建对其它的文件或目录的符号连接。

PHP 可以为这些项目导入或设置别名： 常量、函数、类、接口、trait、枚举和命名空间。

别名是通过操作符 `use` 来实现的。下面是五种导入方式的例子：

示例 #1 使用 use 操作符导入/使用别名

    <?php
    namespace foo;
    use My\Full\Classname as Another;

    // 下面的例子与 use My\Full\NSname as NSname 相同
    use My\Full\NSname;

    // 导入一个全局类
    use ArrayObject;

    // 导入函数
    use function My\Full\functionName;

    // 为函数设置别名
    use function My\Full\functionName as func;

    // 导入常量
    use const My\Full\CONSTANT;

    $obj = new namespace\Another; // 实例化 foo\Another 对象
    $obj = new Another; // 实例化 My\Full\Classname　对象
    NSname\subns\func(); // 调用函数 My\Full\NSname\subns\func
    $a = new ArrayObject(array(1)); // 实例化 ArrayObject 对象
    // 如果不使用 "use \ArrayObject" ，则实例化一个 foo\ArrayObject 对象
    func(); // 调用函数 My\Full\functionName
    echo CONSTANT; // 输出 My\Full\CONSTANT 的值
    ?>

注意对命名空间中的名称（包含命名空间分隔符的完全限定名称如 `Foo\Bar` 以及相对的不包含命名空间分隔符的全局名称如 `FooBar`）来说，前导的反斜杠是不必要的也不推荐的，因为导入的名称必须是完全限定的，不会根据当前的命名空间作相对解析。

为了简化操作，PHP 还支持在一行中使用多个 use 语句

示例 #2 通过 use 操作符导入/使用别名，一行中包含多个 use 语句

    <?php
    use My\Full\Classname as Another, My\Full\NSname;

    $obj = new Another; // 实例化 My\Full\Classname 对象
    NSname\subns\func(); // 调用函数 My\Full\NSname\subns\func
    ?>

导入操作是在编译执行的，但动态的类名称、函数名称或常量名称则不是。

示例 #3 导入和动态名称

    <?php
    use My\Full\Classname as Another, My\Full\NSname;

    $obj = new Another; // 实例化一个 My\Full\Classname 对象
    $a = 'Another';
    $obj = new $a;      // 实际化一个 Another 对象
    ?>

另外，导入操作只影响非限定名称和限定名称。完全限定名称由于是确定的，故不受导入的影响。

示例 #4 导入和完全限定名称

    <?php
    use My\Full\Classname as Another, My\Full\NSname;

    $obj = new Another; // class My\Full\Classname 的实例对象
    $obj = new \Another; // class Another 的实例对象
    $obj = new Another\thing; // class My\Full\Classname\thing 的实例对象
    $obj = new \Another\thing; // class Another\thing 的实例对象
    ?>

### 导入规则的范围

`use` 关键词必须在文件最外层范围 （全局作用域）或在命名空间声明内。 由于导入发生在编译时，而不是运行时，所以不能放入块作用域。 以下例子展示了不合规则的 `use` 关键词使用示例：

示例 #5 不合规的导入规则

    <?php
    namespace Languages;

    function toGreenlandic()
    {
        use Languages\Danish;

        // ...
    }
    ?>

> 注意:

> 导入规则独立于每个文件，意味着包含的文件 不会继承父文件的导入规则。

### `use` 声明编组

通过单个 `use` 语句，可以将来自同一个 `namespace` 的 类、函数、常量一起编组导入。

    <?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;

    // 等同于以下编组的 use 声明
    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};

## 全局空间

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

如果没有定义任何命名空间，所有的类与函数的定义都是在全局空间，与 PHP 引入命名空间概念前一样。在名称前加上前缀 `\` 表示该名称是全局空间中的名称，即使该名称位于其它的命名空间中时也是如此。

示例 #1 使用全局空间说明

    <?php
    namespace A\B\C;

    /* 这个函数是 A\B\C\fopen */
    function fopen() {
         /* ... */
         $f = \fopen(...); // 调用全局的fopen函数
         return $f;
    }
    ?>

## 使用命名空间：回退到全局函数和常量的全局空间

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

在一个命名空间中，当 PHP 遇到一个非限定的类、函数或常量名称时，它使用不同的优先策略来解析该名称。类名称总是解析到当前命名空间中的名称。因此在访问系统内部或不包含在命名空间中的类名称时，必须使用完全限定名称，例如：

示例 #1 在命名空间中访问全局类

    <?php
    namespace A\B\C;
    class Exception extends \Exception {}

    $a = new Exception('hi'); // $a 是类 A\B\C\Exception 的一个对象
    $b = new \Exception('hi'); // $b 是类 Exception 的一个对象

    $c = new ArrayObject; // 致命错误, 找不到 A\B\C\ArrayObject 类
    ?>

对于函数和常量来说，如果当前命名空间中不存在该函数或常量，PHP 会退而使用全局空间中的函数或常量。

示例 #2 命名空间中后备的全局函数/常量

    <?php
    namespace A\B\C;

    const E_ERROR = 45;
    function strlen($str)
    {
        return \strlen($str) - 1;
    }

    echo E_ERROR, "\n"; // 输出 "45"
    echo INI_ALL, "\n"; // 输出 "7" - 使用全局常量 INI_ALL

    echo strlen('hi'), "\n"; // 输出 "1"
    if (is_array('hi')) { // 输出 "is not array"
        echo "is array\n";
    } else {
        echo "is not array\n";
    }
    ?>

## 名称解析规则

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

在说明名称解析规则之前，我们先看一些重要的定义：

命名空间名称定义
非限定名称（Unqualified name）

  名称中不包含命名空间分隔符的标识符，例如 `Foo`

限定名称（Qualified name）

  名称中含有命名空间分隔符的标识符，例如 `Foo\Bar`

完全限定名称（Fully qualified name）

  名称中包含命名空间分隔符，并以命名空间分隔符开始的标识符，例如 `\Foo\Bar`。 `namespace\Foo` 也是一个完全限定名称。

相对名称（Relative name）

  这是个以 `namespace` 开头的标识符， 例如 `namespace\Foo\Bar`。

名称解析遵循下列规则：

1. 完全限定名称总是会解析成没有前缀符号的命名空间名称。 `\A\B` 解析为 `A\B`。
2. 解析相对名称时，会用当前命名空间的名称替换掉 `namespace`。 如果名称出现在全局命名空间，会截掉 `namespace\` 前缀。 例如，在命名空间 `X\Y` 里的 `namespace\A` 会被解析成 `X\Y\A`。 在全局命名空间里，同样的名字却被解析成 `A`。
3. 对于限定名称，名字的第一段会根据当前 class/namespace 导入表进行翻译。 比如命名空间 `A\B\C` 被导入为 `C`， 名称 `C\D\E` 会被翻译成 `A\B\C\D\E`。
4. 对于限定名称，如果没有应用导入规则，就将当前命名空间添加为名称的前缀。 例如，位于命名空间 `A\B` 内的名称 `C\D\E` 会解析成 `A\B\C\D\E`。
5. 根据符号类型和对应的当前导入表，解析非限定名称。 这也就是说，根据 class/namespace 导入表翻译类名称； 根据函数导入表翻译函数名称； 根据常量导入表翻译常量名称。 比如，在 `use A\B\C;` 后，类似 `new C()` 这样的名称会解析为 `A\B\C()`。 类似的，`use function A\B\foo;` 后， `foo()` 的用法，解析名称为 `A\B\foo`。
6. 如果没有应用导入规则，对于类似 class 符号的非限定名称，会添加当前命名空间作为前缀。 比如命名空间 `A\B` 内的 `new C()` 会把名称解析为 `A\B\C`。
7. 如果没有应用导入规则，非限定名称指向函数或常量，且代码位于全局命名空间之外，则会在运行时解析名称。 假设代码位于命名空间 `A\B` 中， 下面演示了调用函数 `foo()` 是如何解析的：
   1. 在当前命名空间中查找函数： `A\B\foo()`。
   2. 它会尝试找到并调用 全局 的函数 `foo()`。

示例 #1 名称解析示例

    <?php
    namespace A;
    use B\D, C\E as F;

    // 函数调用

    foo();      // 首先尝试调用定义在命名空间"A"中的函数foo()
                // 再尝试调用全局函数 "foo"

    \foo();     // 调用全局空间函数 "foo"

    my\foo();   // 调用定义在命名空间"A\my"中函数 "foo"

    F();        // 首先尝试调用定义在命名空间"A"中的函数 "F"
                // 再尝试调用全局函数 "F"

    // 类引用

    new B();    // 创建命名空间 "A" 中定义的类 "B" 的一个对象
                // 如果未找到，则尝试自动装载类 "A\B"

    new D();    // 使用导入规则，创建命名空间 "B" 中定义的类 "D" 的一个对象
                // 如果未找到，则尝试自动装载类 "B\D"

    new F();    // 使用导入规则，创建命名空间 "C" 中定义的类 "E" 的一个对象
                // 如果未找到，则尝试自动装载类 "C\E"

    new \B();   // 创建定义在全局空间中的类 "B" 的一个对象
                // 如果未发现，则尝试自动装载类 "B"

    new \D();   // 创建定义在全局空间中的类 "D" 的一个对象
                // 如果未发现，则尝试自动装载类 "D"

    new \F();   // 创建定义在全局空间中的类 "F" 的一个对象
                // 如果未发现，则尝试自动装载类 "F"

    // 调用另一个命名空间中的静态方法或命名空间函数

    B\foo();    // 调用命名空间 "A\B" 中函数 "foo"

    B::foo();   // 调用命名空间 "A" 中定义的类 "B" 的 "foo" 方法
                // 如果未找到类 "A\B" ，则尝试自动装载类 "A\B"

    D::foo();   // 使用导入规则，调用命名空间 "B" 中定义的类 "D" 的 "foo" 方法
                // 如果类 "B\D" 未找到，则尝试自动装载类 "B\D"

    \B\foo();   // 调用命名空间 "B" 中的函数 "foo"

    \B::foo();  // 调用全局空间中的类 "B" 的 "foo" 方法
                // 如果类 "B" 未找到，则尝试自动装载类 "B"

    // 当前命名空间中的静态方法或函数

    A\B::foo();   // 调用命名空间 "A\A" 中定义的类 "B" 的 "foo" 方法
                  // 如果类 "A\A\B" 未找到，则尝试自动装载类 "A\A\B"

    \A\B::foo();  // 调用命名空间 "A\B" 中定义的类 "B" 的 "foo" 方法
                  // 如果类 "A\B" 未找到，则尝试自动装载类 "A\B"
    ?>

## FAQ：命名空间必知必会

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

本文分两节：常见问题、有助于完全理解的实现详情。

首先，常见问题。

1. 如果我不用命名空间，是否需要关心它？
2. 我如何在命名空间内使用一个全局/内置的类？
3. 如何在命名空间内访问它自己的类、函数、常量？
4. 像 `\my\name` 和 `\name` 这样的名称是如何解析的？
5. 像 `my\name` 这样的名称是如何解析的？
6. 像 `name` 这样的非限定类名是如何解析的？
7. 像 `name` 这样的非限定常量和函数名是如何解析的？

为了帮助理解，我们提供了一些命名空间实现细节。

1. 在同一个文件中，导入名称不能和定义的类名发生冲突。
2. 不允许嵌套 namespace。
3. 动态命名空间名称（引号标识）应该转义反斜线。
4. 引用一个未定义的、带反斜线的常量，会导致 fatal 错误并退出
5. 不能重载特殊常量： `null`, `true` or `false`

### 如果我不用命名空间，是否需要关心它？

不需要。命名空间不影响现存的代码，也不影响即将要写下的不含命名空间的代码。 想要的话可以这样写：

示例 #1 在命名空间之外访问全局类

    <?php
    $a = new \stdClass;

以上等同于：

示例 #2 在命名空间之外访问全局类

    <?php
    $a = new stdClass;

### 我如何在命名空间内使用一个全局/内置的类？

示例 #3 在命名空间内访问内置的类

    <?php
    namespace foo;
    $a = new \stdClass;

    function test(\ArrayObject $parameter_type_example = null) {}

    $a = \DirectoryIterator::CURRENT_AS_FILEINFO;

    // 扩展内置或全局的 class
    class MyException extends \Exception {}
    ?>

### 如何在命名空间内访问它自己的类、函数、常量？

示例 #4 在命名空间中访问内置的类、函数、常量

    <?php
    namespace foo;

    class MyClass {}

    // 以当前命名空间中的 class 作为参数的类型
    function test(MyClass $parameter_type_example = null) {}
    // 以当前命名空间中的 class 作为参数的类型的另一种方式
    function test(\foo\MyClass $parameter_type_example = null) {}

    // 在当前命名空间中扩展一个类
    class Extended extends MyClass {}

    // 访问全局函数
    $a = \globalfunc();

    // 访问全局常量
    $b = \INI_ALL;
    ?>

### 像 `\my\name` 和 `\name` 这样的名称是如何解析的？

以 `\` 开头的名称总是会解析成原样， 因此 `\my\name` 实际上是 `my\name`， 而 `\Exception` 是 `Exception`。

示例 #5 完全限定名称

    <?php
    namespace foo;
    $a = new \my\name(); // class "my\name" 的实例
    echo \strlen('hi'); // 调用函数 "strlen"
    $a = \INI_ALL; // $a 的值设置成常量 "INI_ALL"
    ?>

### 像 `my\name` 这样的名称是如何解析的？

像 `my\name` 这样包含反斜线的名称，但不以反斜线开头的名称， 能够以两种不同的方式解析。

如果有个导入语句，将其他名字设置别名为 `my`， 则导入别名会应用到 `my\name` 的 `my` 部分。

如果没有导入，就会追加当前的命名空间名称为 `my\name` 的前缀。

示例 #6 限定名称

    <?php
    namespace foo;
    use blah\blah as foo;

    $a = new my\name(); // class "foo\my\name" 的实例
    foo\bar::name(); // 调用 class "blah\blah\bar" 的静态方法 "name"
    my\bar(); // 调用函数 "foo\my\bar"
    $a = my\BAR; // 设置 $a 的值为 "foo\my\BAR"
    ?>

### 像 `name` 这样的非限定名称是如何解析的？

像 `name` 这样不包含反斜线的名称， 能够以两种不同的方式解析。

如果有导入语句，设置别名为 `name`，就会应用导入别名。

如果没有，就会把当前命名空间添加到 `name` 的前缀。

示例 #7 非限定类名

    <?php
    namespace foo;
    use blah\blah as foo;

    $a = new name(); // class "foo\name" 的实例
    foo::name(); // 调用 class "blah\blah" 的静态方法 "name"
    ?>

### 像 `name` 这样的非限定常量和函数名是如何解析的？

像 `name` 这样不包含反斜线的常量和函数名，能以两种不同的方式解析。

首先，当前命名空间会添加到 `name` 的前缀。

然后，如果当前命名空间不存在函数和常量 `name`， 而全局存在，就会使用全局的函数和常量 `name`。

示例 #8 非限定函数和常量名

    <?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(); // 调用 "foo\my"
    $a = strlen('hi'); // 由于 "foo\strlen" 不存在，所以调用全局的 "strlen"
    $arr = array(1,3,2);
    $b = sort($arr); // 调用函数 "foo\sort"
    $c = foo(); // 未导入，调用函数 "foo\foo"

    $a = FOO; // 未导入，设置 $a 为常量 "foo\FOO" 的值
    $b = INI_ALL; // 设置 $b 为全局常量 "INI_ALL" 的值
    ?>

### 在同一个文件中，导入名称不能和定义的类名发生冲突

允许以下脚本中的组合：

file1.php

    <?php
    namespace my\stuff;
    class MyClass {}
    ?>

another.php

    <?php
    namespace another;
    class thing {}
    ?>

file2.php

    <?php
    namespace my\stuff;
    include 'file1.php';
    include 'another.php';

    use another\thing as MyClass;
    $a = new MyClass; //  class "thing" 的实例来自于命名空间 another
    ?>

尽管在 `my\stuff` 命名空间中存在 `MyClass`， 因为类定义在了独立的文件中，所以不会发生名称冲突。 不过，接下来的例子中，因为 MyClass 定义在了 use 语句的同一个文件中， 所以发生了名称冲突，导致了 fatal 错误。

    <?php
    namespace my\stuff;
    use another\thing as MyClass;
    class MyClass {} // fatal error: MyClass conflicts with import statement
    $a = new MyClass;
    ?>

### 不允许嵌套 namespace

PHP 不允许嵌套 namespace

    <?php
    namespace my\stuff {
        namespace nested {
            class foo {}
        }
    }
    ?>

实际上，它看上去像是这样：

    <?php
    namespace my\stuff\nested {
        class foo {}
    }
    ?>

### 动态命名空间名称（引号标识）应该转义反斜线

重要的是，字符串中反斜线是一个转义字符，因此在字符串中使用时，必须要写两遍。 否则就会在无意中造成一些后果：

示例 #9 在双引号字符串中使用命名空间的危险性

    <?php
    $a = new "dangerous\name"; // 在双引号字符串中，\n 是换行符！
    $obj = new $a;

    $a = new 'not\at\all\dangerous'; // 这里没有问题
    $obj = new $a;
    ?>

在单引号字符串中，使用反斜线是安全的。 但在最佳实践中，我们仍然推荐为所有字符串统一转义反斜线。

### 引用一个未定义的、带反斜线的常量，会导致 fatal 错误并退出

像 `FOO` 这样的非限定名称常量，如果使用的时候还没定义， 会产生一个 notice。PHP 会假设该常量的值是 `FOO`。 如果没有找到包含反斜线的常量，无论是完全或者不完全限定的名称，都会产生 fatal 错误。

示例 #10 未定义的常量

    <?php
    namespace bar;
    $a = FOO; // 产生 notice - undefined constants "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
    ?>

### 不能重载特殊常量：`null`, `true` or `false`

在命名空间内定义特殊的内置常量，会导致 fatal 错误

示例 #11 未定义的常量

    <?php
    namespace bar;
    const NULL = 0; // fatal error;
    const true = 'stupid'; // 也是 fatal error;
    // etc.
    ?>

# 枚举

## 目录

- 枚举概览
- 枚举基础
- 带值（回退）枚举
- 枚举方法
- 枚举静态方法
- 枚举常量
- Trait
- 常量表达式的枚举值
- 和对象的差异
- 枚举值清单
- 序列化
- 为什么枚举不可扩展
- 示例

## 枚举概览

(PHP 8 >= 8.1.0)

枚举，或称 “Enum”，能够让开发者自定义类型为一系列可能的离散值中的一个。 在定义领域模型中很有用，它能够“隔离无效状态”（making invalid states unrepresentable）。

枚举以各种不同功能的形式出现在诸多语言中。 在 PHP 中， 枚举是一种特殊类型的对象。Enum 本身是一个类（Class）， 它的各种条目（case）是这个类的单例对象，意味着也是个有效对象 —— 包括类型的检测，能用对象的地方，也可以用它。

最常见的枚举例子是内置的 boolean 类型， 该枚举类型有两个有效值 `true` 和 `false`。 Enum 使开发者能够任意定义出用户自己的、足够健壮的枚举。

## 枚举基础

Enum 类似 class，它和 class、interface、trait 共享同样的命名空间。 也能用同样的方式自动加载。 一个 Enum 定义了一种新的类型，它有固定、数量有限、可能的合法值。

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }
    ?>

以上声明了新的枚举类型 `Suit`，仅有四个有效的值： `Suit::Hearts`、`Suit::Diamonds`、 `Suit::Clubs`、`Suit::Spades`。 变量可以赋值为以上有效值里的其中一个。 函数可以检测枚举类型，这种情况下只能传入类型的值。

    <?php

    function pick_a_card(Suit $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');
    ?>

一个枚举可以定义零个或多个`case`，且没有最大数量限制。 虽然零个 case 的 enum 没什么用处，但在语法上也是有效的。

枚举条目的语法规则适用于 PHP 中的任何标签，参见常量。

默认情况下，枚举的条目（case）本质上不是标量。 就是说 `Suit::Hearts` 不等同于 `"0"`。 其实，本质上每个条目是该名称对象的单例。具体来说：

    <?php

    $a = Suit::Spades;
    $b = Suit::Spades;

    $a === $b; // true

    $a instanceof Suit;  // true
    ?>

由于对象间的大小比较毫无意义，这也意味着 enum 值从来不会 `<` 或 `>` 其他值。当 enum 的值用于比较时，总是返回 `false`。

这类没有关联数据的条目（case），被称为“纯粹条目”（Pure Case）。 仅包含纯粹 Case 的 Enum 被称为纯粹枚举（Pure Enum）。

枚举类型里所有的纯粹条目都是自身的实例。枚举类型在内部的实现形式是 class。

所有的 case 有个只读的属性 `name`。 它大小写敏感，是 case 自身的名称。

    <?php

    print Suit::Spades->name;
    // 输出 "Spades"
    ?>

如果名称是动态获取的，也可以使用 defined() 和 constant() 函数来检查枚举成员是否存在或读取其值。然而，这种方法并不推荐，因为对于大多数使用场景，使用带值枚举即可满足需求。

## 带值（回退）枚举

默认情况下，枚举成员没有对应的标量值。它们仅仅是单例对象。然而，在许多情况下，枚举成员需要能够与数据库或类似的数据存储进行往返操作，因此内置一个本质上定义的标量值（从而可以轻松序列化）是非常有用的。

定义标量形式的枚举的语法如下：

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }
    ?>

由于有标量的条目回退（Backed）到一个更简单值，又叫回退条目（Backed Case）。 包含所有回退条目的 Enum 又叫“回退 Enum”（Backed Enum）。 回退 Enum 只能包含回退条目。 纯粹 Enum 只能包含纯粹条目。

回退枚举仅能回退到 `int` 或 `string` 里的一种类型， 且同时仅支持使用一种类型（就是说，不能联合 `int|string`）。 如果枚举为标量形式，所有的条目必须明确定义唯一的标量值。 无法自动生成标量（比如：连续的数字）。 回退条目必须是唯一的；两个回退条目不能有相同的标量。 然而，也可以用常量引用到条目，实际上是创建了个别名。 参见 枚举常量。

等值可以是常量标量表达式。PHP 8.2.0 之前，必须是文字或文字表达式。这意味着不支持常量和常量表达式。也就是说，允许 `1 + 1`，但不允许 `1 + SOME_CONST`。

回退条目有个额外的只读属性 `value`， 它是定义时指定的值。

    <?php

    print Suit::Clubs->value;
    // 输出 "C"
    ?>

为了确保 `value` 的只读性， 无法将变量传引用给它。 也就是说，以下会抛出错误：

    <?php

    $suit = Suit::Clubs;
    $ref = &$suit->value;
    // Error: Cannot acquire reference to property Suit::$value
    ?>

回退枚举实现了内置的 BackedEnum interface， 暴露了两个额外的方法：

- `from(int|string): self` 能够根据标量返回对应的枚举条目。 如果找不到该值，会抛出 ValueError。 主要用于输入标量为可信的情况，使用一个不存在的枚举值，可以考虑为需终止应用的错误。
- `tryFrom(int|string): ?self` 能够根据标量返回对应的枚举条目。 如果找不到该值，会返回 `null`。 主要用于输入标量不可信的情况，调用者需要自己实现默认值的逻辑或错误的处理。

`from()` 和 `tryFrom()` 方法也遵循基本的严格/松散类型规则。 系统在弱类型模式下接受传入 integer 和 string，并自动强制转换对应值。 传入 float 也能运行，并且强制转换。 在严格类型模式下，为 string 回退枚举的 `from()` 传入 integer 会导致 TypeError，反之亦然；float 都会出现有问题。 其他所有的参数类型，在以上所有模式中都会抛出 TypeError。

    <?php

    $record = get_stuff_from_database($id);
    print $record['suit'];

    $suit =  Suit::from($record['suit']);
    // 无效数据抛出 ValueError："X" is not a valid scalar value for enum "Suit"
    print $suit->value;

    $suit = Suit::tryFrom('A') ?? Suit::Spades;
    // 无效数据返回 null，因此会用 Suit::Spades 代替。
    print $suit->value;
    ?>

手动为回退枚举定义 `from()` 或 `tryFrom()` 方法会导致 fatal 错误。

## 枚举方法

枚举（包括纯粹枚举、回退枚举）还能包含方法， 也能实现 interface。 如果 Enum 实现了 interface，则其中的条目也能接受 interface 的类型检测。

    <?php

    interface Colorful
    {
        public function color(): string;
    }

    enum Suit implements Colorful
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;

        // 满足 interface 契约。
        public function color(): string
        {
            return match($this) {
                Suit::Hearts, Suit::Diamonds => 'Red',
                Suit::Clubs, Suit::Spades => 'Black',
            };
        }

        // 不是 interface 的一部分；也没问题
        public function shape(): string
        {
            return "Rectangle";
        }
    }

    function paint(Colorful $c)
    {
       /* ... */
    }

    paint(Suit::Clubs);  // 正常

    print Suit::Diamonds->shape(); // 输出 "Rectangle"
    ?>

在这例子中，`Suit` 所有的四个实例具有两个方法： `color()`、`shape()`。 目前的调用代码和类型检查，和其他对象实例的行为完全一致。

在回退枚举中，interface 的声明紧跟回退类型的声明之后。

    <?php

    interface Colorful
    {
        public function color(): string;
    }

    enum Suit: string implements Colorful
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';

        // 满足 interface 的契约。
        public function color(): string
        {
            return match($this) {
                Suit::Hearts, Suit::Diamonds => 'Red',
                Suit::Clubs, Suit::Spades => 'Black',
            };
        }
    }
    ?>

在方法中，定义了 `$this` 变量，它引用到了条目实例。

方法中可以任意复杂，但一般的实践中，往往会返回静态的值， 或者为 `$this` match 各种情况并返回不同的值。

注意，在本示例中，更好的数据模型实践是再定一个包含 Red 和 Black 枚举值的 `SuitColor` 枚举，并且返回它作为代替。 然而这会让本示例复杂化。

以上的层次在逻辑中类似于下面的 class 结构（虽然这不是它实际运行的代码）：

    <?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
        {
            // 不合法的方法，Enum 中不允许手动定义 cases() 方法
            // 参考 “枚举值清单” 章节
        }
    }
    ?>

尽管 enum 可以包括 public、private、protected 的方法， 但由于它不支持继承，因此在实践中 private 和 protected 效果是相同的。

## 枚举静态方法

枚举也能有静态方法。 在枚举中静态方法主要用于取代构造器，如：

    <?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,
            };
        }
    }
    ?>

虽然 enum 可以包括 public、private、protected 的静态方法， 但由于它不支持继承，因此在实践中 private 和 protected 效果是相同的。

## 枚举常量

虽然 enum 可以包括 public、private、protected 的常量， 但由于它不支持继承，因此在实践中 private 和 protected 效果是相同的。

枚举常量可以引用枚举条目：

    <?php

    enum Size
    {
        case Small;
        case Medium;
        case Large;

        public const Huge = self::Large;
    }
    ?>

## Trait

枚举也能使用 trait，行为和 class 一样。 留意在枚举中 `use` trait 不允许包含属性。 只能包含方法、静态方法和常量。包含属性的 trait 会导致 fatal 错误。

    <?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',
            };
        }
    }
    ?>

## 常量表达式的枚举值

由于用 enum 自身的常量表示条目，它们可当作静态值，用于绝大多数常量表达式： 属性默认值、变量默认值、参数默认值、全局和类常量。 他们不能用于其他 enum 枚举值，但通常的常量可以引用枚举条目。

然而，因为不能保证结果值绝对不变，也不能避免调用方法时带来副作用， 所以枚举里类似 ArrayAccess 这样的隐式魔术方法调用无法用于静态定义和常量定义。 常量表达式还是不能使用函数调用、方法调用、属性访问。

    <?php

    // 这是完全合法的 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
    {
        // 可以这样写。
        const DOWN = Direction::Down;

        // 由于它是不确定的，所以不能这么写。
        const UP = Direction::Up['short'];
        // Fatal error: Cannot use [] on enums in constant expression
    }

    // 由于它不是一个常量表达式，所以是完全合法的
    $x = Direction::Up['short'];
    var_dump("\$x is " . var_export($x, true));

    $foo = new Foo();
    ?>

## 和对象的差异

尽管 enum 基于类和对象，但它们不完全支持对象相关的所有功能。 尤其是枚举条目不能有状态。

- 禁止构造、析构函数。
- 不支持继承。无法 extend 一个 enum。
- 不支持静态属性和对象属性。
- 由于枚举条目是单例对象，所以不支持对象复制。
- 除了下面列举项，不能使用魔术方法。
- 枚举必须在使用前被声明。

以下对象功能可用，功能和其他对象一致：

- Public、private、protected 方法。
- Public、private、protected 静态方法。
- Public、private、protected 类常量。
- enum 可以 implement 任意数量的 interface。
- 枚举和它的条目都可以附加 注解。 目标过滤器 `TARGET_CLASS` 包括枚举自身。 目标过滤器 `TARGET_CLASS_CONST` 包括枚举条目。
- 魔术方法：__call、__callStatic、 __invoke。
- 常量 `__CLASS__` 和 `__FUNCTION__` 的功能和平时无差别

枚举类型的魔术常量 `::class` 和对象完全一样， 它是个包含命名空间的类型名称。 由于枚举条目是枚举类型的一个实例，因此它的 `::class` 也和枚举类型一样。

此外，不能用 `new` 直接实例化枚举条目， 也不能用 ReflectionClass::newInstanceWithoutConstructor() 反射实例化。 这么做都会导致错误。

    <?php

    $clovers = new Suit();
    // Error: Cannot instantiate enum Suit

    $horseshoes = (new ReflectionClass(Suit::class))->newInstanceWithoutConstructor()
    // Error: Cannot instantiate enum Suit
    ?>

## 枚举值清单

无论是纯粹枚举还是回退枚举，都实现了一个叫 UnitEnum 的内部接口。 `UnitEnum` 包含了一个静态方法： `cases()`。 按照声明中的顺序，`cases()` 返回了打包的 array，包含全部定义的条目。

    <?php

    Suit::cases();
    // 产生： [Suit::Hearts, Suit::Diamonds, Suit::Clubs, Suit::Spades]
    ?>

为 Enum 手动定义 `cases()` 方法会导致 fatal 错误。

## 序列化

枚举的序列化不同于对象。 尤其是它们有新的序列化代码： `"E"`，指示了 enum 条目名称。 然后反序列化动作能够设置变量为现有的单例值。 确保那样：

    <?php

    Suit::Hearts === unserialize(serialize(Suit::Hearts));

    print serialize(Suit::Hearts);
    // E:11:"Suit:Hearts";
    ?>

如果枚举和它的条目在反序列化时，无法匹配序列化的值， 会导致 warning 警告，并返回 `false`。

把纯粹枚举序列化为 JSON 将会导致错误。 把回退枚举序列化为 JSON 时，仅会用标量值的形式，以合适的类型表达。 可通过实现 JsonSerializable 来重载序列化行为。

对于 print_r()，输出的枚举条目略微不同于对象， 能减少迷惑。

    <?php

    enum Foo {
        case Bar;
    }

    enum Baz: int {
        case Beep = 5;
    }

    print_r(Foo::Bar);
    print_r(Baz::Beep);

    /* 产生

    Foo Enum (
        [name] => Bar
    )
    Baz Enum:int {
        [name] => Beep
        [value] => 5
    }
    */
    ?>

## 为什么枚举不可扩展

类在方法有契约：

    <?php

    class A {}
    class B extends A {}

    function foo(A $a) {}

    function bar(B $b) {
        foo($b);
    }
    ?>

这段代码类型安全，因为 B 遵循 A 的契约，并通过协变/逆变的逻辑，将会保留任何对方法的期望，除了异常。

枚举在其选项上有契约，而不是方法：

    <?php

    enum ErrorCode {
        case SOMETHING_BROKE;
    }

    function quux(ErrorCode $errorCode)
    {
        // 编写时，此代码似乎涵盖了所有情况
        match ($errorCode) {
            ErrorCode::SOMETHING_BROKE => true,
        };
    }

    ?>

在函数 `quux` 中，match 语句可以进行静态分析，以涵盖 ErrorCode 中的所有情况。

但是想一下，如果允许扩展枚举：

    <?php

    // 当枚举不是 final 时考虑做的实验代码。
    // 注意在 PHP 中实际不起作用。
    enum MoreErrorCode extends ErrorCode {
        case PEBKAC;
    }

    function fot(MoreErrorCode $errorCode) {
        quux($errorCode);
    }

    fot(MoreErrorCode::PEBKAC);

    ?>

根据正常的继承规则，继承另一个类的类将通过类型检查。

问题在于 `quux()` 中的 match 语句不再涵盖所有情况。因为它不知道 `MoreErrorCode::PEBKAC`，所以匹配语句会抛出异常。

因此，枚举是 final，不能扩展。

## 示例

示例 #1 值受限的基本用法

    <?php

    enum SortOrder
    {
        case Asc;
        case Desc;
    }

    function query($fields, $filter, SortOrder $order = SortOrder::Asc)
    {
         /* ... */
    }
    ?>

由于确保 `$order` 不是 `SortOrder::Asc` 就是 `SortOrder::Desc`，所以 `query()` 函数能安全处理。 因为其他任意值都会导致 TypeError， 所以不需要额外的错误检查。

示例 #2 值排他的高级用法

    <?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',
            };
        }
    }
    ?>

这个例子中，用户的状态是 `UserStatus::Pending`、 `UserStatus::Active`、`UserStatus::Suspended`、 `UserStatus::CanceledByUser` 中的一个，具有独占性。 函数可以根据 `UserStatus` 设置参数类型，仅支持这四种值。

所有四个值都有一个 `label()` 方法，返回了人类可读的字符串。 它独立于等同于标量的“机器名”。 机器名用于类似数据库字段或 HTML 选择框这样的地方。

    <?php

    foreach (UserStatus::cases() as $case) {
        printf('<option value="%s">%s</option>\n', $case->value, $case->label());
    }
    ?>

# 错误

## 目录

- 基础概要
- PHP 7 错误处理

## 介绍

可悲的是，不管我们在写代码时多么小心，错误始终是有的。PHP 会为许多常见的编码和运行问题报告错误、警告、通知。知道如何检测和处理这些错误，使得调试程序更容易。

## 基础概要

PHP 对一些内部的错误情况进行报错。 这些错误可以用来表示不同的情况，可以根据需要将错误显示出来或记录到日志中。

每个 PHP 产生的错误都包含了类型。可查看 错误类型清单，它附带了不同类型行为的简短描述和 产生的原因。

### PHP 错误处理

当未设置错误处理函数时，PHP 会根据配置处理出现的错误。 php.ini 中 `error_reporting` 的配置或者是运行时调用 error_reporting() 控制了哪些错误需要报告，哪些错误需要自动忽略。 由于有些错误会在运行用户脚本前就可能出现，所以强烈推荐用配置指令来设置。

在开发环境里为了发现并修复 PHP 产生的问题， 应该总是把 `error_reporting` 设置为 `E_ALL`。 在生产环境里，用户可能为了降低信息的详细程度， 想要将它设置为类似 `E_ALL & ~E_NOTICE & ~E_DEPRECATED`， 但很多情况下 `E_ALL` 也同样适用，这样可以更早地警告潜在问题。

PHP 对这些错误的处理方式，取决于两个更深的 php.ini 指令。 `display_errors` 控制了是否要将错误作为脚本输出的一部分显示。 在生产环境里应该禁用，因为可能包含类似数据库密码这样的敏感信息， 而在开发环境中应该启用，能确保立即报告问题。

PHP 不仅能显示错误，还可以开启 `log_errors` 指令来记录错误日志。它能根据 `error_log` 的设置，记录任意错误到文件或者 syslog。 特别适用于生产环境，用户可以记录发生的错误，并根据这些错误生成报告。

### 用户的错误处理器

如果 PHP 默认错误处理器还不能满足要求，用户可以通过 set_error_handler() 设置自定义错误处理器，可处理很多类型的错误。 虽然有些类型的错误不能通过这种方式处理，但能处理的类型可以用脚本合适的方式处理： 例如为用户显示自定义错误页面，同时以一种比日志更直接的方式上报错误，例如发送邮件。

## PHP 7 错误处理

PHP 7 改变了大多数错误的报告方式。不同于传统（PHP 5）的错误报告机制，现在大多数错误被作为 Error 异常抛出。

这种 Error 异常可以像 Exception 异常一样被第一个匹配的 `try` / `catch` 块所捕获。如果没有匹配的 `catch` 块，则调用异常处理函数（事先通过 set_exception_handler() 注册）进行处理。 如果尚未注册异常处理函数，则按照传统方式处理：被报告为一个致命错误（Fatal Error）。

Error 类并非继承自 Exception 类，所以不能用 `catch (Exception $e) { ... }` 来捕获 Error。你可以用 `catch (Error $e) { ... }`，或者通过注册异常处理函数（ set_exception_handler()）来捕获 Error。

### Error 层次结构

- Throwable
  - Error
    - ArithmeticError
      - DivisionByZeroError
    - AssertionError
    - CompileError
      - ParseError
    - TypeError
      - ArgumentCountError
    - ValueError
    - UnhandledMatchError
    - FiberError
    - RequestParseBodyException
  - Exception
    - ...

# 异常

## 目录

- 扩展（extend）异常处理类

PHP 有一个和其他语言相似的异常模型。在 PHP 里可以 `throw` 并捕获（`catch`）异常。为了捕获潜在的异常，代码会包含在 `try` 块里。每个 `try` 都必须至少有一个相应的 `catch` 或 `finally` 块。

如果抛出异常的函数作用域内没有 `catch` 块，异常会沿调用栈“向上冒泡”，直到找到匹配的 `catch` 块。沿途会执行所有遇到的 `finally` 块。在没有设置全局异常处理程序时，如果调用栈向上都没有遇到匹配的 `catch`，程序会抛出 fatal 错误并终止。

抛出的对象必须是 `instanceof` Throwable。尝试抛出其他对象会导致 PHP Fatal 错误。

PHP 8.0.0 起，`throw` 关键词现在开始是表达式，可用于任何表达式上下文。在此之前，它是语句，必须独占一行。

## `catch`

`catch` 定义了处理抛出异常的方式。 `catch` 块定义了它能处理的异常/错误的类型，并可以选择将异常赋值到变量中。 （在 PHP 8.0.0 之前的版本中必须要赋值到变量） 如果遇到抛出对象的类型匹配了首个 `catch` 块的异常或错误，将会处理该对象。

可用多个 `catch` 捕获不同的异常类。 正常情况下（`try` 代码块里没有抛出异常）会在最后一个定义的 `catch` 后面继续执行。 `catch` 代码块里也可以 `throw` 或者重新抛出异常。 不抛出的话，会在触发的 `catch` 后面继续执行。

当 PHP 抛出一个异常时，将不会执行后续的代码语句，并会尝试查找首个匹配的 `catch` 代码块。 如果没有用 set_exception_handler() 设置异常处理函数， PHP 会在异常未被捕获时产生 Fatal 级错误，提示 "`Uncaught Exception ...`" 消息。

从 PHP 7.1.0 起 `catch` 可以用竖线符（`|`） 指定多个异常。 如果在不同的类层次结构中，不同异常的异常需要用同样的方式处理，就特别适用这种方式。

从 PHP 8.0.0 起，捕获的异常不再强制要求指定变量名。 `catch` 代码块会在未指定时继续执行，只是无法访问到抛出的对象。

## `finally`

`finally` 代码块可以放在 `catch` 之后，或者直接代替它。 无论是否抛出了异常，在 `try` 和 `catch` 之后、在执行后续代码之前， 放在 `finally` 里的代码总是会执行。

值得注意的是 `finally` 和 `return` 语句之间存在相互影响。 如果在 `try` 或 `catch` 里遇到 `return`，仍然会执行 `finally` 里的代码。 而且，遇到 `return` 语句时，会先执行 `finally` 再返回结果。 此外，如果 `finally` 里也包含了 `return` 语句，将返回 `finally` 里的值。

另一个值得注意的交互是发生在 `try` 块内抛出的异常与 `finally` 块内抛出的异常之间。如果两个块都抛出异常，则会传播来自 `finally` 块的异常，而来自 `try` 块的异常将作为其前一个异常。

## 全局异常处理程序

当允许异常冒泡到全局作用域时，它可以被全局异常处理器捕获到。 set_exception_handler() 可以设置一个函数，在没有调用其他块时代替 `catch`。 在本质上，实现的效果等同于整个程序被 `try`-`catch` 包裹起来， 而该函数就是 `catch`。

## 注释

> 注意:

> PHP 内部函数主要使用 错误报告， 只有一些现代 面向对象 的扩展使用异常。 不过，错误很容易用 ErrorException 转化成异常。 然而，这个技术方案仅适用非 Fatal 级的错误。

> 示例 #1 将错误报告转成异常

>     <?php
>     function exceptions_error_handler($severity, $message, $filename, $lineno) {
>         throw new ErrorException($message, 0, $severity, $filename, $lineno);
>     }

>     set_error_handler('exceptions_error_handler');
>     ?>

小技巧

PHP 标准库（SPL） 提供了大量的 标准内置异常。

## 示例

示例 #2 抛出一个异常

    <?php
    function inverse($x) {
        if (!$x) {
            throw new Exception('Division by zero.');
        }
        return 1/$x;
    }

    try {
        echo inverse(5) . "\n";
        echo inverse(0) . "\n";
    } catch (Exception $e) {
        echo 'Caught exception: ',  $e->getMessage(), "\n";
    }

    // 继续执行
    echo "Hello World\n";
    ?>

以上示例会输出：

    0.2
    Caught exception: Division by zero.
    Hello World

示例 #3 带 `finally` 块的异常处理

    <?php
    function inverse($x) {
        if (!$x) {
            throw new Exception('Division by zero.');
        }
        return 1/$x;
    }

    try {
        echo inverse(5) . "\n";
    } catch (Exception $e) {
        echo 'Caught exception: ',  $e->getMessage(), "\n";
    } finally {
        echo "First finally.\n";
    }

    try {
        echo inverse(0) . "\n";
    } catch (Exception $e) {
        echo 'Caught exception: ',  $e->getMessage(), "\n";
    } finally {
        echo "Second finally.\n";
    }

    // 继续执行
    echo "Hello World\n";
    ?>

以上示例会输出：

    0.2
    First finally.
    Caught exception: Division by zero.
    Second finally.
    Hello World

示例 #4 `finally` 和 `return` 相互之间的影响

    <?php

    function test() {
        try {
            throw new Exception('foo');
        } catch (Exception $e) {
            return 'catch';
        } finally {
            return 'finally';
        }
    }

    echo test();
    ?>

以上示例会输出：

    finally

示例 #5 异常嵌套

    <?php

    class MyException extends Exception { }

    class Test {
        public function testing() {
            try {
                try {
                    throw new MyException('foo!');
                } catch (MyException $e) {
                    // 重新 throw
                    throw $e;
                }
            } catch (Exception $e) {
                var_dump($e->getMessage());
            }
        }
    }

    $foo = new Test;
    $foo->testing();

    ?>

以上示例会输出：

    string(4) "foo!"

示例 #6 多个异常的捕获处理

    <?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();

    ?>

以上示例会输出：

    string(11) "MyException"

示例 #7 忽略捕获的变量

仅仅在 PHP 8.0.0 及以上版本有效

    <?php

    function test() {
        throw new SpecificException('Oopsie');
    }

    try {
        test();
    } catch (SpecificException) {
        print "A SpecificException was thrown, but we don't care about the details.";
    }
    ?>

以上示例会输出：

    A SpecificException was thrown, but we don't care about the details.

示例 #8 以表达式的形式抛出

仅仅在 PHP 8.0.0 及以上版本有效

    <?php

    class SpecificException extends Exception {}

    function test() {
        do_something_risky() or throw new Exception('It did not work');
    }

    function do_something_risky() {
        return false; // 模拟失败
    }

    try {
        test();
    } catch (Exception $e) {
        print $e->getMessage();
    }
    ?>

以上示例会输出：

    It did not work

示例 #9 try 和 finally 中的异常

    <?php

    try {
        try {
            throw new Exception(message: 'Third', previous: new Exception('Fourth'));
        } finally {
            throw new Exception(message: 'First', previous: new Exception('Second'));
        }
    } catch (Exception $e) {
        var_dump(
            $e->getMessage(),
            $e->getPrevious()->getMessage(),
            $e->getPrevious()->getPrevious()->getMessage(),
            $e->getPrevious()->getPrevious()->getPrevious()->getMessage(),
        );
    }

以上示例会输出：

    string(5) "First"
    string(6) "Second"
    string(5) "Third"
    string(6) "Fourth"

## 扩展（extend）异常处理类

用户可以用自定义的异常处理类来扩展 PHP 内置的异常处理类。以下的代码说明了在内置的异常处理类中，哪些属性和方法在子类中是可访问和可继承的。

示例 #1 内置的异常处理类

    <?php
    class Exception implements Throwable
    {
        protected $message = 'Unknown exception';   // 异常信息
        private   $string;                          // __toString 的缓存
        protected $code = 0;                        // 用户自定义异常错误码
        protected $file;                            // 发生异常的源文件名
        protected $line;                            // 发生异常的源代码行号
        private   $trace;                           // backtrace
        private   $previous;                        // 如果是嵌套异常，则是之前的 exception

        public function __construct($message = '', $code = 0, ?Throwable $previous = null);

        final private function __clone();           // 禁止克隆异常。

        final public  function getMessage();        // 异常信息
        final public  function getCode();           // 异常错误码
        final public  function getFile();           // 发生异常的源文件名
        final public  function getLine();           // 发生异常的源代码行号
        final public  function getTrace();          // backtrace() 数组
        final public  function getPrevious();       // 之前的 exception
        final public  function getTraceAsString();  // 已格成化成字符串的 getTrace() 信息

        // Overrideable
        public function __toString();               // 可输出的格式化后的字符串
    }
    ?>

如果使用自定义的类来扩展内置异常处理类，并且要重新定义构造函数的话，建议同时调用 parent::__construct() 来确保所有的变量已赋值。当对象要输出字符串的时候，可以重载 __toString() 并自定义输出的样式。

> 注意:

> 不能 复制 Exception 对象。尝试对 clone Exception 会导致 fatal `E_ERROR` 错误。

示例 #2 扩展 PHP 内置的异常处理类

    <?php
    /**
     * 自定义一个异常处理类
     */
    class MyException extends Exception
    {
        // 重定义构造器使 message 变为必须被指定的属性
        public function __construct($message, $code = 0, ?Throwable $previous = null) {
            // 这里写用户的代码

            // 确保所有变量都被正确赋值
            parent::__construct($message, $code, $previous);
        }

        // 自定义字符串输出的格式
        public function __toString() {
            return __CLASS__ . ": [{$this->code}]: {$this->message}\n";
        }

        public function customFunction() {
            echo "A custom function for this type of exception\n";
        }
    }

    /**
     * 创建一个类，测试该 exception 类
     */
    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:
                    // 抛出自定义异常
                    throw new MyException('1 is an invalid parameter', 5);
                    break;

                case self::THROW_DEFAULT:
                    // 抛出默认的异常
                    throw new Exception('2 is not allowed as a parameter', 6);
                    break;

                default:
                    // 没有异常的情况下，创建一个对象
                    $this->var = $avalue;
                    break;
            }
        }
    }

    // 例子 1
    try {
        $o = new TestException(TestException::THROW_CUSTOM);
    } catch (MyException $e) {      // 捕获异常
        echo "Caught my exception\n", $e;
        $e->customFunction();
    } catch (Exception $e) {        // 被忽略
        echo "Caught Default Exception\n", $e;
    }

    // 继续执行后续代码
    var_dump($o); // Null
    echo "\n\n";

    // 例子 2
    try {
        $o = new TestException(TestException::THROW_DEFAULT);
    } catch (MyException $e) {      //  不能匹配异常的种类，被忽略
        echo "Caught my exception\n", $e;
        $e->customFunction();
    } catch (Exception $e) {        // 捕获异常
        echo "Caught Default Exception\n", $e;
    }

    // 执行后续代码
    var_dump($o); // Null
    echo "\n\n";

    // 例子 3
    try {
        $o = new TestException(TestException::THROW_CUSTOM);
    } catch (Exception $e) {        // 捕获异常
        echo "Default Exception caught\n", $e;
    }

    // 执行后续代码
    var_dump($o); // Null
    echo "\n\n";

    // 例子 4
    try {
        $o = new TestException();
    } catch (Exception $e) {        // 没有异常，被忽略
        echo "Default Exception caught\n", $e;
    }

    // 执行后续代码
    var_dump($o); // TestException
    echo "\n\n";
    ?>

# 纤程

### 纤程概述

(PHP 8 >= 8.1.0)

纤程（Fiber）表示一组有完整栈、可中断的功能。 纤程可以在调用堆栈中的任何位置被挂起，在纤程内暂停执行，直到稍后恢复。

纤程可以暂停整个执行堆栈，所以该函数的直接调用者不需要改变调用这个函数的方式。

你可以在调用堆栈的任意地方使用 Fiber::suspend() 中断执行（也就是说，Fiber::suspend() 的调用位置可以在一个深度嵌套的函数中，甚至可以不存在）。

与无栈的 Generator 不同, 每一个 Fiber 拥有自己的调用栈，并允许在一个深度前度的函数调用中将它们暂停。 声明了中断（interruption）点的函数（即调用 Fiber::suspend()） 不需要改变自己的返回类型，不像使用 `yield` 一样需要返回一个 Generator 实例。

纤程可以在任意函数调用中被暂停，包括那些在 PHP VM 中被调用的函数。 例如被用于 array_map() 的函数或者提供 Iterator 对象以被 `foreach` 调用的方法。

纤程一旦被暂停，可以使用 Fiber::resume() 传递任意值、或者使用 Fiber::throw() 向纤程抛出一个异常以恢复运行。这个值或者异常将会在 Fiber::suspend() 中被返回（抛出）。

> 注意: 在 PHP 8.4.0 之前，不允许在对象析构方法执行期间切换纤程。

示例 #1 基础用法

    <?php
    $fiber = new Fiber(function (): void {
       $value = Fiber::suspend('fiber');
       echo "Value used to resume fiber: ", $value, PHP_EOL;
    });

    $value = $fiber->start();

    echo "Value from fiber suspending: ", $value, PHP_EOL;

    $fiber->resume('test');
    ?>

以上示例会输出：

    Value from fiber suspending: fiber
    Value used to resume fiber: test

# 生成器

## 目录

- 生成器总览
- 生成器语法
- 生成器与 Iterator 对象的比较

## 生成器总览

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

生成器提供了一种更容易的方法来实现简单的对象迭代，相比较定义类实现 Iterator 接口的方式，性能开销和复杂性大大降低。

生成器提供了方便的方式来向 `foreach` 循环提供数据，而无需提前在内存中构建数组，这可能会导致程序超出内存限制或需要相当长的处理时间来生成。相反，可以使用生成器函数，与普通的 function 相同，不同之处在于生成器不是 return 一次，而是可以根据需要多次 `yield` 以提供要迭代的值。与迭代器一样，无法进行随机数据访问。

一个简单的例子就是使用生成器来重新实现 range() 函数。 标准的 range() 函数需要在内存中生成一个数组包含每一个在它范围内的值，然后返回该数组, 结果就是会产生多个很大的数组。 比如，调用 range(0, 1000000) 将导致内存占用超过 100 MB。

做为一种替代方法, 我们可以实现一个 `xrange()` 生成器, 只需要足够的内存来创建 Iterator 对象并在内部跟踪生成器的当前状态，这样只需要不到1K字节的内存。

示例 #1 将 range() 实现为生成器

    <?php
    function xrange($start, $limit, $step = 1) {
        if ($start <= $limit) {
            if ($step <= 0) {
                throw new LogicException('Step must be positive');
            }

            for ($i = $start; $i <= $limit; $i += $step) {
                yield $i;
            }
        } else {
            if ($step >= 0) {
                throw new LogicException('Step must be negative');
            }

            for ($i = $start; $i >= $limit; $i += $step) {
                yield $i;
            }
        }
    }

    /*
     * 注意下面range()和xrange()输出的结果是一样的。
     */

    echo 'Single digit odd numbers from range():  ';
    foreach (range(1, 9, 2) as $number) {
        echo "$number ";
    }
    echo "\n";

    echo 'Single digit odd numbers from xrange(): ';
    foreach (xrange(1, 9, 2) as $number) {
        echo "$number ";
    }
    ?>

以上示例会输出：

    Single digit odd numbers from range():  1 3 5 7 9
    Single digit odd numbers from xrange(): 1 3 5 7 9

### Generator 对象

调用生成器函数时会返回一个内部的 Generator 类的对象。 该对象实现了 Iterator 接口，基本上和仅向前的迭代器一样， 它提供的方法可以操控生成器的状态，包括发送值、返回值。

## 生成器语法

生成器函数看起来像普通函数——不同的是普通函数返回一个值，而生成器可以 `yield` 生成多个想要的值。 任何包含 `yield` 的函数都是一个生成器函数。

当一个生成器被调用的时候，它返回一个可以被遍历的对象.当你遍历这个对象的时候(例如通过一个`foreach`循环)，PHP 将会在每次需要值的时候调用对象的遍历方法，并在产生一个值之后保存生成器的状态，这样它就可以在需要产生下一个值的时候恢复调用状态。

一旦不再需要产生更多的值，生成器可以简单返回，而调用生成器的代码还可以继续执行，就像一个数组已经被遍历完了。

> 注意:

> 生成器能够返回多个值，通过 Generator::getReturn() 可以获取到。

### yield 关键字

生成器函数的核心是yield关键字。它最简单的调用形式看起来像一个return申明，不同之处在于普通return会返回值并终止函数的执行，而yield会返回一个值给循环调用此生成器的代码并且只是暂停执行生成器函数。

示例 #1 一个简单的生成值的例子

    <?php
    function gen_one_to_three() {
        for ($i = 1; $i <= 3; $i++) {
            //注意变量$i的值在不同的yield之间是保持传递的。
            yield $i;
        }
    }

    $generator = gen_one_to_three();
    foreach ($generator as $value) {
        echo "$value\n";
    }
    ?>

以上示例会输出：

    1
    2
    3

> 注意:

> 在内部会为生成的值配对连续的整型索引，就像一个非关联的数组。

#### 指定键名来生成值

PHP的数组支持关联键值对数组，生成器也一样支持。所以除了生成简单的值，你也可以在生成值的时候指定键名。

如下所示，生成一个键值对与定义一个关联数组十分相似。

示例 #2 生成一个键值对

    <?php
    /*
     * 下面每一行是用分号分割的字段组合，第一个字段将被用作键名。
     */

    $input = <<<'EOF'
    1;PHP;Likes dollar signs
    2;Python;Likes whitespace
    3;Ruby;Likes blocks
    EOF;

    function input_parser($input) {
        foreach (explode("\n", $input) as $line) {
            $fields = explode(';', $line);
            $id = array_shift($fields);

            yield $id => $fields;
        }
    }

    foreach (input_parser($input) as $id => $fields) {
        echo "$id:\n";
        echo "    $fields[0]\n";
        echo "    $fields[1]\n";
    }
    ?>

以上示例会输出：

    1:
        PHP
        Likes dollar signs
    2:
        Python
        Likes whitespace
    3:
        Ruby
        Likes blocks

#### 生成 null 值

Yield 可以在没有参数传入的情况下被调用来生成一个 `null` 值并配对一个自动的键名。

示例 #3 生成`null`s

    <?php
    function gen_three_nulls() {
        foreach (range(1, 3) as $i) {
            yield;
        }
    }

    var_dump(iterator_to_array(gen_three_nulls()));
    ?>

以上示例会输出：

    array(3) {
      [0]=>
      NULL
      [1]=>
      NULL
      [2]=>
      NULL
    }

#### 使用引用来生成值

生成函数可以像使用值一样来使用引用生成。这个和从函数返回一个引用一样：通过在函数名前面加一个引用符号。

示例 #4 使用引用来生成值

    <?php
    function &gen_reference() {
        $value = 3;

        while ($value > 0) {
            yield $value;
        }
    }

    /*
     * 我们可以在循环中修改 $number 的值，而生成器是使用的引用值来生成，所以 gen_reference() 内部的 $value 值也会跟着变化。
     */
    foreach (gen_reference() as &$number) {
        echo (--$number).'... ';
    }
    ?>

以上示例会输出：

    2... 1... 0...

#### 可用的 yield from 生成器委托

生成器委托允许使用 yield from 关键字从另外一个生成器、 Traversable 对象、array 通过生成值。 外部生成器将从内部生成器、object、array 中生成所有的值，直到它们不再有效， 之后将在外部生成器中继续执行。

如果生成器与 yield from 一起使用，那么 yield from 表达式将返回内部生成器返回的任何值。

警告

# 存储到 array （例如使用 iterator_to_array()）

yield from 不能重置 key。它保留 Traversable 对象或者 array 返回的 key。因此，某些值可能会与其他的 yield 或者 yield from 共享公共的 key，因此，在插入数组时将会用这个 key 覆盖以前的值。

一个非常重要的常见情况是 iterator_to_array() 默认返回带 key 的 array ， 这可能会造成无法预料的结果。 iterator_to_array() 还有第二个参数 `preserve_keys` ，可以设置为 `false` 来收集 Generator 返回的不带 key 的所有值。

示例 #5 使用 iterator_to_array() 的 yield from

    <?php
     function inner() {
         yield 1; // key 0
         yield 2; // key 1
         yield 3; // key 2
     }
     function gen() {
         yield 0; // key 0
         yield from inner(); // keys 0-2
         yield 4; // key 1
     }
     // 传递 false 作为第二个参数获得数组 [0, 1, 2, 3, 4]
     var_dump(iterator_to_array(gen()));
     ?>

以上示例会输出：

     array(3) {
       [0]=>
       int(1)
       [1]=>
       int(4)
       [2]=>
       int(3)
     }

示例 #6 yield from 的基本用法

    <?php
    function count_to_ten() {
        yield 1;
        yield 2;
        yield from [3, 4];
        yield from new ArrayIterator([5, 6]);
        yield from seven_eight();
        yield 9;
        yield 10;
    }

    function seven_eight() {
        yield 7;
        yield from eight();
    }

    function eight() {
        yield 8;
    }

    foreach (count_to_ten() as $num) {
        echo "$num ";
    }
    ?>

以上示例会输出：

    1 2 3 4 5 6 7 8 9 10

示例 #7 yield from 并返回多个值

    <?php
    function count_to_ten() {
        yield 1;
        yield 2;
        yield from [3, 4];
        yield from new ArrayIterator([5, 6]);
        yield from seven_eight();
        return yield from nine_ten();
    }

    function seven_eight() {
        yield 7;
        yield from eight();
    }

    function eight() {
        yield 8;
    }

    function nine_ten() {
        yield 9;
        return 10;
    }

    $gen = count_to_ten();
    foreach ($gen as $num) {
        echo "$num ";
    }
    echo $gen->getReturn();
    ?>

以上示例会输出：

    1 2 3 4 5 6 7 8 9 10

## 生成器与 Iterator 对象的比较

生成器最主要的优点是简洁。和实现一个 Iterator 类相较而言， 同样的功能，用生成器可以编写更少的代码，可读性也更强。 举例，下面的类和函数是相等的：

    <?php
    function getLinesFromFile($fileName) {
        if (!$fileHandle = fopen($fileName, 'r')) {
            return;
        }

        while (false !== $line = fgets($fileHandle)) {
            yield $line;
        }

        fclose($fileHandle);
    }

    // 比较下...

    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);
        }
    }
    ?>

不过，这也付出了灵活性的代价： 生成器是一个只能向前的迭代器，一旦开始遍历就无法后退。 意思也就是说，同样的生成器无法遍历多次：要么再次调用生成器函数，重新生成后再遍历。

### 参见

- 遍历对象

# 注解

## 目录

- 注解概览
- 注解语法
- 使用反射 API 读取注解
- 声明注解类

## 注解概览

(PHP 8)

PHP 注解为类、方法、函数、参数、属性和常量提供了结构化且机器可读的元数据。它们可以通过反射 API 在运行时进行检查，从而实现动态行为而无需修改代码。注解提供了声明式的方式来为代码添加元数据注释。

注解使得功能实现与其使用之间实现解耦。接口通过强制定义方法来规范结构，而注解则为方法、函数、属性和常量在内的多个元素提供元数据。与接口不同，接口强制实现方法，而注解则在不改变代码结构的情况下为其添加注释。

注解可以通过提供元数据而非强制结构来补充或替代可选的接口方法。以表示应用程序中操作的 `ActionHandler` 接口为例。某些实现可能需要设置步骤，而其他实现则不需要。与其强制所有实现（implementing）`ActionHandler` 的类都定义 `setUp()` 方法，不如使用注解来表明设置需求。这种方法提高了灵活性，并允许在必要时多次应用属性。

示例 #1 用注解实现接口的可选方法

    <?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("File does not exist");
            }
        }

        #[SetUp]
        public function targetDirectoryExists()
        {
            if (!file_exists($this->targetDirectory)) {
                mkdir($this->targetDirectory);
            } elseif (!is_dir($this->targetDirectory)) {
                throw new RuntimeException("Target directory $this->targetDirectory is not a directory");
            }
        }

        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);

## 注解语法

注解语法由几个关键组件组成。属性声明以 `#[` 开始，以 `]` 结束。内部可以列出一个或多个注解，注解之间用逗号分隔。注解名称如使用命名空间基础中所述，可以是未限定、限定或完全限定的。注解的参数是可选的，并用圆括号 `()` 括起来。参数只能是字面值或常量表达式，同时支持位置参数和命名参数语法。

注解名称及其参数会解析为类，并在通过反射 API 请求注解实例时，将参数传递给其构造方法。因此，建议为每个注解都引入对应的类。

示例 #1 注解语法

    <?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
    {
    }

## 使用反射 API 读取注解

要访问类、方法、函数、参数、属性以及类常量中的注解，可以使用反射 API 提供的 getAttributes() 方法。该方法返回包含 ReflectionAttribute 实例的数组。这些实例可用于查询注解名称和参数，并可用于实例化所表示注解的对象。

将反射注解表示与其实际实例分离，可以更好地控制错误处理，例如缺失的注解类、参数拼写错误或缺少值等问题。注解类的对象只有在调用 ReflectionAttribute::newInstance() 之后才会实例化，从而确保参数验证在此时进行。

示例 #1 通过反射 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)
    }
    */

无需遍历反射实例上的所有注解，可以通过将注解类名作为参数传递，来仅检索特定注解类的注解。

示例 #2 使用反射 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));

## 声明注解类

建议为每个注解定义单独的类。在最简单的情况下，带有 `#[Attribute]` 声明的空类即可满足需求。可以使用 `use` 语句从全局命名空间导入该注解。

示例 #1 简单的 Attribute 类

    <?php

    namespace Example;

    use Attribute;

    #[Attribute]
    class MyAttribute
    {
    }

要限制注解可以应用的声明类型，可以将位掩码作为第一个参数传递给 `#[Attribute]` 声明。

示例 #2 目标限定使用的注解

    <?php

    namespace Example;

    use Attribute;

    #[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION)]
    class MyAttribute
    {
    }

在另一个类型中声明 MyAttribute 会在调用 ReflectionAttribute::newInstance() 时抛出异常。

可以指定以下目标：

- `Attribute::TARGET_CLASS`
- `Attribute::TARGET_FUNCTION`
- `Attribute::TARGET_METHOD`
- `Attribute::TARGET_PROPERTY`
- `Attribute::TARGET_CLASS_CONSTANT`
- `Attribute::TARGET_PARAMETER`
- `Attribute::TARGET_ALL`

默认情况下，每个声明中一个注解只能使用一次。要允许注解可重复使用，可以在 `#[Attribute]` 声明的位掩码中使用 `Attribute::IS_REPEATABLE` flag 进行指定。

示例 #3 使用 IS_REPEATABLE 允许注解在声明中出现多次

    <?php

    namespace Example;

    use Attribute;

    #[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION | Attribute::IS_REPEATABLE)]
    class MyAttribute
    {
    }

# 引用的解释

## 目录

- 引用是什么
- 引用做什么
- 引用不是什么
- 引用传递
- 引用返回
- 取消引用
- 引用定位

## 引用是什么

在 PHP 中引用意味着用不同的名字访问同一个变量内容。这并不像 C 的指针：例如你不能对他们做指针运算，他们并不是实际的内存地址…… 查看引用不是什么了解更多信息。 替代的是，引用是符号表别名。 注意在PHP 中，变量名和变量内容是不一样的， 因此同样的内容可以有不同的名字。最接近的比喻是 Unix 的文件名和文件本身——变量名是目录条目，而变量内容则是文件本身。引用可以被看作是 Unix 文件系统中的硬链接。

## 引用做什么

使用引用执行有三种基本操作： 引用赋值 、 传引用 、 引用返回 。 本节介绍这些操作，并提供进一步阅读的链接。

### 引用赋值

PHP 的引用允许用两个变量来指向同一个内容。意思是，当这样做时：

    <?php

    $a =& $b;

    ?>

这意味着 $a 和 $b 指向了同一个变量。

> 注意:

> $a 和 $b 在这里是完全相同的，这并不是 $a 指向了 $b 或者相反，而是 $a 和 $b 指向了同一个地方。

> 注意:

> 如果对一个未定义的变量进行引用赋值、引用参数传递或引用返回，则会自动创建该变量。

> 示例 #1 对未定义的变量使用引用

>     <?php

>     function foo(&$var) {}

>     foo($a); // 创建 $a 并赋值为 null

>     $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)

>     ?>

同样的语法可以用在返回引用的函数中：

    <?php

    $foo =& find_var($bar);

    ?>

在函数内使用相同的语法 不 通过引用返回将会产生错误， 就像将它与 new 运算符的结果一起使用一样。 正如 对象和引用 中所述， 尽管对象是通过指针传递的，但是它们与引用不同。

警告

如果在一个函数内部给一个声明为 `global` 的变量赋于一个引用，该引用只在函数内部可见。可以通过使用 $GLOBALS 数组避免这一点。

示例 #2 在函数内引用全局变量

    <?php

    $var1 = "Example variable";
    $var2 = "";

    function global_references($use_globals)
    {
        global $var1, $var2;

        if (!$use_globals) {
            $var2 =& $var1; // 仅在函数内部可见
        } else {
            $GLOBALS["var2"] =& $var1; // 全局上下文可见
        }
    }

    global_references(false);
    echo "var2 is set to '$var2'\n"; // var2 is set to ''

    global_references(true);
    echo "var2 is set to '$var2'\n"; // var2 is set to 'Example variable'

    ?>

把 `global $var;` 当成是 `$var =& $GLOBALS['var'];` 的简写。从而将其它引用赋给 `$var` 只改变了本地变量的引用。

> 注意:

> 如果在 `foreach` 语句中给一个具有引用的变量赋值，被引用的对象也被改变。

> 示例 #3 引用与 foreach 语句

>     <?php

>     $ref = 0;
>     $row =& $ref;

>     foreach (array(1, 2, 3) as $row) {
>         // 做点什么
>     }

>     echo $ref; // 3 - 迭代数组的最后一个元素

>     ?>

虽然不是严格意义上的引用赋值，但使用语言构造 `array()` 创建的表达式也可以通过在要添加的数组元素加上 `&` 前缀来表现为这样。例如：

    <?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); */

    ?>

但是请注意，数组内的引用具有潜在的危险。 在右侧引用正常的赋值（不是通过引用）不会将左侧变为引用， 但是数组内部的引用会保留在这些正常赋值中。 这也适用于调用函数时按值传递数组的情况。例如：

    <?php

    /* 标量变量赋值 */
    $a = 1;
    $b =& $a;
    $c = $b;
    $c = 7; // $c 不是引用；不会改变 $a 或者 $b

    /* 数组变量赋值 */
    $arr = array(1);
    $a =& $arr[0]; // $a 和 $arr[0] 设置了相同的引用
    $arr2 = $arr; // 不是引用赋值！
    $arr2[0]++;
    /* $a == 2, $arr == array(2) */
    /* 尽量 $arr 不是引用，但是它的内容已经更改！ */

    ?>

换句话说，数组的引用行为是在逐个元素的基础上定义； 单个元素的引用行为与数组容器的引用状态分离。

### 传引用

引用做的第二件事是用引用传递变量。这是通过在函数内建立一个本地变量并且该变量在呼叫范围内引用了同一个内容来实现的。例如：

    <?php

    function foo(&$var)
    {
        $var++;
    }

    $a=5;
    foo($a);

    ?>

将使 $a 变成 6。这是因为在 foo 函数中变量 $var 指向了和 $a 指向的同一个内容。更多详细解释见引用传递。

### 引用返回

引用做的第三件事是引用返回。

## 引用不是什么

如前所述，引用不是指针。这意味着下面的结构不会产生预期的效果：

    <?php

    function foo(&$var)
    {
        $var =& $GLOBALS["baz"];
    }

    foo($bar);

    ?>

这将使 foo 函数中的 $var 变量在函数调用时和 $bar 绑定在一起，但接着又被重新绑定到了 $GLOBALS["baz"] 上面。不可能通过引用机制将 $bar 在函数调用范围内绑定到别的变量上面，因为在函数 foo 中并没有变量 $bar（它被表示为 $var，但是 $var 只有变量内容而没有调用符号表中的名字到值的绑定）。可以使用引用返回来引用被函数选择的变量。

## 引用传递

可以将一个变量通过引用传递给函数，这样该函数就可以修改其参数的值。语法如下：

    <?php

    function foo(&$var)
    {
        $var++;
    }

    $a=5;

    foo($a);
    // 这里 $a 是 6

    ?>

注意在函数调用时没有引用符号——只有函数定义中有。光是函数定义就足够使参数通过引用来正确传递了。

以下内容可以通过引用传递：

- 变量，例如 `foo($a)`

- 从函数中返回的引用，例如：

      <?php

      function foo(&$var)
      {
          $var++;
      }

      function &bar()
      {
          $a = 5;
          return $a;
      }

      foo(bar());

      ?>

  详细解释见引用返回。

任何其它表达式都不能通过引用传递，结果未定义。例如下面引用传递的例子是无效的：

    <?php

    function foo(&$var)
    {
        $var++;
    }

    function bar() // 注意缺少 &
    {
        $a = 5;
        return $a;
    }

    foo(bar()); // 导致 notice 信息

    foo($a = 5) // 表达式，不是变量
    foo(5) // 导致致命错误

    class Foobar {}

    foo(new Foobar()) // 自 PHP 7.0.7 起生成通知
                      // 注意：只有变量应该通过引用传递

    ?>

## 引用返回

引用返回用在当想用函数找到引用应该被绑定在哪一个变量上面时。 不要用返回引用来增加性能，引擎足够聪明来自己进行优化。 仅在有合理的技术原因时才返回引用！ 使用此语法返回引用：

    <?php

    class Foo
    {
        public $value = 42;

        public function &getValue()
        {
            return $this->value;
        }
    }

    $obj = new Foo();
    $myValue = &$obj->getValue(); // $myValue 是对 $obj->value 的引用，即 42
    $obj->value = 2;
    echo $myValue;                // 打印 $obj->value 的新值，即 2

    ?>

本例中 getValue 函数所返回的对象的属性将被赋值， 而不是拷贝，就和没有用引用语法一样。

> 注意: 和参数传递不同，这里必须在两个地方都用 `&` 符号——指出返回的是一个引用，而不是通常的一个拷贝，同样也指出 $myValue 是作为引用的绑定，而不是通常的赋值。

> 注意: 如果试图这样从函数返回引用：`return ($this->value);`，这将不会起作用， 因为在试图返回一个表达式的结果而不是一个引用的变量。 只能从函数返回引用变量——没别的方法。

要使用返回的引用，必须使用引用赋值：

    <?php

    function &collector()
    {
        static $collection = array();
        return $collection;
    }

    $collection = &collector();
    // 现在，$collection 是引用变量，引用了函数内部的静态数组

    $collection[] = 'foo';

    print_r(collector());
    // Array
    // (
    //    [0] => foo
    // )

    ?>

> 注意: 如果赋值操作未使用 `&` 符号，例如 `$collection = collector();`，则 $collection 变量将接收值的副本，而非函数返回的引用。

要将返回的引用传递给另外一个需要引用的函数，可以使用如下语法：

    <?php

    function &collector()
    {
        static $collection = array();
        return $collection;
    }

    array_push(collector(), 'foo');

    ?>

> 注意: 注意 `array_push(&collector(), 'foo');` 将 不 起作用，它会导致 Fatal 错误。

## 取消引用

当 unset 一个引用，只是断开了变量名和变量内容之间的绑定。这并不意味着变量内容被销毁了。例如：

    <?php

    $a = 1;
    $b =& $a;
    unset($a);

    ?>

不会 unset $b，只是 $a。

再拿这个和 Unix 的 unlink 调用来类比一下可能有助于理解。

## 引用定位

许多 PHP 的语法结构是通过引用机制实现的，所以上述有关引用绑定的一切也都适用于这些结构。 一些结构，例如引用传递和返回，已经在上面提到了。 其它使用引用的结构有：

### global 引用

当用 global $var 声明一个变量时实际上建立了一个到全局变量的引用。 也就是说和这样做是相同的：

    <?php

    $var =& $GLOBALS["var"];

    ?>

这意味着，例如，unset $var 不会 unset 全局变量。

### `$this`

在一个对象的方法中，$this 永远是调用它的对象的引用。

# 预定义变量

PHP 提供了预定义变量，这些变量表述为外部变量、内置环境变量以及有关执行环境的其他信息，例如在 CLI 环境中传递给脚本的参数的数量和值。

# 超全局变量

超全局变量 — 在全部作用域中始终可用的内置变量

### 说明

PHP 中的许多预定义变量都是“超全局的”，这意味着它们在一个脚本的全部作用域中都可用。在函数或方法中无需执行 global $variable; 就可以访问它们。

这些超全局变量是：

- $GLOBALS
- $_SERVER
- $_GET
- $_POST
- $_FILES
- $_COOKIE
- $_SESSION
- $_REQUEST
- $_ENV

### 注释

> 注意: 变量可用性

> 默认情况下，所有的超全局变量都是可用的。但是，有一些指令会影响这种可用性。更多信息，参见文档 variables_order.

> 注意: 可变变量

> 在函数或类方法中，超全局变量不能被用作可变变量。

### 参见

- 变量作用域
- variables_order 指令
- 过滤器扩展

# $GLOBALS

$GLOBALS — 引用全局作用域中可用的全部变量

### 说明

关联数组 array，包含当前脚本内定义成全局范围的所有变量的引用。 数组的键就是变量的名字。

### 示例

示例 #1 $GLOBALS 范例

    <?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();

    ?>

以上示例的输出类似于：

    $foo in global scope: Example content
    $foo in current scope: local variable

警告

从 PHP 8.1.0 起，不再支持对整个 $GLOBALS 数组的写访问：

示例 #2 写入整个 $GLOBALS 将会导致错误。

    <?php
    // 生成编译时错误：
    $GLOBALS = [];
    $GLOBALS += [];
    $GLOBALS =& $x;
    $x =& $GLOBALS;
    unset($GLOBALS);
    array_pop($GLOBALS);
    // ...以及对 $GLOBALS 的任何其他写入/读写操作
    ?>

### 注释

> 注意: “Superglobal”也称为自动化的全局变量。这就表示其在脚本的所有作用域中都是可用的。不需要在函数或方法中用 global $variable; 来访问它。

> 注意: 变量可用性

> 与所有其他超全局变量不同，$GLOBALS在PHP中总是可用的。

> 注意:

> 从 PHP 8.1.0 起，$GLOBALS 现在是全局符号表的只读副本。 也就是说，全局变量不能通过副本进行修改。 在之前的版本中，$GLOBALS 数组和 PHP 数组通常传值的行为不一样，全局变量可通过副本修改。

>     <?php

>     // PHP 8.1.0 之前
>     $a = 1;

>     $globals = $GLOBALS; // 表面意义的按值复制
>     $globals['a'] = 2;
>     var_dump($a); // int(2)

>     // 从 PHP 8.1.0 起
>     // 这不再修改 $a。先前的行为违反了按值语义。
>     $globals = $GLOBALS;
>     $globals['a'] = 1;

>     // 要恢复以前的行为，请迭代其副本并将每个属性分配回 $GLOBALS。
>     foreach ($globals as $key => $value) {
>         $GLOBALS[$key] = $value;
>     }

>     ?>

# $_SERVER

$_SERVER — 服务器和执行环境信息

### 说明

$_SERVER 是一个包含了诸如头信息（header）、路径（path）、以及脚本位置（script locations）等信息的 array。这个数组中的条目由 Web 服务器创建，所以不能保证每个 Web 服务器都提供全部条目；服务器可能会忽略一些，或者提供此处没有列举出来的其它内容。然而，大部分变量在 » CGI 1.1 规范中都有说明，并且很可能会定义。

> 注意: 当在命令行运行 PHP 时，这些条目都将无效或者没有任何意义。

除了下面列出的元素之外，PHP 还将使用请求报头中的值创建其它元素，这些条目将命名为 `HTTP_` 后跟报头名称，大写且使用下划线而不是连字符。例如 `Accept-Language` 报头将作为 `$_SERVER['HTTP_ACCEPT_LANGUAGE']` 提供。

### 目录

'PHP_SELF'
  当前执行脚本的文件名，与 document root 有关。例如，在地址为 http://example.com/foo/bar.php 的脚本中使用 $_SERVER['PHP_SELF'] 将得到 /foo/bar.php。__FILE__ 常量包含当前(例如包含)文件的完整路径和文件名。 如果 PHP 以命令行模式运行，这个变量将包含脚本名。
'argv'
  传递给该脚本的参数的数组。当脚本以命令行方式运行时，argv 变量传递给程序 C 语言样式的命令行参数。当通过 GET 方式调用时，该变量包含query string。
'argc'
  包含命令行模式下传递给该脚本的参数的数目(如果运行在命令行模式下)。
'GATEWAY_INTERFACE'
  服务器使用的 CGI 规范的版本；例如，`'CGI/1.1'`。
'SERVER_ADDR'
  当前运行脚本所在的服务器的 IP 地址。
'SERVER_NAME'
  当前运行脚本所在的服务器的主机名。如果脚本运行于虚拟主机中，该名称是由那个虚拟主机所设置的值决定。

  > 注意: 在 Apache 2 里，必须设置 `UseCanonicalName = On` 和 `ServerName`。否则该值会由客户端提供，就有可能被伪造。上下文有安全性要求的环境里，不应该依赖此值。

'SERVER_SOFTWARE'
  服务器标识字符串，在响应请求时的头信息中给出。
'SERVER_PROTOCOL'
  请求页面时通信协议的名称和版本。例如，`'HTTP/1.0'`。
'REQUEST_METHOD'
  访问页面使用的请求方法；例如，`'GET'`、`'HEAD'`、`'POST'`、`'PUT'`。

  > 注意:

  > 如果请求方法为 `HEAD`，PHP 脚本将在发送 Header 头信息之后终止(这意味着在产生任何输出后，不再有输出缓冲)。

'REQUEST_TIME'
  PHP 开始处理请求时的时间戳。
'REQUEST_TIME_FLOAT'
  PHP 开始处理请求时的时间戳，具有微秒精度。
'QUERY_STRING'
  query string（查询字符串），如果有的话，通过它进行页面访问。
'DOCUMENT_ROOT'
  当前运行脚本所在的文档根目录。在服务器配置文件中定义。
'HTTPS'
  如果脚本是通过 HTTPS 协议被访问，则被设为一个非空的值。
'REMOTE_ADDR'
  浏览当前页面的用户的 IP 地址。
'REMOTE_HOST'
  浏览当前页面的用户的主机名。DNS 反向解析不依赖于用户的 REMOTE_ADDR。

  > 注意: 必须配置 Web 服务器以创建这个变量。例如在 Apache 中，`HostnameLookups On` 必须在 httpd.conf 中设置才能存在。参见 gethostbyaddr()。

'REMOTE_PORT'
  用户机器上连接到 Web 服务器所使用的端口号。
'REMOTE_USER'
  经验证的用户
'REDIRECT_REMOTE_USER'
  验证的用户，如果请求已在内部重定向。
'SCRIPT_FILENAME'

  当前执行脚本的绝对路径。

  > 注意:

  > 如果在命令行界面（Command Line Interface, CLI）使用相对路径执行脚本，例如 file.php 或 ../file.php，那么 $_SERVER['SCRIPT_FILENAME'] 将包含用户指定的相对路径。

'SERVER_ADMIN'
  该值指明了 Apache 服务器配置文件中的 SERVER_ADMIN 参数。如果脚本运行在一个虚拟主机上，则该值是那个虚拟主机的值。
'SERVER_PORT'
  Web 服务器使用的端口。默认值为 `'80'`。如果使用 SSL 安全连接，则这个值为用户设置的 HTTP 端口。

  > 注意: 在 Apache 2 里，为了获取真实物理端口，必须设置 `UseCanonicalName = On` 以及 `UseCanonicalPhysicalPort = On`，否则可能伪造此值，不一定会返回真实端口值。 上下文有安全性要求的环境里，不应该依赖此值。

'SERVER_SIGNATURE'
  包含了服务器版本和虚拟主机名的字符串。
'PATH_TRANSLATED'
  当前脚本所在文件系统（非文档根目录）的基本路径。这是在服务器进行虚拟到真实路径的映像后的结果。

  > 注意: Apache 2 用户可以在 httpd.conf 中设置 `AcceptPathInfo = On` 来定义 PATH_INFO。

'SCRIPT_NAME'
  包含当前脚本的路径。这在页面需要指向自己时非常有用。__FILE__ 常量包含当前脚本(例如包含文件)的完整路径和文件名。
'REQUEST_URI'
  URI 用来指定要访问的页面。例如 “`/index.html`”。
'PHP_AUTH_DIGEST'
  当作为 Apache 模块运行时，进行 HTTP Digest 认证的过程中，此变量被设置成客户端发送的“Authorization” HTTP 头内容（以便作进一步的认证操作）。
'PHP_AUTH_USER'
  当 PHP 运行在 Apache 或 IIS（PHP 5 是 ISAPI）模块方式下，并且正在使用 HTTP 认证功能，这个变量便是用户输入的用户名。
'PHP_AUTH_PW'
  当 PHP 运行在 Apache 或 IIS（PHP 5 是 ISAPI）模块方式下，并且正在使用 HTTP 认证功能，这个变量便是用户输入的密码。
'AUTH_TYPE'
  当 PHP 运行在 Apache 模块方式下，并且正在使用 HTTP 认证功能，这个变量便是认证的类型。
'PATH_INFO'
  如果存在的话，包含由客户端提供的、跟在真实脚本名称之后并且在查询字符串之前的路径信息。例如，如果当前脚本是通过 URI http://www.example.com/php/path_info.php/some/stuff?foo=bar 访问，那么 $_SERVER['PATH_INFO'] 将包含 `/some/stuff`。
'ORIG_PATH_INFO'
  在被 PHP 处理之前，“PATH_INFO” 的原始版本。

### 示例

示例 #1 $_SERVER 范例

    <?php
    echo $_SERVER['SERVER_NAME'];
    ?>

以上示例的输出类似于：

    www.example.com

### 注释

> 注意: “Superglobal”也称为自动化的全局变量。这就表示其在脚本的所有作用域中都是可用的。不需要在函数或方法中用 global $variable; 来访问它。

### 参见

- 过滤器扩展

# $_GET

$_GET — 查询字符串变量

### 说明

通过 URL 参数（也称为查询字符串）传递给当前脚本的变量（关联数组）。需要注意的是，只要存在查询字符串，就会填充此数组，无论 HTTP 请求方法为何。

### 示例

示例 #1 $_GET 范例

    <?php
    echo 'Hello ' . htmlspecialchars($_GET["name"]) . '!';
    ?>

假设用户访问的是 `http://example.com/?name=Hannes`。

以上示例的输出类似于：

    Hello Hannes!

### 注释

> 注意: “Superglobal”也称为自动化的全局变量。这就表示其在脚本的所有作用域中都是可用的。不需要在函数或方法中用 global $variable; 来访问它。

> 注意:

> $_GET 中的值会自动通过 urldecode() 解码。

### 参见

- 处理外部变量
- 过滤器扩展

# $_POST

$_POST — 来自 HTTP POST 请求的表单数据

### 说明

当 HTTP POST 请求的 Content-Type 是 `application/x-www-form-urlencoded` 或 `multipart/form-data` 时，会将变量以关联数组形式传入当前脚本。

### 示例

示例 #1 $_POST 范例

    <?php
    echo 'Hello ' . htmlspecialchars($_POST["name"]) . '!';
    ?>

假设用户发送了一个包含 `name=Hannes` 的 POST 请求体。

以上示例的输出类似于：

    Hello Hannes!

### 注释

> 注意: “Superglobal”也称为自动化的全局变量。这就表示其在脚本的所有作用域中都是可用的。不需要在函数或方法中用 global $variable; 来访问它。

> 注意: 读取与其他内容类型一起发送的 POST 数据（例如 `application/json` 或 `application/xml`） 必须使用 php://input。 与仅适用于 `application/x-www-form-urlencoded` 和 `multipart/form-data` 的 $_POST 不同， php://input 提供对请求正文中原始数据的直接访问。

### 参见

- 处理外部变量
- 过滤器扩展

# $_FILES

$_FILES — HTTP 文件上传变量

### 说明

通过 HTTP POST 方式上传到当前脚本的项目的数组。 此数组的概况在 POST 方法上传 章节中有描述。

### 注释

> 注意: “Superglobal”也称为自动化的全局变量。这就表示其在脚本的所有作用域中都是可用的。不需要在函数或方法中用 global $variable; 来访问它。

### 参见

- move_uploaded_file() - 将上传的文件移动到新位置
- 处理文件上传

# $_REQUEST

$_REQUEST — HTTP Request 变量

### 说明

默认情况下包含了 $_GET，$_POST 和 $_COOKIE 的数组。

### 注释

> 注意: “Superglobal”也称为自动化的全局变量。这就表示其在脚本的所有作用域中都是可用的。不需要在函数或方法中用 global $variable; 来访问它。

> 注意:

> 以命令行方式运行时，将不包含 argv 和 argc 信息；它们将存在于 $_SERVER 数组。

> 注意:

> 由于 $_REQUEST 中的变量通过 GET，POST 和 COOKIE 输入机制传递给脚本文件，因此可以被远程用户篡改而并不可信。这个数组的项目及其顺序依赖于 PHP 的 request_order 和 variables_order 指令的配置。

### 参见

- 处理外部变量
- 过滤器扩展

# $_SESSION

$_SESSION — Session 变量

### 说明

当前脚本可用 SESSION 变量的数组。更多关于如何使用的信息，参见 Session 函数 文档。

### 注释

> 注意: “Superglobal”也称为自动化的全局变量。这就表示其在脚本的所有作用域中都是可用的。不需要在函数或方法中用 global $variable; 来访问它。

### 参见

- session_start() - 启动新会话或者重用现有会话

# $_ENV

$_ENV — 环境变量

### 说明

通过环境方式传递给当前脚本的变量的数组。

这些变量被从 PHP 解析器的运行环境导入到 PHP 的全局命名空间。很多是由支持 PHP 运行的 Shell 提供的，并且不同的系统很可能运行着不同种类的 Shell，所以不可能有一份确定的列表。请查看你的 Shell 文档来获取定义的环境变量列表。

其他环境变量包含了 CGI 变量，而不管 PHP 是以服务器模块还是 CGI 处理器的方式运行。

### 示例

示例 #1 $_ENV 范例

    <?php
    echo 'My username is ' .$_ENV["USER"] . '!';
    ?>

假设 "bjori" 运行此段脚本

以上示例的输出类似于：

    My username is bjori!

### 注释

> 注意: “Superglobal”也称为自动化的全局变量。这就表示其在脚本的所有作用域中都是可用的。不需要在函数或方法中用 global $variable; 来访问它。

### 参见

- getenv() - 获取单个或者全部环境变量
- 过滤器扩展

# $_COOKIE

$_COOKIE — HTTP Cookies

### 说明

通过 HTTP Cookies 方式传递给当前脚本的变量的数组。

### 示例

示例 #1 $_COOKIE 范例

    <?php
    echo 'Hello ' . htmlspecialchars($_COOKIE["name"]) . '!';
    ?>

假设之前发送了 "name" Cookie

以上示例的输出类似于：

    Hello Hannes!

### 注释

> 注意: “Superglobal”也称为自动化的全局变量。这就表示其在脚本的所有作用域中都是可用的。不需要在函数或方法中用 global $variable; 来访问它。

### 参见

- setcookie() - 发送 Cookie
- 处理外部变量
- 过滤器扩展

# $php_errormsg

$php_errormsg — 前一个错误信息

警告

本特性自 PHP 7.2.0 起废弃，并且自 PHP 8.0.0 起被移除。 强烈建议不要使用本特性。

用 error_get_last() 函数代替。

### 说明

$php_errormsg 变量包含由 PHP 生成的最新错误信息。这个变量只在错误发生的作用域内可用，并且要求 track_errors 配置项是开启的（默认是关闭的）。

警告

如果用户定义了错误处理句柄（set_error_handler()）并且返回 `false` 的时候，$php_errormsg 就会被设置。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 可使 $php_errormsg 可用的 track_errors 指令已被删除。
7.2.0 | 可使 $php_errormsg 可用的 track_errors 指令已被弃用。

### 示例

示例 #1 $php_errormsg 范例

    <?php
    @strpos();
    echo $php_errormsg;
    ?>

以上示例的输出类似于：

    Wrong parameter count for strpos()

### 参见

- error_get_last() - 获取最后发生的错误

# $http_response_header

$http_response_header — HTTP 响应头

警告

此功能自 PHP 8.5.0 起弃用。强烈建议不要应用此功能。

使用 http_get_last_response_headers() 代替。

### 说明

$http_response_header 数组与 get_headers() 函数类似。当使用HTTP 包装器时，$http_response_header 将会被 HTTP 响应头信息填充。$http_response_header 将被创建于局部作用域中。

### 示例

示例 #1 $http_response_header 范例

    <?php
    function get_contents() {
      file_get_contents("http://example.com");
      var_dump($http_response_header); // 变量在本地作用域中填充
    }
    get_contents();
    var_dump($http_response_header); // 调用 get_contents() 不会在函数作用域之外填充变量
    ?>

以上示例的输出类似于：

    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

### 参见

- http_get_last_response_headers() - Retrieve last HTTP response headers
- http_clear_last_response_headers() - Clears the stored HTTP response headers

# $argc

$argc — 传递给脚本的参数数目

### 说明

包含当运行于命令行下时传递给当前脚本的参数的数目。

> 注意: 脚本的文件名总是作为参数传递给当前脚本，因此 $argc 的最小值为 `1`。

> 注意: 这个变量仅在 register_argc_argv 打开时可用。

### 示例

示例 #1 $argc 范例

    <?php
    var_dump($argc);
    ?>

当使用这个命令执行: php script.php arg1 arg2 arg3

以上示例的输出类似于：

    int(4)

### 注释

> 注意:

> 也可以在 $_SERVER['argc'] 中获取。

### 参见

- getopt() - 从命令行参数列表中获取选项
- $argv

# $argv

$argv — 传递给脚本的参数数组

### 说明

包含当运行于命令行下时传递给当前脚本的参数的数组。

> 注意: 第一个参数总是当前脚本的文件名，因此 $argv[0] 就是脚本文件名。

> 注意: 这个变量仅在 register_argc_argv 打开时可用。

警告

要测试脚本是否从命令行运行，应使用 php_sapi_name()，而不是检查是否设置了 $argv 或 $_SERVER['argv']。

### 示例

示例 #1 $argv 示例

    <?php
    var_dump($argv);
    ?>

当使用这个命令执行：php script.php arg1 arg2 arg3

以上示例的输出类似于：

    array(4) {
      [0]=>
      string(10) "script.php"
      [1]=>
      string(4) "arg1"
      [2]=>
      string(4) "arg2"
      [3]=>
      string(4) "arg3"
    }

### 注释

> 注意:

> 也可以在 $_SERVER['argv'] 中获取。

### 参见

- getopt() - 从命令行参数列表中获取选项
- $argc

## 目录

- 超全局变量 — 在全部作用域中始终可用的内置变量
- $GLOBALS — 引用全局作用域中可用的全部变量
- $_SERVER — 服务器和执行环境信息
- $_GET — 查询字符串变量
- $_POST — 来自 HTTP POST 请求的表单数据
- $_FILES — HTTP 文件上传变量
- $_REQUEST — HTTP Request 变量
- $_SESSION — Session 变量
- $_ENV — 环境变量
- $_COOKIE — HTTP Cookies
- $php_errormsg — 前一个错误信息
- $http_response_header — HTTP 响应头
- $argc — 传递给脚本的参数数目
- $argv — 传递给脚本的参数数组

# 预定义异常

## 目录

- Exception
- ErrorException
- ClosedGeneratorException
- Error
- ArgumentCountError
- ArithmeticError
- AssertionError
- DivisionByZeroError
- CompileError
- ParseError
- TypeError
- ValueError
- UnhandledMatchError
- FiberError
- RequestParseBodyException

参见 SPL 异常处理。

# Exception

(PHP 5, PHP 7, PHP 8)

## 简介

Exception是所有用户级异常的基类。

## 类摘要

class Exception implements Throwable {
/* 属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 方法 */
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
}

## 属性

message

  异常消息内容

code

  异常代码

file

  抛出异常的文件名

line

  抛出异常在该文件中的行号

previous

  之前抛出的异常

string

  字符串形式的堆栈跟踪

trace

  数组形式的堆栈跟踪

# Exception::__construct

(PHP 5, PHP 7, PHP 8)

Exception::__construct — 异常构造函数

### 说明

public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)

异常构造函数。

### 参数

`message`

  抛出的异常消息内容。

`code`

  异常代码。

`previous`

  异常链中的前一个异常。

> 注意: 如果子类的 $code 和 $message 属性已设置，在调用 Exception 父类的构造器时可以省略默认参数。

### 注释

> 注意:

> `message` 不是二进制安全的。

# Exception::getMessage

(PHP 5, PHP 7, PHP 8)

Exception::getMessage — 获取异常消息内容

### 说明

final public function Exception::getMessage(): string

返回异常消息内容。

### 参数

此函数没有参数。

### 返回值

返回字符串类型的异常消息内容。

### 示例

示例 #1 Exception::getMessage()示例

    <?php
    try {
        throw new Exception("Some error message");
    } catch(Exception $e) {
        echo $e->getMessage();
    }
    ?>

以上示例的输出类似于：

    Some error message

### 参见

- Throwable::getMessage() - 获取信息

# Exception::getPrevious

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Exception::getPrevious — 返回前一个 Throwable

### 说明

final public function Exception::getPrevious(): ?Throwable

返回前一个 Throwable （传递给 Exception::__construct()方法的第三个参数）。

### 参数

此函数没有参数。

### 返回值

返回异常链中的前一个异常 Throwable，否则返回`null`。

### 示例

示例 #1 Exception::getPrevious()示例

追踪异常，并循环打印。

    <?php
    class MyCustomException extends Exception {}

    function doStuff() {
        try {
            throw new InvalidArgumentException("You are doing it wrong!", 112);
        } catch(Exception $e) {
            throw new MyCustomException("Something happend", 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());
    }
    ?>

以上示例的输出类似于：

    /home/bjori/ex.php:8 Something happend (911) [MyCustomException]
    /home/bjori/ex.php:6 You are doing it wrong! (112) [InvalidArgumentException]

### 参见

- Throwable::getPrevious() - 返回先前的 Throwable

# Exception::getCode

(PHP 5, PHP 7, PHP 8)

Exception::getCode — 获取异常代码

### 说明

final public function Exception::getCode(): int

返回异常代码。

### 参数

此函数没有参数。

### 返回值

Exception 返回整型（int）的异常代码，但在其他类中可能返回其他类型(比如在 PDOException 中返回 string)。

### 示例

示例 #1 Exception::getCode()示例

    <?php
    try {
        throw new Exception("Some error message", 30);
    } catch(Exception $e) {
        echo "The exception code is: " . $e->getCode();
    }
    ?>

以上示例的输出类似于：

    The exception code is: 30

### 参见

- Throwable::getCode() - 获取异常代码

# Exception::getFile

(PHP 5, PHP 7, PHP 8)

Exception::getFile — 创建异常时的程序文件名称

### 说明

final public function Exception::getFile(): string

获取创建异常的程序文件名称。

### 参数

此函数没有参数。

### 返回值

返回发生异常的程序文件名称。

### 示例

示例 #1 Exception::getFile()示例

    <?php
    try {
        throw new Exception;
    } catch(Exception $e) {
        echo $e->getFile();
    }
    ?>

以上示例的输出类似于：

    /home/bjori/tmp/ex.php

### 参见

- Throwable::getFile() - 获取创建对象的文件

# Exception::getLine

(PHP 5, PHP 7, PHP 8)

Exception::getLine — 获取创建的异常所在文件中的行号

### 说明

final public function Exception::getLine(): int

返回发生异常的代码在文件中的行号。

### 参数

此函数没有参数。

### 返回值

返回发生异常的代码在文件中的行号。

### 示例

示例 #1 Exception::getLine()示例

    <?php
    try {
        throw new Exception("Some error message");
    } catch(Exception $e) {
        echo "The exception was thrown on line: " . $e->getLine();
    }
    ?>

以上示例的输出类似于：

    The exception was thrown on line: 3

### 参见

- Throwable::getLine() - 获取初始化对象时候的行号

# Exception::getTrace

(PHP 5, PHP 7, PHP 8)

Exception::getTrace — 获取异常追踪信息

### 说明

final public function Exception::getTrace(): array

返回异常追踪信息。

### 参数

此函数没有参数。

### 返回值

返回包含异常追踪信息的数组（array）。

### 示例

示例 #1 Exception::getTrace()示例

    <?php
    function test() {
     throw new Exception;
    }

    try {
     test();
    } catch(Exception $e) {
     var_dump($e->getTrace());
    }
    ?>

以上示例的输出类似于：

    array(1) {
      [0]=>
      array(4) {
        ["file"]=>
        string(22) "/home/bjori/tmp/ex.php"
        ["line"]=>
        int(7)
        ["function"]=>
        string(4) "test"
        ["args"]=>
        array(0) {
        }
      }
    }

### 参见

- Throwable::getTrace() - 获取堆栈踪迹（Stack Trace）

# Exception::getTraceAsString

(PHP 5, PHP 7, PHP 8)

Exception::getTraceAsString — 获取字符串类型的异常追踪信息

### 说明

final public function Exception::getTraceAsString(): string

以字符串类型返回异常追踪信息。

### 参数

此函数没有参数。

### 返回值

以字符串类型返回异常追踪信息。

### 示例

示例 #1 Exception::getTraceAsString()示例

    <?php
    function test() {
        throw new Exception;
    }

    try {
        test();
    } catch(Exception $e) {
        echo $e->getTraceAsString();
    }
    ?>

以上示例的输出类似于：

    #0 /home/bjori/tmp/ex.php(7): test()
    #1 {main}

### 参见

- Throwable::getTraceAsString() - 以 string 形式获取堆栈踪迹

# Exception::__toString

(PHP 5, PHP 7, PHP 8)

Exception::__toString — 将异常对象转换为字符串

### 说明

public function Exception::__toString(): string

返回转换为字符串（string）类型的异常。

### 参数

此函数没有参数。

### 返回值

返回转换为字符串（string）类型的异常。

### 示例

示例 #1 Exception::__toString()示例

    <?php
    try {
        throw new Exception("Some error message");
    } catch(Exception $e) {
        echo $e;
    }
    ?>

以上示例的输出类似于：

    exception 'Exception' with message 'Some error message' in /home/bjori/tmp/ex.php:3
    Stack trace:
    #0 {main}

### 参见

- Throwable::__toString() - 获取 Throwable 对象 string 形式的表达

# Exception::__clone

(PHP 5, PHP 7, PHP 8)

Exception::__clone — 异常克隆

### 说明

private function Exception::__clone(): void

Exceptions 不能被克隆， 这将抛出一个 Error。

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 错误／异常

异常被不允许克隆。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | Exception::__clone() 不再是 final 的。

## 目录

- Exception::__construct — 异常构造函数
- Exception::getMessage — 获取异常消息内容
- Exception::getPrevious — 返回前一个 Throwable
- Exception::getCode — 获取异常代码
- Exception::getFile — 创建异常时的程序文件名称
- Exception::getLine — 获取创建的异常所在文件中的行号
- Exception::getTrace — 获取异常追踪信息
- Exception::getTraceAsString — 获取字符串类型的异常追踪信息
- Exception::__toString — 将异常对象转换为字符串
- Exception::__clone — 异常克隆

# ErrorException

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## 简介

错误异常。

## 类摘要

class ErrorException extends Exception {
/* 属性 */
protected int $severity = E_ERROR;
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 方法 */
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
/* 继承的方法 */
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
}

## 属性

severity

  异常级别

## 示例

示例 #1 使用 set_error_handler() 函数将错误信息托管至 ErrorException

    <?php

    set_error_handler(function (int $errno, string $errstr, string $errfile, int $errline) {
        if (!(error_reporting() & $errno)) {
            // 这个错误代码未包含在 error_reporting 中。
            return;
        }

        if ($errno === E_DEPRECATED || $errno === E_USER_DEPRECATED) {
            // 因为新的或意外的弃用会破坏应用程序，
            // 不要因弃用 warning 而抛出 Exception。
            return;
        }

        throw new \ErrorException($errstr, 0, $errno, $errfile, $errline);
    });

    // 反序列化已损坏的数据会触发 warning，
    // 错误处理程序会将其转换为 ErrorException。
    unserialize('broken data');

    ?>

以上示例的输出类似于：

    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 — 构造一个异常（Exception）

### 说明

public function ErrorException::__construct(
string `$message` = "",
int `$code` = 0,
int `$severity` = `E_ERROR`,
?string `$filename` = `null`,
?int `$line` = `null`,
?Throwable `$previous` = `null`
)

构造一个异常（Exception）。

### 参数

`message`

  抛出的异常消息内容。

`code`

  异常代码。

`severity`

  异常的严重级别。

  > 注意:

  > severity 可以是任意 int 值，即错误常量里面的值。

`filename`

  抛出异常所在的文件名。

`line`

  抛出异常所在的行号。

`previous`

  异常链中的前一个异常。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `filename` 和 `line` 可以为空。 之前，它们的默认值分别是 `__FILE__` 和 `__LINE__` 。

# ErrorException::getSeverity

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ErrorException::getSeverity — 获取异常的严重程度

### 说明

final public function ErrorException::getSeverity(): int

返回异常的严重程度。

### 参数

此函数没有参数。

### 返回值

返回异常的严重级别。

### 示例

示例 #1 ErrorException::getSeverity() 例子

    <?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);
    }
    ?>

以上示例的输出类似于：

    This exception severity is: 256
    bool(true)

## 目录

- ErrorException::__construct — 构造一个异常（Exception）
- ErrorException::getSeverity — 获取异常的严重程度

# ClosedGeneratorException 类

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## 简介

当尝试从已关闭的 Generator 中检索值时，会引发 ClosedGeneratorException。

## 类摘要

class ClosedGeneratorException extends Exception {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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)

## 简介

Error 是所有PHP内部错误类的基类。

## 类摘要

class Error implements Throwable {
/* 属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 方法 */
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
}

## 属性

message

  错误消息内容

code

  错误代码

file

  抛出错误的文件名

line

  抛出错误的行数

previous

  之前抛出的异常

string

  字符串形式的堆栈跟踪

trace

  数组形式的堆栈跟踪

# Error::__construct

(PHP 7, PHP 8)

Error::__construct — 初始化 error 对象

### 说明

public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)

初始化 Error。

### 参数

`message`

  错误信息。

`code`

  错误代码。

`previous`

  先前的 throwable，用于异常链。

### 注释

> 注意:

> `message` 不是二进制安全的。

# Error::getMessage

(PHP 7, PHP 8)

Error::getMessage — 获取错误信息

### 说明

final public function Error::getMessage(): string

返回错误信息。

### 参数

此函数没有参数。

### 返回值

返回字符串错误信息。

### 示例

示例 #1 Error::getMessage() 例子

    <?php
    try {
        throw new Error("Some error message");
    } catch(Error $e) {
        echo $e->getMessage();
    }
    ?>

以上示例的输出类似于：

    Some error message

### 参见

- Throwable::getMessage() - 获取信息

# Error::getPrevious

(PHP 7, PHP 8)

Error::getPrevious — 返回先前的 Throwable

### 说明

final public function Error::getPrevious(): ?Throwable

返回先前的 Throwable（Error::__construct() 的第三个参数）。

### 参数

此函数没有参数。

### 返回值

如果有的话，返回先前的 Throwable，否则返回 `null` 。

### 示例

示例 #1 Error::getPrevious() 例子

循环输出错误栈。

    <?php
    class MyCustomError extends Error {}

    function doStuff() {
        try {
            throw new InvalidArgumentError("You are doing it wrong!", 112);
        } catch(Error $e) {
            throw new MyCustomError("Something happened", 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());
    }
    ?>

以上示例的输出类似于：

    /home/bjori/ex.php:8 Something happened (911) [MyCustomError]
    /home/bjori/ex.php:6 You are doing it wrong! (112) [InvalidArgumentError]

### 参见

- Throwable::getPrevious() - 返回先前的 Throwable

# Error::getCode

(PHP 7, PHP 8)

Error::getCode — 获取错误代码

### 说明

final public function Error::getCode(): int

返回错误代码。

### 参数

此函数没有参数。

### 返回值

返回 int 的错误代码

### 示例

示例 #1 Error::getCode() 例子

    <?php
    try {
        throw new Error("Some error message", 30);
    } catch(Error $e) {
        echo "The Error code is: " . $e->getCode();
    }
    ?>

以上示例的输出类似于：

    The Error code is: 30

### 参见

- Throwable::getCode() - 获取异常代码

# Error::getFile

(PHP 7, PHP 8)

Error::getFile — 获取错误发生时的文件

### 说明

final public function Error::getFile(): string

获取错误发生时的文件名称。

### 参数

此函数没有参数。

### 返回值

返回错误发生时的文件名。

### 示例

示例 #1 Error::getFile() 例子

    <?php
    try {
        throw new Error;
    } catch(Error $e) {
        echo $e->getFile();
    }
    ?>

以上示例的输出类似于：

    /home/bjori/tmp/ex.php

### 参见

- Throwable::getFile() - 获取创建对象的文件

# Error::getLine

(PHP 7, PHP 8)

Error::getLine — 获取错误发生时的行号

### 说明

final public function Error::getLine(): int

获取错误发生时的行号。

### 参数

此函数没有参数。

### 返回值

返回错误发生时的行号。

### 示例

示例 #1 Error::getLine() 例子

    <?php
    try {
        throw new Error("Some error message");
    } catch(Error $e) {
        echo "The error was created on line: " . $e->getLine();
    }
    ?>

以上示例的输出类似于：

    The error was created on line: 3

### 参见

- Throwable::getLine() - 获取初始化对象时候的行号

# Error::getTrace

(PHP 7, PHP 8)

Error::getTrace — 获取调用栈（stack trace）

### 说明

final public function Error::getTrace(): array

返回 stack trace。

### 参数

此函数没有参数。

### 返回值

返回 array 的 stack trace。

### 示例

示例 #1 Error::getTrace() 例子

    <?php
    function test() {
     throw new Error;
    }

    try {
     test();
    } catch(Error $e) {
     var_dump($e->getTrace());
    }
    ?>

以上示例的输出类似于：

    array(1) {
      [0]=>
      array(4) {
        ["file"]=>
        string(22) "/home/bjori/tmp/ex.php"
        ["line"]=>
        int(7)
        ["function"]=>
        string(4) "test"
        ["args"]=>
        array(0) {
        }
      }
    }

### 参见

- Throwable::getTrace() - 获取堆栈踪迹（Stack Trace）

# Error::getTraceAsString

(PHP 7, PHP 8)

Error::getTraceAsString — 获取字符串形式的调用栈（stack trace）

### 说明

final public function Error::getTraceAsString(): string

以字符串形式返回 stack trace。

### 参数

此函数没有参数。

### 返回值

以字符串形式返回 stack trace。

### 示例

示例 #1 Error::getTraceAsString() 例子

    <?php
    function test() {
        throw new Error;
    }

    try {
        test();
    } catch(Error $e) {
        echo $e->getTraceAsString();
    }
    ?>

以上示例的输出类似于：

    #0 /home/bjori/tmp/ex.php(7): test()
    #1 {main}

### 参见

- Throwable::getTraceAsString() - 以 string 形式获取堆栈踪迹

# Error::__toString

(PHP 7, PHP 8)

Error::__toString — error 的字符串表达

### 说明

public function Error::__toString(): string

返回 Error 的 string表达形式。

### 参数

此函数没有参数。

### 返回值

返回 Error 的 string表达形式。

### 示例

示例 #1 Error::__toString() 例子

    <?php
    try {
        throw new Error("Some error message");
    } catch(Error $e) {
        echo $e;
    }
    ?>

以上示例的输出类似于：

    Error: Some error message in /home/bjori/tmp/ex.php:3
    Stack trace:
    #0 {main}

### 参见

- Throwable::__toString() - 获取 Throwable 对象 string 形式的表达

# Error::__clone

(PHP 7, PHP 8)

Error::__clone — 克隆 error

### 说明

private function Error::__clone(): void

Error 无法被克隆，调用该方法会导致 fatal error。

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 错误／异常

Error 无法被克隆。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | Error::__clone() 不再是 final 的。

## 目录

- Error::__construct — 初始化 error 对象
- Error::getMessage — 获取错误信息
- Error::getPrevious — 返回先前的 Throwable
- Error::getCode — 获取错误代码
- Error::getFile — 获取错误发生时的文件
- Error::getLine — 获取错误发生时的行号
- Error::getTrace — 获取调用栈（stack trace）
- Error::getTraceAsString — 获取字符串形式的调用栈（stack trace）
- Error::__toString — error 的字符串表达
- Error::__clone — 克隆 error

# ArgumentCountError

(PHP 7 >= PHP 7.1.0, PHP 8)

## 简介

ArgumentCountError 当传递给用户定义的函数或方法的参数太少时被抛出。

当传递到非可变内置函数的参数太多时，也会抛出此错误。

## 类摘要

class ArgumentCountError extends TypeError {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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)

## 简介

当执行数学运算发生错误时抛出 ArithmeticError 。 这些错误包括尝试执行负数的位移，以及对任何可能会导致值超出 int 的范围 intdiv() 调用。

## 类摘要

class ArithmeticError extends Error {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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)

## 简介

AssertionError 在函数 assert() 断言失败时被抛出。

## 类摘要

class AssertionError extends Error {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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)

## 简介

DivisionByZeroError 当除数为零时被抛出。

## 类摘要

class DivisionByZeroError extends ArithmeticError {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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)

## 简介

CompileError 是针对一些编译错误抛出的，之前是会发出致命错误。

## 类摘要

class CompileError extends Error {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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)

## 简介

ParseError 当解析 PHP 代码时发生错误时抛出，比如当 eval()被调用出错时。

> 注意: 从 PHP 7.3.0 开始，ParseError 继承自 CompileError。之前的版本，则继承自 Error。

## 类摘要

class ParseError extends CompileError {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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)

## 简介

会抛出TypeError 的情况:

- 为类属性设置的值与该属性申明的类型不匹配。
- 传递给函数的参数类型与函数预期声明的参数类型不匹配。
- 函数返回的值与声明的函数返回类型不匹配

## 类摘要

class TypeError extends Error {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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
}

## 更新日志

版本 | 说明
--- | ---
7.1.0 | 在严格模式下，传递给内置 PHP 函数的参数数量不正确时，不再抛出通用的 TypeError。 相反，会抛出更具体的 ArgumentCountError，它是 TypeError 的子类。

# ValueError

(PHP 8)

## 简介

当参数类型正确但是值不正确的时候会抛出 ValueError。 例如，当函数期望是正整数时传递负整数， 或者当函数期望它不为空时传递空字符串/数组。

## 类摘要

class ValueError extends Error {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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)

## 简介

当传递给 match 表达式的主体未被 match 表达式的任何分支处理时， 将会抛出 UnhandledMatchError。

## 类摘要

class UnhandledMatchError extends Error {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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)

## 简介

当在 Fiber 上执行无效操作时，会抛出 FiberError。

## 类摘要

final class FiberError extends Error {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 方法 */
public function __construct()
/* 继承的方法 */
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 — 不允许直接实例化的构造函数

### 说明

public function FiberError::__construct()

### 参数

此函数没有参数。

### 错误／异常

当调用时抛出 Error 异常。

## 目录

- FiberError::__construct — 不允许直接实例化的构造函数

# RequestParseBodyException

(PHP 8 >= 8.4.0)

## 简介

当请求体根据 `Content-Type` 头无效时，request_parse_body() 中会抛出 RequestParseBodyException。

## 类摘要

class RequestParseBodyException extends Exception {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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
}

# 预定义接口和类

## 目录

- Traversable
- Iterator
- IteratorAggregate
- InternalIterator
- Throwable
- Countable
- ArrayAccess
- Serializable
- Closure
- stdClass
- Generator
- Fiber
- WeakReference
- WeakMap
- Stringable
- UnitEnum
- BackedEnum
- SensitiveParameterValue
- __PHP_Incomplete_Class

参见 SPL 接口 和 预定义类。

# Traversable （遍历）接口

(PHP 5, PHP 7, PHP 8)

## 简介

检测一个类是否可以使用 `foreach` 进行遍历的接口。

无法被单独实现的基本抽象接口。相反，它必须由 IteratorAggregate 或 Iterator 接口实现。

## 接口摘要

interface Traversable {
}

这个接口没有任何方法，它的作用仅仅是作为所有可遍历类的基本接口。

## 更新日志

版本 | 说明
--- | ---
7.4.0 | Traversable 接口现在可以由抽象类实现。继承的类必须实现 Iterator 或 IteratorAggregate。

## 注释

> 注意:

> 实现此接口的内置类可以使用 `foreach` 进行遍历而无需实现 IteratorAggregate 或 Iterator 接口。

> 注意:

> 在 PHP 7.4.0 之前，这个内部引擎接口无法在 PHP 脚本中实现。必须改用 IteratorAggregate 或 Iterator。

# Iterator（迭代器）接口

(PHP 5, PHP 7, PHP 8)

## 简介

可在内部迭代自己的外部迭代器或类的接口。

## 接口摘要

interface Iterator extends Traversable {
/* 方法 */
public function current(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function valid(): bool
}

## 预定义迭代器

PHP 已经提供了一些用于日常任务的迭代器。 详细列表参见 SPL 迭代器。

## 示例

示例 #1 基本用法

这个例子展示了使用 `foreach` 时，迭代器方法的调用顺序。

    <?php
    class myIterator implements Iterator {
        private $position = 0;
        private $array = array(
            "firstelement",
            "secondelement",
            "lastelement",
        );

        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 myIterator;

    foreach($it as $key => $value) {
        var_dump($key, $value);
        echo "\n";
    }
    ?>

以上示例的输出类似于：

    string(18) "myIterator::rewind"
    string(17) "myIterator::valid"
    string(19) "myIterator::current"
    string(15) "myIterator::key"
    int(0)
    string(12) "firstelement"

    string(16) "myIterator::next"
    string(17) "myIterator::valid"
    string(19) "myIterator::current"
    string(15) "myIterator::key"
    int(1)
    string(13) "secondelement"

    string(16) "myIterator::next"
    string(17) "myIterator::valid"
    string(19) "myIterator::current"
    string(15) "myIterator::key"
    int(2)
    string(11) "lastelement"

    string(16) "myIterator::next"
    string(17) "myIterator::valid"

## 参见

参见 遍历对象。

# Iterator::current

(PHP 5, PHP 7, PHP 8)

Iterator::current — 返回当前元素

### 说明

public function Iterator::current(): mixed

返回当前元素。

### 参数

此函数没有参数。

### 返回值

可返回任何类型。

# Iterator::key

(PHP 5, PHP 7, PHP 8)

Iterator::key — 返回当前元素的键

### 说明

public function Iterator::key(): mixed

返回当前元素的键。

### 参数

此函数没有参数。

### 返回值

成功返回标量，失败则返回 `null`。

### 错误／异常

失败时分发 `E_NOTICE` 级错误。

# Iterator::next

(PHP 5, PHP 7, PHP 8)

Iterator::next — 向前移动到下一个元素

### 说明

public function Iterator::next(): void

移动当前位置到下一个元素。

> 注意:

> 此方法在 `foreach` 循环之后被调用。

### 参数

此函数没有参数。

### 返回值

任何返回都将被忽略。

# Iterator::rewind

(PHP 5, PHP 7, PHP 8)

Iterator::rewind — 返回到迭代器的第一个元素

### 说明

public function Iterator::rewind(): void

返回到迭代器的第一个元素。

> 注意:

> 当开始一个 `foreach` 循环时，这是第一个被调用的方法。它将不会在 `foreach` 循环之后被调用。

### 参数

此函数没有参数。

### 返回值

任何返回都将被忽略。

# Iterator::valid

(PHP 5, PHP 7, PHP 8)

Iterator::valid — 检查当前位置是否有效

### 说明

public function Iterator::valid(): bool

此方法在 Iterator::rewind() 和 Iterator::next() 方法之后被调用以此用来检查当前位置是否有效。

### 参数

此函数没有参数。

### 返回值

返回将被转换为bool 。成功时返回 `true`， 或者在失败时返回 `false`。

## 目录

- Iterator::current — 返回当前元素
- Iterator::key — 返回当前元素的键
- Iterator::next — 向前移动到下一个元素
- Iterator::rewind — 返回到迭代器的第一个元素
- Iterator::valid — 检查当前位置是否有效

# IteratorAggregate（聚合式迭代器）接口

(PHP 5, PHP 7, PHP 8)

## 简介

创建外部迭代器的接口。

## 接口摘要

interface IteratorAggregate extends Traversable {
/* 方法 */
public function getIterator(): Traversable
}

## 示例

示例 #1 基本用法

    <?php

    class myData implements IteratorAggregate
    {
        public $property1 = "Public property one";
        public $property2 = "Public property two";
        public $property3 = "Public property three";
        public $property4 = "";

        public function __construct()
        {
            $this->property4 = "last property";
        }

        public function getIterator(): Traversable
        {
            return new ArrayIterator($this);
        }
    }

    $obj = new myData();

    foreach ($obj as $key => $value) {
        var_dump($key, $value);
        echo "\n";
    }

    ?>

以上示例的输出类似于：

    string(9) "property1"
    string(19) "Public property one"

    string(9) "property2"
    string(19) "Public property two"

    string(9) "property3"
    string(21) "Public property three"

    string(9) "property4"
    string(13) "last property"

# IteratorAggregate::getIterator

(PHP 5, PHP 7, PHP 8)

IteratorAggregate::getIterator — 获取一个外部迭代器或可遍历对象

### 说明

public function IteratorAggregate::getIterator(): Traversable

返回一个外部迭代器或可遍历对象。

### 参数

此函数没有参数。

### 返回值

实现了 Iterator 或 Traversable 接口的类的一个实例。

### 错误／异常

失败时抛出 Exception。

## 目录

- IteratorAggregate::getIterator — 获取一个外部迭代器或可遍历对象

# InternalIterator 类

(PHP 8)

## 简介

用于简化内部类实现 IteratorAggregate 的类。

## 类摘要

final class InternalIterator implements Iterator {
/* 方法 */
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 — 禁止直接实例化私有构造方法

### 说明

private function InternalIterator::__construct()

### 参数

此函数没有参数。

# InternalIterator::current

(PHP 8)

InternalIterator::current — 返回当前元素

### 说明

public function InternalIterator::current(): mixed

返回当前元素。

### 参数

此函数没有参数。

### 返回值

返回当前元素。

# InternalIterator::key

(PHP 8)

InternalIterator::key — 返回当前元素的键

### 说明

public function InternalIterator::key(): mixed

返回当前元素的键。

### 参数

此函数没有参数。

### 返回值

返回当前元素的键。

# InternalIterator::next

(PHP 8)

InternalIterator::next — 向前移动到下一个元素

### 说明

public function InternalIterator::next(): void

移动当前位置到下一个元素。

### 参数

此函数没有参数。

### 返回值

没有返回值。

# InternalIterator::rewind

(PHP 8)

InternalIterator::rewind — 迭代器返回到第一个元素

### 说明

public function InternalIterator::rewind(): void

迭代器返回到第一个元素。

### 参数

此函数没有参数。

### 返回值

没有返回值。

# InternalIterator::valid

(PHP 8)

InternalIterator::valid — 检测当前位置是否有效

### 说明

public function InternalIterator::valid(): bool

检测当前位置是否有效。

### 参数

此函数没有参数。

### 返回值

返回当前位置是否有效。

## 目录

- InternalIterator::__construct — 禁止直接实例化私有构造方法
- InternalIterator::current — 返回当前元素
- InternalIterator::key — 返回当前元素的键
- InternalIterator::next — 向前移动到下一个元素
- InternalIterator::rewind — 迭代器返回到第一个元素
- InternalIterator::valid — 检测当前位置是否有效

# Throwable

(PHP 7, PHP 8)

## 简介

Throwable 是能被 `throw` 语句抛出的最基本的接口（interface），包含了 Error 和 Exception 。

> 注意:

> PHP 类无法直接实现 （implement） Throwable 接口，而应当去继承 Exception。

## 接口摘要

interface Throwable extends Stringable {
/* 方法 */
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
/* 继承的方法 */
public function Stringable::__toString(): string
}

## 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 Throwable 实现了 Stringable。

# Throwable::getMessage

(PHP 7, PHP 8)

Throwable::getMessage — 获取信息

### 说明

public function Throwable::getMessage(): string

返回抛出对象所关联的描述信息。

### 参数

此函数没有参数。

### 返回值

返回抛出对象所关联的描述信息。

### 参见

- Exception::getMessage() - 获取异常消息内容

# Throwable::getCode

(PHP 7, PHP 8)

Throwable::getCode — 获取异常代码

### 说明

public function Throwable::getCode(): int

返回 thrown 对象关联的的错误号。

### 参数

此函数没有参数。

### 返回值

返回 Exception 的 int 异常代码， 但如果是 Exception 的子类，可能会使其他类型（例如，PDOException 返回的类型是 string ）。

### 参见

- Exception::getCode() - 获取异常代码

# Throwable::getFile

(PHP 7, PHP 8)

Throwable::getFile — 获取创建对象的文件

### 说明

public function Throwable::getFile(): string

返回对象抛出的文件名称

### 参数

此函数没有参数。

### 返回值

返回对象抛出文件的名称

### 参见

- Exception::getFile() - 创建异常时的程序文件名称

# Throwable::getLine

(PHP 7, PHP 8)

Throwable::getLine — 获取初始化对象时候的行号

### 说明

public function Throwable::getLine(): int

返回初始化 throwable 时的行号。

### 参数

此函数没有参数。

### 返回值

返回初始化 throwable 时的行号。

### 参见

- Exception::getLine() - 获取创建的异常所在文件中的行号

# Throwable::getTrace

(PHP 7, PHP 8)

Throwable::getTrace — 获取堆栈踪迹（Stack Trace）

### 说明

public function Throwable::getTrace(): array

返回 array 的堆栈踪迹（Stack Trace）。

### 参数

此函数没有参数。

### 返回值

返回 array 的堆栈踪迹（Stack Trace），和 debug_backtrace() 具有相同的格式。

### 参见

- Exception::getTrace() - 获取异常追踪信息

# Throwable::getTraceAsString

(PHP 7, PHP 8)

Throwable::getTraceAsString — 以 string 形式获取堆栈踪迹

### 说明

public function Throwable::getTraceAsString(): string

### 参数

此函数没有参数。

### 返回值

返回 string 形式的堆栈踪迹（Stack Trace）。

### 参见

- Exception::getTraceAsString() - 获取字符串类型的异常追踪信息

# Throwable::getPrevious

(PHP 7, PHP 8)

Throwable::getPrevious — 返回先前的 Throwable

### 说明

public function Throwable::getPrevious(): ?Throwable

返回任意一个先前的错误 (例如， Exception::__construct()中提供的第三个参数)。

### 参数

此函数没有参数。

### 返回值

如果有的话，返回先前的 Throwable，否则就返回 `null` 。

### 参见

- Exception::getPrevious() - 返回前一个 Throwable

# Throwable::__toString

(PHP 7, PHP 8)

Throwable::__toString — 获取 Throwable 对象 string 形式的表达

### 说明

public function Throwable::__toString(): string

### 参数

此函数没有参数。

### 返回值

返回抛出对象 string 形式的表达。

### 参见

- Exception::__toString() - 将异常对象转换为字符串

## 目录

- Throwable::getMessage — 获取信息
- Throwable::getCode — 获取异常代码
- Throwable::getFile — 获取创建对象的文件
- Throwable::getLine — 获取初始化对象时候的行号
- Throwable::getTrace — 获取堆栈踪迹（Stack Trace）
- Throwable::getTraceAsString — 以 string 形式获取堆栈踪迹
- Throwable::getPrevious — 返回先前的 Throwable
- Throwable::__toString — 获取 Throwable 对象 string 形式的表达

# Countable 接口

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## 简介

类实现 Countable 可被用于 count() 函数.

## 接口摘要

interface Countable {
/* 方法 */
public function count(): int
}

# Countable::count

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Countable::count — 统计对象的元素个数

### 说明

public function Countable::count(): int

当 count() 的 `value` 是实现 Countable 的对象时，会执行此方法。

### 参数

此函数没有参数。

### 返回值

int 形式的自定义计数。

### 示例

示例 #1 Countable::count() 示例

    <?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 "I have been count()ed " . count($counter) . " times\n";
    }

    ?>

以上示例的输出类似于：

    I have been count()ed 1 times
    I have been count()ed 2 times
    I have been count()ed 3 times
    I have been count()ed 4 times
    I have been count()ed 5 times
    I have been count()ed 6 times
    I have been count()ed 7 times
    I have been count()ed 8 times
    I have been count()ed 9 times
    I have been count()ed 10 times

## 目录

- Countable::count — 统计对象的元素个数

# ArrayAccess（数组式访问）接口

(PHP 5, PHP 7, PHP 8)

## 简介

提供像访问数组一样访问对象的能力的接口。

## 接口摘要

interface ArrayAccess {
/* 方法 */
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
}

## 示例

示例 #1 基础用法

    <?php
    class Obj implements ArrayAccess {
        public $container = [
            "one"   => 1,
            "two"   => 2,
            "three" => 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["two"]));
    var_dump($obj["two"]);
    unset($obj["two"]);
    var_dump(isset($obj["two"]));
    $obj["two"] = "A value";
    var_dump($obj["two"]);
    $obj[] = 'Append 1';
    $obj[] = 'Append 2';
    $obj[] = 'Append 3';
    print_r($obj);
    ?>

以上示例的输出类似于：

    bool(true)
    int(2)
    bool(false)
    string(7) "A value"
    obj Object
    (
        [container:obj:private] => Array
            (
                [one] => 1
                [three] => 3
                [two] => A value
                [0] => Append 1
                [1] => Append 2
                [2] => Append 3
            )

    )

# ArrayAccess::offsetExists

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetExists — 检查一个偏移位置是否存在

### 说明

public function ArrayAccess::offsetExists(mixed `$offset`): bool

检查一个偏移位置是否存在。

对一个实现了 ArrayAccess 接口的对象使用 isset() 或 empty() 时，此方法将执行。

> 注意:

> 当使用 empty() 并且仅当 ArrayAccess::offsetExists() 返回 `true` 时，ArrayAccess::offsetGet() 将被调用以检查是为否空。

### 参数

`offset`

  需要检查的偏移位置。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

> 注意:

> 如果一个非布尔型返回值被返回，将被转换为 bool 。

### 示例

示例 #1 ArrayAccess::offsetExists() 示例

    <?php
    class obj implements ArrayAccess {
        public function offsetSet($offset, $value): 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 "value";
        }
    }

    $obj = new obj;

    echo "Runs obj::offsetExists()\n";
    var_dump(isset($obj["foobar"]));

    echo "\nRuns obj::offsetExists() and obj::offsetGet()\n";
    var_dump(empty($obj["foobar"]));

    echo "\nRuns obj::offsetExists(), *not* obj:offsetGet() as there is nothing to get\n";
    var_dump(empty($obj["foobaz"]));
    ?>

以上示例的输出类似于：

    Runs obj::offsetExists()
    string(17) "obj::offsetExists"
    bool(true)

    Runs obj::offsetExists() and obj::offsetGet()
    string(17) "obj::offsetExists"
    string(14) "obj::offsetGet"
    bool(false)

    Runs obj::offsetExists(), *not* obj:offsetGet() as there is nothing to get
    string(17) "obj::offsetExists"
    bool(true)

# ArrayAccess::offsetGet

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetGet — 获取一个偏移位置的值

### 说明

public function ArrayAccess::offsetGet(mixed `$offset`): mixed

返回指定偏移位置的值。

当检查一个偏移位置是否为 empty() 时，会执行此方法。

### 参数

`offset`

  需要获取的偏移位置。

### 返回值

可返回任何类型。

### 注释

> 注意:

> 此方法的实现可以通过引用返回。 这使得可以间接修改 ArrayAccess 对象，能够重载数组的维度。

> 直接修改是完全替代数组维度的值，例如 `$obj[6] = 7`。 另一方面，间接修改是指仅修改某个维度中的一部分，或者传引用的方式赋值一个维度， 例如 `$obj[6][7] = 7` 和 `$var =& $obj[6]`。 使用 `++` 自增或者使用 `--` 自减也是通过间接修改的方式实现的。

> 直接修改会触发对 ArrayAccess::offsetSet() 的调用，而间接修改则会触发对 ArrayAccess::offsetGet() 的调用。在这种情况下， ArrayAccess::offsetGet() 的实现必须能通过引用返回，否则会引发 `E_NOTICE` 消息。

### 参见

- ArrayAccess::offsetExists() - 检查一个偏移位置是否存在

# ArrayAccess::offsetSet

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetSet — 设置一个偏移位置的值

### 说明

public function ArrayAccess::offsetSet(mixed `$offset`, mixed `$value`): void

为指定的偏移位置设置一个值。

### 参数

`offset`

  待设置的偏移位置。

`value`

  需要设置的值。

### 返回值

没有返回值。

### 注释

> 注意:

> 如果另一个值不可用，那么 `offset` 参数将被设置为 `null`，就像下面的示例。

>     <?php
>     $arrayaccess[] = "first value";
>     $arrayaccess[] = "second value";
>     print_r($arrayaccess);
>     ?>

> 以上示例会输出：

>     Array
>     (
>         [0] => first value
>         [1] => second value
>     )

> 注意:

> 在通过引用赋值以及其它间接更改使用 ArrayAccess 重载的数组维度时，不会调用此函数（间接是指不直接更改维度本身，而是更改子维度或子属性，或者将数组维度通过引用赋值给另一个变量）。而是调用 ArrayAccess::offsetGet()。只有该方法通过引用返回，操作才会成功。

# ArrayAccess::offsetUnset

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetUnset — 复位一个偏移位置的值

### 说明

public function ArrayAccess::offsetUnset(mixed `$offset`): void

复位一个偏移位置的值。

> 注意:

> 当使用 (unset) 进行类型转换时，该方法不会被调用。

### 参数

`offset`

  待复位的偏移位置。

### 返回值

没有返回值。

## 目录

- ArrayAccess::offsetExists — 检查一个偏移位置是否存在
- ArrayAccess::offsetGet — 获取一个偏移位置的值
- ArrayAccess::offsetSet — 设置一个偏移位置的值
- ArrayAccess::offsetUnset — 复位一个偏移位置的值

# Serializable 接口

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## 简介

自定义序列化的接口。

实现此接口的类将不再支持 __sleep() 和 __wakeup() 。 不论何时，只要有实例需要被序列化， serialize 方法都将被调用。它不会调用 __destruct()，除非在该方法中编写了相关功能，否则它也不会有副作用（side effect）。 当数据被反序列化时，类将被感知并且调用合适的 unserialize() 方法而不是调用 __construct()。如果需要执行标准的构造器，应该在这个方法中进行处理。

警告

从 PHP 8.1.0 起，实现 Serializable 接口的类如果没有同时实现 __serialize()、__unserialize() 方法，将产生弃用警告。

## 接口摘要

interface Serializable {
/* 方法 */
public function serialize(): ?string
public function unserialize(string `$data`): void
}

## 示例

示例 #1 基础用法

    <?php
    class obj implements Serializable {
        private $data;
        public function __construct() {
            $this->data = "My private data";
        }
        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());
    ?>

以上示例的输出类似于：

    string(38) "C:3:"obj":23:{s:15:"My private data";}"
    string(15) "My private data"

# Serializable::serialize

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Serializable::serialize — 对象的字符串表示

### 说明

public function Serializable::serialize(): ?string

返回对象的字符串表示。

### 参数

此函数没有参数。

### 返回值

返回对象的字符串表示或者 `null` 。

### 错误／异常

如果返回除了字符串或 `null` 之外的其他类型，将抛出 Exception。

### 参见

- __sleep()
- __serialize()

# Serializable::unserialize

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Serializable::unserialize — 构造对象

### 说明

public function Serializable::unserialize(string `$data`): void

在反序列化对象时被调用。

> 注意:

> 这个方法担当着对象构造器的角色。在此方法之后，__construct() 将不会被调用。

### 参数

`data`

  对象的字符串表示

### 返回值

返回没有序列化之前的原始值。

### 参见

- __wakeup()
- __unserialize()

## 目录

- Serializable::serialize — 对象的字符串表示
- Serializable::unserialize — 构造对象

# Closure 类

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## 简介

用于代表 匿名函数 的类.

匿名函数会产生这种类型的对象。这个类带有一些方法允许在匿名函数创建后对其进行更多的控制。

除了此处列出的方法，还有一个 `__invoke` 方法。这是为了与其他实现了 __invoke()魔术方法 的对象保持一致性，但调用匿名函数的过程与它无关。

## 类摘要

final class Closure {
/* 方法 */
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
}

## 更新日志

版本 | 说明
--- | ---
8.4.0 | 现在 Closure::__debugInfo() 的输出包含 closure 的名称、行数和文件名。

# Closure::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Closure::__construct — 用于禁止实例化的构造函数

### 说明

private function Closure::__construct()

这个方法仅用于禁止实例化一个 Closure 类的对象。这个类的对象的创建方法写在 匿名函数 页。

### 参数

此函数没有参数。

### 参见

- 匿名函数

# Closure::bind

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

Closure::bind — 用特定的绑定对象和类作用域复制闭包。

### 说明

public static function Closure::bind(Closure `$closure`, ?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure

这个方法是 Closure::bindTo() 的静态版本。查看它的文档获取更多信息。

### 参数

`closure`

  需要绑定的匿名函数。

`newThis`

  需要绑定到匿名函数的对象，或者 `null` 创建未绑定的闭包。

`newScope`

  想要绑定给闭包的类作用域，或者 'static' 表示不改变。如果传入一个对象，则使用这个对象的类型名。 类作用域用来决定在闭包中 $this 对象的 私有、保护方法 的可见性。 不允许内置类（的对象）作为参数传递。

### 返回值

返回一个新的 Closure 对象，失败时返回 `null`。

### 示例

示例 #1 Closure::bind() 示例

    <?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";
    ?>

以上示例的输出类似于：

    1
    2

### 参见

- 匿名函数
- Closure::bindTo() - 用特定的绑定对象和类作用域复制闭包。

# Closure::bindTo

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

Closure::bindTo — 用特定的绑定对象和类作用域复制闭包。

### 说明

public function Closure::bindTo(?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure

创建并返回一个 匿名函数， 它与当前对象的函数体相同、绑定了同样变量，但可以绑定不同的对象，也可以绑定新的类作用域。

“绑定的对象”决定了函数体中的 `$this` 的取值，“类作用域”代表一个类型、决定在这个匿名函数中能够调用哪些 private 和 protected 的方法。 也就是说，此时 $this 可以调用的方法，与 `newScope` 类的成员函数是相同的。

静态闭包不能有绑定的对象（ `newThis` 参数的值应该设为 `null`）不过仍然可以用 bindTo 方法来改变它们的类作用域。

此方法确保对于非静态闭包，拥有绑定实例也意味着被限定作用域，反之亦然。 为此，非静态闭包给定一个 `null` 实例的作用域可以使其变为静态， 非静态无作用域的闭包给定一个非 null 的实例作用在一个非指定类。

> 注意:

> 如果你只是想要复制一个匿名函数，可以用 cloning 代替。

### 参数

`newThis`

  绑定给匿名函数的一个对象，或者 `null` 来取消绑定。

`newScope`

  关联到匿名函数的类作用域，或者 'static' 保持当前状态。如果是一个对象，则使用这个对象的类型为新的类作用域。 这会决定绑定的对象的 保护、私有成员 方法的可见性。 不允许内部类（的对象）作为参数传递。

### 返回值

返回新创建的 Closure 对象， 或者失败时返回 `null` 。

### 示例

示例 #1 Closure::bindTo() 实例

    <?php

    class A
    {
        private $val;

        public function __construct($val)
        {
            $this->val = $val;
        }

        public function getClosure()
        {
            // 返回绑定到此对象和作用域的闭包
            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";

    ?>

以上示例的输出类似于：

    1
    2

### 参见

- 匿名函数
- Closure::bind() - 用特定的绑定对象和类作用域复制闭包。

# Closure::call

(PHP 7, PHP 8)

Closure::call — 绑定并调用闭包

### 说明

public function Closure::call(object `$newThis`, mixed `...$args`): mixed

暂时将闭包绑定到 `newThis`，并使用任意给定的参数调用它。

### 参数

`newThis`

  在调用期间将闭包绑定到 object。

`args`

  零个或多个参数，他们将作为参数传递给闭包。

### 返回值

返回闭包的返回值。

### 示例

示例 #1 Closure::call() 示例

    <?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);
    ?>

以上示例会输出：

    int(7)
    int(8)

# Closure::fromCallable

(PHP 7 >= 7.1.0)

Closure::fromCallable — 将 callable 转换为闭包

### 说明

public static function Closure::fromCallable(callable `$callback`): Closure

使用当前范围从给定的 `callback` 创建并返回一个新的 匿名函数。 此方法检查 `callback` 函数在作用域是否可调用， 如果不能，就抛出 TypeError。

> 注意:

> 从 PHP 8.1.0 开始，First-class 可调用语法 的语义与此方法相同。

### 参数

`callback`

  要转换的回调。

### 返回值

返回新创建的 Closure， 或者如果 `callback` 在当前作用域无法调用， 则抛出 TypeError。

### 参见

- 匿名函数
- First-class 可调用语法

## 目录

- Closure::__construct — 用于禁止实例化的构造函数
- Closure::bind — 用特定的绑定对象和类作用域复制闭包。
- Closure::bindTo — 用特定的绑定对象和类作用域复制闭包。
- Closure::call — 绑定并调用闭包
- Closure::fromCallable — 将 callable 转换为闭包

# stdClass 类

(PHP 4, PHP 5, PHP 7, PHP 8)

## 简介

具有动态属性的通用空类。

此类的对象可以使用 new 运算符实例化，也可以通过类型转换为对象创建。几个 PHP 函数也会创建此类的实例，比如 json_decode()、mysqli_fetch_object() 或 PDOStatement::fetchObject()。

尽管没有实现 __get()/__set() 魔术方法，但此类允许动态属性且不需要 `#[\AllowDynamicProperties]` 属性。

这不是 PHP 的基类，因为 PHP 没有通用基类的概念。然而，可以创建继承 stdClass 的自定义类，从而继承动态属性的功能。

## 类摘要

#[\AllowDynamicProperties]
class stdClass {
}

此类没有方法和默认属性。

## 示例

示例 #1 通过类型转换为对象创建

    <?php
    $obj = (object) array('foo' => 'bar');
    var_dump($obj);

以上示例会输出：

    object(stdClass)#1 (1) {
      ["foo"]=>
      string(3) "bar"
    }

示例 #2 通过 json_decode() 创建

    <?php
    $json = '{"foo":"bar"}';
    var_dump(json_decode($json));

以上示例会输出：

    object(stdClass)#1 (1) {
      ["foo"]=>
      string(3) "bar"
    }

示例 #3 声明动态属性

    <?php
    $obj = new stdClass();
    $obj->foo = 42;
    $obj->{1} = 42;
    var_dump($obj);

以上示例会输出：

    object(stdClass)#1 (2) {
      ["foo"]=>
      int(42)
      ["1"]=>
      int(42)
    }

# 生成器类

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## 简介

Generator 对象是从 generators返回的.

警告

Generator 对象不能通过 new 实例化.

## 类摘要

final class Generator implements Iterator {
/* 方法 */
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
}

## 参见

也可以参考 遍历对象。

# Generator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::current — 返回当前产生的值

### 说明

public function Generator::current(): mixed

### 参数

此函数没有参数。

### 返回值

返回当前产生的值。

# Generator::getReturn

(PHP 7, PHP 8)

Generator::getReturn — 获取生成器的返回值

### 说明

public function Generator::getReturn(): mixed

### 参数

此函数没有参数。

### 返回值

在生成器执行完成后，获取生成器的 return 值。

### 示例

示例 #1 Generator::getReturn() 示例

    <?php

    $gen = (function() {
        yield 1;
        yield 2;

        return 3;
    })();

    foreach ($gen as $val) {
        echo $val, PHP_EOL;
    }

    echo $gen->getReturn(), PHP_EOL;

以上示例会输出：

    1
    2
    3

# Generator::key

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::key — 返回当前产生的键

### 说明

public function Generator::key(): mixed

获取产生的值的键

### 参数

此函数没有参数。

### 返回值

返回当前产生的键。

### 示例

示例 #1 Generator::key() example

    <?php

    function Gen()
    {
        yield 'key' => 'value';
    }

    $gen = Gen();

    echo "{$gen->key()} => {$gen->current()}";

以上示例会输出：

    key => value

# Generator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::next — 生成器继续执行

### 说明

public function Generator::next(): void

调用 Generator::next() 与以 `null` 作为参数调用 Generator::send() 具有同样的效果。

### 参数

此函数没有参数。

### 返回值

没有返回值。

# Generator::rewind

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::rewind — 执行生成器，直至并包含第一个 yield 语句

### 说明

public function Generator::rewind(): void

执行生成器，直至并包含第一个 `yield`。若生成器已位于第一个 `yield` 处，则不执行任何操作。若生成器曾向前推进超过某个 `yield` 表达式，则此方法将抛出 Exception。

> 注意:

> 这是开始 `foreach` 循环时调用的第一个方法，不会在 `foreach` 循环结束后执行。

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 示例

示例 #1 Generator::rewind() 示例

    <?php

    function generator(): Generator
    {
        echo "I'm a generator!\n";

        for ($i = 1; $i <= 3; $i++) {
            yield $i;
        }
    }

    // 初始化生成器
    $generator = generator();

    // 将生成器重置到第一个 yield 表达式的起始位置（如果尚未处于该位置）
    $generator->rewind(); // I'm a generator!

    // 此处无任何操作；生成器已处于重置状态
    $generator->rewind(); // 没有输出（NULL）

    // 会将生成器重置到第一个 yield 表达式（如果尚未处于该位置），并对其进行遍历
    foreach ($generator as $value) {
        // 在生成第一个值后，生成器会停留在第一个 yield 表达式处，直到恢复执行并继续前进到下一个 yield
        echo $value, PHP_EOL; // 1

        break;
    }

    // 恢复执行后再次重置，不会产生错误，因为生成器尚未越过第一个 yield
    $generator->rewind();

    echo $generator->current(), PHP_EOL; // 1

    // 不会产生错误，生成器仍处于第一个 yield 处
    $generator->rewind();

    // 此操作将生成器推进至第二个 yield 表达式
    $generator->next();

    try {
        // 此操作会抛出异常，因为生成器已推进至第二个 yield
        $generator->rewind(); // Fatal error: Uncaught Exception: Cannot rewind a generator that was already run
    } catch (Exception $e) {
        echo $e->getMessage();
    }

    ?>

以上示例会输出：

    I'm a generator!
    1
    1
    Cannot rewind a generator that was already run

# Generator::send

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::send — 向生成器中传入一个值

### 说明

public function Generator::send(mixed `$value`): mixed

向生成器中传入一个值，并且当做 `yield` 表达式的结果，然后继续执行生成器。

如果当这个方法被调用时，生成器不在 `yield` 表达式，那么在传入值之前，它会先运行到第一个 `yield` 表达式。 因此没有必要调用 Generator::next() 让 PHP 生成器 “准备”（就像是 Python 那样做）。

### 参数

`value`

  传入生成器的值。这个值将会被作为生成器当前所在的 `yield` 的返回值

### 返回值

返回生成的值。

### 示例

示例 #1 用 Generator::send() 向生成器函数中传值

    <?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!');
    ?>

以上示例会输出：

    I'm printer!
    Hello world!
    Bye world!

# Generator::throw

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::throw — 向生成器中抛入一个异常

### 说明

public function Generator::throw(Throwable `$exception`): mixed

抛出一个异常到生成器并恢复生成器的执行。 与当前 `yield` 表达式被 `throw $exception` 语句替换是一样的行为。

如果调用此方法时生成器已经关闭，则将会在调用者的上下文中抛出异常。

### 参数

`exception`

  抛出异常到生成器。

### 返回值

返回生成的值。

### 示例

示例 #1 抛出异常到生成器

    <?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'));
    ?>

以上示例会输出：

    Foo
    Exception: Test
    Bar

# Generator::valid

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::valid — 检查迭代器是否被关闭

### 说明

public function Generator::valid(): bool

### 参数

此函数没有参数。

### 返回值

如果迭代器已被关闭返回 `false`，否则返回 `true`。

# Generator::__wakeup

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::__wakeup — 序列化回调

### 说明

public function Generator::__wakeup(): void

抛出一个异常以表示生成器不能被序列化。

### 参数

此函数没有参数。

### 返回值

没有返回值。

## 目录

- Generator::current — 返回当前产生的值
- Generator::getReturn — 获取生成器的返回值
- Generator::key — 返回当前产生的键
- Generator::next — 生成器继续执行
- Generator::rewind — 执行生成器，直至并包含第一个 yield 语句
- Generator::send — 向生成器中传入一个值
- Generator::throw — 向生成器中抛入一个异常
- Generator::valid — 检查迭代器是否被关闭
- Generator::__wakeup — 序列化回调

# 纤程（Fiber）类

(PHP 8 >= 8.1.0)

## 简介

纤程（Fiber）代表了有完整栈、可中断的功能。Fiber 可以从调用堆栈中的任何位置挂起，在 fiber 内暂停执行，直到稍后恢复 fiber。

## 类摘要

final class Fiber {
/* 方法 */
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
}

## 参见

纤程概述

# Fiber::__construct

(PHP 8 >= 8.1.0)

Fiber::__construct — 创建新的 Fiber 实例

### 说明

public function Fiber::__construct(callable `$callback`)

### 参数

`callback`

  启动 fiber 时调用 callable。提供给 Fiber::start() 的参数，也将是调用 callable 时的参数。

# Fiber::start

(PHP 8 >= 8.1.0)

Fiber::start — 启动 fiber 的执行

### 说明

public function Fiber::start(mixed `...$args`): mixed

当构造 fiber 时提供用于 callable 的可变参数列表。

如果调用此方法时 fiber 已经启动，则会抛出 FiberError。

### 参数

`args`

  该参数用于调用 fiber 构造函数内指定的 callable。

### 返回值

首次调用 Fiber::suspend() 提供的值；如果 fiber 已返回，则是 `null`。 如果 fiber 在挂起前抛出异常，那么会在调用此方法时的位置抛出异常。

# Fiber::resume

(PHP 8 >= 8.1.0)

Fiber::resume — 使用值恢复 fiber 的执行

### 说明

public function Fiber::resume(mixed `$value` = `null`): mixed

使用给定值作为当前 Fiber::suspend() 调用的结果来恢复 fiber。

如果调用此方法时 fiber 还没挂起，将会抛出 FiberError。

### 参数

`value`

  恢复 fiber 的值。这个值将会从当前调用 Fiber::suspend() 中返回。

### 返回值

如果 fiber 已返回，将是 `null`；否则就是下次调用 Fiber::suspend() 时提供的值。 如果 fiber 暂停前抛出一个异常，它将会从调用本方法时的位置抛出异常。

# Fiber::throw

(PHP 8 >= 8.1.0)

Fiber::throw — 用一个异常来恢复 fiber 的执行

### 说明

public function Fiber::throw(Throwable `$exception`): mixed

在当前调用 Fiber::suspend() 的位置抛出指定的异常，恢复 fiber 执行。

如果调用此方法时 fiber 未挂起，将抛出 FiberError。

### 参数

`exception`

  在当前调用 Fiber::suspend() 所在的位置，要抛出的异常。

### 返回值

下次调用 Fiber::suspend() 所提供的值；如果 fiber 已返回，则是 `null`。 如果 fiber 暂停前抛出一个异常，它将会从调用本方法的位置抛出。

# Fiber::getReturn

(PHP 8 >= 8.1.0)

Fiber::getReturn — 获取 Fiber 的返回值

### 说明

public function Fiber::getReturn(): mixed

### 参数

此函数没有参数。

### 返回值

返回的值是 Fiber::__construct() 参数 callable 所返回的值。 如果因为 Fiber 没有启动、没有正常终止、抛出异常等等，导致没有返回值，将抛出 FiberError 异常。

# Fiber::isStarted

(PHP 8 >= 8.1.0)

Fiber::isStarted — 确定 fiber 是否启动

### 说明

public function Fiber::isStarted(): bool

### 参数

此函数没有参数。

### 返回值

只有在 fiber 启动后返回 `true`，否则返回 `false`。

# Fiber::isSuspended

(PHP 8 >= 8.1.0)

Fiber::isSuspended — 确认 fiber 是否挂起

### 说明

public function Fiber::isSuspended(): bool

### 参数

此函数没有参数。

### 返回值

如果 fiber 当前挂起则返回 `true` 否则返回 `false`。

# Fiber::isRunning

(PHP 8 >= 8.1.0)

Fiber::isRunning — 确认 fiber 是否正在运行

### 说明

public function Fiber::isRunning(): bool

### 参数

此函数没有参数。

### 返回值

仅在 fiber 运行时返回 `true`。在调用 Fiber::start()、Fiber::resume()、 Fiber::throw() 还没有返回之后，将认为 fiber 正在运行。如果 fiber 没有运行则返回 `false`。

# Fiber::isTerminated

(PHP 8 >= 8.1.0)

Fiber::isTerminated — 确认 fiber 是否终止

### 说明

public function Fiber::isTerminated(): bool

### 参数

此函数没有参数。

### 返回值

如果 fiber 因为已返回或抛出了异常，处于终止状态，则返回 `true`，否则返回 `false`。

# Fiber::suspend

(PHP 8 >= 8.1.0)

Fiber::suspend — 暂停当前 fiber 的执行

### 说明

public static function Fiber::suspend(mixed `$value` = `null`): mixed

暂停当前 fiber 的执行。调用 Fiber::start()、 Fiber::resume()、 Fiber::throw() 将执行切换到当前 fiber 时，提供给本方法的值，也将是这几个方法所返回的值，

当 fiber 恢复后，此方法的返回值是 Fiber::resume() 所提供的值。 如果 fiber 使用 Fiber::throw() 恢复，则把传入的异常在调用本方法的位置抛出。

如果此方法是用 fiber 外部调用，将会抛出 FiberError。

### 参数

`value`

  该值会在调用 Fiber::start()、 Fiber::resume()、 Fiber::throw() 时作为返回值，并将执行切换到当前 fiber。

### 返回值

提供给 Fiber::resume() 的值。

# Fiber::getCurrent

(PHP 8 >= 8.1.0)

Fiber::getCurrent — 获取当前正在执行的 Fiber 实例

### 说明

public static function Fiber::getCurrent(): ?Fiber

### 参数

此函数没有参数。

### 返回值

返回当前正在执行的 Fiber 实例，如果在 Fiber 外部调用此方法，则返回 `null`。

## 目录

- Fiber::__construct — 创建新的 Fiber 实例
- Fiber::start — 启动 fiber 的执行
- Fiber::resume — 使用值恢复 fiber 的执行
- Fiber::throw — 用一个异常来恢复 fiber 的执行
- Fiber::getReturn — 获取 Fiber 的返回值
- Fiber::isStarted — 确定 fiber 是否启动
- Fiber::isSuspended — 确认 fiber 是否挂起
- Fiber::isRunning — 确认 fiber 是否正在运行
- Fiber::isTerminated — 确认 fiber 是否终止
- Fiber::suspend — 暂停当前 fiber 的执行
- Fiber::getCurrent — 获取当前正在执行的 Fiber 实例

# WeakReference 类

(PHP 7 >= 7.4.0, PHP 8)

## 简介

弱引用允许保留对对象的引用，而不会阻止销毁对象。对于实现类似缓存的结构很有用。如果原始对象已销毁，则调用 WeakReference::get() 方法时将返回 `null`。当原始对象的 refcount 降至零时，会销毁原始对象；创建弱引用不会增加被引用对象的 `refcount`。

弱引用类不能序列化。

## 类摘要

final class WeakReference {
/* 方法 */
public function __construct()
public static function create(object `$object`): WeakReference
public function get(): ?object
}

## 弱引用示例

示例 #1 弱引用的基础用法

    <?php

    $obj = new stdClass();
    $weakref = WeakReference::create($obj);

    var_dump($weakref->get());

    unset($obj);

    var_dump($weakref->get());

    ?>

以上示例的输出类似于：

    object(stdClass)#1 (0) {
    }
    NULL

## 更新日志

版本 | 说明
--- | ---
8.4.0 | 现在 WeakReference::__debugInfo() 的输出包含引用的对象，当引用不可用时，为 `NULL`。

# WeakReference::__construct

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::__construct — 不允许实例化的构造函数

### 说明

public function WeakReference::__construct()

这个方法的存在只是为了禁止实例化 WeakReference 类。 弱引用使用工厂方法 WeakReference::create() 进行实例化。

### 参数

此函数没有参数。

### 参见

- WeakReference::create() - 创建新的弱引用

# WeakReference::create

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::create — 创建新的弱引用

### 说明

public static function WeakReference::create(object `$object`): WeakReference

创建新的 WeakReference。

### 参数

`object`

  要弱引用的对象。

### 返回值

返回一个新的 WeakReference， 如果已经有一个指向相同对象的 WeakReference，则返回现有实例。

# WeakReference::get

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::get — 获取弱引用对象

### 说明

public function WeakReference::get(): ?object

获取弱引用对象。 如果对象已销毁，则返回 `null`。

### 参数

此函数没有参数。

### 返回值

返回引用的 object，如果对象已销毁，则返回 `null`。

## 目录

- WeakReference::__construct — 不允许实例化的构造函数
- WeakReference::create — 创建新的弱引用
- WeakReference::get — 获取弱引用对象

# WeakMap 类

(PHP 8)

## 简介

WeakMap 是将对象作为 key 来访问的 map（或者说字典）。然而，与其它类似 SplObjectStorage 不同，WeakMap 中的对象 key 不影响对象的引用计数。也就是说，如果在任何时候对其唯一的剩余引用是 WeakMap key，那么该对象将会被垃圾收集并从 WeakMap 移除。它的主要用法是从对象中编译数据派生缓存，这种场景下不需要存活得比对象更久。

WeakMap 实现了 ArrayAccess、 Traversable（通过 IteratorAggregate）和 Countable， 因此大多数情况下，它能和关联数组一样使用。

## 类摘要

final class WeakMap implements ArrayAccess, Countable, IteratorAggregate {
/* 方法 */
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
}

## 示例

示例 #1 Weakmap 用法示例

    <?php
    $wm = new WeakMap();

    $o = new stdClass;

    class A {
        public function __destruct() {
            echo "Dead!\n";
        }
    }

    $wm[$o] = new A;

    var_dump(count($wm));
    echo "Unsetting...\n";
    unset($o);
    echo "Done\n";
    var_dump(count($wm));

以上示例会输出：

    int(1)
    Unsetting...
    Dead!
    Done
    int(0)

# WeakMap::count

(PHP 8)

WeakMap::count — 统计 map 中存活实体的数量

### 说明

public function WeakMap::count(): int

统计 map 中存活实体的数量。

### 参数

此函数没有参数。

### 返回值

返回 map 中存活实体的数量。

# WeakMap::getIterator

(PHP 8)

WeakMap::getIterator — 接收一个外部迭代器

### 说明

public function WeakMap::getIterator(): Iterator

返回一个外部迭代器.

### 参数

此函数没有参数。

### 返回值

一个实现了 Iterator 或者 Traversable 的类实例

### 错误／异常

失败时抛出 Exception。

# WeakMap::offsetExists

(PHP 8)

WeakMap::offsetExists — 检测 map 中是否存在某个对象

### 说明

public function WeakMap::offsetExists(object `$object`): bool

检查传入的对象在 map 中是否被引用。

### 参数

`object`

  要检查的对象。

### 返回值

如果 map 中包含该对象返回 `true`，否则返回 `false`。

# WeakMap::offsetGet

(PHP 8)

WeakMap::offsetGet — 返回某个对象指向的值

### 说明

public function WeakMap::offsetGet(object `$object`): mixed

返回某个对象指向的值。

### 参数

`object`

  map 中包含的 key 对象。

### 返回值

返回与作为参数传入对象关联的值。

### 错误／异常

失败时抛出一个 Error 异常。

# WeakMap::offsetSet

(PHP 8)

WeakMap::offsetSet — 更新 map 新的键值对

### 说明

public function WeakMap::offsetSet(object `$object`, mixed `$value`): void

更新 map 新的键值对。如果 key 已经在 map 中存在， 新的值会替换老的值。

### 参数

`object`

  键值对中作为 key 的对象。

`value`

  任意数据作为键值对的值。

### 返回值

没有返回值。

# WeakMap::offsetUnset

(PHP 8)

WeakMap::offsetUnset — 从 map 中移除一条

### 说明

public function WeakMap::offsetUnset(object `$object`): void

从 map 中移除一项。

### 参数

`object`

  从 map 中移除的 key 对象。

### 返回值

没有返回值。

## 目录

- WeakMap::count — 统计 map 中存活实体的数量
- WeakMap::getIterator — 接收一个外部迭代器
- WeakMap::offsetExists — 检测 map 中是否存在某个对象
- WeakMap::offsetGet — 返回某个对象指向的值
- WeakMap::offsetSet — 更新 map 新的键值对
- WeakMap::offsetUnset — 从 map 中移除一条

# Stringable 接口

(PHP 8)

## 简介

Stringable 接口表示拥有 __toString() 方法的类。 和大多数接口不同， Stringable 隐式存在于任何定义了 __toString() 魔术方法的类上， 当然也可以显式声明它，并且推荐这么做。

它的主要价值是能让函数针对简单的字符串或可以转化为字符串的对象，检测联合类型 `string|Stringable`。

## 接口摘要

interface Stringable {
/* 方法 */
public function __toString(): string
}

## Stringable 示例

示例 #1 基础 Stringable 用法

这里使用了构造器属性提升。

    <?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) {
        // 存在 Stringable，这将默认调用 __toString()。
        print $value;
    }

    $ip = new IPv4Address('123', '234', '42', '9');

    showStuff($ip);
    ?>

以上示例的输出类似于：

    123.234.42.9

# Stringable::__toString

(PHP 8)

Stringable::__toString — 从对象中获取字符串表示

### 说明

public function Stringable::__toString(): string

### 参数

此函数没有参数。

### 返回值

返回对象的 string 表示。

### 参见

- __toString()

## 目录

- Stringable::__toString — 从对象中获取字符串表示

# UnitEnum 接口

(PHP 8 >= 8.1.0)

## 简介

引擎会自动应用 UnitEnum 接口到所有枚举。 用户自定义类不能实现该接口。 由于引擎已提供枚举的默认实现，因此不能重载它的接口。 主要将它用于类型检测。

## 接口摘要

interface UnitEnum {
/* 方法 */
public static function cases(): array
}

# UnitEnum::cases

(PHP 8 >= 8.1.0)

UnitEnum::cases — 生成枚举的条目清单

### 说明

public static function UnitEnum::cases(): array

该方法返回打包后的 array，以声明的顺序，包含了枚举的所有条目。

### 参数

此函数没有参数。

### 返回值

以语法中声明的顺序，返回该枚举中定义的所有条目数组。

### 示例

示例 #1 基本用法

下例演示了如何返回枚举条目。

    <?php
    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    var_dump(Suit::cases());
    ?>

以上示例会输出：

    array(4) {
        [0]=>
        enum(Suit::Hearts)
        [1]=>
        enum(Suit::Diamonds)
        [2]=>
        enum(Suit::Clubs)
        [3]=>
        enum(Suit::Spades)
    }

## 目录

- UnitEnum::cases — 生成枚举的条目清单

# BackedEnum 接口

(PHP 8 >= 8.1.0)

## 简介

引擎会自动应用 BackedEnum 接口到回退枚举。 用户自定义类不能实现该接口。 由于引擎已提供枚举的默认实现，因此不能重载它的接口。 主要将它用于类型检测。

## 接口摘要

interface BackedEnum extends UnitEnum {
/* 方法 */
public static function from(int|string `$value`): static
public static function tryFrom(int|string `$value`): ?static
/* 继承的方法 */
public static function UnitEnum::cases(): array
}

# BackedEnum::from

(PHP 8 >= 8.1.0)

BackedEnum::from — 映射标量为 enum 实例

### 说明

public static function BackedEnum::from(int|string `$value`): static

from() 方法将 string 和 int 翻译成对应存在的 enum 条目。 如果没有匹配的条目，会抛出 ValueError。

### 参数

`value`

  要映射到枚举条目的标量值。

### 返回值

该枚举的一个条目实例。

### 示例

示例 #1 基本用法

以下的例子演示了如何返回 enum 条目。

    <?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');
    ?>

以上示例会输出：

    enum(Suit::Hearts)

    Fatal error: Uncaught ValueError: "B" is not a valid backing value for enum "Suit" in /file.php:15

### 参见

- UnitEnum::cases() - 生成枚举的条目清单
- BackedEnum::tryFrom() - 映射标量为 enum 实例或 null

# BackedEnum::tryFrom

(PHP 8 >= 8.1.0)

BackedEnum::tryFrom — 映射标量为 enum 实例或 null

### 说明

public static function BackedEnum::tryFrom(int|string `$value`): ?static

tryFrom() 方法将 string 和 int 翻译成对应存在的 enum 条目。 如果没有找到匹配的条目，返回 null。

### 参数

`value`

  要映射到枚举条目的标量值。

### 返回值

该枚举的一个条目实例，未找到时返回 null。

### 示例

示例 #1 基本用法

以下的例子演示了如何返回 enum 条目。

    <?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);
    ?>

以上示例会输出：

    enum(Suit::Hearts)
    enum(Suit::Spades)

### 参见

- UnitEnum::cases() - 生成枚举的条目清单
- BackedEnum::from() - 映射标量为 enum 实例

## 目录

- BackedEnum::from — 映射标量为 enum 实例
- BackedEnum::tryFrom — 映射标量为 enum 实例或 null

# SensitiveParameterValue 类

(PHP 8 >= 8.2.0)

## 简介

SensitiveParameterValue 类允许包装敏感值以防止意外暴露。

具有 SensitiveParameter 属性的参数值将在堆栈跟踪中自动包装在 SensitiveParameterValue 对象中。

## 类摘要

final class SensitiveParameterValue {
/* 属性 */
private readonly mixed $value;
/* 方法 */
public function __construct(mixed `$value`)
public function __debugInfo(): array
public function getValue(): mixed
}

## 属性

value

  需要防止意外暴露的敏感值。

# SensitiveParameterValue::__construct

(PHP 8 >= 8.2.0)

SensitiveParameterValue::__construct — 构造新的 SensitiveParameterValue 对象

### 说明

public function SensitiveParameterValue::__construct(mixed `$value`)

构造一个持有敏感值的 SensitiveParameterValue。

### 参数

`value`

  应存储在 SensitiveParameterValue 对象内部的任意值。

# SensitiveParameterValue::__debugInfo

(PHP 8 >= 8.2.0)

SensitiveParameterValue::__debugInfo — 保护敏感值免于意外暴露

### 说明

public function SensitiveParameterValue::__debugInfo(): array

在使用 var_dump() 时返回空 array 以保护敏感值免于意外暴露。

### 参数

此函数没有参数。

### 返回值

空 array。

### 示例

示例 #1 将 SensitiveParameterValue 对象传递给 var_dump()

    <?php
    $s = new \SensitiveParameterValue('secret');

    var_dump($s);
    ?>

以上示例会输出：

    object(SensitiveParameterValue)#1 (0) {
    }

# SensitiveParameterValue::getValue

(PHP 8 >= 8.2.0)

SensitiveParameterValue::getValue — 返回敏感值

### 说明

public function SensitiveParameterValue::getValue(): mixed

获取敏感值。

### 参数

此函数没有参数。

### 返回值

敏感值。

### 示例

示例 #1 SensitiveParameterValue::getValue() 示例

    <?php
    $s = new \SensitiveParameterValue('secret');

    echo "The protected value is: ", $s->getValue(), "\n";
    ?>

以上示例会输出：

    The protected value is: secret

## 目录

- SensitiveParameterValue::__construct — 构造新的 SensitiveParameterValue 对象
- SensitiveParameterValue::__debugInfo — 保护敏感值免于意外暴露
- SensitiveParameterValue::getValue — 返回敏感值

# __PHP_Incomplete_Class 类

(PHP 4 >=4.0.1, PHP 5, PHP 7, PHP 8)

## 简介

由 unserialize() 创建的在尝试反序列化未定义类或未在 unserialize() 的 `options` 数组的 `allowed_classes` 中列出的类。

在 PHP 7.2.0 之前，对 __PHP_Incomplete_Class 类使用 is_object() 会返回 `false`。从 PHP 7.2.0 开始，将返回 `true`。

## 类摘要

#[\AllowDynamicProperties]
final class __PHP_Incomplete_Class {
}

此类没有默认属性或方法。 由 unserialize() 创建时， 除了所有反序列化的属性和值之外， 对象还将具有一个 `__PHP_Incomplete_Class_Name` 属性， 该属性将包含反序列化类的名称。

## 更新日志

版本 | 说明
--- | ---
8.0.0 | 此类现在是 `final`。

## 示例

示例 #1 由 unserialize() 创建

    <?php

    class MyClass
    {
        public string $property = "myValue";
    }

    $myObject = new MyClass;

    $foo = serialize($myObject);

    // unserializes all objects into __PHP_Incomplete_Class objects
    $disallowed = unserialize($foo, ["allowed_classes" => false]);

    var_dump($disallowed);

    // unserializes all objects into __PHP_Incomplete_Class objects except those of MyClass2 and MyClass3
    $disallowed2 = unserialize($foo, ["allowed_classes" => ["MyClass2", "MyClass3"]]);

    var_dump($disallowed2);

    // unserializes undefined class into __PHP_Incomplete_Class object
    $undefinedClass = unserialize('O:16:"MyUndefinedClass":0:{}');

    var_dump($undefinedClass);

以上示例会输出：

    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"
    }

# 预定义注解

## 目录

- Attribute
- AllowDynamicProperties
- Deprecated
- Override
- ReturnTypeWillChange
- SensitiveParameter

PHP 提供了一些可以使用的预定义注解。

# Attribute 属性

(PHP 8)

## 简介

注解提供了向代码声明中添加结构化、机器可读的元数据信息的能力：类、方法、函数、参数、属性和类常量都可以作为注解的目标。然后可以在运行时使用反射 API 检查注解定义的元数据。因此，注解可以被看作是直接嵌入代码的配置语言。

## 类摘要

#[\Attribute]
final class Attribute {
/* 常量 */
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_CONSTANT;
const int TARGET_ALL;
const int IS_REPEATABLE;
/* 属性 */
public int $flags;
/* 方法 */
public function __construct(int `$flags` = Attribute::TARGET_ALL)
}

## 预定义常量

`Attribute::TARGET_CLASS`

`Attribute::TARGET_FUNCTION`

`Attribute::TARGET_METHOD`

`Attribute::TARGET_PROPERTY`

`Attribute::TARGET_CLASS_CONSTANT`

`Attribute::TARGET_PARAMETER`

`Attribute::TARGET_CONSTANT`

`Attribute::TARGET_ALL`

`Attribute::IS_REPEATABLE`

## 属性

flags

## 更新日志

版本 | 说明
--- | ---
8.5.0 | 新增 `Attribute::TARGET_CONSTANT`。

## 参见

注解概述

# Attribute::__construct

(PHP 8)

Attribute::__construct — 构造新的 Attribute 实例

### 说明

public function Attribute::__construct(int `$flags` = Attribute::TARGET_ALL)

构造新的 Attribute 实例。

### 参数

`flags`

## 目录

- Attribute::__construct — 构造新的 Attribute 实例

# AllowDynamicProperties 注解

(PHP 8 >= 8.2.0)

## 简介

此注解用于标记 class，允许动态属性。

## 类摘要

#[\Attribute]
final class AllowDynamicProperties {
/* 方法 */
public function __construct()
}

## 示例

从 PHP 8.2.0 起弃用动态属性，因此在不使用此注解标记类的情况下使用动态属性将发出弃用通知。

    <?php
    class DefaultBehaviour { }

    #[\AllowDynamicProperties]
    class ClassAllowsDynamicProperties { }

    $o1 = new DefaultBehaviour();
    $o2 = new ClassAllowsDynamicProperties();

    $o1->nonExistingProp = true;
    $o2->nonExistingProp = true;
    ?>

以上示例在 PHP 8.2 中的输出：

    Deprecated: Creation of dynamic property DefaultBehaviour::$nonExistingProp is deprecated in file on line 10

## 参见

注解概览

# AllowDynamicProperties::__construct

(PHP 8 >= 8.2.0)

AllowDynamicProperties::__construct — 构造新的 AllowDynamicProperties 注解实例

### 说明

public function AllowDynamicProperties::__construct()

构造新 AllowDynamicProperties 实例。

### 参数

此函数没有参数。

## 目录

- AllowDynamicProperties::__construct — 构造新的 AllowDynamicProperties 注解实例

# Deprecated 属性

(PHP 8 >= 8.4.0)

## 简介

此属性用于将功能标记为已弃用。使用已弃用的功能将导致发出 `E_USER_DEPRECATED` 错误。

## 类摘要

#[\Attribute]
final class Deprecated {
/* 属性 */
public readonly ?string $message;
public readonly ?string $since;
/* 方法 */
public function __construct(?string `$message` = `null`, ?string `$since` = `null`)
}

## 属性

message

  可选的消息，说明弃用的原因和可能的替代功能。将包含在发出的弃用消息中。

since

  可选的字符串，指示功能从何时起被弃用。内容不会被 PHP 验证，可以包含版本号、日期或任何被认为合适的值。将包含在发出的弃用消息中。

  PHP 自身的功能将使用 Major.Minor 作为 since 值，例如 `'8.4'`。

## 示例

    <?php

    #[\Deprecated(message: "use safe_replacement() instead", since: "1.5")]
    function unsafe_function()
    {
       echo "This is unsafe", PHP_EOL;
    }

    unsafe_function();

    ?>

上述示例在 PHP 8.4 中的输出类似于：

    Deprecated: Function unsafe_function() is deprecated since 1.5, use safe_replacement() instead in example.php on line 9
    This is unsafe

## 参见

- 注解概述
- ReflectionFunctionAbstract::isDeprecated()
- ReflectionClassConstant::isDeprecated()
- `E_USER_DEPRECATED`

# Deprecated::__construct

(PHP 8 >= 8.4.0)

Deprecated::__construct — 构造新的 Deprecated 属性实例

### 说明

public function Deprecated::__construct(?string `$message` = `null`, ?string `$since` = `null`)

构造新的 Deprecated 实例。

### 参数

`message`

  message 属性的值。

`since`

  since 属性的值。

## 目录

- Deprecated::__construct — 构造新的 Deprecated 属性实例

# Override 注解

(PHP 8 >= 8.3.0)

## 简介

此注解用于表明某个方法或属性意图重写父类中的方法或属性，或实现接口中定义的方法或属性。

如果父类或实现的接口中不存在同名方法或属性，则会引发编译时错误。

此注解不能用于 __construct() 方法，该方法不进行签名检查。

## 类摘要

#[\Attribute]
final class Override {
/* 方法 */
public function __construct()
}

## 更新日志

版本 | 说明
--- | ---
8.5.0 | Override 可以应用于属性。

## 示例

示例 #1 与方法一起使用

    <?php

    class Base {
        protected function foo(): void {}
    }

    final class Extended extends Base {
        #[\Override]
        protected function boo(): void {}
    }

    ?>

上述示例在 PHP 8.3 中的输出类似于：

    Fatal error: Extended::boo() has #[\Override] attribute, but no matching parent method exists

示例 #2 与属性一起使用

    <?php

    class Base {
        protected string $foo;
    }

    final class Extended extends Base {
        #[\Override]
        protected string $boo;
    }

    ?>

上述示例在 PHP 8.5 中的输出类似于：

    Fatal error: Extended::$boo has #[\Override] attribute, but no matching parent property exists

## 参见

- 注解概览

# Override::__construct

(PHP 8 >= 8.3.0)

Override::__construct — 构造新的 Override 属性实例

### 说明

public function Override::__construct()

构造新的 Override 实例。

### 参数

此函数没有参数。

## 目录

- Override::__construct — 构造新的 Override 属性实例

# ReturnTypeWillChange 注解

(PHP 8 >= 8.1.0)

## 简介

大多数非 final 内部方法现在需要重写方法来声明兼容的返回类型，否则在继承验证期间会发出弃用通知。 如果由于 PHP 跨版本兼容性问题而无法为重写方法声明返回类型，可以添加 `#[\ReturnTypeWillChange]` 注解以消除弃用通知。

## 类摘要

#[\Attribute]
final class ReturnTypeWillChange {
/* 方法 */
public function __construct()
}

## 参见

注解概览

# ReturnTypeWillChange::__construct

(PHP 8 >= 8.1.0)

ReturnTypeWillChange::__construct — 构造新的 ReturnTypeWillChange 注解实例

### 说明

public function ReturnTypeWillChange::__construct()

构造新 ReturnTypeWillChange 实例。

### 参数

此函数没有参数。

## 目录

- ReturnTypeWillChange::__construct — 构造新的 ReturnTypeWillChange 注解实例

# SensitiveParameter 注解

(PHP 8 >= 8.2.0)

## 简介

该注解用于标记敏感参数，如果出现在栈跟踪中，则应编辑其值。

## 类摘要

#[\Attribute]
final class SensitiveParameter {
/* 方法 */
public function __construct()
}

## 示例

    <?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;
    }

    ?>

上述示例在 PHP 8.2 中的输出类似于：

    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}

## 参见

- 注解概览
- SensitiveParameterValue

# SensitiveParameter::__construct

(PHP 8 >= 8.2.0)

SensitiveParameter::__construct — 构造新的 SensitiveParameter 属性实例

### 说明

public function SensitiveParameter::__construct()

构造新的 SensitiveParameter 实例。

### 参数

此函数没有参数。

## 目录

- SensitiveParameter::__construct — 构造新的 SensitiveParameter 属性实例

# 上下文（Context）选项和参数

PHP 提供了多种上下文选项和参数，可用于所有的文件系统或数据流封装协议。上下文（Context）由 stream_context_create() 创建。选项可通过 stream_context_set_option() 设置，参数可通过 stream_context_set_params() 设置。

# 套接字上下文选项

套接字上下文选项 — 套接字上下文选项列表

### 说明

套接字上下文选项可用于所有工作在套接字上的封装协议，像 `tcp`, `http` 和 `ftp`。

### 可选项

`bindto`

  用户 PHP 访问网络的指定的 IP 地址（IPv4 或 IPv6 其中的一个）和/或 端口号，这个语法是 `ip:port`。 设置 IP 或者 port 为 `0` 将会让系统选择 IP 或 port。

  > 注意:

  > 由于 FTP 在正常操作时会创建两个 socket 连接，因此无法使用此选项指定端口号。

`backlog`

  用于限制 socket 监听队列中未完成连接的数量。

  > 注意:

  > 这仅适用于 stream_socket_server()。

`ipv6_v6only`

  覆盖有关 IPv4 映射到 IPv6 的操作系统默认值。

  > 注意:

  > 在 `[::]` 上存在绑定的时候，当尝试在各自的 Ipv4 地址上监听，这是尤其重要。

  > 这仅适用于 stream_socket_server()。

`so_reuseport`

  即使来自不同的进程，也能对同一个 ip:port 对进行多个绑定。

  > 注意:

  > 这仅适用于 stream_socket_server()。

`so_broadcast`

  允许向广播地址发送数据，从广播地址接收数据。

  > 注意:

  > 这仅适用于 stream_socket_server()。

`tcp_nodelay`

  设置此选项为 `true` 将相应地设置 `SOL_TCP,NO_DELAY=1`， 从而禁用 TCP Nagle 算法。

### 更新日志

版本 | 说明
--- | ---
7.1.0 | 添加 `tcp_nodelay`。
7.0.1 | 添加 `ipv6_v6only`。

### 示例

示例 #1 基础的 `bindto` 用法示例

    <?php
    // 使用 IP '192.168.0.100'  连接到互联网
    $opts = array(
        'socket' => array(
            'bindto' => '192.168.0.100:0',
        ),
    );

    // 使用 IP '192.168.0.100'  和端口 '7000' 连接到互联网
    $opts = array(
        'socket' => array(
            'bindto' => '192.168.0.100:7000',
        ),
    );

    // 使用 IPv6 地址 '2001:db8::1' 和端口 '7000' 连接到互联网
    $opts = array(
        'socket' => array(
            'bindto' => '[2001:db8::1]:7000',
        ),
    );

    // 使用端口 '7000' 连接到互联网
    $opts = array(
        'socket' => array(
            'bindto' => '0:7000',
        ),
    );

    // 创建上下文...
    $context = stream_context_create($opts);

    // ...并使用它来读取数据
    echo file_get_contents('http://www.example.com', false, $context);

    ?>

# HTTP context 选项

HTTP context 选项 — HTTP context 的选项列表

### 说明

提供给 `http://` 和 `https://` 传输协议的 context 选项。 transports.

### 可选项

`method` string

  远程服务器支持的 `GET`，`POST` 或其它 HTTP 方法。

  默认值是 `GET`。

`header` array 或 string

  请求期间发送的附加 header 。此选项中的值将覆盖其他值 （如 `User-agent:`， `Host:` 和 `Authentication:`)， 即使在执行 `Location:` 重定向时也是如此。 所以，如果启用了 `follow_location` 就不建议设置 `Host:` header。

  字符串值是以 `\r\n` 分隔的 `Key: value`，例如 `"Content-Type: application/json\r\nConnection: close"`。数组值应为 `Key: value` 的列表，例如 `["Content-Type: application/json", "Connection: close"]`。

`user_agent` string

  要发送的 header `User-Agent:` 的值。如果在上面的 `header` context 选项中没有指定 user-agent，此值将被使用。

  默认使用 php.ini 中设置的 user_agent。

`content` string

  在 header 后面要发送的额外数据。通常使用POST或PUT请求。

`proxy` string

  URI 指定的代理服务器的地址（例如： `tcp://proxy.example.com:5100`）。

`request_fulluri` bool

  当设置为 `true` 时，在构建请求时将使用整个 URI（例如： `GET http://www.example.com/path/to/file.html HTTP/1.0`）。 虽然这是一个非标准的请求格式，但某些代理服务器需要它。

  默认值是 `false`.

`follow_location` int

  跟随 `Location` header 的重定向。设置为 `0` 以禁用。

  默认值是 `1`。

`max_redirects` int

  跟随重定向的最大次数。值为 `1` 或更少则意味不跟随重定向。

  默认值是 `20`。

`protocol_version` float

  HTTP 协议版本。

  PHP 8.0.0 起默认值是 `1.1`。在此之前默认值是 `1.0`。

`timeout` float

  读取超时时间，单位为秒（s），用 float 指定（例如：`10.5`）。

  默认使用 php.ini 中设置的 default_socket_timeout。

`ignore_errors` bool

  即使是故障状态码依然获取内容。

  默认值为 `false`.

### 示例

示例 #1 获取一个页面并发送 POST 数据

    <?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);

    ?>

示例 #2 忽略重定向并获取 header 和内容

    <?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);

    // header 信息和 stream 的元数据一样
    var_dump(stream_get_meta_data($stream));

    // $url 的实际数据
    var_dump(stream_get_contents($stream));
    fclose($stream);
    ?>

### 注释

> 注意: 底层 socket stream 上下文选项
> 底层传输可能支持额外的上下文选项。对于 `http://` 流，请参阅 `tcp://` 传输的上下文选项。对于 `https://` 流，请参阅 `ssl://` 传输的上下文选项。

> 注意: HTTP 状态行
> 当此流包装器跟随重定向时，stream_get_meta_data() 返回的 `wrapper_data` 中索引 `0` 处不一定包含实际适用于内容数据的 HTTP 状态行。

>     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',
>         ...

> 第一个请求返回 `301` （永久重定向）， 因此 stream 包装器自动跟随重定向到获得 `200` 响应（index = `4`）。

### 参见

- http://
- 套接字上下文选项
- SSL 上下文选项

# FTP 上下文选项

FTP 上下文选项 — FTP 上下文选项列表

### 说明

`ftp://` 和 `ftps://` 传输的上下文选项。

### 可选项

`overwrite` bool

  允许覆盖远程服务器上已有的文件。仅适用于写入模式（上传）。

  默认为 `false`。

`resume_pos` int

  开始传输的文件偏移量。仅适用于读取模式（下载）。

  默认为 `0` （文件开头）。

`proxy` string

  通过 http 代理服务器代理 FTP 请求。 仅适用于文件读取操作。 例如：`tcp://squid.example.com:8000`。

### 注释

> 注意: 底层套接字流上下文选项
> 底层传输 可能支持其他上下文选项。 对于 `ftp://` 流，请参阅 `tcp://` 传输的上下文选项。 对于 `ftps://` 流，请参阅 `ssl://` 传输的上下文选项。

### 参见

- ftp://
- 套接字上下文选项
- SSL 上下文选项

# SSL 上下文选项

SSL 上下文选项 — SSL 上下文选项清单

### 说明

`ssl://` 和 `tls://` 传输协议上下文选项清单。

### 可选项

`peer_name` string

  要连接的服务器名称。如果未设置，那么服务器名称将根据打开 SSL 流的主机名称猜测得出。

`verify_peer` bool

  是否需要验证 SSL 证书。

  默认值为 `true`。

`verify_peer_name` bool

  是否需要验证 peer name。

  默认值为 `true`.

`allow_self_signed` bool

  是否允许自签名证书。需要配合 `verify_peer` 参数使用（注：当 verify_peer 参数为 true 时才会根据 allow_self_signed 参数值来决定是否允许自签名证书）。

  默认值为 `false`

`cafile` string

  当设置 `verify_peer` 为 true 时， 用来验证远端证书所用到的 CA 证书。 本选项值为 CA 证书在本地文件系统的全路径及文件名。

`capath` string

  如果未设置 `cafile`，或者 `cafile` 所指的文件不存在时， 会在 `capath` 所指定的目录搜索适用的证书。 该目录必须是已经经过哈希处理的证书目录。 （注：所谓 hashed certificate 目录是指使用类似 c_rehash 命令将目录中的 .pem 和 .crt 文件扫描并提取哈希码，然后根据此哈希码创建文件链接，以便于快速查找证书）

`local_cert` string

  文件系统上的本地证书路径。 必须是 PEM 编码的文件，包含证书及私钥。 也可以包含证书颁发者证书链。 也可以通过 `local_pk` 指定包含私钥的独立文件。

`local_pk` string

  如果使用独立的文件来存储证书（`local_cert`）和私钥， 那么使用此选项来指明私钥文件的路径。

`passphrase` string

  `local_cert` 文件的密码。

`verify_depth` int

  如果证书链条层次太深，超过了本选项的设定值，则终止验证。

  默认情况下不限制证书链条层次深度。

`ciphers` string

  设置可用的密码列表。 可用的值参见： » ciphers(1)。

  默认值为 `DEFAULT`.

`capture_peer_cert` bool

  如果设置为 `true` 将会在上下文中创建 `peer_certificate` 选项， 该选项中包含远端证书。

`capture_peer_cert_chain` bool

  如果设置为 `true` 将会在上下文中创建 `peer_certificate_chain` 选项， 该选项中包含远端证书链条。

`SNI_enabled` bool

  设置为 `true` 将启用服务器名称指示（server name indication）。 启用 SNI 将允许同一 IP 地址使用多个证书。

`disable_compression` bool

  如果设置，则禁用 TLS 压缩，有助于减轻恶意攻击。

`peer_fingerprint` string | array

  当远程服务器证书的摘要和指定的散列值不相同的时候， 终止操作。

  当使用 string 时， 会根据字符串的长度来检测所使用的散列算法：“md5”（32 字节）还是“sha1”（40 字节）。

  当使用 array 时， 数组的键表示散列算法名称，其对应的值是预期的摘要值。

`security_level` int

  设置安全级别。如果未指定，则使用库默认安全级别。 安全级别说明请参考 » SSL_CTX_get_security_level(3)。

  从 PHP 7.2.0 和 OpenSSL 1.1.0 开始可用。

### 更新日志

版本 | 说明
--- | ---
7.2.0 | 添加了 `security_level`。 需要 OpenSSL >= 1.1.0。

### 注释

> 注意: 因为 `ssl://` 是 `https://` 和 `ftps://` 的底层传输协议， 所以，`ssl://` 的上下文选项也同样适用于 `https://` 和 `ftps://` 上下文。

> 注意: PHP 必须联合 OpenSSL 0.9.8j 或以上版本编译才可以支持 SNI， 同时也支持使用 `OPENSSL_TLSEXT_SERVER_NAME` 来探测 SNI 服务器名称。

### 参见

- 套接字上下文选项

# Phar 上下文（context）选项

Phar 上下文（context）选项 — Phar 上下文（context）选项列表

### 说明

`phar://` 封装（wrapper）的上下文（context）选项。

### 可选项

`compress` int

  Phar 压缩常量中的一个。

`metadata` mixed

  Phar 元数据（metadata）。查看 Phar::setMetadata()。

### 参见

- phar://
- Phar stream wrapper

# Context 参数

Context 参数 — Context 参数列表

### 说明

这些参数（`parameters`）可以设置为由函数 stream_context_set_params() 返回的 `context`。

### 参数

`notification` callable

  当一个流（stream）上发生事件时，callable 将被调用。

  查看 stream_notification_callback 以获得更多信息。

# Zip 上下文选项

Zip 上下文选项 — Zip 上下文选项列表

### 说明

Zip 上下文选项可用于 `zip` 包装器。

### 可选项

`password`

  用于指定加密归档的密码。

### 更新日志

版本 | 说明
--- | ---
7.2.0，PECL zip 1.14.0 | 添加 `password`。

### 示例

示例 #1 基础 `password` 用法示例

    <?php
    // 读取加密归档
    $opts = array(
        'zip' => array(
            'password' => 'secret',
        ),
    );
    // 创建上下文...
    $context = stream_context_create($opts);

    // ...并且使用它读取数据
    echo file_get_contents('zip://test.zip#test.txt', false, $context);

    ?>

# Zlib 上下文选项

Zlib 上下文选项 — Zlib 上下文选项列表

### 说明

Zlib 上下文选项可用于 `zlib` 封装协议。

### 可选项

`level`

  用于指定压缩级别（`0` - `9`）。

### 更新日志

版本 | 说明
--- | ---
7.3.0 | 新增 `level`。

## 目录

- 套接字上下文选项 — 套接字上下文选项列表
- HTTP context 选项 — HTTP context 的选项列表
- FTP 上下文选项 — FTP 上下文选项列表
- SSL 上下文选项 — SSL 上下文选项清单
- Phar 上下文（context）选项 — Phar 上下文（context）选项列表
- Context 参数 — Context 参数列表
- Zip 上下文选项 — Zip 上下文选项列表
- Zlib 上下文选项 — Zlib 上下文选项列表

# 支持的协议和封装协议

PHP 带有很多内置 URL 风格的封装协议，可用于类似 fopen()、 copy()、 file_exists() 和 filesize() 的文件系统函数。 除了这些封装协议，还能通过 stream_wrapper_register() 来注册自定义的封装协议。

> 注意: 用于描述一个封装协议的 URL 语法仅支持 `scheme://...` 的语法。 `scheme:/` 和 `scheme:` 语法是不支持的。

# file://

file:// — 访问本地文件系统

### 说明

`file://` 是 PHP 默认使用的封装器，表示本地文件系统。 当指定相对路径（不以 `/`、`\`、`\\` 或 Windows 驱动器号开头）时， 提供的路径将应用于当前工作目录。在许多情况下，这是脚本所在的目录，除非已更改。 使用 CLI SAPI 时，默认为从调用脚本的目录。

在某些函数里，例如 fopen() 和 file_get_contents()，`include_path` 可能也会被搜索相对路径。

### 用法

- /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

### 可选项

封装协议概要
属性 | 支持
--- | ---
受 allow_url_fopen 影响 | No
允许读取 | Yes
允许写入 | Yes
允许添加 | Yes
允许同时读和写 | Yes
支持 stat() | Yes
支持 unlink() | Yes
支持 rename() | Yes
支持 mkdir() | Yes
支持 rmdir() | Yes

# http://

# https://

http:// -- https:// — 访问 HTTP(s) 网址

### 说明

允许通过 HTTP 对文件/资源进行可读访问。默认使用 HTTP 1.0 GET。 HTTP 请求会附带一个 `Host:` 头，用于兼容基于域名的虚拟主机。 如果在你的 php.ini 文件中或字节流上下文（context）配置了 user_agent 字符串，它也会被包含在请求之中。

数据流允许读取资源的 body，而 headers 则储存在了 $http_response_header 变量里。

如果需要知道文档资源来自哪个 URL（经过所有重定向的处理后）， 需要处理数据流返回的系列响应报头（response headers）。

The from directive will be used for the `From:` header if set and not overwritten by the 上下文（Context）选项和参数.

### 用法

- 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

### 可选项

封装协议概要
属性 | 支持
--- | ---
受 allow_url_fopen 限制 | Yes
允许读取 | Yes
允许写入 | No
允许添加 | No
允许同时读和写 | N/A
支持 stat() | No
支持 unlink() | No
支持 rename() | No
支持 mkdir() | No
支持 rmdir() | No

### 示例

示例 #1 检测重定向后最终的 URL

    <?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) {

        /* 我们是否被重定向了？ */
        if (strtolower(substr($response, 0, 10)) == 'location: ') {

            /* 更新我们被重定向后的 $url */
            $url = substr($response, 10);
        }

    }

    ?>

### 注释

> 注意: openssl 扩展启用后才能够支持 HTTPS 协议。

HTTP 连接是只读的；还不支持对一个 HTTP 资源进行写数据或者复制文件。

比如发送 POST 和 PUT 请求， 可以在 HTTP Contexts 的支持下实现。

### 参见

- HTTP context 选项
- $http_response_header
- stream_get_meta_data() - 从流或文件指针中获取 header/meta 数据

# ftp://

# ftps://

ftp:// -- ftps:// — 访问 FTP(s) URLs

### 说明

允许通过 FTP 读取存在的文件，以及创建新文件。 如果服务器不支持被动（passive）模式的 FTP，连接会失败。

打开文件后你既可以读也可以写，但是不能同时进行。 当远程文件已经存在于 ftp 服务器上，如果尝试打开并写入文件的时候， 未指定上下文（context）选项 `overwrite`，连接会失败。 如果要通过 FTP 覆盖存在的文件， 指定上下文（context）的 `overwrite` 选项来打开、写入。 另外可使用 FTP 扩展来代替。

如果你设置了 php.ini 中的 from 指令， 这个值会作为匿名（anonymous）ftp 的密码。

### 用法

- 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

### 可选项

封装协议概要
属性 | 是否支持
--- | ---
受 allow_url_fopen 影响 | 是
允许读取 | 是
允许写入 | 是 (新文件/启用 `overwrite` 后已存在的文件)
允许添加 | 是
允许同时读和写 | 否
支持 stat() | 仅 filesize()、filemtime()、 filetype()、 file_exists()、 is_file() 和 is_dir()。
支持 unlink() | 是
支持 rename() | 是
支持 mkdir() | 是
支持 rmdir() | 是

### 注释

> 注意:

> FTPS 仅在 openssl 扩展开启时有效。

> 如果服务器不支持 SSL，这个连接会降级（falls back）到普通未加密的 ftp。

> 注意: 追加
> 文件可以通过 `ftp://` URL 封装器来追加（append）。

### 参见

- FTP 上下文选项

# php://

php:// — 访问各个输入/输出流（I/O streams）

### 说明

PHP 提供了一些杂项输入/输出（IO）流，允许访问 PHP 的输入输出流、标准输入输出和错误描述符， 内存中、磁盘备份的临时文件流以及可以操作其他读取写入文件资源的过滤器。

#### php://stdin, php://stdout 和 php://stderr

php://stdin、php://stdout 和 php://stderr 允许直接访问 PHP 进程相应的输入或者输出流。 数据流引用了复制的文件描述符，所以如果你打开 php://stdin 并在之后关了它， 仅是关闭了复制品，真正被引用的 `STDIN` 并不受影响。 推荐你简单使用常量 `STDIN`、 `STDOUT` 和 `STDERR` 来代替手工打开这些封装器。

php://stdin 是只读的， php://stdout 和 php://stderr 是只写的。

#### php://input

php://input 是个可以访问请求的原始数据的只读流。 如果启用了 enable_post_data_reading 选项， php://input 在使用 `enctype="multipart/form-data"` 的 POST 请求中不可用。

#### php://output

php://output 是一个只写的数据流， 允许你以 print 和 echo 一样的方式 写入到输出缓冲区。

#### php://fd

php://fd 允许直接访问指定的文件描述符。 例如 php://fd/3 引用了文件描述符 3。

#### php://memory 和 php://temp

php://memory 和 php://temp 是一个类似文件 包装器的数据流，允许读写临时数据。 两者的一个区别是 php://memory 总是把数据储存在内存中， 而 php://temp 会在内存量达到预定义的限制后（默认是 2MB）存入临时文件中。 临时文件位置的决定和 sys_get_temp_dir() 的方式一致。

php://temp 的内存限制可通过添加 `/maxmemory:NN` 来控制，`NN` 是以字节为单位、保留在内存的最大数据量，超过则使用临时文件。

警告

某些 PHP 扩展可能需要标准 IO 流，并且可能尝试将指定流转换为标准 IO 流。对于内存流，此转换可能会失败，因为需要 C fopencookie() 函数可以调用。此 C 函数在 Windows 上无效。

#### php://filter

php://filter 是一种元封装器， 设计用于数据流打开时的筛选过滤应用。 这对于一体式（all-in-one）的文件函数非常有用，类似 readfile()、 file() 和 file_get_contents()， 在数据流内容读取之前没有机会应用其他过滤器。

php://filter 目标使用以下的参数作为它路径的一部分。 复合过滤链能够在一个路径上指定。详细使用这些参数可以参考具体范例。

php://filter 参数
名称 | 描述
--- | ---
`resource=<要过滤的数据流>` | 这个参数是必须的。它指定了你要筛选过滤的数据流。
`read=<读链的筛选列表>` | 该参数可选。可以设定一个或多个过滤器名称，以管道符（`|`）分隔。
`write=<写链的筛选列表>` | 该参数可选。可以设定一个或多个过滤器名称，以管道符（`|`）分隔。
`<；两个链的筛选列表>` | 任何没有以 `read=` 或 `write=` 作前缀 的筛选器列表会视情况应用于读或写链。

### 可选项

封装协议摘要（针对 `php://filter`，参考被筛选的封装器。）
属性 | 支持
--- | ---
受限于 allow_url_fopen | No
受限于 allow_url_include | 仅 `php://input`、 `php://stdin`、 `php://memory` 和 `php://temp`。
允许读取 | 仅 `php://stdin`、 `php://input`、 `php://fd`、 `php://memory` 和 `php://temp`。
允许写入 | 仅 `php://stdout`、 `php://stderr`、 `php://output`、 `php://fd`、 `php://memory` 和 `php://temp`。
允许追加 | 仅 `php://stdout`、 `php://stderr`、 `php://output`、 `php://fd`、 `php://memory` 和 `php://temp`（等于写入）
允许同时读写 | 仅 `php://fd`、 `php://memory` 和 `php://temp`。
支持 stat() | 不支持。不过，`php://memory` 和 `php://temp` 支持 fstat()。
支持 unlink() | No
支持 rename() | No
支持 mkdir() | No
支持 rmdir() | No
仅仅支持 stream_select() | `php://stdin`、 `php://stdout`、 `php://stderr`、 `php://fd` 和 `php://temp`。

### 示例

示例 #1 php://temp/maxmemory

这个可选选项允许设置 php://temp 开始使用临时文件前的最大内存限制。

    <?php
    // 限制内存为 5 MB。
    $fiveMBs = 5 * 1024 * 1024;
    $fp = fopen("php://temp/maxmemory:$fiveMBs", 'r+');

    fputs($fp, "hello\n");

    // 读取刚才写入的内容。
    rewind($fp);
    echo stream_get_contents($fp);
    ?>

示例 #2 php://filter/resource=<待过滤的数据流>

这个参数必须位于 php://filter 的末尾，并且指向需要过滤筛选的数据流。

    <?php
    /* 这简单等同于：
      readfile("http://www.example.com");
      实际上没有指定过滤器 */

    readfile("php://filter/resource=http://www.example.com");
    ?>

示例 #3 php://filter/read=<读链需要应用的过滤器列表>

这个参数采用一个或以管道符 `|` 分隔的多个过滤器名称。

    <?php
    /* 这会以大写字母输出 www.example.com 的全部内容 */
    readfile("php://filter/read=string.toupper/resource=http://www.example.com");

    /* 这会和以上所做的一样，但还会用 ROT13 加密。 */
    readfile("php://filter/read=string.toupper|string.rot13/resource=http://www.example.com");
    ?>

示例 #4 php://filter/write=<写链需要应用的过滤器列表>

这个参数采用一个或以管道符 `|` 分隔的多个过滤器名称。

    <?php
    /* 这会通过 rot13 过滤器筛选出字符 "Hello World"
      然后写入当前目录下的 example.txt */
    file_put_contents("php://filter/write=string.rot13/resource=example.txt","Hello World");
    ?>

示例 #5 php://memory 和 php://temp 是一次性的

php://memory 和 php://temp 是一次性的，比如：stream 流关闭后，就无法再次得到以前的内容了。

    <?php
    file_put_contents('php://memory', 'PHP');
    echo file_get_contents('php://memory'); // 啥也没有

示例 #6 php://input 从请求体中读取 JSON 数据

此例演示了如何使用 php://input 读取 POST、PUT 和 PATCH 请求中的原始 JSON 数据。

    <?php
    $input = file_get_contents("php://input");
    $json_array = json_decode(
      json: $input,
      associative: true,
      flags: JSON_THROW_ON_ERROR
    );

    echo "Received JSON data: ";
    print_r($json_array);
    ?>

# zlib://

# bzip2://

# zip://

zlib:// -- bzip2:// -- zip:// — 压缩流

### 说明

compress.zlib:// and compress.bzip2://

zlib: 的功能类似 gzopen()，但是 其数据流还能被 fread() 和其他文件系统函数使用。 不建议使用，因为会和其他带“:”字符的文件名混淆； 请使用 compress.zlib:// 替代。

compress.zlib://、 compress.bzip2:// 和 gzopen()、bzopen() 是相等的。并且可以在不支持 fopencookie 的系统中使用。

ZIP 扩展 注册了 zip: 封装器。 自 PHP 7.2.0 和 libzip 1.2.0+ 起，加密归档开始支持密码，允许数据流中使用密码。 字节流上下文（stream contexts）中使用 `'password'` 选项设置密码。

### 可选项

- compress.zlib://file.gz
- compress.bzip2://file.bz2
- zip://archive.zip#dir/file.txt

### 用法

封装协议摘要
属性 | 支持
--- | ---
受限于 allow_url_fopen | No
允许读取 | Yes
允许写入 | Yes（除了 `zip://`）
允许附加 | Yes（除了 `zip://`）
允许同时读写 | No
支持 stat() | No，请使用普通的 `file://` 封装器统计压缩文件。
支持 unlink() | No，请使用 `file://` 封装器删除压缩文件。
支持 rename() | No
支持 mkdir() | No
支持 rmdir() | No

### 参见

- Zlib 上下文选项

# data://

data:// — 数据（RFC 2397）

### 说明

data:（» RFC 2397）数据流封装器。

### 用法

- data://text/plain;base64,

### 可选项

封装协议摘要
属性 | 支持
--- | ---
受限于 allow_url_fopen | Yes
受限于 allow_url_include | Yes
允许读取 | Yes
允许写入 | No
允许追加 | No
允许同时读写 | No
支持 stat() | No
支持 unlink() | No
支持 rename() | No
支持 mkdir() | No
支持 rmdir() | No

### 示例

示例 #1 打印 data:// 的内容

    <?php
    // 打印 "I love PHP"
    echo file_get_contents('data://text/plain;base64,SSBsb3ZlIFBIUAo=');
    ?>

示例 #2 获取媒体类型

    <?php
    $fp   = fopen('data://text/plain;base64,', 'r');
    $meta = stream_get_meta_data($fp);

    // 打印 "text/plain"
    echo $meta['mediatype'];
    ?>

# glob://

glob:// — 查找匹配的文件路径模式

### 说明

glob: 数据流包装器。

### 用法

- glob://

### 可选项

封装协议摘要
属性 | 支持
--- | ---
受限于 allow_url_fopen | No
受限于 allow_url_include | No
允许读取 | No
允许写入 | No
允许附加 | No
允许同时读写 | No
支持 stat() | No
支持 unlink() | No
支持 rename() | No
支持 mkdir() | No
支持 rmdir() | No

### 示例

示例 #1 基本用法

    <?php
    // 循环 ext/spl/examples/ 目录里所有 *.php 文件
    // 并打印文件名和文件尺寸
    $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 归档

### 说明

phar:// 数据流包装器。详细的描述可参见 Phar 数据流包装器。

### 用法

- phar://

### 可选项

封装协议摘要
属性 | 支持
--- | ---
支持 allow_url_fopen | No
支持 allow_url_include | No
允许读取 | Yes
允许写入 | Yes
允许附加 | No
允许同时读写 | Yes
支持 stat() | Yes
支持 unlink() | Yes
支持 rename() | Yes
支持 mkdir() | Yes
支持 rmdir() | Yes

### 参见

- Phar 上下文（context）选项

# ssh2://

ssh2:// — 安全外壳协议 2

### 说明

ssh2.shell:// ssh2.exec:// ssh2.tunnel:// ssh2.sftp:// ssh2.scp:// (PECL)

> 注意: 该封装器默认没有激活
> 为了使用 ssh2.*:// 封装协议，必须从 » PECL 中安装有效的 » SSH2 扩展。

除了支持传统的 URI 登录信息，ssh2 封装协议也支持通过 URL 的主机（host）部分来复用打开连接。

### 用法

- 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

### 可选项

封装协议概要
属性 | ssh2.shell | ssh2.exec | ssh2.tunnel | ssh2.sftp | ssh2.scp
--- | --- | --- | --- | --- | ---
受 allow_url_fopen 影响 | Yes | Yes | Yes | Yes | Yes
允许读取 | Yes | Yes | Yes | Yes | Yes
允许写入 | Yes | Yes | Yes | Yes | No
允许追加 | No | No | No | Yes（当服务器支持的时候） | No
允许同时读和写 | Yes | Yes | Yes | Yes | No
支持 stat() | No | No | No | Yes | No
支持 unlink() | No | No | No | Yes | No
支持 rename() | No | No | No | Yes | No
支持 mkdir() | No | No | No | Yes | No
支持 rmdir() | No | No | No | Yes | No

上下文选项（Context）
名称 | 用法 | 默认
--- | --- | ---
`session` | 重复使用预连接的 ssh2 资源 |
`sftp` | 重复使用预先分配的 sftp 资源 |
`methods` | 密钥交换（key exchange）、主机密钥（hostkey）、cipher、压缩和 MAC 方法 |
`callbacks` |  |
`username` | 以该用户名连接 |
`password` | 使用的密码来进行密码验证 |
`pubkey_file` | 用于验证的公钥（public key）文件 |
`privkey_file` | 用于验证的私钥（private key）文件 |
`env` | 需要设置的环境变量的关联数组 |
`term` | 在分配一个 pty 时请求的终端类型 |
`term_width` | 在分配一个 pty 时请求的终端宽度 |
`term_height` | 在分配一个 pty 时请求的终端宽度高度 |
`term_units` | term_width 和 term_height 的单位 | `SSH2_TERM_UNIT_CHARS`

### 示例

示例 #1 从一个活跃的连接中打开流

    <?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');
    ?>

示例 #2 $session 变量必须保持可用！

为了使用 ssh2.*://$session 封装协议， 必须保留 $session 资源变量。下面的代码就不会有预期的效果：

    <?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() 会关闭 session，因为 $connection_string 不保存对 $session 变量的引用，只是源自它的字符串转换。当离开（像函数）作用域隐性调用 unset() 时，也会发生这种情况。

# rar://

rar:// — RAR

### 说明

封装协议采用 url 编码，（相对/绝对）路径的 RAR 归档、一个可选的星号（`*`）、一个可选的井号（`#` ）和一个可选的存储在归档中的 url 编码条目名称。指定条目名称必须带有井号，条目名称开头的斜线是可选的。

该封装协议可以打开文件和目录。当打开目录时，星号会强制返回未编码的目录条目名称。如果不指定星号，将返回 URL 编码的目录条目名称 —— 这样做的原因是存在类似 URL 编码的文件名时，允许封装协议能够与内置方法（比如 RecursiveDirectoryIterator）一起正确使用。

如果不包含井号和条目名称部分，将会显示归档的根目录。与常规目录不同的是生成的流不会包含诸如修改时间之类的信息， 因为根目录不会存储在归档的条目中。当访问根目录时， RecursiveDirectoryIterator 与封装协议一起使用时需要在 ULR 中包含井号，以便正确构建子级 URL。

> 注意: 该封装协议不会默认启用
> 为了使用 rar:// 封装协议，必须从 » PECL 中安装有效的 » rar 扩展。

rar:// 自 PECL rar 3.0.0 起可用

### 用法

- rar://<url encoded archive name>[*][#[<url encoded entry name>]]

### 可选项

封装协议摘要
属性 | 支持
--- | ---
受限于 allow_url_fopen | No
受限于 allow_url_include | No
允许读取 | Yes
允许写入 | No
允许附加 | No
允许同时读写 | No
支持 stat() | Yes
支持 unlink() | No
支持 rename() | No
支持 mkdir() | No
支持 rmdir() | No

上下文选项
名称 | 用法 | 默认
--- | --- | ---
`open_password` | 用于加密归档报头的密码（如果有）。如果存在后者，WinRAR 将使用相同的密码作为报头密码加密所有文件， 因此对于带有加密报头的归档， `file_password` 将会被忽略。 |
`file_password` | 用于加密文件的密码（如果有）。如果报头也加密，这个选项将会被忽略以支持 `open_password`。 有两个选项的原因是为了支持可能会出现的报头和文件密码不同的归档。请注意，如果归档没有加密它的报头， `open_password` 将会忽略且必须使用此选项代替。 |
`volume_callback` | 确定缺失卷的路径回调。请参阅 RarArchive::open() 获取更多信息。 |

### 示例

示例 #1 遍历 RAR 归档

    <?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";
    }
    ?>

以上示例的输出类似于：

    |-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

示例 #2 打开加密文件（报头加密）

    <?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));
    /* 在 WinRAR 中创建日期和最后访问日期是可选的，
     * 因此大多数文件都没有 */
    var_dump(fstat($stream));
    ?>

以上示例的输出类似于：

    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:// — 音频流

### 说明

通过包装器 ogg:// 读取的文件， 是作为 `OGG/Vorbis` 格式的压缩音频编码。 同样，通过包装器 ogg:// 写入或追加的数据格式也是压缩音频。 当 stream_get_meta_data() 用于一个打开读取的 `OGG/Vorbis` 文件时，会返回关于数据流的详细信息，包含了 `vendor` 标签、任何内含的 `comments`、 `channels` 数字、采样率（`rate`），以及 用 `bitrate_lower`、`bitrate_upper`、 `bitrate_nominal` 和 `bitrate_window` 描述的可变比特率范围。

ogg:// （PECL）

> 注意: 该封装器默认未激活
> 要使用 ogg:// 封装协议，必须从 » PECL 中安装有效的 » OGG/Vorbis 扩展。

### 用法

- ogg://soundfile.ogg
- ogg:///path/to/soundfile.ogg
- ogg://http://www.example.com/path/to/soundstream.ogg

### 可选项

封装协议摘要
属性 | 支持
--- | ---
受限于 allow_url_fopen | No
允许读取 | Yes
允许写入 | Yes
允许附加 | Yes
允许同时读写 | No
支持 stat() | No
支持 unlink() | No
支持 rename() | No
支持 mkdir() | No
支持 rmdir() | No

上下文选项
名称 | 用法 | 默认 | 模式
--- | --- | --- | ---
`pcm_mode` | 读取时使用如下 PCM 编码之一: `OGGVORBIS_PCM_U8`、`OGGVORBIS_PCM_S8`、 `OGGVORBIS_PCM_U16_BE`、`OGGVORBIS_PCM_S16_BE`、 `OGGVORBIS_PCM_U16_LE` 和 `OGGVORBIS_PCM_S16_LE`。 (8 或 16 位，签名或未签名，大或小的 `endian`) | OGGVORBIS_PCM_S16_LE | 读取
`rate` | 输入数据的采样率，单位为 Hz | 44100 | 写入/附加
`bitrate` | 若给的值为整数，则是用固定的比特率进行编码。（16000 到 131072）若给的值为浮点数，则使用可变的比特率（质。(-1.0 到 1.0） | 128000 | 写入/附加
`channels` | 要编码的声道的数量，典型为 1 (单声道), 或 2 (立体声)。最高支持 16 声道。 | 2 | 写入/附加
`comments` | 编码到音轨头部的字符串数组。 |  | 写入/附加

# expect://

expect:// — 处理交互式的流

### 说明

由 expect:// 封装协议打开的数据流 PTY 通过提供了对进程 stdio、stdout 和 stderr 的访问。

> 注意: 该封装协议默认未开启
> 为了使用 expect:// 封装协议，必须从 » PECL 中安装有效的 » Expect 扩展。

expect:// (PECL)

### 用法

- expect://command

### 可选项

封装协议概要
属性 | 支持
--- | ---
受 allow_url_fopen 影响 | No
允许读取 | Yes
允许写入 | Yes
允许添加 | Yes
允许同时读和写 | No
支持 stat() | No
支持 unlink() | No
支持 rename() | No
支持 mkdir() | No
支持 rmdir() | No

## 目录

- file:// — 访问本地文件系统
- http:// — 访问 HTTP(s) 网址
- ftp:// — 访问 FTP(s) URLs
- php:// — 访问各个输入/输出流（I/O streams）
- zlib:// — 压缩流
- data:// — 数据（RFC 2397）
- glob:// — 查找匹配的文件路径模式
- phar:// — PHP 归档
- ssh2:// — 安全外壳协议 2
- rar:// — RAR
- ogg:// — 音频流
- expect:// — 处理交互式的流

- 基本语法
  - PHP 标签
  - 从 HTML 中分离
  - 指令分隔符
  - 注释
- 类型
  - 简介
  - 类型系统
  - NULL
  - Boolean 布尔类型
  - Integer 整型
  - Float 浮点型
  - String 字符串
  - 数字字符串
  - Array 数组
  - Object 对象
  - Enum 枚举
  - Resource 资源类型
  - Callable
  - Mixed
  - Void
  - Never
  - 相对类类型
  - 单例类型
  - Iterable 可迭代对象
  - 类型声明
  - 类型转换
- 变量
  - 基础
  - 预定义变量
  - 变量作用域
  - 可变变量
  - 来自 PHP 之外的变量
- 常量
  - 语法
  - 预定义常量
  - 魔术常量
- 表达式
- 运算符
  - 运算符优先级
  - 算术 — 算术运算符
  - 递增/递减 — 递增/递减运算符
  - 赋值 — 赋值运算符
  - 位 — 位运算符
  - 比较 — 比较运算符
  - 错误控制 — 错误控制运算符
  - 执行 — 执行运算符
  - 逻辑 — 逻辑运算符
  - 字符串 — 字符串运算符
  - 数组 — 数组运算符
  - 类型 — 类型运算符
  - 函数式 — 函数式运算符
- 流程控制
  - 简介
  - if
  - else
  - elseif/else if
  - 流程控制的替代语法
  - while
  - do-while
  - for
  - foreach
  - break
  - continue
  - switch
  - match
  - declare
  - return
  - require
  - include
  - require_once
  - include_once
  - goto
- 函数
  - 用户自定义函数
  - 函数的参数和参数值
  - 返回值
  - 可变函数
  - 内部（内置）函数
  - 匿名函数
  - 箭头函数
  - 一级可调用语法
- 类与对象
  - 简介
  - 基本概念
  - 属性
  - 属性挂钩
  - 类常量
  - 类的自动加载
  - 构造函数和析构函数
  - 访问控制（可见性）
  - 对象继承
  - 范围解析操作符 （::）
  - 静态（static）关键字
  - 抽象类
  - 对象接口
  - Trait
  - 匿名类
  - 重载
  - 遍历对象
  - 魔术方法
  - Final 关键字
  - 对象复制
  - 对象比较
  - 后期静态绑定
  - 对象和引用
  - 对象序列化 — 序列化对象 - 在会话中存放对象
  - 协变与逆变
  - 延迟对象
  - OOP 变更日志
- 概述 — 命名空间概述
  - 命名空间概述
  - 命名空间 — 定义命名空间
  - 子命名空间 — 定义子命名空间
  - 在一个文件中定义多个命名空间 — 在同一个文件中定义多个命名空间
  - 基础 — 使用命名空间：基础
  - 命名空间和动态语言特征
  - namespace 关键字和 __NAMESPACE__ — namespace 关键字和 __NAMESPACE__ 魔术常量
  - 别名和导入 — 使用命名空间：别名/导入
  - 全局空间
  - 回退到全局空间 — 使用命名空间：回退到全局函数和常量的全局空间
  - 名称解析规则
  - FAQ — FAQ：命名空间必知必会
- 枚举
  - 枚举概览
  - 枚举基础
  - 带值（回退）枚举
  - 枚举方法
  - 枚举静态方法
  - 枚举常量
  - Trait
  - 常量表达式的枚举值
  - 和对象的差异
  - 枚举值清单
  - 序列化
  - 为什么枚举不可扩展
  - 示例
- 错误
  - 基础概要
  - PHP 7 错误处理
- 异常
  - 扩展（extend）异常处理类
- 纤程
- 生成器
  - 生成器总览
  - 生成器语法
  - 生成器与 Iterator 对象的比较
- 注解
  - 注解概览
  - 注解语法
  - 使用反射 API 读取注解
  - 声明注解类
- 引用的解释
  - 引用是什么
  - 引用做什么
  - 引用不是什么
  - 引用传递
  - 引用返回
  - 取消引用
  - 引用定位
- 预定义变量
  - 超全局变量 — 在全部作用域中始终可用的内置变量
  - $GLOBALS — 引用全局作用域中可用的全部变量
  - $_SERVER — 服务器和执行环境信息
  - $_GET — 查询字符串变量
  - $_POST — 来自 HTTP POST 请求的表单数据
  - $_FILES — HTTP 文件上传变量
  - $_REQUEST — HTTP Request 变量
  - $_SESSION — Session 变量
  - $_ENV — 环境变量
  - $_COOKIE — HTTP Cookies
  - $php_errormsg — 前一个错误信息
  - $http_response_header — HTTP 响应头
  - $argc — 传递给脚本的参数数目
  - $argv — 传递给脚本的参数数组
- 预定义异常
  - Exception
  - ErrorException
  - ClosedGeneratorException — ClosedGeneratorException 类
  - Error
  - ArgumentCountError
  - ArithmeticError
  - AssertionError
  - DivisionByZeroError
  - CompileError
  - ParseError
  - TypeError
  - ValueError
  - UnhandledMatchError
  - FiberError
  - RequestParseBodyException
- 预定义接口和类
  - Traversable — Traversable （遍历）接口
  - Iterator — Iterator（迭代器）接口
  - IteratorAggregate — IteratorAggregate（聚合式迭代器）接口
  - InternalIterator — InternalIterator 类
  - Throwable
  - Countable — Countable 接口
  - ArrayAccess — ArrayAccess（数组式访问）接口
  - Serializable — Serializable 接口
  - Closure — Closure 类
  - stdClass — stdClass 类
  - Generator — 生成器类
  - Fiber — 纤程（Fiber）类
  - WeakReference — WeakReference 类
  - WeakMap — WeakMap 类
  - Stringable — Stringable 接口
  - UnitEnum — UnitEnum 接口
  - BackedEnum — BackedEnum 接口
  - SensitiveParameterValue — SensitiveParameterValue 类
  - __PHP_Incomplete_Class — __PHP_Incomplete_Class 类
- 预定义注解
  - Attribute — Attribute 属性
  - AllowDynamicProperties — AllowDynamicProperties 注解
  - Deprecated — Deprecated 属性
  - Override — Override 注解
  - ReturnTypeWillChange — ReturnTypeWillChange 注解
  - SensitiveParameter — SensitiveParameter 注解
- 上下文（Context）选项和参数
  - 套接字上下文选项 — 套接字上下文选项列表
  - HTTP context 选项 — HTTP context 的选项列表
  - FTP 上下文选项 — FTP 上下文选项列表
  - SSL 上下文选项 — SSL 上下文选项清单
  - Phar 上下文（context）选项 — Phar 上下文（context）选项列表
  - Context 参数 — Context 参数列表
  - Zip 上下文选项 — Zip 上下文选项列表
  - Zlib 上下文选项 — Zlib 上下文选项列表
- 支持的协议和封装协议
  - file:// — 访问本地文件系统
  - http:// — 访问 HTTP(s) 网址
  - ftp:// — 访问 FTP(s) URLs
  - php:// — 访问各个输入/输出流（I/O streams）
  - zlib:// — 压缩流
  - data:// — 数据（RFC 2397）
  - glob:// — 查找匹配的文件路径模式
  - phar:// — PHP 归档
  - ssh2:// — 安全外壳协议 2
  - rar:// — RAR
  - ogg:// — 音频流
  - expect:// — 处理交互式的流

# 安全

# 简介

PHP 作为一种强大的语言和解析器，无论是作为包含在 Web 服务器中的模块还是作为单独的 CGI 二进制文件执行，它都可以在服务器上访问文件、运行命令以及创建网络连接等。 默认情况下，这些功能会使 web 服务器运行的任何内容变得不安全。 PHP 专门设计为一种比 Perl 或者 C 编写 CGI 程序更安全的语言，并且正确选择编译时和运行时配置选项以及正确的编码实践，它可以同时满足所需的自由和安全。

由于使用 PHP 有很多不同的方式，因此有很多配置选项来控制其行为。大量选项保证可以将 PHP 用于多种用途，但是这也意味着这些选项和服务器配置的组合会导致设置不安全。

PHP 配置的灵活性与代码的灵活性不相上下。Shell 用户具备的所有服务器端应用功能，PHP 同样也能构建完整。也可以在严格控制的环境中用于简单的服务器端包含，具有很小的风险。 环境如何构建、安全性如何，很大程度上取决于 PHP 开发者。

本章以一些常规的安全建议作为开始，解释了不同配置选项组合以及可以安全使用的情况， 并描述了不同安全级别进行编码时的不同注意事项。

# 总则

绝对安全的系统是不存在的，因此安全业界常用的方法有助于平衡可用性和风险。对用户提交的每一个变量都进行双重验证可能是一个很负责任的行为，但会导致用户必须花很多时间去填写一张复杂无比的表格，从而迫使某些用户尝试绕过安全机制。

最好的安全机制应该能在不防碍用户，并且不过多地增加开发难度的情况下做到能满足需求。实际上，一些安全问题往往会发生在这种过度强化安全机制的系统上。

不要忘记著名的等强原则：一个系统的强度是由它最薄弱的环节决定的（译者注：相当于木桶原理）。如果所有的事务都基于时间、地点、事务种类进行详细的记录，而用户验证却只依靠一个 cookie，那么用户所对应的事务记录的可信度就被大大削弱了。

调试代码的时候一定要记住，就算是一个简单的页面也很难对所有可能发生的情况进行检测：对你不满的雇员不一定会输入如你所愿的东西，黑客也有足够的时间研究你的系统，当然，你的宠物猫也会跳到你的键盘上。这就是为什么必须检查所有的代码，去发现哪里可以引入不正当的数据，然后对代码改进、简化或者增强。

互联网上充满了为了成名而破坏你的代码、攻击你的网站并输入不正当数据的人，总之他们会使你的生活充满乐趣。无论是大网站还是小网站，只要能和互联网连接，就会成为一个目标。很多黑客程序并不理会网站的大小，只会机械地扫描 IP 地址并找寻受害者。我们希望那个不要是你。

# 以 CGI 模式安装时

## 目录

- 可能受到的攻击
- 情形一：只运行公开的文件
- 情形二：使用 cgi.force_redirect
- 情形三：设置 doc_root 或 user_dir
- 情形四：PHP 解释器放在 web 目录以外

## 可能受到的攻击

如果不想把 PHP 嵌入到服务器端软件（如 Apache）作为一个模块安装的话，可以选择以 CGI 的模式安装。或者把 PHP 用于不同的 CGI 封装以便为代码创建安全的 chroot 和 setuid 环境。这种安装方式通常会把 php 的可执行文件安装到 web 服务器的 cgi-bin 目录。CERT 建议书 » CA-96.11 建议不要把任何的解释器放到 cgi-bin 目录。尽管 php 可以作为一个独立的解释器，但是它的设计使它可以防止下面类型的攻击：

- 访问系统文件：http://my.host/cgi-bin/php?/etc/passwd 在 URL 请求的问号（`?`）后面的信息会传给 CGI 接口作为命令行的参数。其它的解释器会在命令行中打开并执行第一个参数所指定的文件。 当作为 CGI 二进制文件调用时，php 会拒绝解释命令行参数。
- 访问服务器上的任意 Web 文档：http://my.host/cgi-bin/php/secret/doc.html URL 中位于 PHP 二进制名称后面的路径信息 /secret/doc.html，通常用于指定由 CGI 程序打开和解释的文件名。通常一些 web 服务器配置指令（Apache：`Action`）用于将 URL （如 http://my.host/secret/script.php）重定向请求到 PHP 解释器。使用此设置，Web 服务器会先检查目录 /secret 的访问权限，然后创建 http://my.host/cgi-bin/php/secret/script.php 的重定向请求。不幸的是，如果请求最初是这种形式发出的，那么 Web 服务器不会对文件 /secret/script.php 进行任何访问检查，而只会对 /cgi-bin/php 进行访问检查。 这样任何能访问 /cgi-bin/php 的用户都可以访问 web 服务器上任何受保护的文档。 在 PHP 里，运行时配置指令 cgi.force_redirect、 doc_root 和 user_dir 都可以为服务器上的文件和目录添加限制，用于防止这类攻击。下面将对各个选项的设置进行详细讲解。

## 情形一：只运行公开的文件

如果 web 服务器中所有内容都受到密码或 IP 地址的访问限制，就不需要设置这些选项。如果 web 服务器不支持重定向，或者 web 服务器不能和 PHP 通信而使访问请求变得更为安全，可以开启 cgi.force_redirect ini 指令。除此之外，还要确认 PHP 程序不依赖其它方式调用，比如通过直接的 http://my.host/cgi-bin/php/dir/script.php 访问或通过重定向访问 http://my.host/dir/script.php。

在Apache中，重定向可以使用 `AddHandler` 和 `Action` 语句来设置，请看下一节。

## 情形二：使用 `cgi.force_redirect`

配置指令 cgi.force_redirect 可以防止任何人通过如 http://my.host/cgi-bin/php/secretdir/script.php 这样的 URL 直接调用 php。PHP 在此模式下只会解析已经通过了 web 服务器的重定向规则的 URL。

通常 Apache 中的重定向设置可以通过以下指令完成：

    Action php-script /cgi-bin/php
    AddHandler php-script .php

此选项只在 Apache 下进行过测试，并且要依赖于 Apache 在重定向操作中所设置的非标准 CGI 环境变量 REDIRECT_STATUS。如果 web 服务器不支持任何方式能够判断请求是直接的还是重定向的，就不能使用这个选项，而应该用其它方法。请看下一节。

## 情形三：设置 doc_root 或 user_dir

在 web 服务器的主文档目录中包含动态内容如脚本和可执行程序有时被认为是一种不安全的实践。如果因为配置上的错误而未能执行脚本而作为普通 HTML 文档显示，那就可能导致知识产权或密码资料的泄露。所以很多系统管理员都会专门设置一个只能通过 PHP CGI 来访问的目录，这样该目录中的内容只会被解析而不会原样显示出来。

对于前面所说无法判断是否重定向的情况，很有必要在主文档目录之外建立一个专用于脚本的 doc_root 目录。

可以通过配置文件内的 doc_root 指令或设置环境变量 PHP_DOCUMENT_ROOT 来定义 PHP 脚本主目录。如果设置了该项，那么 PHP 的 CGI 版本就只会解释 `doc_root` 目录下的文件，并确保目录外的脚本不会被 PHP 解释器执行（下面所说的 `user_dir` 除外）。

另一个可用的选项就是 user_dir。当 `user_dir` 没有设置的时候，`doc_root` 就是唯一能控制在哪里打开文件的选项。访问如 http://my.host/~user/doc.php 这个 URL 时，并不会打开用户主目录下文件，而只会执行 `doc_root` 目录下的 ~user/doc.php（这个子目录以 [`~`] 作开头）。

如果设置了 `user_dir`，例如 public_php，那么像 http://my.host/~user/doc.php 这样的请求将会执行用户主目录下的 public_php 子目录下的 doc.php 文件。假设用户主目录的绝对路径是 /home/user，那么被执行文件将会是 /home/user/public_php/doc.php。

`user_dir` 的设置与 `doc_root` 无关，所以可以分别控制 PHP 脚本的主目录和用户目录。

## 情形四：PHP 解释器放在 web 目录以外

一个非常安全的做法就是把 PHP 解释器放在 web 目录外的地方，比如说 /usr/local/bin。这样做唯一不便的地方就是必须在每一个包含 PHP 代码的文件的第一行加入如下语句：

    #!/usr/local/bin/php

还要将这些文件的属性改成可执行。也就是说，要像处理用 Perl 或 sh 或其它任何脚本语言写的 CGI 脚本一样，使用以 `#!` 开头的 shell-escape 机制来启动它们。

要使 PHP 能使用此设置正确处理 PATH_INFO 和 PATH_TRANSLATED 信息，需要开启 cgi.discard_path ini 指令。

# 以 Apache 模块安装时

当 PHP 以 Apache 模块方式安装时，它将继承 Apache 用户（通常为“nobody”）的权限。这对安全和认证有一些影响。比如，如果用 PHP 来访问数据库，除非数据库有自己的访问控制，否则就要使“nobody”用户可以访问数据库。这意味着恶意的脚本在不用提供用户名和密码时就可能访问和修改数据库。一个 web Spider 也完全有可能偶然发现数据库的管理页面，并且删除所有的数据库。可以通过 Apache 认证来避免此问题，或者用 LDAP、.htaccess 等技术来设计自己的访问模型，并把这些代码作为 PHP 脚本的一部份。

通常，一旦安全性达到可以使 PHP 用户（这里也就是 Apache 用户）承担的风险极小的程度时候，可能 PHP 已经到了阻止向用户目录写入任何文件或禁止访问和修改数据库的地步了。这就是说，无论是正常的文件还是非正常的文件，无论是正常的数据库事务还是恶意的请求，都会被拒之门外。

一个常犯的对安全性不利的错误就是让 Apache 拥有 root 权限，或者通过其它途径赋予 Apache 更强大的功能。

把 Apache 用户的权限提升为 root 是极度危险的做法，而且可能会危及到整个系统的安全。所以除非是安全专家，否则决不要考虑使用 su，chroot 或者以 root 权限运行。

除此之外还有一些比较简单的解决方案。比如说可以使用 open_basedir 来限制哪些目录可以被 PHP 使用。也可以设置 Apache 的专属区域，从而把所有的 web 活动都限制到非用户和非系统文件之中。

# 会话（Session）安全

保持 HTTP 会话管理的安全是重要的。会话安全相关内容描述章节在 Session 模块文档下的会话安全部分。

# 文件系统安全

## 目录

- 空字符（Null bytes）相关问题

PHP 受大多数服务器系统中文件和目录权限的内置安全机制的影响。 这允许控制文件系统中哪些文件是可读的。应该小心对待任何全局可读的文件， 要确保所有有权限访问该文件系统的用户都可以安全的读取文件。

PHP 被设计为以用户级别访问文件系统， 因此完全可以编写 PHP 脚本来读取系统文件，例如 /etc/passwd、 修改网络连接、发送大量打印任务等。这有一些明显的影响，因此需要确保读写的是合适的文件。

请看下面的脚本，用户表示想要删除自己主目录下的一个文件。 假设 PHP web 界面通常用于文件管理， 因此 Apache 用户允许删除用户主目录中的文件。

示例 #1 不对变量检查会导致....

    <?php

    // 从用户主目录移除一个文件
    $username = $_POST['user_submitted_name'];
    $userfile = $_POST['user_submitted_filename'];
    $homedir  = "/home/$username";

    unlink("$homedir/$userfile");

    echo "The file has been deleted!";

    ?>

由于 username 和 filename 由用户表单中提交，那就能提交属于其他人的 username 和 filename，甚至可以删除不被允许的文件。这种情况下， 应该使用一些其它形式的身份验证。不妨考虑一下，如果提交的变量是 `“../etc/”` 和 `“passwd”` 会发生什么。上面代码将等同于：

示例 #2 ... 文件系统攻击

    <?php

    // 删除磁盘中任何 PHP 有访问权限的文件。如果 PHP 有 root 权限：
    $username = $_POST['user_submitted_name']; // "../etc"
    $userfile = $_POST['user_submitted_filename']; // "passwd"
    $homedir  = "/home/$username"; // "/home/../etc"

    unlink("$homedir/$userfile"); // "/home/../etc/passwd"

    echo "The file has been deleted!";

    ?>

有两个重要措施来防止此类问题。

- PHP web 用户二进制文件仅允许有限的权限。
- 检查所有提交上来的变量。

这是改进的脚本：

示例 #3 更安全的文件名检查

    <?php

    // 删除磁盘中 PHP 有权访问的文件。
    $username = $_SERVER['REMOTE_USER']; // 使用认证机制
    $userfile = basename($_POST['user_submitted_filename']);
    $homedir  = "/home/$username";

    $filepath = "$homedir/$userfile";

    if (file_exists($filepath) && unlink($filepath)) {
        $logstring = "Deleted $filepath\n";
    } else {
        $logstring = "Failed to delete $filepath\n";
    }

    $fp = fopen("/home/logging/filedelete.log", "a");
    fwrite($fp, $logstring);
    fclose($fp);

    echo htmlentities($logstring, ENT_QUOTES);

    ?>

然而，这样做也是有缺陷的。如果认证系统允许用户创建自己的登录用户名， 而用户选择 `“../etc/”` 作为登录名，系统将再次暴露。 出于这个原因，需要编写自定义检查：

示例 #4 更安全的文件名检查

    <?php

    $username     = $_SERVER['REMOTE_USER']; // 使用认证机制
    $userfile     = $_POST['user_submitted_filename'];
    $homedir      = "/home/$username";

    $filepath     = "$homedir/$userfile";

    if (!ctype_alnum($username) || !preg_match('/^(?:[a-z0-9_-]|\.(?!\.))+$/iD', $userfile)) {
        die("Bad username/filename");
    }

    //等等...

    ?>

根据操作系统的不同，需要关心各种各样的文件，比如设备条目（/dev/ 或 COM1）、配置文件（/etc/ 文件和 `.ini` 文件）、 众所周知的文件存储区域（/home/，My Documents）等等。出于这个原因， 创建一个禁止所有权限而只开放明确允许的策略通常更容易些。

## 空字符（Null bytes）相关问题

由于 PHP 使用底层 C 函数进行文件系统相关操作，因此它可能会以完全意想不到的方式处理空字符。 在 C 语言中空字符标识字符串的结束，所以一个完整的字符串是从其开头到遇见空字符为止。 下面的示例展示了易受攻击的代码，演示了这个问题：

示例 #1 会被空字符攻击的代码

    <?php

    $file = $_GET['file']; // "../../etc/passwd\0"
    if (file_exists('/home/wwwrun/' . $file . '.php')) {
        // 当 /home/wwwrun/../../etc/passwd 文件存在的时候 file_exists 将会返回 true
        include '/home/wwwrun/' . $file . '.php';

        // 将会加载 /etc/passwd 文件
    }

    ?>

因此，在文件系统操作中都应该正确检查任何被污染的字符串。这是上个示例的改进版本：

示例 #2 验证输入的正确性

    <?php

    $file = $_GET['file'];

    // 对值进行白名单检查
    switch ($file) {
        case 'main':
        case 'foo':
        case 'bar':
            include '/home/wwwrun/include/' . $file . '.php';
            break;
        default:
            include '/home/wwwrun/include/main.php';
    }

    ?>

# 数据库安全

## 目录

- 设计数据库
- 连接数据库
- 加密存储模型
- SQL 注入

今时今日，数据库系统已经成为各个动态网站上 web 应用程序的重要组成部分。由于非常敏感和机密的数据有可能保存在数据库中，所以对数据库实施保护就显得尤为重要了。

要从数据库中提取或者存入数据，就必须经过连接数据库、发送一条合法查询、获取结果、关闭连接等步骤。目前，能完成这一系列动作的最常用的查询语言是结构化查询语言 Structured Query Language (SQL)。可以看看攻击者是如何篡改 SQL 查询语句的。

PHP 本身并不能保护数据库的安全。下面的章节只是讲述怎样用 PHP 脚本对数据库进行基本的访问和操作。

记住一条简单的原则：深入防御。保护数据库的措施越多，攻击者就越难获得和使用数据库内的信息。正确地设计和应用数据库可以减少被攻击的担忧。

## 设计数据库

第一步一般都是创建数据库，除非是使用第三方的数据库服务。当创建一个数据库的时候，会指定一个所有者来执行和新建语句。通常，只有所有者（或超级用户）才有权对数据库中的对象进行任意操作。如果想让其他用户使用，就必须赋予他们权限。

应用程序永远不要使用数据库所有者或超级用户帐号来连接数据库，因为这些帐号可以执行任意的操作，比如说修改数据库结构（例如删除一个表）或者清空整个数据库的内容。

应该为程序的每个方面创建不同的数据库帐号，并赋予对数据库对象的极有限的权限。仅分配给能完成其功能所需的权限，避免同一个用户可以完成另一个用户的事情。这样即使攻击者利用程序漏洞取得了数据库的访问权限，也最多只能做到和该程序一样的影响范围。

## 连接数据库

把连接建立在 SSL 加密技术上可以增加客户端和服务器端通信的安全性，或者 SSH 也可以用于加密客户端和数据库之间的连接。如果使用了这些技术的话，攻击者要监视服务器的通信或者得到数据库的信息是很困难的。

## 加密存储模型

SSL/SSH 能保护客户端和服务器端交换的数据，但 SSL/SSH 并不能保护数据库中已有的数据。SSL 只是一个加密网络数据流的协议。

如果攻击者取得了直接访问数据库的许可（绕过 web 服务器），敏感数据就可能暴露或者被滥用，除非数据库自己保护了这些信息。对数据库内的数据加密是减少这类风险的有效途径，但是只有很少的数据库提供这些加密功能。

解决这个问题最简单的方法是创建自己的加密包，然后在 PHP 脚本中使用它。PHP 可以通过一些扩展来帮助你解决这个问题，比如 OpenSSL 和 Sodium，涵盖了多种加密算法。脚本在将数据插入数据库之前对其进行加密，并在检索时对其进行解密。更多关于加密工作的例子请参见参考文献。

### 散列

对于真正隐藏的数据，如果不需要其原始表示形式（即不需要显示），应该考虑使用散列。 散列的典型例子是将密码的加密散列值存储在数据库中，而不是存储密码本身。

password 函数提供了一种便捷的方式来对敏感数据进行散列处理，并使用这些散列值进行验证。

password_hash() 用于使用当前可用的最强算法对给定字符串进行散列， password_verify() 用于检查给定密码是否与存储在数据库中的散列值匹配。

示例 #1 对密码字段进行散列

    <?php

    // 存储密码散列
    $query  = sprintf("INSERT INTO users(name,pwd) VALUES('%s','%s');",
                pg_escape_string($username),
                password_hash($password, PASSWORD_DEFAULT));
    $result = pg_query($connection, $query);

    // 发送请求来验证用户密码
    $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 'Welcome, ' . htmlspecialchars($username) . '!';
    } else {
        echo 'Authentication failed for ' . htmlspecialchars($username) . '.';
    }

    ?>

## SQL 注入

SQL 注入是一种攻击技术，攻击者利用应用程序代码中构建动态 SQL 查询的缺陷。攻击者可以访问应用程序的特权部分，从数据库检索所有信息，篡改现有数据，甚至在数据库主机上执行危险的系统级命令。当开发人员在他们的 SQL 语句中连接或插入任意输入时，这种漏洞就会发生。

示例 #1 将结果集切割成页面……并创建超级用户（PostgreSQL）。

在下面的示例中，用户输入直接插入到 SQL 查询中，使得攻击者能够在数据库中获得超级用户账户。

    <?php

    $offset = $_GET['offset']; // 注意，没有输入验证！
    $query  = "SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET $offset;";
    $result = pg_query($conn, $query);

    ?>

普通用户会点击“上一页”、“下一页”，$offset 已经编码到 URL 的链接。脚本期望传入的 $offset 是数字。然而，如果有人尝试把以下语句追加入 URL 中的话：

    0;
    insert into pg_shadow(usename,usesysid,usesuper,usecatupd,passwd)
        select 'crack', usesysid, 't','t','crack'
        from pg_shadow where usename='postgres';
    --

如果发生，脚本将向攻击者提供超级用户访问权限。注意那个 `0;` 是为了向原始查询提供有效的偏移量并终止。

> 注意:

> 这是常见的技术，使用 SQL 中的注释符号 `--`，强制 SQL 解析器忽略开发者编写的查询的其余部分。

获取密码的一种可行方式是欺骗搜索结果页面。攻击者只需查看是否有已提交的未经适当处理变量在 SQL 语句中使用。这些过滤器通常可以在先前的表单中设置，以定制 `SELECT` 语句中的 `WHERE、ORDER BY、LIMIT` 和 `OFFSET` 子句。如果数据库支持 `UNION` 构造，攻击者可能会尝试将整个查询附加到原始查询中，以从任意表中列出密码。强烈建议仅存储密码的安全散列值，而不是密码本身。

示例 #2 列出文章……以及一些密码（任何数据库服务器）

    <?php

    $query  = "SELECT id, name, inserted, size FROM products
               WHERE size = '$size'";
    $result = odbc_exec($conn, $query);

    ?>

查询的静态部分可以与另一个 `SELECT` 语句组合来显示所有密码：

    '
    union select '1', concat(uname||'-'||passwd) as name, '1971-01-01', '0' from usertable;
    --

`UPDATE` 和 `INSERT` 语句也容易受到这种攻击的影响。

示例 #3 从重置密码……到获得更多权限（任何数据库服务器）

    <?php
    $query = "UPDATE usertable SET pwd='$pwd' WHERE uid='$uid';";
    ?>

如果恶意的用户提交值 `' or uid like'%admin%` 给 $uid 来改变 admin 的密码，或者简单设置 $pwd 为 `hehehe', trusted=100, admin='yes` 去获得更多权限，然后查询语句实际上就变成了：

    <?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
    ...;";

    ?>

虽然攻击者必须具备至少一些关于数据库架构的知识才能进行成功的攻击，但获取这些信息通常非常简单。例如代码可以是开源软件的一部分并且公开可用。这些信息也可能通过闭源代码泄露 —— 即使它经过了编码、混淆或编译 —— 甚至通过自己的代码显示错误消息来泄露。其他方法包括使用典型的表名和列名。例如，使用 ”users” 表以及列名”id”、 ”username” 和 ”password” 的登录表单。

示例 #4 攻击数据库主机操作系统（MSSQL Server）

一种可怕的示例是一些数据库主机上可以访问操作系统级别的命令。

    <?php

    $query  = "SELECT * FROM products WHERE id LIKE '%$prod%'";
    $result = mssql_query($query);

    ?>

如果攻击者提交 `a%' exec master..xp_cmdshell 'net user test testpass /ADD' --` 作为变量 $prod 的值，那么 $query 将会变成

    <?php

    $query  = "SELECT * FROM products
               WHERE id LIKE '%a%'
               exec master..xp_cmdshell 'net user test testpass /ADD' --%'";
    $result = mssql_query($query);

    ?>

MSSQL Server 执行批处理中的 SQL 语句，其中包括向本地账户数据库添加新用户的命令。如果该应用程序以 `sa` 身份运行，并且 MSSQLSERVER 服务以足够的权限运行，则攻击者现在将拥有一个账户，可以用此账户访问这台机器。

> 注意:

> 以上的一些示例与特定的数据库服务器相关联，这并不意味着不能对其他产品进行类似的攻击。用户的数据库服务器可能以其他方式同样存在漏洞。

图片由 » xkcd 提供

### 预防措施

避免 SQL 注入的推荐方法是通过使用预处理语句绑定所有数据。仅仅使用参数化查询并不能完全避免 SQL 注入，但它是提供输入给 SQL 语句的最简单和最安全的方式。在 `WHERE`、`SET` 和 `VALUES` 子句中，所有动态数据常量都必须替换为占位符。实际数据将在执行过程中进行绑定，并与 SQL 命令分开发送。

参数绑定只能用于数据。SQL 查询的其他动态部分必须根据已知的允许值列表进行筛选。

示例 #5 通过使用 PDO 预处理语句来避免 SQL 注入

    <?php

    // 动态 SQL 部分根据预期值进行验证
    $sortingOrder = $_GET['sortingOrder'] === 'DESC' ? 'DESC' : 'ASC';
    $productId = $_GET['productId'];
    // 使用占位符准备 SQL
    $stmt = $pdo->prepare("SELECT * FROM products WHERE id LIKE ? ORDER BY price {$sortingOrder}");
    // 使用 LIKE 通配符提供值
    $stmt->execute(["%{$productId}%"]);

    ?>

预处理语句由 PDO、MySQLi 和其他数据库库提供。

SQL 注入攻击主要是基于利用代码在编写时没有考虑安全性。永远不要相信任何输入，特别是来自客户端的输入，即使它来自于选择框、隐藏的输入字段或 cookie。第一个示例表明，即使是如此简单的查询也可能带来灾难。

深度防御策略涉及几种良好的编程实践：

- 永远不要以超级用户或数据库所有者的身份连接到数据库。始终使用具有最低权限的自定义用户。
- 检查指定输入是否具有预期的数据类型。PHP 拥有很多输入验证函数，从最简单的变量函数和字符类型函数（例如 is_numeric()、ctype_digit()）到支持 Perl 兼容正则表达式的函数。
- 如果应用程序期望数字输入，可以考虑使用 ctype_digit() 验证数据，使用 settype()更改其类型，或者使用 sprintf() 打印其数字表示形式。
- 如果数据库层不支持绑定变量，则应使用特定于数据库的字符串转义函数（例如 mysql_real_escape_string()、sqlite_escape_string() 等）对传递给数据库的用户提供的非数字值进行转义。通用的函数如 addslashes() 只在非常特定的环境中有用（例如在禁用了 NO_BACKSLASH_ESCAPES 的单字节字符集 MySQL），因此最好避免使用它们。
- 请勿以正当或非正当手段打印出任何特定于数据库的信息，特别是关于 schema 的信息。另请参阅错误报告和错误处理以及日志记录函数。

除此之外，如果数据库支持日志记录，还可以从脚本里或通过数据库自身记录查询语句。显然，日志记录无法阻止任何有害尝试，但它可以帮助追踪绕过了哪个应用程序。日志本身并没有用处，但通过其中包含的信息可以得到帮助。通常情况下，更详细的信息比较少的信息更好。

# 错误报告

对于 PHP 的安全性来说错误报告是一把双刃剑。一方面可以提高安全性，另一方面又有害。

攻击系统时经常使用的手法就是输入不正确的数据，然后查看错误提示的类型及上下文。这样做有利于攻击者收集服务器的信息以便寻找弱点。比如说，如果一个攻击者知道了一个页面所基于的表单信息，那么他就会尝试修改变量：

示例 #1 用自定义的 HTML 页面攻击变量

    <form method="post" action="attacktarget?username=badfoo&amp;password=badfoo">
    <input type="hidden" name="username" value="badfoo" />
    <input type="hidden" name="password" value="badfoo" />
    </form>

通常 PHP 所返回的错误提示都能帮助开发者调试程序，它会提出哪个文件的哪些函数或代码出错，并指出错误发生的在文件的第几行，这些就是 PHP 本身所能给出的信息。很多 PHP 开发者会使用 show_source()、highlight_string() 或者 highlight_file() 函数来调试代码，但是在正式运行的网站中，这种做法可能会暴露出隐藏的变量、未检查的语法和其它的可能危及系统安全的信息。在运行一些具有内部调试处理的程序，或者使用通用调试技术是很危险的。如果让攻击者确定了程序是使用了哪种具体的调试技术，他们会尝试发送变量来打开调试功能：

示例 #2 利用变量打开调试功能

    <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>

不管错误处理机制如何，可以探测系统错误的能力会给攻击者提供更多信息。

比如说，PHP 的独有的错误提示风格可以说明系统在运行 PHP。如果攻击者在寻找一个 `.html` 页面，想知道其后台的技术（为了寻找系统弱点），他们就会把错误的数据提交上去，然后就可以得知系统是基于 PHP 的了。

一个函数错误就可能暴露系统正在使用的数据库，或者为攻击者提供有关网页、程序或设计方面的有用信息。攻击者往往会顺藤摸瓜地找到开放的数据库端口，以及页面上某些 bug 或弱点等。比如说，攻击者可以一些不正常的数据使程序出错，来探测脚本中认证的顺序（通过错误提示的行号数字）以及脚本中其它位置可能泄露的信息。

一个文件系统或者 PHP 的错误就会暴露 web 服务器具有什么权限，以及文件在服务器上的组织结构。开发者自己写的错误代码会加剧此问题，导致泄漏了原本隐藏的信息。

有三个常用的办法处理这些问题。第一个是彻底地检查所有函数，并尝试弥补大多数错误。第二个是对在线系统彻底关闭错误报告。第三个是使用 PHP 自定义的错误处理函数创建自己的错误处理机制。根据不同的安全策略，三种方法可能都适用。

一个能提前阻止这个问题发生的方法就是利用 error_reporting() 来帮助使代码更安全并发现变量使用的危险之处。在发布程序之前，先打开 `E_ALL` 测试代码，可以帮你很快找到变量使用不当的地方。一旦准备正式发布，就应该把 error_reporting() 的参数设为 0 来彻底关闭错误报告或者把 php.ini 中的 `display_errors` 设为 off 来关闭所有的错误显示以将代码隔绝于探测。当然，如果要迟一些再这样做，就不要忘记打开 ini 文件内的 `log_errors` 选项，并通过 `error_log` 指定用于记录错误信息的文件。

示例 #3 用 E_ALL 来查找危险的变量

    <?php
    if ($username) {  // Not initialized or checked before usage
        $good_login = 1;
    }
    if ($good_login == 1) { // If above test fails, not initialized or checked before usage
        readfile ("/highly/sensitive/data/index.html");
    }
    ?>

# 用户提交的数据

很多 PHP 程序所存在的重大弱点并不是 PHP 语言本身的问题，而是编程者的安全意识不高而导致的。因此，必须时时注意每一段代码可能存在的问题，去发现非正确数据提交时可能造成的影响。

示例 #1 危险的变量用法

    <?php
    // 从用户目录中删除一个文件，或者……能删除更多的东西？
    unlink ($evil_var);

    // 记录用户的登陆，或者……能否在 /etc/passwd 添加数据？
    fwrite ($fp, $evil_var);

    // 执行一些普通的命令，或者……可以执行 rm -rf * ？
    system ($evil_var);
    exec ($evil_var);

    ?>

必须时常留意你的代码，以确保每一个从客户端提交的变量都经过适当的检查，然后问自己以下一些问题：

- 此脚本是否只能影响所预期的文件？
- 非正常的数据被提交后能否产生作用？
- 此脚本能用于计划外的用途吗？
- 此脚本能否和其它脚本结合起来做坏事？
- 是否所有的事务都被充分记录了？

在写代码的时候问自己这些问题，否则以后可能要为了增加安全性而重写代码了。注意了这些问题的话，也许还不完全能保证系统的安全，但是至少可以提高安全性。

为了提高安全性，禁用那些会隐藏输入数据的来源、有效性或完整性的便利设置。 隐式变量创建和未检查的输入可能导致像注入攻击和数据操纵这样的漏洞。

`register_globals` 和 `magic_quotes` 这两个特性（在 PHP 5.4.0 中被移除） 曾经通过自动创建变量和不一致的数据转义来增加这些风险。 虽然这两个特性已经不在 PHP 中了，但是如果输入处理不当，类似的风险仍然存在。

启用 error_reporting(E_ALL) 可以帮助检测未初始化的变量和验证输入。 使用严格类型（PHP 7 中引入的 declare(strict_types=1)）来强制类型安全， 防止意外的类型转换，提高整体安全性。

# 隐藏 PHP

一般而言，通过隐藏来实现安全是最脆弱的安全方式之一。但在某些情况下，每一点额外的安全都是值得的。

一些简单的方法可以帮助隐藏 PHP，这可能会减慢攻击者试图找到系统弱点的速度。 通过在 php.ini 文件中设置 expose_php 为 `off`， 可以减少能获得的有用信息。

另一个策略是配置 web 服务器（例如 apache）通过 PHP 解析不同的文件类型， 无论是通过 .htaccess 文件还是 apache 的配置文件，都可以设置能误导攻击者的文件扩展名：

示例 #1 把 PHP 隐藏为另一种语言

    # 使 PHP 代码看起来像其他代码类型
    AddType application/x-httpd-php .asp .py .pl

或者干脆彻底隐藏它：

示例 #2 使用未知的扩展名作为 PHP 的扩展名

    # 使 PHP 代码看起来像未知的类型
    AddType application/x-httpd-php .bop .foo .133t

或者隐藏它为 HTML 代码，这样会有轻微的性能影响，因为所有的 HTML 都将通过 PHP 引擎进行解析：

示例 #3 使用 HTML 作为 PHP 扩展名

    # 使所有的 PHP 代码看起来像 HTML
    AddType application/x-httpd-php .htm .html

要让此方法生效，必须把 PHP 文件的扩展名改为以上的扩展名。这样就通过隐藏来提高了安全性，这是一个小的预防措施，几乎没有缺点。

# 保持更新

PHP 和其它的大型系统一样，在持续不断的详细审查和改进过程中。 每个新版本常常将会包含主要和次要的改变以增强安全性、修复任何缺陷、配置问题以及将会影响整个系统安全性和稳定性的其他问题。

和其它系统级别的脚本语言和程序一样，最好的方法是经常更新，并保持对最新版本及其更改的了解。

- 简介
- 总则
- 以 CGI 模式安装时
  - 可能受到的攻击
  - 情形一：只运行公开的文件
  - 情形二：使用 cgi.force_redirect
  - 情形三：设置 doc_root 或 user_dir
  - 情形四：PHP 解释器放在 web 目录以外
- 以 Apache 模块安装时
- 会话（Session）安全
- 文件系统安全
  - 空字符（Null bytes）相关问题
- 数据库安全
  - 设计数据库
  - 连接数据库
  - 加密存储模型
  - SQL 注入
- 错误报告
- 用户提交的数据
- 隐藏 PHP
- 保持更新

# 特点

# 用 PHP 进行 HTTP 认证

可以用 header() 函数来向客户端浏览器发送“`Authentication Required`”信息，使其弹出一个用户名／密码输入窗口。当用户输入用户名和密码后，包含有 URL 的 PHP 脚本将会加上预定义变量 PHP_AUTH_USER，PHP_AUTH_PW 和 AUTH_TYPE 被再次调用，这三个变量分别被设定为用户名，密码和认证类型。预定义变量保存在 $_SERVER 数组中。仅 支持 “Basic” 认证方法。 请参阅 header() 函数以获取更多信息。

以下是在页面上强迫客户端认证的脚本范例：

示例 #1 Basic HTTP 认证范例

    <?php
      if (!isset($_SERVER['PHP_AUTH_USER'])) {
        header('WWW-Authenticate: Basic realm="My Realm"');
        header('HTTP/1.0 401 Unauthorized');
        echo 'Text to send if user hits Cancel button';
        exit;
      } else {
        echo "<p>Hello {$_SERVER['PHP_AUTH_USER']}.</p>";
        echo "<p>You entered {$_SERVER['PHP_AUTH_PW']} as your password.</p>";
      }
    ?>

> 注意: 兼容性问题

> 在编写 HTTP 标头代码时请格外小心。为了对所有的客户端保证兼容性，关键字“Basic”的第一个字母必须大写为“B”， 分界字符串必须用双引号（不是单引号）引用；并且在标头行 HTTP/1.0 401 中，在 401 前必须有且仅有一个空格。 认证参数必须用逗号分隔。

在以上例子中，仅仅只打印出了 PHP_AUTH_USER 和 PHP_AUTH_PW 的值，但在实际运用中，可能需要对用户名和密码的合法性进行检查。或许进行数据库的查询，或许从 dbm 文件中检索。

注意有些 Internet Explorer 浏览器本身有问题。它对标头的顺序显得似乎有点吹毛求疵。目前看来在发送 `HTTP/1.0 401` 之前先发送 WWW-Authenticate 标头似乎可以解决此问题。

> 注意: 配置说明

> PHP 用是否有 `AuthType` 指令来判断外部认证机制是否有效。

注意，这仍然不能防止有人通过未认证的 URL 来从同一服务器上认证的 URL 上偷取密码。

Netscape Navigator 和 Internet Explorer 浏览器都会在收到 401 的服务端返回信息时清空所有的本地浏览器整个域的 Windows 认证缓存。这能够有效的注销一个用户，并迫使他们重新输入他们的用户名和密码。有些人用这种方法来使登录状态“过期”，或者作为“注销”按钮的响应行为。

示例 #2 强迫重新输入用户名和密码的 HTTP 认证的范例

    <?php
    function authenticate() {
        header('WWW-Authenticate: Basic realm="Test Authentication System"');
        header('HTTP/1.0 401 Unauthorized');
        echo "You must enter a valid login ID and password to access this resource\n";
        exit;
    }

    if (!isset($_SERVER['PHP_AUTH_USER']) ||
        ($_POST['SeenBefore'] == 1 && $_POST['OldAuth'] == $_SERVER['PHP_AUTH_USER'])) {
        authenticate();
    } else {
        echo "<p>Welcome: " . htmlspecialchars($_SERVER['PHP_AUTH_USER']) . "<br />";
        echo "Old: " . htmlspecialchars($_REQUEST['OldAuth']);
        echo "<form action='' method='post'>\n";
        echo "<input type='hidden' name='SeenBefore' value='1' />\n";
        echo "<input type='hidden' name='OldAuth' value=\"" . htmlspecialchars($_SERVER['PHP_AUTH_USER']) . "\" />\n";
        echo "<input type='submit' value='Re Authenticate' />\n";
        echo "</form></p>\n";
    }
    ?>

该行为对于 HTTP 的 Basic 认证标准来说并不是必须的，因此不能依靠这种方法。对 Lynx 浏览器的测试表明 Lynx 在收到 401 的服务端返回信息时不会清空认证文件，因此只要对认证文件的检查要求没有变化，只要用户点击“后退”按钮，再点击“前进”按钮，其原有资源仍然能够被访问。不过，用户可以通过按“_”键来清空他们的认证信息。

为了能够使HTTP工作在 IIS 服务器的 CGI 模式下。 你需要编辑 IIS的设置“`目录安全`”。点击“`编辑`”并且只选择“`匿名访问`”，其它所有的复选框都应该留空。

> 注意: IIS 注意事项
> 要 HTTP 认证能够在 IIS 下工作，PHP 配置选项 cgi.rfc2616_headers 必须设置成 `0`（默认值）。

# Cookie

PHP 透明地支持 HTTP cookie。cookie 是一种在远程浏览器端储存数据并以此来跟踪和识别用户的机制。可以用 setcookie() 或 setrawcookie() 函数来设置 cookie。cookie 是 HTTP 标头的一部分，因此 setcookie() 函数必须在其它信息被输出到浏览器前调用，这和对 header() 函数的限制类似。可以使用输出缓冲函数来延迟脚本的输出，直到按需要设置好了所有的 cookie 或者其它HTTP头。

如果 variables_order 中包括“C”，则任何从客户端发送的 cookie 都会被自动包括进 $_COOKIE 自动全局数组。如果希望对一个 cookie 变量设置多个值，则需在 cookie 的名称后加 `[]` 符号。

关于更多细节以及有关浏览器问题的注意事项，参见 setcookie() 和 setrawcookie() 函数。

# 会话

PHP 中的会话支持包含在后续的访问中保留某些数据的方法。这使得能够构建更多的自定义应用程序以及增加网站的吸引力。在 Session 参考节获取所有信息。

# 文件上传处理

## 目录

- POST 方法上传
- 错误信息说明
- 常见缺陷
- 上传多个文件
- 对 PUT 方法的支持
- 参见

## POST 方法上传

本特性可以使用户上传文本和二进制文件。用 PHP 的认证和文件操作函数，可以完全控制允许哪些人上传以及文件上传后怎样处理。

PHP 能够接受任何来自符合 RFC-1867 标准的浏览器上传的文件。

> 注意: 相关的设置

> 请参阅 php.ini 的 file_uploads，upload_max_filesize，upload_tmp_dir，post_max_size 以及 max_input_time 设置选项。

请注意 PHP 也支持 PUT 方法的文件上传，Netscape Composer 和 W3C 的 Amaya 客户端使用这种方法。请参阅对 PUT 方法的支持以获取更多信息。

示例 #1 文件上传表单

可以如下建立一个特殊的表单来支持文件上传：

    <!-- The data encoding type, enctype, MUST be specified as below -->
    <form enctype="multipart/form-data" action="__URL__" method="POST">
        <!-- MAX_FILE_SIZE must precede the file input field -->
        <input type="hidden" name="MAX_FILE_SIZE" value="30000" />
        <!-- Name of input element determines name in $_FILES array -->
        Send this file: <input name="userfile" type="file" />
        <input type="submit" value="Send File" />
    </form>

以上范例中的 `__URL__` 应该被换掉，指向一个真实的 PHP 文件。

`MAX_FILE_SIZE` 隐藏字段（单位为字节）必须放在文件输入字段之前，其值为接收文件的最大尺寸。这是对浏览器的一个建议，PHP 也会检查此项。在浏览器端可以简单绕过此设置，因此不要指望用此特性来阻挡大文件。实际上，PHP 设置中的上传文件最大值是不会失效的。但是最好还是在表单中加上此项目，因为它可以避免用户在花时间等待上传大文件之后才发现文件过大上传失败的麻烦。

> 注意:

> 要确保文件上传表单的属性是 `enctype="multipart/form-data"`，否则文件上传不了。

全局变量 $_FILES 包含有所有上传的文件信息。 数组的内容来自以下范例表单。我们假设文件上传字段的名称如下例所示，为 userfile。名称可随意命名。

$_FILES['userfile']['name']

  客户端机器文件的原名称。

$_FILES['userfile']['type']

  文件的 MIME 类型，如果浏览器提供此信息的话。一个例子是“`image/gif`”。不过此 MIME 类型在 PHP 端并不检查，因此不要想当然认为有这个值。

$_FILES['userfile']['size']

  已上传文件的大小，单位为字节。

$_FILES['userfile']['tmp_name']

  文件被上传后在服务端储存的临时文件名。

$_FILES['userfile']['error']

  和该文件上传相关的错误代码。

$_FILES['userfile']['full_path']

  浏览器提交的完整路径。该值并不总是包含真实的目录结构，因此不能被信任。从 PHP 8.1.0 起可用。

文件被上传后，默认地会被储存到服务端的默认临时目录中，除非 php.ini 中的 upload_tmp_dir 设置为其它的路径。服务端的默认临时目录可以通过更改 PHP 运行环境的环境变量 TMPDIR 来重新设置，但是在 PHP 脚本内部通过运行 putenv() 函数来设置是不起作用的。该环境变量也可以用来确认其它的操作也是在上传的文件上进行的。

示例 #2 验证上传的文件

请查阅函数 is_uploaded_file() 和 move_uploaded_file() 以获取进一步的信息。 以下范例处理由表单提供的文件上传。

    <?php
    $uploaddir = '/var/www/uploads/';
    $uploadfile = $uploaddir . basename($_FILES['userfile']['name']);

    echo '<pre>';
    if (move_uploaded_file($_FILES['userfile']['tmp_name'], $uploadfile)) {
        echo "File is valid, and was successfully uploaded.\n";
    } else {
        echo "Possible file upload attack!\n";
    }

    echo 'Here is some more debugging info:';
    print_r($_FILES);

    print "</pre>";

    ?>

接受上传文件的 PHP 脚本为了决定接下来要对该文件进行哪些操作，应该实现任何逻辑上必要的检查。例如可以用 $_FILES['userfile']['size'] 变量来排除过大或过小的文件，也可以通过 $_FILES['userfile']['type'] 变量来排除文件类型和某种标准不相符合的文件，但只把这个当作一系列检查中的第一步，因为此值完全由客户端控制而在 PHP 端并不检查。同时，还可以通过 $_FILES['userfile']['error'] 变量来根据不同的错误代码来计划下一步如何处理。不管怎样，要么将该文件从临时目录中删除，要么将其移动到其它的地方。

如果表单中没有选择上传的文件，则 PHP 变量 $_FILES['userfile']['size'] 的值将为 0，$_FILES['userfile']['tmp_name'] 将为空。

如果该文件没有被移动到其它地方也没有被改名，则该文件将在表单请求结束时被删除。

示例 #3 上传一组文件

PHP 的 HTML 数组特性甚至支持文件类型。

    <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() may prevent filesystem traversal attacks;
            // further validation/sanitation of the filename may be appropriate
            $name = basename($_FILES["pictures"]["name"][$key]);
            move_uploaded_file($tmp_name, "data/$name");
        }
    }
    ?>

文件上传进度条可以使用 Session Upload Progress 来实现。

## 错误信息说明

PHP 将随文件信息数组一起返回一个对应的错误代码。该代码可以在文件上传时生成的文件数组中的 `error` 字段中被找到，也就是 $_FILES['userfile']['error']。

此错误代码的值是 `UPLOAD_ERR_*` 常量中的一个。

## 常见缺陷

对 `MAX_FILE_SIZE` 设置的值，不能大于 php.ini 文件 设置中 upload_max_filesize 选项设置的值。其默认值为 2M 字节。

如果内存限制设置被激活，可能需要将 memory_limit 设置的更大些，请确认 memory_limit 的设置足够的大。

如果 max_execution_time 设置的值太小，脚本运行的时间可能会超过该设置。因此，也请保证 `max_execution_time` 足够的大。

> 注意: max_execution_time 仅仅只影响脚本本身运行的时间。任何其它花费在脚本运行之外的时间，诸如用函数 system() 对系统的调用、sleep() 函数的使用、数据库查询、文件上传等，在计算脚本运行的最大时间时都不包括在内。

警告

max_input_time 以秒为单位设定了脚本接收输入的最大时间，包括文件上传。对于较大或多个文件，或者用户的网速较慢时，可能会超过默认的 `60` 秒。

如果 post_max_size 设置的值太小，则较大的文件会无法被上传。因此，请保证 `post_max_size` 的值足够的大。

max_file_uploads 配置选项控制单个请求中可上传的最大文件数量。如果上传的文件数量超过限制，$_FILES 将在达到限制后停止处理文件。例如，如果 max_file_uploads 设置为 `10`，则 $_FILES 将永远不会包含超过 10 个条目。

不对正在操作的文件进行验证可能意味着用户能够访问其它目录下的敏感信息。

鉴于文件路径的表示方法有很多种，我们无法确保用使用各种外语的文件名（尤其是包含空格的）能够被正确的处理。

开发人员不应将普通的 `input` 输入字段和文件上传的字段混用同一个表单变量（例如 `input` 名都用 `foo[]`）。

## 上传多个文件

可以对 `input` 域使用不同的 `name` 来上传多个文件。

PHP 支持同时上传多个文件并将它们的信息自动以数组的形式组织。要完成这项功能，需要在 HTML 表单中对文件上传域使用和多选框与复选框相同的数组式提交语法。

示例 #1 上传多个文件

    <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>

当以上表单被提交后，数组 $_FILES['userfile']，$_FILES['userfile']['name'] 和 $_FILES['userfile']['size'] 将被初始化。

例如，假设名为 /home/test/review.html 和 /home/test/xwp.out 的文件被提交，则 $_FILES['userfile']['name'][0] 的值将是 review.html，而 $_FILES['userfile']['name'][1] 的值将是 xwp.out。类似的，$_FILES['userfile']['size'][0] 将包含文件 review.html 的大小，依此类推。

此外也同时设置了 $_FILES['userfile']['name'][0]， $_FILES['userfile']['tmp_name'][0]， $_FILES['userfile']['size'][0] 以及 $_FILES['userfile']['type'][0]。

警告

max_file_uploads 配置选项对单次请求中可上传的文件数量进行了限制。需要确保表单在单次请求中上传的文件数量不超过此限制。

示例 #2 上传整个目录

在 HTML 文件上传字段中，可以使用 `webkitdirectory` 属性上传整个目录。大多数现代浏览器都支持此功能。

利用 `full_path` 信息，可以存储相对路径，或者在服务器上重建相同的目录结构。

    <form action="file-upload.php" method="post" enctype="multipart/form-data">
      Send this directory:<br />
      <input name="userfile[]" type="file" webkitdirectory multiple />
      <input type="submit" value="Send files" />
    </form>

警告

`webkitdirectory` 属性是非标准的，也不在标准化进程中。不要在面向公众的生产环境中使用它：它不会对所有用户都有效。各实现之间可能存在很大的不兼容性，将来行为可能会发生变化。

PHP 仅解析浏览器/用户代理提交的相对路径信息，并将该信息传递到 $_FILES 数组中。不能保证 `full_path` 数组中的值包含真实的目录结构，PHP 应用程序不得信任此信息。

## 对 PUT 方法的支持

PHP 对部分客户端具备的 HTTP PUT 方法提供了支持。PUT 请求比文件上传要简单的多，它们一般的形式为：

    PUT /path/filename.html HTTP/1.1

这通常意味着远程客户端会将其中的 /path/filename.html 存储到 web 目录树。让 Apache 或者 PHP 自动允许所有人覆盖 web 目录树下的任何文件显然是很不明智的。因此，要处理类似的请求，必须先告诉 web 服务器需要用特定的 PHP 脚本来处理该请求。在 Apache 下，可以用 Script 选项来设置。它可以被放置到 Apache 配置文件中几乎所有的位置。通常我们把它放置在 `<Directory>` 区域或者 `<VirtualHost>` 区域。可以用如下一行来完成该设置：

    Script PUT /put.php

这将告诉 Apache 将所有对 URI 的 PUT 请求全部发送到 put.php 脚本，这些 URI 必须和 PUT 命令中的内容相匹配。当然，这是建立在 PHP 支持 .php 扩展名，并且 PHP 已经在运行的假设之上。此脚本的所有 PUT 请求的目标资源必须是脚本本身，而不是上传文件本身的文件名。

使用 PHP，可以在 put.php 中执行类似下面的操作。这会将上传文件的内容复制到服务器上的文件 myputfile.ext。在执行此文件复制之前，可能会希望执行一些检查并且验证用户身份。

示例 #1 保存 HTTP PUT 文件

    <?php
    /* PUT 数据来自于 stdin 流 */
    $putdata = fopen("php://input", "r");

    /* 打开要写入的文件 */
    $fp = fopen("myputfile.ext", "w");

    /* 每次读取 1KB 的数据并写入到文件 */
    while ($data = fread($putdata, 1024))
      fwrite($fp, $data);

    /* 关闭流 */
    fclose($fp);
    fclose($putdata);
    ?>

## 参见

- 文件系统安全

# 使用远程文件

只要在 php.ini 中启用 allow_url_fopen，就可以将 HTTP 和 FTP URL 与大多数以文件名作为参数的函数一起使用。此外，也可以在 include、include_once、require 及 require_once 语句中使用 URL（必须启用 allow_url_include）。PHP 协议支持的更多信息参见支持的协议和封装协议。

例如，可以用此打开远程 web 服务器上的文件，解析输出以获取所需数据，然后在数据库查询中使用该数据，或者网站其余部分相同的样式输出内容。

示例 #1 获取远程页面的标题

    <?php
    $file = fopen ("http://www.example.com/", "r");
    if (!$file) {
        echo "<p>Unable to open remote file.\n";
        exit;
    }
    while (!feof ($file)) {
        $line = fgets ($file, 1024);
        /* 仅当标题跟标签在同一行时才有效 */
        if (preg_match ("@\<title\>(.*)\</title\>@i", $line, $out)) {
            $title = $out[1];
            break;
        }
    }
    fclose($file);
    ?>

也可以在 FTP 服务器上写入文件（提供具有正确访问权限的用户身份连接）。只能使用此方法创建新文件；如果尝试覆盖已存在的文件，则调用 fopen() 将失败。

要以“anonymous”以外的用户名连接服务器，需要指明用户名（可能还有密码），例如“`ftp://user:password@ftp.example.com/path/to/file`”（当需要基础认证的 HTTP 协议访问远程文件时也可以使用相同的语法）。

示例 #2 将数据保存到远程服务器

    <?php
    $file = fopen ("ftp://ftp.example.com/incoming/outputfile", "w");
    if (!$file) {
        echo "<p>Unable to open remote file for writing.\n";
        exit;
    }
    /* 这里写入数据。 */
    fwrite ($file, $_SERVER['HTTP_USER_AGENT'] . "\n");
    fclose ($file);
    ?>

> 注意:

> 或许可以从以上范例中了解到可以使用该技术写入远程日志文件。但不幸的是，这不起作用，因为如果远程文件已存在，调用 fopen() 将失败。要进行这样的分布式日志记录，应该参考 syslog()。

# 连接处理

在 PHP 内部，系统维护着连接状态，其状态有 4 种可能的情况：

- 0 - NORMAL（正常）
- 1 - ABORTED（异常退出）
- 2 - TIMEOUT（超时）
- 3 - ABORTED and TIMEOUT（异常退出且超时）

当 PHP 脚本正常地运行，NORMAL 状态为有效。当远程客户端中断连接时，ABORTED 状态的标记将会被打开。远程客户端连接的中断通常是由用户点击 STOP 按钮导致的。当连接时间超过 PHP 的时限（请参阅 set_time_limit() 函数）时，TIMEOUT 状态的标记将被打开。

可以决定脚本是否需要在客户端中断连接时退出。有时候让脚本完整地运行会带来很多方便，即使没有远程浏览器接受脚本的输出。默认的情况是当远程客户端连接中断时脚本将会退出。该处理过程可由 php.ini 的 ignore_user_abort 或由 httpd.conf 设置中对应的“php_value ignore_user_abort”以及 ignore_user_abort() 函数来控制。如果没有告诉 PHP 忽略用户的中断，脚本将会被中断，除非通过 register_shutdown_function() 设置了关闭触发函数。通过该关闭触发函数，当远程用户点击 STOP 按钮后，脚本再次尝试输出数据时，PHP 将会检测到连接已被中断，并调用关闭触发函数。

脚本也有可能被内置的脚本计时器中断。默认的超时限制为 30 秒。这个值可以通过设置 php.ini 的 max_execution_time 或 httpd.conf 设置中对应的“`php_value max_execution_time`”参数或者 set_time_limit() 函数来更改。当计数器超时的时候，脚本将会类似于以上连接中断的情况退出，先前被注册过的关闭触发函数也将在这时被执行。在该关闭触发函数中，可以通过调用 connection_status() 函数来检查超时是否导致关闭触发函数被调用。如果超时导致了关闭触发函数的调用，该函数将返回 2。

需要注意的一点是 ABORTED 和 TIMEOUT 状态可以同时有效。这在告诉 PHP 忽略用户的退出操作时是可能的。PHP 将仍然注意用户已经中断了连接但脚本仍然在运行的情况。如果到了运行的时间限制，脚本将被退出，设置过的关闭触发函数也将被执行。在这时会发现函数 connection_status() 返回 3。

# 持久数据库连接

### 什么是持久连接？

持久数据库连接是指在脚本结束运行时不关闭的连接。当收到持久连接的请求时，PHP 将检查是否已经存在相同的持久连接（前面已经开启的）——如果存在，将直接使用这个连接。如果不存在，则建立新的连接。所谓“相同”的连接是指用相同的用户名和密码连接到相同主机的连接。

目前无法请求特定的连接，也无法保证获取的是现有连接还是全新的连接（如果所有现有连接都在使用中，或者请求由不同的 worker 进程处理，而该 worker 进程拥有独立的连接池）。

这意味着无法使用 PHP 持久连接来实现以下目的，例如：

- 为特定的 Web 用户分配特定的数据库会话
- 创建跨多个请求的大型事务
- 在一个请求中发起查询并在另一个请求中收集结果

持久连接并没有提供非持久连接无法实现的任何功能。

### Web 请求

web 服务器可以通过两种方法来利用 PHP 生成 web 页面。

第一种方法是将 PHP 用作 CGI”包装器”即一个单独运行的语言解释器(CGI Wapper)。当以这种方法运行时，PHP 会为向 web 服务器的每个 PHP 页面请求创建并销毁 PHP 解释器的时候实例。由于其会随每个请求的结束而销毁，因此其获取的任何资源（例如指向 SQL 数据库服务器的链接）都会在销毁时关闭。在这种情况下，不会从使用持久连接中获得任何好处——因为根本不会持久。

第二，也是最流行的方法是运行 PHP-FPM，或将 PHP 用作多进程 web 服务器的一个模块，目前只适用于 Apache。多进程的服务器通常有一个父进程和一组子进程协调运行，子进程负责提供网页的工作。每当接收达到客户端提出请求时，该请求会传递给尚未给其它客户端提供服务的某个子进程。这也就是说当相同的客户端第二次向服务端发出请求时，它将有可能由与第一次不同的某个子进程提供服务。在开启了一个持久连接后，所有请求 SQL 服务的后继页面都能够重用与 SQL 服务器建立的相同连接。

> 注意:

> 通过检查 phpinfo() 输出中的“Server API”值，或者在 Web 请求中运行 `PHP_SAPI` 的值，可以确认 Web 请求所使用的方法。

> 如果服务器 API 为“Apache 2 Handler”或“FPM/FastCGI”，则持久连接将在同一 worker 进程处理的请求之间使用。对于其他任何值，持久连接在每次请求后将不会保持。

### 命令行进程

由于命令行 PHP 为每个脚本使用新进程，持久连接不会在命令行脚本之间共享，因此在诸如定时任务或命令之类的临时脚本中使用持久连接并无意义。然而，如果正在编写长时间运行的应用服务器，该服务器处理大量请求或任务，并且每个任务可能需要各自的数据库连接，那么持久连接可能会很有用。

### 为何使用它们？

如果创建链接到服务器的开销很高，则持久连接是好的。开销高低取决于很多因素。例如，数据库的类型，数据库服务和 web 服务是否在同一台服务器上，SQL 服务器负载状况等。事实是，如果连接开销很高，持久连接将显著的提高效率。它使得子进程在其整个生命周期中只做一次连接操作，而非每次在处理页面时都要向 SQL 服务器提出连接请求。这意味着，每个打开持久连接的子进程将对服务器建立各自的持久连接。例如，如果有 20 个不同的子进程运行与 SQL 服务器建立持久连接的脚本，那么将有 20 个与 SQL 服务器建立的不同连接，每个进程一个。

### 潜在缺点：连接限制

注意，如果持久连接的数量超过了数据库设定的连接数限制，系统将会产生一些问题。如果数据库的同时连接数限制为 16，而在繁忙会话的情况下，有 17 个线程试图连接，那么有一个线程将无法连接。如果这个时候，在脚本中出现了不允许关闭连接的错误（例如无限循环），则该数据库的 16 个连接将迅速地受到影响。请查阅数据库文档以获取关于如何处理废弃及空闲连接的信息。

持久连接通常会增加任意时刻的打开连接数，因为处于空闲状态的 worker 进程仍会保留其之前处理请求时所建立的连接。如果启动了大量 worker 进程以应对请求激增，这些进程所打开的连接将会一直保留，直到 worker 进程终止或数据库服务器关闭连接为止。

确保数据库服务器允许的最大连接数大于 Web 请求工作进程的最大数量（以及任何其他用途，例如定时任务或管理连接）。

查阅数据库文档以获取有关处理遗弃或空闲连接（超时）的信息。较长的超时时间可能会显著增加任意时刻打开的持久连接数量。

### 潜在缺点：维护连接状态

某些数据库扩展在重用连接时会自动执行清理操作，而其他扩展则将此任务交由应用程序开发者决定。根据所选的数据库扩展和应用程序设计，可能需要在脚本退出前进行手动清理。可能导致连接处于意外状态的更改包括：

- 已选择或默认的数据库
- 表锁
- 未提交的事务
- 临时表
- 与连接相关的特定设置或功能（例如性能分析）

未清理或未关闭的表锁和事务可能会导致无限期阻塞其他查询，或导致连接的后续重用引发意外更改。

选择了错误的数据库将导致连接的后续重用无法按预期执行查询（或者在数据库模式足够相似的情况下，可能会对错误的数据库执行查询）。

如果未清理临时表，后续请求将无法重新创建相同的表。

可以使用类析构方法或 register_shutdown_function() 来实现清理操作。还可以考虑使用包含此功能的专用连接池代理。

### 结语

鉴于上述行为及潜在缺点，不应未经慎重考虑就使用持久连接。在没有对应用程序进行额外更改，以及未对数据库服务器和 Web 服务器及/或 PHP-FPM 进行谨慎配置的情况下，不应使用持久连接。

可以考虑其他解决方案，例如调查并修复导致连接创建开销的原因（例如，在数据库服务器上禁用反向 DNS 查找），或使用专用的连接池代理。

对于高流量的 Web API，可以考虑使用其他运行时环境或长时间运行的应用服务器。

### 参见

- ibase_pconnect()
- oci_pconnect()
- odbc_pconnect()
- pfsockopen()
- pg_connect()
- MySQLi 与持久连接
- PDO 连接管理

# PHP 的命令行模式

## 目录

- 和其它 SAPI 模块的区别
- 选项
- 用法
- I/O 流
- 交互式 shell
- 内置 Web Server
- INI 配置

## 简介

CLI SAPI 主要是使用 PHP 开发 shell 应用。CLI SAPI 与本章中解释的其它 SAPI 存在相当多的差异。值得一提的是，尽管 CLI 和 `CGI` 有很多共同的行为，但它们是不同的 SAPI。

CLI SAPI 模块会通过默认的 --enable-cli 参数设置启用， 也可以在运行 ./configure 时用参数 --disable-cli 来屏蔽。

CLI/CGI 二进制执行文件的文件名、位置和是否存在会根据 PHP 在系统上的安装而不同。在默认情况下，当运行 make 时，CGI 和 CLI 都会被编译并且分别放置在 PHP 源文件目录的 sapi/cgi/php-cgi 和 sapi/cli/php 下。可以注意到两个文件都被命名为了 php。在 make install 的过程中会发生什么取决于配置行。如果在配置的时候选择了一个 SAPI 模块，如 apxs，或者使用了 --disable-cgi 参数，则在 make install 的过程中，CLI 将被拷贝到 {PREFIX}/bin/php，除非 CGI 已经被放置在了那个位置。因此，例如，如果在配置行中有 --with-apxs，则在 `make install` 的过程中，CLI 将被拷贝到 `{PREFIX}/bin/php`。如果希望覆盖 CGI 执行文件的安装，请在 make install 之后运行 make install-cli。或者，也可以在配置行中加上 --disable-cgi 参数。

> 注意:

> 由于 --enable-cli 和 --enable-cgi 同时默认有效，因此，不必再配置行中加上 --enable-cli 来使得 CLI 在 make install 过程中被拷贝到 {PREFIX}/bin/php。

在 Windows 发行包中，CLI 在主目录中的二进制文件名为 php.exe。CGI 版本的文件名为 php-cgi.exe。 如果 PHP 配置使用了 --enable-cli-win32，还会有一个额外的 php-win.exe 随包发布。 它相当于 CLI 版本，但是 php-win 不输出任何内容，便不提供控制台（不会弹出“DOS 窗口”）。

> 注意: 如何得知自己使用的是哪个 SAPI？

> 在命令行下，运行 php -v 便能得知该 php 是 CGI 还是 CLI。请参考函数 php_sapi_name() 以及常量 `PHP_SAPI`。

> 注意:

> 在命令行中键入 man php 可以查看 Unix `man` 手册页面。

## 和其它 SAPI 模块的区别

以下为 CLI SAPI 和其它 SAPI 模块相比的显著区别：

- 与 CGI SAPI 不同，其输出没有任何头信息。

  尽管 CGI SAPI 提供了取消 HTTP 头信息的方法，但在 CLI SAPI 中并不存在类似的方法以开启 HTTP 头信息的输出。

  CLI 默认以安静模式开始，但为了保证兼容性，-q 和 --no-header 参数为了向后兼容仍然保留，使得可以使用旧的 CGI 脚本。

  在运行时，不会把工作目录改为脚本的当前目录（可以使用 -C 和 --no-chdir 参数来兼容 CGI 模式）。

  出错时输出纯文本的错误信息（非 HTML 格式）。

- CLI SAPI 强制覆盖了 php.ini 中的某些设置，因为这些设置在外壳环境下是没有意义的。

  覆盖 php.ini 设置选项
  设置选项 | CLI SAPI 默认值 | 备注
  --- | --- | ---
  html_errors | `false` | 无意义的 HTML 标记符会使得出错信息很凌乱，所以在外壳下阅读报错信息是十分困难的。因此将该选项的默认值改为 `false`。
  implicit_flush | `true` | 在命令行模式下，所有来自 `print` 和 `echo` 的输出将被立即写到输出端，而不作任何地缓冲操作。如果希望延缓或控制标准输出，仍然可以使用 output buffering 设置项。
  max_execution_time | 0（无限值） | 鉴于在外壳环境下使用 PHP 的无穷的可能性，最大运行时间被设置为了无限值。为 web 开发的应用程序可能只需运行几秒钟时间，而外壳应用程序的运行时间可能会长的多。
  register_argc_argv | `true` | 由于该设置为 `true`，将总是可以在 CLI SAPI 中访问到 argc（传送给应用程序参数的个数）和 argv（包含有实际参数的数组）。 在使用 CLI SAPI 时，PHP 变量 `$argc` 和 `$argv` 已被注册并且设定了对应的值。随时可以通过 $_SERVER 数组 来访问它们，例如：$_SERVER['argv'] 警告 $argv 或 $_SERVER['argv'] 的存在并不能表明脚本一定正在从命令行运行，因为当启用 register_argc_argv 时，它们可能在其他上下文中设置。应改为检查 php_sapi_name() 返回的值。
      <?php

      if (php_sapi_name() === 'cli') {
          echo "This is being run from the command line!\n";
      }
  output_buffering | `false` | 虽然 php.ini 设置已经硬编码为 `false`， 输出缓冲控制函数仍然有效。
  max_input_time | `false` | PHP CLI 不支持 GET、POST、文件上传。

  > 注意:

  > 这些设置无法在设置文件 php.ini 或任何指定的其它文件中被初始化为其它值。这些默认值被限制在所有其它的设置文件被解析后改变。 不过，它们的值可以在程序运行的过程中被改变 （尽管对于该运行过程来说，这些设置项是没有意义的，例如 register_argc_argv）。

  > 注意:

  > 推荐命令行脚本设置 ignore_user_abort。 更多信息参见 ignore_user_abort()。

- 为了减轻外壳环境下的工作，我们为 I/O 流 定义了一系列常量。

- CLI SAPI 不会将当前目录改为已运行的脚本所在的目录。

  以下范例显示了本模块与 CGI SAPI 模块之间的不同：

      <?php
      // 名为 test.php 的简单测试程序
      echo getcwd(), "\n";
      ?>

  在使用 `CGI` 版本时，其输出为

      $ pwd
      /tmp

      $ php-cgi -f another_directory/test.php
      /tmp/another_directory

  明显可以看到 PHP 将当前目录改成了刚刚运行过的脚本所在的目录。

  使用 CLI SAPI 模式，得到：

      $ pwd
      /tmp

      $ php -q another_directory/test.php
      /tmp

  这使得在利用 PHP 编写外壳工具时获得了很大的便利。

  > 注意:

  > 可以在命令行运行时给该 CGI SAPI 加上 -C 参数，使其支持 CLI SAPI 的功能。

## 命令行选项

PHP 二进制文件可以随时通过执行带 -h 参数的 PHP 命令获取提供的命令行选项列表：

    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>.

命令行选项
选项 | 长选项 | 说明
--- | --- | ---
-a | --interactive | 运行交互式 PHP。参阅交互式 shell 章节获取更多信息。
-b | --bindpath | 外部 FASTCGI 服务器模式绑定路径（仅 CGI 可用）。
-C | --no-chdir | 不改变脚本的目录（仅 CGI 可用）。
-q | --no-header | 安静模式。禁止输出 HTTP 头（仅 CGI 可用）。
-T | --timing | 测量脚本重复 count 次的执行时间（仅 CGI 可用）。
-c | --php-ini | 在指定目录查找 php.ini 或者自定义 `INI` 文件（名称可以不是 php.ini），例如：
    $ php -c /custom/directory/ my_script.php

    $ php -c /custom/directory/custom-file.ini my_script.php
如果未指定此选项，php.ini 将在默认位置搜索。
-n | --no-php-ini | 完全忽略 php.ini。
-d | --define | 允许设置 php.ini 中配置指令的值。语法是：
     -d configuration_directive[=value]
示例 #1 使用 `-d` 设置 INI 配置的示例
    # 忽略值部分，将会设置配置指令为 "1"
    $ php -d max_execution_time
            -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
    string(1) "1"

    # 传递空值，将会设置配置指令为 ""
    php -d max_execution_time=
            -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
    string(0) ""

    # 配置指令将会设置为 '=' 字符之后传递的任何值
    $  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 | 激活扩展信息模式，用于调试/分析。
-f | --file | 解析并执行指定文件。 -f 可选且可以忽略 —— 只需提供需要执行的文件名就足够。
-h and -? | --help and --usage | 输出命令行选项列表并描述了这些选项的作用。
-i | --info | 调用 phpinfo() 并输出结果。如果 PHP 不能正常工作，建议使用命令 php -i 查看在信息表输出之前或者中间某个位置是否有错误消息。注意当使用 CGI 模式时会输出 HTML， 这会非常大。
-l | --syntax-check | 检查语法但不执行指定 PHP 代码。如果未指定文件，则将处理来自标准输入的输入，否则将检查每个文件。成功时，文本 `No syntax errors detected in <filename>` 将写入标准输出。失败时，除了内部解析器错误外，文本 `Errors parsing <filename>` 将写入标准输出。如果在指定文件（或标准输入）中发现任何错误，则将 shell 返回代码设置为 `-1`，否则将 shell 返回代码设置为 `0`。 此选项不会找到需要执行代码的致命错误（如未定义的函数）。 注意: 在 PHP 8.3.0 之前，只能指定一个要检查的文件。 注意: 此选项不能和 -r 一起使用。
-m | --modules | 示例 #2 打印内置（且已加载的） PHP 和 Zend 模块
    $ php -m
    [PHP Modules]
    xml
    tokenizer
    standard
    session
    posix
    pcre
    overload
    mysql
    mbstring
    ctype

    [Zend Modules]
> -r | --run | 允许在命令行内直接执行单行 PHP 代码。 不需要加上 PHP 开始和结束标识符（`<?php` 和 `?>`），否则将会造成语法错误。 注意: 使用这种形式的 PHP 时，应注意避免和 shell 环境进行的命令行参数替换相冲突。 示例 #3 当使用双引号时会造成语法错误
>     $ 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
> 这里的问题是在使用双引号 `"` 时 sh/bash 会执行变量替换。 由于 $foo 变量没有被定义，因此它将替换为空字符， 从而导致传递给 PHP 执行的代码实际上会变成：
>     $ php -r " = get_defined_constants();"
> 正确的方式是使用单引号 `'` 。使用单引号时 sh/bash 不会进行变量替换。 示例 #4 使用单引号防止 shell 变量替换
>     $ 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"]=>
>       [...]
如果使用的 shell 不是 sh/bash，可能会碰到更多的问题 —— 如果有的话，请向 » https://github.com/php/php-src/issues 报告 bug。试图在命令行中使用（ shell/PHP ）变量或者使用反斜杠转义时需要格外小心，因为很容易遇到问题。勿谓言之不预！ 注意: 可以在 CLI SAPI 中使用 -r，但不能在 CGI SAPI 中使用。 注意: 此选项仅适用于非常基本的代码，因此在此模式下会忽略某些配置指令（如 auto_prepend_file 和 auto_append_file）。
-B | --process-begin | 处理 stdin 之前需要执行的 PHP 代码。
-R | --process-code | 对每个输入行都执行的 PHP 代码。 此模式下有两个特殊变量： $argn 和 $argi。 $argn 将包含 PHP 正在处理的行， $argi 将包含正在处理的行号。
-F | --process-file | 对每个输入行都执行的 PHP 文件。
-E | --process-end | 在处理完输入后执行的 PHP 代码。 示例 #5 使用 -B 、 -R 、 -E 选项统计项目总行数。
    $ find my_proj | php -B '$l=0;' -R '$l += count(@file($argn));' -E 'echo "Total Lines: $l\n";'
    Total Lines: 37328
-S | --server | 启动 内置 web 服务器.
-t | --docroot | 为内置 web 服务器指定文档根目录。
-s | --syntax-highlight 和 --syntax-highlighting | 为源代码添加语法高亮显示。 此选项将使用内部机制解析文件并将生成的 HTML 高亮版本写入到标准输出。 注意它所做的只是生成一块 `<code> [...] </code>` HTML 标记，没有 HTML header。 注意: 此选项不能和 -r 一起使用。
-v | --version | 示例 #6 使用 -v 获取 SAPI 的名称以及 PHP 和 Zend 的版本号
    $ 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 | 显示忽略注释和空格后的源代码。 注意: 此选项不能和 -r 一起使用。
-z | --zend-extension | 加载 Zend 扩展。如果仅指定了文件名，PHP 将尝试从当前系统默认函数库中尝试加载此扩展 （例如在 Linux 上通常是 /etc/ld.so.conf）。 传递绝对路径的文件名将不会使用系统库搜索路径。如果用相对路径指定的文件名，则 PHP 仅试图在当前目录的相对目录加载扩展库。
| --ini | 展示配置文件名和扫描目录。 示例 #7 `--ini` 示例
    $ 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 | 展示指定函数或者类方法的有关信息（例如参数名称和数量）。 如果 PHP 在编译时启用 Reflection 支持，该选项才可以使用。 示例 #8 基础 `--rf` 用法
    $ php --rf var_dump
    Function [ <internal> public function var_dump ] {

      - Parameters [2] {
        Parameter #0 [ <required> $var ]
        Parameter #1 [ <optional> $... ]
      }
    }
--rc | --rclass | 展示指定类的有关信息（常量、属性和方法的列表）。 如果 PHP 在编译时启用 Reflection 支持，该选项才可以使用。 示例 #9 `--rc` 示例
    $ 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 | 展示指定扩展的有关信息（php.ini 选项、定义函数、常量和类的列表）。 如果 PHP 在编译时启用 Reflection 支持，该选项才可以使用。 示例 #10 `--re` 示例
    $ 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 | 展示指定 Zend 扩展的配置信息（也可以通过 phpinfo() 返回相同信息）。
--ri | --rextinfo | 展示指定扩展的配置信息（也可以通过 phpinfo() 返回相同信息）。 使用 “main” 作为扩展名可以获取到核心配置信息。 示例 #11 `--ri` 示例
    $ 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

> 注意:

> 选项 `-rBRFEH`、 `--ini` 、 `--r[fcezi]` 仅可以在 CLI 中使用。

## 执行 PHP 文件

CLI SAPI 有三种不同的方法执行 PHP 代码：

1. 让 PHP 运行指定文件。

       $ php my_script.php

       $ php -f my_script.php

   以上两种方法（使用或不使用 -f 参数）都能够运行给定的 my_script.php 文件。注意，没有限制可以执行哪种文件， 特别是文件名也不必用 `.php` 作为扩展名。

2. 在命令行中直接传递 PHP 代码执行。

       $ php -r 'print_r(get_defined_constants());'

   必须特别注意 shell 变量的替代及引号的使用。

   > 注意:

   > 请仔细阅读以上范例，它们没有开始和结束标识符！加上 -r 参数后不需要这些标记符，并且加上它们还会导致语法错误。

3. 通过标准输入（`stdin`）提供需要运行的 PHP 代码。

   这为动态创建 PHP 代码并通过二进制文件执行提供了强大的能力，就像下面（虚构的）例子展示的一样：

       $ some_application | some_filter | php | sort -u > final_output.txt

以上三种运行代码的方法不能混合使用。

和所有的 shell 应用程序一样，PHP 的二进制文件及其 PHP 脚本能够接受一系列的参数。PHP 没有限制传送给脚本的参数的个数（ shell 对传递的字符数有限制，但通常都不会超过该限制）。传递给脚本的参数可在全局数组 $argv 中获取。第一个索引（零）始终包含从命令行中调用的脚本名称。注意在命令行内使用 -r 执行 PHP 代码时， $argv[0] 的值将是 `"Standard input code"`； 在 PHP 7.2.0 之前是破折号（`-`）。如果代码是通过来自 `STDIN` 的管道执行的，同样如此。

另外，第二个全局变量 $argc 包含 $argv 数组中元素的个数（而不是传递给脚本的参数个数）。

只要传送给脚本的参数不是以 `-` 字符开头，就无需过多的注意什么。向脚本传递以 `-` 开头的参数会导致错误，因为 PHP 会认为在执行脚本之前应该由它自身来处理这些参数。为防止发生这种情况，可以用列表分隔符 `--` 参数来解决。在 PHP 解析此分隔符之后， 该符号后的所有参数将会被原样传递给脚本程序。

    # 以下命令将不会运行 PHP 代码，而只显示 PHP 命令行模式的使用说明
    $ php -r 'var_dump($argv);' -h
    Usage: php [options] [-f] <file> [args...]
    [...]

    # 将会传递 “-h” 参数传送给脚本，且 PHP 不会显示命令行模式的使用说明
    $ php -r 'var_dump($argv);' -- -h
    array(2) {
      [0]=>
      string(1) "-"
      [1]=>
      string(2) "-h"
    }

然而，在 Unix 系统中还有一个将 PHP 用于 shell 脚本的方法：写个脚本，第一行以 `#!/usr/bin/php` 为开头 （如果 PHP CLI 二进制文件路径不一样，则可以指定为任意实际的路径）。文件的剩余部分应该包含通用的 PHP 开始标签、正常的 PHP 代码、PHP 结束标签。一旦设置正确的文件执行属性（例如 chmod +x test），脚本就像其他 shell/perl 脚本一样可以执行。

示例 #1 PHP 脚本作为 shell 脚本执行

    #!/usr/bin/php
    <?php
    var_dump($argv);
    ?>

假设在当前目录下，该文件名为 test，可以做如下操作：

    $ chmod +x test
    $ ./test -h -- foo
    array(4) {
      [0]=>
      string(6) "./test"
      [1]=>
      string(2) "-h"
      [2]=>
      string(2) "--"
      [3]=>
      string(3) "foo"
    }

正如看到的，在向该脚本传递以 `-` 开头的参数时，无需关心这种情况。

PHP 可执行文件可用于运行完全独立于 web 服务器的 PHP 脚本。在 Unix 系统上，需要在 PHP 脚本的第一行指定 `#!`（或者说 “shebang”）以便系统可以自动判断用哪个程序运行脚本。 在 Windows 平台上可以使用双击扩展名是`.php`的文件与 php.exe 相关联，也可以编写一个批处理文件使用 PHP 运行脚本。为 Unix 系统增加的指定 shebang 的第一行代码不会影响 Windows （它也是 PHP 注释的格式），因此也可以用该方法编写跨平台的程序。以下是编写的一个简单 PHP 命令行程序的示例。

示例 #2 试图以命令行方式运行的 PHP 脚本（script.php）

    #!/usr/bin/php
    <?php

    if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
    ?>

    This is a command line PHP script with one option.

      Usage:
      <?php echo $argv[0]; ?> <option>

      <option> can be some word you would like
      to print out. With the --help, -help, -h,
      or -? options, you can get this help.

    <?php
    } else {
        echo $argv[1];
    }
    ?>

在以上脚本中，用包含 Unix shebang 的第一行代码来指明该文件应该由 PHP 来执行。这里使用 CLI 版本运行，因此不会输出 HTTP 头。

程序首先检查是否有需要的参数（除了脚本名，因为它也会被计算进来）。如果没有参数或者参数是 --help、 -help、 -h、 -?，将会打印出帮助消息， 在命令行上使用 $argv[0] 动态输出脚本名称。否则参数将按照接收的方式进行准确回显。

如果在 Unix 下运行以上脚本，它必须有可执行权限，并简单的以 script.php echothis 或者 script.php -h 方式调用。在 Windows 下，可以为此类任务编写与以下内容类似的批处理文件：

示例 #3 运行 PHP 命令行脚本的批处理文件（script.bat）

    @echo OFF
    "C:\php\php.exe" script.php %*

假设将上述程序名为 script.php，且 CLI 版的 php.exe 位于 C:\php\php.exe， 该批处理文件将会运行并传递所有追加选项： script.bat echothis 或者 script.bat -h。

参阅 Readline 扩展文档获取更多函数，以用于 PHP 中增强命令行应用程序。

在 Windows 上， PHP 可以配置为无需提供 C:\php\php.exe 或者 扩展名为 `.php` 的文件运行，如 PHP 在 Microsoft Windows 下的命令行方式中所述。

> 注意:

> 在 Windows 上，推荐在真实用户账户下运行 PHP。在网络服务下运行某些操作时将会失败， 因为“帐户名与安全标识间无任何映射完成”。

## 输入输出流

CLI SAPI 为 I/O 流定义了一些常量，以使命令行变量编程更容易一些。

CLI 特定常量
常量 | 描述
--- | ---
`STDIN` | 已经打开的 `stdin` 流。使得无需再用以下方式打开：
    <?php
    $stdin = fopen('php://stdin', 'r');
    ?>
如果想从 `stdin` 中读取一行内容，可以使用如下方式：
    <?php
    $line = trim(fgets(STDIN)); // 从 STDIN 读取一行
    fscanf(STDIN, "%d\n", $number); // 从 STDIN 读取数字
    ?>
`STDOUT` | 已经打开的 `stdout` 流。使得无需再用以下方式打开：
    <?php
    $stdout = fopen('php://stdout', 'w');
    ?>
`STDERR` | 已经打开的 `stderr` 流。使得无需再用以下方式打开：
    <?php
    $stderr = fopen('php://stderr', 'w');
    ?>

综上所述，则无需打开 `stderr` 流，只需使用常量代替流资源：

    php -r 'fwrite(STDERR, "stderr\n");'

无须显式关闭这些流，因为它们会在脚本结束时由 PHP 自动关闭。

> 注意:

> 如果从 `stdin` 中读取 PHP 脚本，则这些常量不可用。

## 交互式 shell

如果 PHP 使用 --with-readline 选项编译，则 CLI SAPI 使用 -a 选项时会提供交互式 shell。自 PHP 7.1.0 起，如果启用了 readline 扩展 ，交互式 shell 也可以在 Windows 上使用。

使用交互式 shell，你可以输入 PHP 代码并直接执行。

示例 #1 使用交互式 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 >

交互式 shell 还有对函数、常量、类名、变量、静态方法调用和类常量的 Tab 键补全功能。

示例 #2 Tab 键补全

当可能有多个补全时，按两次 Tab 键将会得到补全列表：

    php > strp[TAB][TAB]
    strpbrk   strpos    strptime
    php > strp

当仅可能有一个补全，按一次 Tab 键即可在同一行中补全剩余：

    php > strpt[TAB]ime(

补全也适用于当前交互式 shell 会话期间定义的名称：

    php > $fooThisIsAReallyLongVariableName = 42;
    php > $foo[TAB]ThisIsAReallyLongVariableName

交互式 shell 会存储的操作历史记录，可以通过上下键访问。历史记录存储于 ~/.php_history 文件。自 PHP 8.4.0 起，history 文件的路径可以使用 PHP_HISTFILE 环境变量设置。

CLI SAPI 提供了 `cli.pager` 和 `cli.prompt` 两个 php.ini 配置。`cli.pager` 配置允许外部程序（例如 less）充当分页器输出而不是直接在屏幕上显示。 `cli.prompt` 配置可以更改 `php >` 提示符。

在交互式 shell 中还可以使用缩写符号设置 php.ini 配置。

示例 #3 在交互式 shell 中设置 php.ini 配置

`cli.prompt` 配置：

    php > #cli.prompt=hello world :>
    hello world :>

使用反引号可以在提示中执行 PHP 代码：

    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 >

设置分页器为 less：

    php > #cli.pager=less
    php > phpinfo();
    (output displayed in less)
    php >

`cli.prompt` 配置支持一些转义字符：

`cli.prompt` 转义字符
字符 | 描述
--- | ---
`\e` | 用于添加提示符颜色。一个例子是 `\e[032m\v \e[031m\b \e[34m\> \e[0m`
`\v` | PHP 版本。
`\b` | 指明 PHP 所在的块。例如 `/*` 表示在多行注释中。外部作用域用 `php` 来表示。
`\>` | 指明提示字符。默认是 `>`，但当 shell 位于未结束的块或者字符串时会发生变化。可能的字符有 `' " { ( >`

> 注意:

> 在该模式下，通过 auto_prepend_file 和 auto_append_file 解析加载的文件会有一些限制 —— 例如函数必须在调用前定义。

## 交互模式

如果 readline 扩展不可用，在 PHP 8.1.0 之前，使用 -a 选项调用 CLI SAPI 会提供交互模式。 在此模式中，一个完整的 PHP 脚本应该通过 STDIN 给出，并用 ``CTRL` +`D`` （POSIX）或者 ``CTRL` +`Z`` 终止然后 +`ENTER`（Windows），脚本执行。这与不加 -a 选项调用 CLI SAPI 基本相同。

自 PHP 8.1.0 起，如果 readline 扩展不可用，使用 -a 调用 CLI SAPI 会失败。

## 内置 Web Server

警告

该 Web 服务器目的是帮助应用程序开发。还可用于测试目的或在受控环境中运行的应用程序演示。但并不是一个功能齐全的 Web 服务器。不应该在公共网络上使用。

CLI SAPI 提供了内置的 Web 服务器。

Web 服务器仅运行一个单线程进程，因此如果堵塞了请求，PHP 应用程序将停止运行。

URI 请求将从启动 PHP 的当前工作目录提供服务，除非使用 -t 选项指定文档根目录。如果 URI 请求未指定文件，则返回指定目录中的 index.php 或 index.html。如果两个文件都不存在，则将在父目录中继续查找 index.php 和 index.html，依此类推，直到找到一个文件或到达文档根目录。如果找到 index.php 或 index.html，则将其返回，并将 $_SERVER['PATH_INFO'] 设置为 URI 的尾部部分。否则将返回 404 响应代码。

如果在命令行上启动 Web 服务器时指定了 PHP 文件，则会将其视为“router”脚本。该脚本在每个 HTTP 请求开始时运行。如果此脚本返回 `false`，则按原样返回所请求的资源。否则脚本的输出将返回到浏览器。

对于有扩展名的文件，将返回标准的 MIME 类型： `.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` 。

从 PHP 7.4.0 开始，内置 Web 服务器可以配置为派生多个工作线程，以便测试需要向内置 Web 服务器发出多个并发请求的代码。在启动服务器之前，将 PHP_CLI_SERVER_WORKERS 环境变量设置为所需的 worker 数量。

> 注意: 此功能不支持 Windows。

警告

此实验功能不适用于生产用途。通常，内置 Web 服务器不适合生产用途。

示例 #1 启动 Web 服务器

    $ cd ~/public_html
    $ php -S localhost:8000

终端将显示:

    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

在 URI 请求 http://localhost:8000/ 和 http://localhost:8000/myscript.html 之后，终端会显示类似以下的内容：

    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

请注意，在 PHP 7.4.0 之前，在 Windows 上无法访问符号链接的静态资源，除非 router 脚本可以处理这些资源。

示例 #2 启动时指定文档根目录

    $ cd ~/public_html
    $ php -S localhost:8000 -t foo/

终端将显示：

    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

示例 #3 使用 router 脚本

在此示例中，请求图像将显示图片，但对 HTML 文件的请求将显示“Welcome to PHP”：

    <?php
    // router.php
    if (preg_match('/\.(?:png|jpg|jpeg|gif)$/', $_SERVER["REQUEST_URI"])) {
        return false;    // 原样提供所请求的资源
    } else {
        echo "<p>Welcome to PHP</p>";
    }
    ?>

    $ php -S localhost:8000 router.php

示例 #4 检查 CLI Web 服务器的使用

要在使用 CLI Web 服务器开发期间以及稍后使用生产 Web 服务器重复使用的框架 router 脚本：

    <?php
    // router.php
    if (php_sapi_name() == 'cli-server') {
        /* 发送静态资源并返回 false */
    }
    /* 继续正常的 index.php 操作 */
    ?>

    $ php -S localhost:8000 router.php

示例 #5 处理不支持的文件类型

如果需要提供不由 CLI Web 服务器处理的静态资源的 MIME 类型，请使用：

    <?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

示例 #6 从远程计算机访问 CLI Web 服务器

可以通过以下方式使 Web 服务器可通过端口 8000 接受任何链接：

    $ php -S 0.0.0.0:8000

警告

内置 Web 服务器不应该在公共网络上使用。

## INI 配置

CLI SAPI 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
cli_server.color | "0" | `INI_ALL`

这是配置指令的简短说明。

`cli_server.color` boolean

  控制内置Web Server的终端输出有无颜色。

# 垃圾回收

## 目录

- 引用计数基础
- 回收循环
- 性能方面考虑的因素

本节介绍了新垃圾回收（也称为 GC）机制作为 PHP 5.3 一部分的优点。

## 引用计数基础

PHP 变量存储在称为“zval”的容器中。zval 容器除了变量的类型和值之外，还包含两个额外的信息位。第一个是“is_ref”，是布尔值，表示变量是否是“引用集合”的一部分。通过这个位，PHP 引擎知道如何区分普通变量和引用。由于 PHP 允许用户自定义引用，通过 & 运算符创建引用，zval 容器还有内部引用计数机制来优化内存使用。第二个是“refcount”，表示有多少个变量名（也称为符号）指向这个 zval 容器。所有符号都存储在一个符号表中，每个作用域都有一个符号表。主脚本（即通过浏览器请求的脚本）有一个作用域，每个函数或方法也有一个作用域。

当使用常量值创建新变量时，也会创建 zval 容器，例如

示例 #1 创建新 zval 容器

    <?php
    $a = "new string";
    ?>

在这种情况下，新的符号名称 `a` 会在当前作用域中创建，并且会创建新的变量容器，其类型为 string，值为 `new string`。由于没有创建用户定义的引用，“is_ref”位默认设置为 `false`。“refcount”设置为 `1`，因为只有一个符号使用了这个变量容器。请注意，具有“refcount”为 `1` 的引用（即"is_ref"为 `true`）会视为非引用（即“is_ref”为 `false`）。如果安装了 » Xdebug，可以通过调用 xdebug_debug_zval() 来显示此信息。

示例 #2 显示 zval 信息

    <?php
    $a = "new string";
    xdebug_debug_zval('a');
    ?>

以上示例会输出：

    a: (refcount=1, is_ref=0)='new string'

将这个变量赋值给另一变量名将增加 refcount 的计数。

示例 #3 增加 zval 的 refcount

    <?php
    $a = "new string";
    $b = $a;
    xdebug_debug_zval( 'a' );
    ?>

以上示例会输出：

    a: (refcount=2, is_ref=0)='new string'

这里的 refcount 是 `2`，因为同一个变量容器链接到 a 和 b。PHP 很聪明，当没有必要的时候，不会复制实际的变量容器。当“refcount”到 0 时，就会销毁变量容器。当链接到变量容器的任何符号离开作用域（例如函数结束时）或取消符号赋值（例如通过调用 unset()）时，“refcount”会减少 1。以下是示例：

示例 #4 减少 zval refcount

    <?php
    $a = "new string";
    $c = $b = $a;
    xdebug_debug_zval( 'a' );
    $b = 42;
    xdebug_debug_zval( 'a' );
    unset( $c );
    xdebug_debug_zval( 'a' );
    ?>

以上示例会输出：

    a: (refcount=3, is_ref=0)='new string'
    a: (refcount=2, is_ref=0)='new string'
    a: (refcount=1, is_ref=0)='new string'

如果现在调用 `unset($a);`，变量容器，包含类型和值，会从内存中移除。

### 复合类型

对于 array 和 object 这样的复合类型，情况会稍微复杂一些。与 scalar 值不同，array 和 object 的属性存储在自己的符号表中。这意味着以下示例将创建三个 zval 容器：

示例 #5 创建 array zval

    <?php
    $a = array( 'meaning' => 'life', 'number' => 42 );
    xdebug_debug_zval( 'a' );
    ?>

以上示例的输出类似于：

    a: (refcount=1, is_ref=0)=array (
       'meaning' => (refcount=1, is_ref=0)='life',
       'number' => (refcount=1, is_ref=0)=42
    )

图示：

这三个 zval 变量容器是 a、meaning 和 number。增加和减少“refcounts”的规则也适用于此。下面，再向数组添加一个元素，并将其值设置为已存在元素的内容：

示例 #6 添加已存在的元素到数组

    <?php
    $a = array( 'meaning' => 'life', 'number' => 42 );
    $a['life'] = $a['meaning'];
    xdebug_debug_zval( 'a' );
    ?>

以上示例的输出类似于：

    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'
    )

图示：

从上面的 Xdebug 输出中，可以看到新旧的数组元素现在都指向“refcount”为 `2` 的 zval 容器。尽管 Xdebug 的输出显示了两个值为 `'life'` 的 zval 容器，但它们实际上是同一个。xdebug_debug_zval() 函数没有显示这一点，但可以通过显示内存指针来看到它。

从数组中删除元素就像从作用域中删除符号一样。删除后，数组元素指向的容器的“refcount”会减少。同样，当“refcount”到 0 时，变量容器就会从内存中删除。再举个例子来说明这一点：

示例 #7 从数组中删除元素

    <?php
    $a = array( 'meaning' => 'life', 'number' => 42 );
    $a['life'] = $a['meaning'];
    unset( $a['meaning'], $a['number'] );
    xdebug_debug_zval( 'a' );
    ?>

以上示例的输出类似于：

    a: (refcount=1, is_ref=0)=array (
       'life' => (refcount=1, is_ref=0)='life'
    )

现在，如果将数组本身作为数组的一个元素添加进去，情况就会变得有趣起来。在下一个例子中这样做，并且偷偷加入引用运算符，否则 PHP 会创建副本：

示例 #8 将数组添加为自身的一个元素

    <?php
    $a = array( 'one' );
    $a[] =& $a;
    xdebug_debug_zval( 'a' );
    ?>

以上示例的输出类似于：

    a: (refcount=2, is_ref=1)=array (
       0 => (refcount=1, is_ref=0)='one',
       1 => (refcount=2, is_ref=1)=...
    )

图示：

可以看到数组变量（a）以及第二个元素（1）现在都指向“refcount”为 `2` 的变量容器。上面显示的“...”表示存在递归，这在这种情况下意味着“...”指向原数组。

就像之前一样，清除变量会删除符号，并且指向的变量容器的引用计数会减少 1。因此，如果在运行上述代码后清除变量 $a，那么 $a 和元素“1”所指向的变量容器的引用计数会减少 1，从“2”变为“1”。可以表示为：

示例 #9 清除 $a

    (refcount=1, is_ref=1)=array (
       0 => (refcount=1, is_ref=0)='one',
       1 => (refcount=1, is_ref=1)=...
    )

图示：

### 清理问题

虽然在任何作用域中都没有指向这个结构的符号，却无法清理它，因为数组元素“1”仍然指向同一个数组。由于没有外部符号指向它，用户无法清理该结构；因此会出现内存泄漏。幸运的是，PHP 会在请求结束时清理这个数据结构，但在此之前，它会占用宝贵的内存空间。如果你正在实现解析算法或其他需要子级元素指向"父级"元素的情况，会经常发生。当然，object 也可能出现相同的情况，因为 object 始终隐式“引用”。

如果这种情况只发生一两次，可能不是问题，但如果出现数千次，甚至数百万次的内存损失，显然就成了问题。这在长时间运行的脚本中尤为棘手，比如守护进程，其中请求基本上永远不会结束，或者在大量的单元测试集中。后者在运行 eZ Components 库的模板组件的单元测试时出现了问题。在某些情况下，它需要超过 2GB 的内存，而测试服务器并没有那么多内存可用。

## 回收循环

传统上，像 PHP 之前使用的引用计数内存机制无法解决循环引用内存泄漏的问题；然而，从 5.3.0 版本开始，PHP 实施了» 引用计数系统中的同步循环回收论文中的同步算法来解决这个问题。

对算法的完全说明有点超出这部分内容的范围，将只介绍其中基础部分。首先，需要确立一些基本规则。如果 refcount 增加，则该变量仍在使用中，因此不是垃圾。如果 refcount 减少到 0，则 zval 可以释放。这意味着只有当引用计数参数减少到非零值时，才能创建垃圾循环。其次，在垃圾循环中，可以通过检查是否可以将 refcount 减少 1，并检查哪些 zval 的 refcount 为 0 来确定哪些部分是垃圾。

为避免不得不检查所有引用计数可能减少的垃圾循环，这个算法把所有可能根(possible roots 都是zval变量容器),放在根缓冲区(root buffer)中(用紫色来标记，称为疑似垃圾)，这样可以同时确保每个可能的垃圾根(possible garbage root)在缓冲区中只出现一次。仅仅在根缓冲区满了时，才对缓冲区内部所有不同的变量容器执行垃圾回收操作。看上图的步骤 A。

在步骤 B 中，模拟删除每个紫色变量。模拟删除时可能将不是紫色的普通变量引用数减"1"，如果某个普通变量引用计数变成0了，就对这个普通变量再做一次模拟删除。每个变量只能被模拟删除一次，模拟删除后标记为灰，确保不会对同一个变量容器减两次"1"。

在步骤 C 中，模拟恢复每个紫色变量。恢复是有条件的，当变量的引用计数大于0时才对其做模拟恢复。同样每个变量只能恢复一次，恢复后标记为黑，基本就是步骤 B 的逆运算。这样剩下的一堆没能恢复的就是该删除的蓝色节点了，在步骤 D 中遍历出来真的删除掉。

算法中都是模拟删除、模拟恢复、真的删除，都使用简单的遍历即可（最典型的深搜遍历）。复杂度为执行模拟操作的节点数正相关，不只是紫色的那些疑似垃圾变量。

对算法的工作原理有了基本的了解后，现在可以回顾一下如何与 PHP 集成。默认情况下，PHP 的垃圾回收器是打开的。然而，有个 php.ini 设置可以进行更改：zend.enable_gc。

当打开垃圾回收器时，如上所述的循环查找算法将在根缓冲区满时执行。根缓冲区的大小是固定的，可以容纳 10,000 个可能的根（尽管可以通过更改 PHP 源代码中的 `Zend/zend_gc.c` 中的 `GC_THRESHOLD_DEFAULT` 常量并重新编译 PHP 来修改这个值）。当关闭垃圾回收器时，循环查找算法将永不运行。然而，无论是否使用此配置激活垃圾回收机制，可能根都将始终记录在根缓冲区中。

如果在垃圾回收机制关闭时，根缓冲区存满了可能的根，那么将不会记录进一步的可能根。算法永远不会分析那些没有记录的可能根。如果他们是循环引用的一部分，将永不会清除从而导致内存泄漏的产生。

即使在垃圾回收机制不可用时，可能根也被记录的原因是，相对于每次找到可能根后检查垃圾回收机制是否打开而言，记录可能根的操作更快。不过垃圾回收和分析机制本身要耗不少时间。

除了改变配置中的 zend.enable_gc 之外，还可以通过调用 gc_enable() 或 gc_disable() 来启用/禁用垃圾回收机制。调用这些函数与通过配置打开或关闭机制的效果相同。即使可能的根缓冲区尚未满，还可以强制回收循环。为此，可以使用 gc_collect_cycles() 函数。该函数将返回算法回收的循环数量。

允许打开和关闭垃圾回收机制并且允许自主的初始化的原因，是由于你的应用程序的某部分可能是高时效性的。在这种情况下，你可能不想使用垃圾回收机制。当然，对你的应用程序的某部分关闭垃圾回收机制，是在冒着可能内存泄漏的风险，因为一些可能根也许存不进有限的根缓冲区。因此，就在你调用gc_disable()函数释放内存之前，先调用gc_collect_cycles()函数可能比较明智。因为这将清除已存放在根缓冲区中的所有可能根，然后在垃圾回收机制被关闭时，可留下空缓冲区以有更多空间存储可能根。

## 性能方面考虑的因素

在上一节我们已经简单的提到：回收可能根有细微的性能上影响，但这是把PHP 5.2与PHP 5.3比较时才有的。尽管在PHP 5.2中，记录可能根相对于完全不记录可能根要慢些，而PHP 5.3中对 PHP run-time 的其他修改减少了这个性能损失。

这里主要有两个领域对性能有影响。第一个是内存占用空间的节省，另一个是垃圾回收机制执行内存清理时的执行时间增加(run-time delay)。我们将研究这两个领域。

### 内存占用空间的节省

首先，实现垃圾回收机制的整个原因是为了，一旦先决条件满足，通过清理循环引用的变量来节省内存占用。在PHP执行中，一旦根缓冲区满了或者调用gc_collect_cycles() 函数时，就会执行垃圾回收。在下图中，显示了下面脚本分别在PHP 5.2 和 PHP 5.3环境下的内存占用情况，其中排除了脚本启动时PHP本身占用的基本内存。

示例 #1 Memory usage example

    <?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";
        }
    }
    ?>

在这个很理论性的例子中，我们创建了一个对象，这个对象中的一个属性被设置为指回对象本身。在循环的下一个重复(iteration)中，当脚本中的变量被重新复制时，就会发生典型性的内存泄漏。在这个例子中，两个变量容器是泄漏的(对象容器和属性容器)，但是仅仅能找到一个可能根：就是被unset的那个变量。在10,000次重复后(也就产生总共10,000个可能根)，当根缓冲区满时，就执行垃圾回收机制，并且释放那些关联的可能根的内存。这从PHP 5.3的锯齿型内存占用图中很容易就能看到。每次执行完10,000次重复后，执行垃圾回收，并释放相关的重复使用的引用变量。在这个例子中由于泄漏的数据结构非常简单，所以垃圾回收机制本身不必做太多工作。从这个图表中，你能看到 PHP 5.3的最大内存占用大概是9 Mb，而PHP 5.2的内存占用一直增加。

### 执行时间增加(Run-Time Slowdowns)

垃圾回收影响性能的第二个领域是它释放已泄漏的内存耗费的时间。为了看到这个耗时时多少，我们稍微改变了上面的脚本，有更多次数的重复并且删除了循环中的内存占用计算，第二个脚本代码如下：

示例 #2 GC性能影响

    <?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";
    ?>

运行这个脚本两次，一次将 zend.enable_gc 设置打开，一次关闭。

示例 #3 执行以上脚本

    time php -dzend.enable_gc=0 -dmemory_limit=-1 -n example2.php
    # and
    time php -dzend.enable_gc=1 -dmemory_limit=-1 -n example2.php

在我的机器上，第一个命令持续执行时间大概为10.7秒，而第二个命令耗费11.4秒。时间上增加了7%。然而，执行这个脚本时内存占用的峰值降低了98%，从931Mb 降到 10Mb。这个基准不是很科学，或者并不能代表真实应用程序的数据，但是它的确显示了垃圾回收机制在内存占用方面的好处。好消息就是，对这个脚本而言，在执行中出现更多的循环引用变量时，内存节省的更多的情况下，每次时间增加的百分比都是7%。

### PHP内部 GC 统计信息

在PHP内部，可以显示更多的关于垃圾回收机制如何运行的信息。但是要显示这些信息，你需要先重新编译PHP使benchmark和data-collecting code可用。你需要在按照你的意愿运行`./configure`前，把环境变量`CFLAGS`设置成`-DGC_BENCH=1`。下面的命令串就是做这个事：

示例 #4 重新编译PHP以启用GC benchmarking

    export CFLAGS=-DGC_BENCH=1
    ./config.nice
    make clean
    make

当你用新编译的PHP二进制文件来重新执行上面的例子代码，在PHP执行结束后，你将看到下面的信息：

示例 #5 GC 统计数据

    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

主要的信息统计在第一个块。你能看到垃圾回收机制运行了110次，而且在这110次运行中，总共有超过两百万的内存分配被释放。只要垃圾回收机制运行了至少一次，根缓冲区峰值(Root buffer peak)总是10000.

### 结论

通常，PHP中的垃圾回收机制，仅仅在循环回收算法确实运行时会有时间消耗上的增加。但是在平常的(更小的)脚本中应根本就没有性能影响。

然而，在平常脚本中有循环回收机制运行的情况下，内存的节省将允许更多这种脚本同时运行在你的服务器上。因为总共使用的内存没达到上限。

这种好处在长时间运行脚本中尤其明显，诸如长时间的测试套件或者daemon脚本此类。同时，对通常比Web脚本运行时间长的» PHP-GTK应用程序，新的垃圾回收机制，应该会大大改变一直以来认为内存泄漏问题难以解决的看法。

# DTrace 动态跟踪

## 目录

- PHP 和 DTrace 介绍
- 使用 PHP 和 DTrace
- 使用 SystemTap 监控 PHP DTrace 静态探针

## PHP 和 DTrace 介绍

包括 Solaris，macOS，Oracle Linux 和 BSD 在内的很多操作系统 都提供了 DTrace 跟踪调试框架，它永远可用，并且额外消耗极低。 DTrace 可以跟踪操作系统行为和用户程序的执行情况。 它可以显示参数值，也可以用来分析性能问题。 用户可以使用 DTrace D 脚本语言创建脚本文件来监控探针，进而高效分析数据指针。

除非用户使用 DTrace D 脚本激活并监控 PHP 探针，否则它并不会运行，所以不会给正常的应用执行带来任何性能损耗。 即使 PHP 探针被激活，它的消耗也是非常低的，甚至可以直接在生产系统中使用。

在运行时可以激活 PHP “用户级静态定义跟踪”（USDT）探针。 举例说明，如果 D 脚本正在监控 PHP `function-entry` 探针， 那么，每当 PHP 脚本函数被调用的时候，这个探针将被触发，同时 D 脚本中所关联的动作代码将被执行。 在脚本的动作代码中，可以打印出诸如函数所在源文件等信息的探针参数， 也可以记录诸如函数执行次数这样的聚合数据。

这里仅描述了 PHP USDT 探针。请参考各操作系统文档中关于 DTrace 的部分获取更多信息， 例如，如何使用 DTrace 跟踪函数调用，如何跟踪操作系统行为等。 需要注意的是，不同平台提供的 DTrace 功能并不完全相同。

在某些 Linux 发行版中，可以使用 SystemTap 工具来监控 PHP DTrace 静态探针。

## 使用 PHP 和 DTrace

在支持 DTrace 动态跟踪的平台上，可以配置 PHP 打开 DTrace 静态探针。

### PHP DTrace 静态探针配置

请参考操作系统文档获取启用操作系统 DTrace 支持的信息。 例如，在 Oracle Linux 系统上启动 UEK3 内核，并进行如下操作：

    # modprobe fasttrap
    # chmod 666 /dev/dtrace/helper

除了 `chmod` 命令，您也可以使用 ACL 包规则来限制特定用户对于设备的访问权限。

使用 `--enable-dtrace` 配置参数构建 PHP：

    # ./configure --enable-dtrace ...
    # make
    # make install

这样就可以在 PHP 中启用 DTrace 静态探针了。 对于提供了自有探针的 PHP 扩展，需要单独构建为共享扩展。

要启用探针，需要将 USE_ZEND_DTRACE=1 环境变量设置到目标 PHP 进程。

### PHP 核心的 DTrace 静态探针

PHP 中包括以下可用的静态探针
探针名称 | 探针描述 | 探针参数
--- | --- | ---
`request-startup` | 请求开始时触发。 | char *file, char *request_uri, char *request_method
`request-shutdown` | 请求关闭时触发。 | char *file, char *request_uri, char *request_method
`compile-file-entry` | 脚本开始编译时触发。 | char *compile_file, char *compile_file_translated
`compile-file-return` | 脚本完成编译时触发。 | char *compile_file, char *compile_file_translated
`execute-entry` | 操作数数组开始执行时触发。例如：函数调用，文件包含以及生成器恢复时会被触发。 | char *request_file, int lineno
`execute-return` | 操作数数组执行完毕之后触发。 | char *request_file, int lineno
`function-entry` | PHP 引擎进入 PHP 函数或者方法调用时触发。 | char *function_name, char *request_file, int lineno, char *classname, char *scope
`function-return` | PHP 引擎从 PHP 函数或者方法调用返回后触发。. | char *function_name, char *request_file, int lineno, char *classname, char *scope
`exception-thrown` | 有异常抛出时触发。 | char *classname
`exception-caught` | 有异常被捕获时触发。 | char *classname
`error` | 无论 error_reporting 的设定如何，在发生错误时都会触发。 | char *errormsg, char *request_file, int lineno

PHP 扩展可以拥有额外的静态探针。

### 列出 PHP 中可用的静态探针

要列出 PHP 中可用的静态探针，开启一个 PHP 进程，然后运行：

    # dtrace -l

输出信息类似如下所示：

       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

Provider 一列由 `php` 和当前进程 id 的组成。

如果运行的是 Apache web 服务器，那么模块名称可能是 libphp5.so， 并且可能会出现多块信息，每个运行中的 Apache 进程对应一个输出块。

Function Name 一列表示 Provider 对应的 PHP 内部 C 实现函数名称。

如果没有运行任何 PHP 进程，那么就不会显示任何 PHP 探针。

### PHP DTrace 示例

下例展示了基本的 DTrace D 脚本。

示例 #1 all_probes.d for tracing all PHP Static Probes with 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));
    }

此脚本在 dtrace 命令中使用了 `-Z` 选项。 此选项保证即使在没有任何 PHP 进程运行的时候脚本也能够正确执行。 如果省略了此选项，当没有任何探针可监控的时候，脚本会立即终止执行。

在运行此脚本的过程中，它将监控全部 PHP 核心静态探针。 运行 D 脚本：

    # ./all_probes.d

再运行一个 PHP 脚本或者 PHP 应用，用来进行监控的 D 脚本会输出每个探针被触发时所携带的参数。

监控完成之后，使用 ``CTRL`+`C`` 来终止 D 脚本的执行。

在多 CPU 的主机上，探针的显示顺序可能不是连续的，这取决于哪颗 CPU 执行探针以及多个 CPU 之间的线程迁移情况。 可以通过显示探针时间戳来减少混淆，例如：

    php*:::function-entry
    {
          printf("%lld: PHP function-entry ", walltimestamp);
          [ . . .]
    }

### 参见

- OCI8 和 DTrace 动态跟踪

## 使用 SystemTap 监控 PHP DTrace 静态探针

在某些 Linux 发行版上，可以使用 SystemTap 跟踪工具来跟踪 PHP 的静态 DTrace 探针。 此特性在 PHP 5.4.20 和 PHP 5.5 中具备。

### 安装支持 SystemTap 的 PHP

安装 SystemTap SDT 开发包。

    # yum install systemtap-sdt-devel

安装 PHP 并启用 DTrace 探针：

    # ./configure --enable-dtrace ...
    # make

### 使用 SystemTap 列出 PHP 静态探针

使用 stap 命令列出 PHP 静态探针：

    # stap -l 'process.provider("php").mark("*")' -c 'sapi/cli/php -i'

输出如下：

    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")

### SystemTap 示例

示例 #1 all_probes.stp for tracing all PHP Static Probes with 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));
    }

在 PHP 脚本的执行过程中，上述脚本会跟踪所有的 PHP 核心静态探针：

    # stap -c 'sapi/cli/php test.php' all_probes.stp

- 用 PHP 进行 HTTP 认证
- Cookie
- 会话
- 文件上传处理
  - POST 方法上传
  - 错误信息说明
  - 常见缺陷
  - 上传多个文件
  - 对 PUT 方法的支持
  - 参见
- 使用远程文件
- 连接处理
- 持久数据库连接
- PHP 的命令行模式
  - 和其它 SAPI 模块的区别
  - 选项 — 命令行选项
  - 用法 — 执行 PHP 文件
  - I/O 流 — 输入输出流
  - 交互式 shell
  - 内置 Web Server
  - INI 配置
- 垃圾回收
  - 引用计数基础
  - 回收循环
  - 性能方面考虑的因素
- DTrace 动态跟踪
  - PHP 和 DTrace 介绍
  - 使用 PHP 和 DTrace
  - 使用 SystemTap 监控 PHP DTrace 静态探针

# 函数参考

小技巧

参见 扩展库列表/归类.

# 影响 PHP 行为的扩展

# APC 用户缓存

# 简介

APCu 是 PHP 版的内存键值存储。 键是 string 类型且值可以为 PHP 任何变量。 APCu 仅支持用户空间（userland）级别的变量缓存。

APCu 缓存在 Windows 上是按进程的，所以当使用基于进程（而不是基于线程）的 SAPI 时，它不会在不同的进程之间共享。

APCu 是去除了操作码缓存的 APC。

第一个 APCu 代码库版本是 v4.0.0，是在那时从 APC master 分支中 fork 出来的。 APCu v5.0.0 起提供 PHP 7 支持。自 APCu v5.1.19 起提供 PHP 8 支持。

# 安装/配置

## 目录

- 安装
- 运行时配置

## 安装

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/apcu.

小技巧

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.

警告

As of PHP 8.0.0, apcu-bc is no longer supported.

> 注意: 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.

> 注意: For more in-depth, highly technical implementation details, see the » developer-supplied TECHNOTES file .

APCu sources can be found » here.

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

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
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
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` |

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`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.
  警告

  This feature is potentially dangerous. Unmapping the shared memory segment in a fatal signal handler may cause undefined behaviour if a fatal error occurs.

  > 注意: 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.

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`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 函数

# apcu_add

(PECL apcu >= 4.0.0)

apcu_add — 缓存一个新变量到存储中

### 说明

function apcu_add(string `$key`, mixed `$var`, int `$ttl` = 0): bool
function apcu_add(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): array

将一个从未被缓存过的变量添加到到存储中。

> 注意: 与 PHP 中常见的变量生命周期不同的是，通过 apcu_add() 存储的变量可以在多个 request 之间共享（直到该变量从 cache 中被删除）。

### 参数

`key`
  使用此名称存储变量。`key` 必须是唯一的，因此如果用 apcu_add() 存储变量时指定的 key 已经存在， 就会直接返回 `false`，不会覆写已有的数据。（这也是 apcu_add() 和 apcu_store() 之间唯一的区别。）
`var`
  被存储的变量
`ttl`
  变量生存时间（Time To Live）；被存储的 `var` 经过 `ttl` 秒后，会从存储中被删除（下一次请求时）。如果没提供 `ttl` （或 `ttl` 为 `0` ），该变量会一直存在直到手动删除它，或者其他原因导致该变量从缓存中消失（清除，重启等等。）。
`values`
  数组索引作为 key，数组值作为被存储的 var。

### 返回值

变量被成功添加时返回 TRUE，否则返回 FALSE。第二种语法返回包含添加失败的 key 的数组。

### 示例

示例 #1 apcu_add() 示例

    <?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";
    ?>

以上示例会输出：

    string(3) "BAR"
    string(3) "BAR"

### 参见

- apcu_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 — 从 APCu 存储中获取缓存信息

### 说明

function apcu_cache_info(bool `$limited` = `false`): array|false

从 APCu 存储中获取缓存信息和元数据（meta-data）。

### 参数

`limited`
  如果 `limited` 为 `true`，则不会返回具体被缓存的数据的列表，这在尝试根据统计数据进行调用优化时是很有用的。

### 返回值

成功时返回包含缓存数据（和元数据）的数组 或者在失败时返回 `false`

> 注意: 当 apcu_cache_info() 无法获取到缓存信息时会触发警告（warning），这种情况通常是因为没有开启 APC 功能。

### 更新日志

版本 | 说明
--- | ---
PECL apcu 3.0.11 | 引入了 `limited` 参数。
PECL apcu 3.0.16 | 为 `cache_type` 参数增加了 "`filehits`" 选项。

### 示例

示例 #1 apcu_cache_info() 示例

    <?php
    print_r(apcu_cache_info());
    ?>

以上示例的输出类似于：

    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 (...依次列出每个缓存文件)
    )

### 参见

- APCu 配置指令
- 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

### 说明

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.

### 参数

`key`
  The key of the value being updated.
`old`
  The old value (the value currently stored).
`new`
  The new value to update to.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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;
    ?>

以上示例的输出类似于：

    $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

### 参见

- apcu_dec() - Decrease a stored number
- apcu_store() - 缓存一个变量到存储中

# apcu_clear_cache

(PECL apcu >= 4.0.0)

apcu_clear_cache — Clears the APCu cache

### 说明

function apcu_clear_cache(): bool

Clears the cache.

### 参数

此函数没有参数。

### 返回值

Returns `true` always

### 参见

- apcu_cache_info() - 从 APCu 存储中获取缓存信息

# apcu_dec

(PECL apcu >= 4.0.0)

apcu_dec — Decrease a stored number

### 说明

function apcu_dec(
string `$key`,
int `$step` = 1,
bool `&$success` = ?,
int `$ttl` = 0
): int|false

Decreases a stored integer value.

### 参数

`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).

### 返回值

Returns the current value of `key`'s value on success, 或者在失败时返回 `false`

### 示例

示例 #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);
    ?>

以上示例的输出类似于：

    Let's do something with success
    42
    41
    31
    21
    bool(true)
    Now, let's fail

    bool(false)
    bool(false)

### 参见

- apcu_inc() - Increase a stored number

# apcu_delete

(PECL apcu >= 4.0.0)

apcu_delete — Removes a stored variable from the cache

### 说明

function apcu_delete(mixed `$key`): mixed

Removes a stored variable from the cache.

### 参数

`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.

### 返回值

If `key` is an array, an indexed array of the keys is returned. Otherwise `true` is returned on success, or `false` on failure.

### 示例

示例 #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_#'));
    ?>

### 参见

- apcu_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 — Whether APCu is usable in the current environment

### 说明

function apcu_enabled(): bool

Returns whether APCu is usable in the current environment.

### 参数

此函数没有参数。

### 返回值

Returns `true` when APCu is usable in the current environment, `false` otherwise.

# apcu_entry

(PECL apcu >= 5.1.0)

apcu_entry — Atomically fetch or generate a cache entry

### 说明

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.

> 注意: 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.

警告

The only APCu function that can be called safely by `callback` is apcu_entry().

### 参数

`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.).

### 返回值

Returns the cached value

### 示例

示例 #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);
    ?>

以上示例会输出：

    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"
      }
    }

### 参见

- apcu_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

### 说明

function apcu_exists(string|array `$keys`): bool|array

Checks if one or more APCu entries exist.

### 参数

`keys`
  A string, or an array of strings, that contain keys.

### 返回值

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.

### 示例

示例 #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);

    ?>

以上示例的输出类似于：

    Foo exists: apple
    Baz does not exist
    array(2) {
      ["foo"]=>
      bool(true)
      ["bar"]=>
      bool(true)
    }

### 参见

- apcu_cache_info() - 从 APCu 存储中获取缓存信息
- 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

### 说明

function apcu_fetch(mixed `$key`, bool `&$success` = ?): mixed

Fetches an entry from the cache.

### 参数

`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.

### 返回值

The stored variable or array of variables on success; `false` on failure

### 更新日志

版本 | 说明
--- | ---
PECL apcu 3.0.17 | The `success` parameter was added.

### 示例

示例 #1 A apcu_fetch() example

    <?php
    $bar = 'BAR';
    apcu_store('foo', $bar);
    var_dump(apcu_fetch('foo'));
    ?>

以上示例会输出：

    string(3) "BAR"

### 参见

- apcu_store() - 缓存一个变量到存储中
- apcu_delete() - Removes a stored variable from the cache
- APCUIterator

# apcu_inc

(PECL apcu >= 4.0.0)

apcu_inc — Increase a stored number

### 说明

function apcu_inc(
string `$key`,
int `$step` = 1,
bool `&$success` = ?,
int `$ttl` = 0
): int|false

Increases a stored number.

### 参数

`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).

### 返回值

Returns the current value of `key`'s value on success, 或者在失败时返回 `false`

### 示例

示例 #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);
    ?>

以上示例的输出类似于：

    Let's do something with success
    42
    43
    53
    63
    bool(true)
    Now, let's fail

    bool(false)
    bool(false)

### 参见

- apcu_dec() - Decrease a stored number

# apcu_key_info

(PECL apcu >= 4.0.2)

apcu_key_info — Get detailed information about the cache key

### 说明

function apcu_key_info(string `$key`): ?array

Get detailed information about the cache key

### 参数

`key`
  The key to retrieve information for.

### 返回值

An array containing the detailed information about the cache key, or `null` if the key does not exist.

### 示例

示例 #1 A apcu_key_info() example

    <?php
    apcu_add('a','b');
    var_dump(apcu_key_info('a'));
    ?>

以上示例会输出：

    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)
    }

### 参见

- apcu_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

### 说明

function apcu_sma_info(bool `$limited` = `false`): array|false

Retrieves APCu Shared Memory Allocation information.

### 参数

`limited`
  When set to `false` (default) apcu_sma_info() will return a detailed information about each segment.

### 返回值

Array of Shared Memory Allocation data; `false` on failure.

### 示例

示例 #1 A apcu_sma_info() example

    <?php
    print_r(apcu_sma_info());
    ?>

以上示例的输出类似于：

    Array
    (
        [num_seg] => 1
        [seg_size] => 31457280
        [avail_mem] => 31448408
        [block_lists] => Array
            (
                [0] => Array
                    (
                        [0] => Array
                            (
                                [size] => 31448408
                                [offset] => 8864
                            )

                    )

            )

    )

### 参见

- APCu configuration directives

# apcu_store

(PECL apcu >= 4.0.0)

apcu_store — 缓存一个变量到存储中

### 说明

function apcu_store(string `$key`, mixed `$var`, int `$ttl` = 0): bool
function apcu_store(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): array

缓存一个变量到存储中。

> 注意: 与 PHP 中常见的变量生命周期不同的是，通过 apcu_store() 存储的变量可以在多个 request 之间共享（直到该变量从 cache 中被删除）。

### 参数

`key`
  使用此名称存储变量。`key` 是唯一的，因此当多次使用同样的 `key` 存储变量时，后一次会覆盖前一次的值。
`var`
  被存储的变量
`ttl`
  变量生存时间（Time To Live）；被存储的 `var` 经过 `ttl` 秒后，会从存储中被删除（下一次请求时）。如果没提供 `ttl` （或 `ttl` 为 `0` ），该变量会一直存在直到手动删除它，或者其他原因导致该变量从缓存中消失（清除，重启等等。）。
`values`
  数组索引作为 key，数组值作为被存储的 var。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。 第二种语法返回包含存储失败的 key 的数组。

### 示例

示例 #1 apcu_store() 示例

    <?php
    $bar = 'BAR';
    apcu_store('foo', $bar);
    var_dump(apcu_fetch('foo'));
    ?>

以上示例会输出：

    string(3) "BAR"

### 参见

- apcu_add() - 缓存一个新变量到存储中
- apcu_fetch() - Fetch a stored variable from the cache
- apcu_delete() - Removes a stored variable from the cache

## 目录

- apcu_add — 缓存一个新变量到存储中
- apcu_cache_info — 从 APCu 存储中获取缓存信息
- 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 — Whether APCu is usable in the current environment
- 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 — Get detailed information about the cache key
- apcu_sma_info — Retrieves APCu Shared Memory Allocation information
- apcu_store — 缓存一个变量到存储中

# APCUIterator 类

(PECL apcu >= 5.0.0)

## 简介

APCUIterator 类可以更轻松的迭代大型 APCu 缓存。 它所支持的逐步迭代功能对于遍历大型缓存非常有用，每次加锁后只会获取指定数量（默认 100 条）的缓存条目就会释放锁而非一直锁住整个缓存，以便其他活动对缓存进行操作。 此外，使用正则表达式匹配是更高效的，因为它已经被移到了 C 语言层级（C level）。

## 类摘要

class APCUIterator implements Iterator {
/* 方法 */
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

### 说明

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.

### 参数

`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`.

### 示例

示例 #1 A APCUIterator::__construct() example

    <?php
    foreach (new APCUIterator('/^counter\./') as $counter) {
        echo "$counter[key]: $counter[value]\n";
        apc_dec($counter['key'], $counter['value']);
    }
    ?>

### 参见

- apcu_exists() - Checks if entry exists
- apcu_cache_info() - 从 APCu 存储中获取缓存信息

# APCUIterator::current

(PECL apcu >= 5.0.0)

APCUIterator::current — Get current item

### 说明

public function APCUIterator::current(): mixed

Gets the current item from the APCUIterator stack.

### 参数

此函数没有参数。

### 返回值

Returns the current item on success, or `false` if no more items exist, or on failure.

### 参见

- APCUIterator::next() - Move pointer to next item
- Iterator::current() - 返回当前元素

# APCUIterator::getTotalCount

(PECL apcu >= 5.0.0)

APCUIterator::getTotalCount — Get total count

### 说明

public function APCUIterator::getTotalCount(): int

Get the total count.

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

The total count.

### 参见

- APCUIterator::getTotalHits() - Get total cache hits
- APCUIterator::getTotalSize() - Get total cache size
- apcu_cache_info() - 从 APCu 存储中获取缓存信息

# APCUIterator::getTotalHits

(PECL apcu >= 5.0.0)

APCUIterator::getTotalHits — Get total cache hits

### 说明

public function APCUIterator::getTotalHits(): int

Gets the total number of cache hits.

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

The number of hits on success, or `false` on failure.

### 参见

- APCUIterator::getTotalCount() - Get total count
- APCUIterator::getTotalSize() - Get total cache size
- apcu_cache_info() - 从 APCu 存储中获取缓存信息

# APCUIterator::getTotalSize

(PECL apcu >= 5.0.0)

APCUIterator::getTotalSize — Get total cache size

### 说明

public function APCUIterator::getTotalSize(): int

Gets the total cache size.

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

The total cache size.

### 参见

- 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

### 说明

public function APCUIterator::key(): string

Gets the current iterator key.

### 参数

此函数没有参数。

### 返回值

Returns the key on success, or `false` upon failure.

### 参见

- APCUIterator::current() - Get current item
- Iterator::key() - 返回当前元素的键

# APCUIterator::next

(PECL apcu >= 5.0.0)

APCUIterator::next — Move pointer to next item

### 说明

public function APCUIterator::next(): bool

Moves the iterator pointer to the next element.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- APCUIterator::current() - Get current item
- APCUIterator::rewind() - Rewinds iterator
- Iterator::next() - 向前移动到下一个元素

# APCUIterator::rewind

(PECL apcu >= 5.0.0)

APCUIterator::rewind — Rewinds iterator

### 说明

public function APCUIterator::rewind(): void

Rewinds back the iterator to the first element.

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 参见

- APCUIterator::next() - Move pointer to next item
- Iterator::next() - 向前移动到下一个元素

# APCUIterator::valid

(PECL apcu >= 5.0.0)

APCUIterator::valid — Checks if current position is valid

### 说明

public function APCUIterator::valid(): bool

Checks if the current iterator position is valid.

### 参数

此函数没有参数。

### 返回值

Returns `true` if the current iterator position is valid, otherwise `false`.

### 参见

- APCUIterator::current() - Get current item
- Iterator::valid() - 检查当前位置是否有效

## 目录

- 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

- 安装/配置
  - 安装
  - 运行时配置
- 预定义常量
- APCu 函数
  - apcu_add — 缓存一个新变量到存储中
  - apcu_cache_info — 从 APCu 存储中获取缓存信息
  - 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 — Whether APCu is usable in the current environment
  - 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 — Get detailed information about the cache key
  - apcu_sma_info — Retrieves APCu Shared Memory Allocation information
  - apcu_store — 缓存一个变量到存储中
- APCUIterator — APCUIterator 类
  - 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

# 简介

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

# 安装/配置

## 目录

- 需求
- 安装

## 需求

Reflection is required

## 安装

Componere source and releases are available on » github

# The Componere\Abstract\Definition class

(Componere 2 >= 2.1.0)

## 简介

This final abstract represents a class entry, and should not be used by the programmer.

## 类摘要

final abstract class Componere\Abstract\Definition {
/* 方法 */
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

### 说明

public function Componere\Abstract\Definition::addInterface(string `$interface`): Definition

Shall implement the given interface on the current definition

### 参数

`interface`
  The case insensitive name of an interface

### 返回值

The current Definition

### Exceptions

警告

Shall throw RuntimeException if Definition was registered

# Componere\Abstract\Definition::addMethod

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addMethod — Add Method

### 说明

public function Componere\Abstract\Definition::addMethod(string `$name`, Componere\Method `$method`): Definition

Shall create or override a method on the current definition.

### 参数

`name`
  The case insensitive name for method
`method`
  Componere\Method not previously added to another Definition

### 返回值

The current Definition

### Exceptions

警告

Shall throw RuntimeException if Definition was registered

警告

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

### 说明

public function Componere\Abstract\Definition::addTrait(string `$trait`): Definition

Shall use the given trait for the current definition

### 参数

`trait`
  The case insensitive name of a trait

### 返回值

The current Definition

### Exceptions

警告

Shall throw RuntimeException if Definition was registered

# Componere\Abstract\Definition::getReflector

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::getReflector — Reflection

### 说明

public function Componere\Abstract\Definition::getReflector(): ReflectionClass

Shall create or return a ReflectionClass

### 返回值

A ReflectionClass for the current definition (cached)

## 目录

- 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)

## 简介

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.

## 类摘要

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`)
/* 方法 */
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
/* 继承的方法 */
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

### 说明

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`)

### 参数

`name`
  A case insensitive class name
`parent`
  A case insensitive class name
`interfaces`
  An array of case insensitive class names

### Exceptions

警告

Shall throw InvalidArgumentException if an attempt is made to replace an internal class

警告

Shall throw InvalidArgumentException if an attempt is made to replace an interface

警告

Shall throw InvalidArgumentException if an attempt is made to replace a trait

警告

Shall throw RuntimeException if a class in `interfaces` cannot be found

警告

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

### 说明

public function Componere\Definition::addConstant(string `$name`, Componere\Value `$value`): Definition

Shall declare a class constant on the current Definition

### 参数

`name`
  The case sensitive name for the constant
`value`
  The Value for the constant, must not be undefined or static

### 返回值

The current Definition

### Exceptions

警告

Shall throw RuntimeException if Definition was registered

警告

Shall throw RuntimeException if `name` is already declared as a constant

警告

Shall throw RuntimeException if `value` is static

警告

Shall throw RuntimeException if `value` is undefined

# Componere\Definition::addProperty

(Componere 2 >= 2.1.0)

Componere\Definition::addProperty — Add Property

### 说明

public function Componere\Definition::addProperty(string `$name`, Componere\Value `$value`): Definition

Shall declare a class property on the current Definition

### 参数

`name`
  The case sensitive name for the property
`value`
  The default Value for the property

### 返回值

The current Definition

### Exceptions

警告

Shall throw RuntimeException if Definition was registered

警告

Shall throw RuntimeException if `name` is already declared as a property

# Componere\Definition::register

(Componere 2 >= 2.1.0)

Componere\Definition::register — Registration

### 说明

public function Componere\Definition::register(): void

Shall register the current Definition

### Exceptions

警告

Shall throw RuntimeException if Definition was registered

# Componere\Definition::isRegistered

(Componere 2 >= 2.1.0)

Componere\Definition::isRegistered — State Detection

### 说明

public function Componere\Definition::isRegistered(): bool

Shall detect the registration state of this Definition

### 返回值

Shall return true if this Definition is registered

# Componere\Definition::getClosure

(Componere 2 >= 2.1.0)

Componere\Definition::getClosure — Get Closure

### 说明

public function Componere\Definition::getClosure(string `$name`): Closure

Shall return a Closure for the method specified by name

### 参数

`name`
  The case insensitive name of the method

### 返回值

A Closure bound to the correct scope

### Exceptions

警告

Shall throw RuntimeException if Definition was registered

警告

Shall throw RuntimeException if `name` could not be found

# Componere\Definition::getClosures

(Componere 2 >= 2.1.0)

Componere\Definition::getClosures — Get Closures

### 说明

public function Componere\Definition::getClosures(): array

Shall return an array of Closures

### 返回值

Shall return all methods as an array of Closure objects bound to the correct scope

### Exceptions

警告

Shall throw RuntimeException if Definition was registered

## 目录

- 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)

## 简介

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.

## 类摘要

final class Componere\Patch extends Componere\Abstract\Definition {
/* Constructors */
public function __construct(object `$instance`)
public function __construct(object `$instance`, array `$interfaces`)
/* 方法 */
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
/* 继承的方法 */
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

### 说明

public function Componere\Patch::__construct(object `$instance`)
public function Componere\Patch::__construct(object `$instance`, array `$interfaces`)

### 参数

`instance`
  The target for this Patch
`interfaces`
  A case insensitive array of class names

### Exceptions

警告

Shall throw RuntimeException if a class in `interfaces` cannot be found

警告

Shall throw RuntimeException if a class in `interfaces` is not an interface

# Componere\Patch::apply

(Componere 2 >= 2.1.0)

Componere\Patch::apply — Application

### 说明

public function Componere\Patch::apply(): void

Shall apply the current patch

# Componere\Patch::revert

(Componere 2 >= 2.1.0)

Componere\Patch::revert — Reversal

### 说明

public function Componere\Patch::revert(): void

Shall revert the current patch

# Componere\Patch::isApplied

(Componere 2 >= 2.1.0)

Componere\Patch::isApplied — State Detection

### 说明

public function Componere\Patch::isApplied(): bool

# Componere\Patch::derive

(Componere 2 >= 2.1.1)

Componere\Patch::derive — Patch Derivation

### 说明

public function Componere\Patch::derive(object `$instance`): Patch

Shall derive a Patch for the given `instance`

### 参数

`instance`
  The target for the derived Patch

### 返回值

Patch for `instance` derived from the current Patch

### Exceptions

警告

Shall throw InvalidArgumentException if `instance` is not compatible

# Componere\Patch::getClosure

(Componere 2 >= 2.1.0)

Componere\Patch::getClosure — Get Closure

### 说明

public function Componere\Patch::getClosure(string `$name`): Closure

Shall return a Closure for the method specified by name

### 参数

`name`
  The case insensitive name of the method

### 返回值

A Closure bound to the correct scope and object

### Exceptions

警告

Shall throw RuntimeException if `name` could not be found

# Componere\Patch::getClosures

(Componere 2 >= 2.1.0)

Componere\Patch::getClosures — Get Closures

### 说明

public function Componere\Patch::getClosures(): array

Shall return an array of Closures

### 返回值

Shall return all methods as an array of Closure objects bound to the correct scope and object

## 目录

- 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)

## 简介

A Method represents a function with modifiable accessibility flags

## 类摘要

final class Componere\Method {
/* Constructor */
public function __construct(Closure `$closure`)
/* 方法 */
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

### 说明

public function Componere\Method::__construct(Closure `$closure`)

### 参数

`closure`

# Componere\Method::setPrivate

(Componere 2 >= 2.1.0)

Componere\Method::setPrivate — Accessibility Modification

### 说明

public function Componere\Method::setPrivate(): Method

### 返回值

The current Method

### Exceptions

警告

Shall throw RuntimeException if access level was previously set

# Componere\Method::setProtected

(Componere 2 >= 2.1.0)

Componere\Method::setProtected — Accessibility Modification

### 说明

public function Componere\Method::setProtected(): Method

### 返回值

The current Method

### Exceptions

警告

Shall throw RuntimeException if access level was previously set

# Componere\Method::setStatic

(Componere 2 >= 2.1.0)

Componere\Method::setStatic — Accessibility Modification

### 说明

public function Componere\Method::setStatic(): Method

### 返回值

The current Method

# Componere\Method::getReflector

(Componere 2 >= 2.1.0)

Componere\Method::getReflector — Reflection

### 说明

public function Componere\Method::getReflector(): ReflectionMethod

Shall create or return a ReflectionMethod

### 返回值

A ReflectionMethod for the current method (cached)

## 目录

- 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)

## 简介

A Value represents a PHP variable of all types, including undefined

## 类摘要

final class Componere\Value {
/* Constructor */
public function __construct(mixed `$default` = ?)
/* 方法 */
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

### 说明

public function Componere\Value::__construct(mixed `$default` = ?)

### 参数

`default`

### Exceptions

警告

Shall throw InvalidArgumentException if `default` does not have a suitable value

# Componere\Value::setPrivate

(Componere 2 >= 2.1.0)

Componere\Value::setPrivate — Accessibility Modification

### 说明

public function Componere\Value::setPrivate(): Value

### 返回值

The current Value

### Exceptions

警告

Shall throw RuntimeException if access level was previously set

# Componere\Value::setProtected

(Componere 2 >= 2.1.0)

Componere\Value::setProtected — Accessibility Modification

### 说明

public function Componere\Value::setProtected(): Value

### 返回值

The current Value

### Exceptions

警告

Shall throw RuntimeException if access level was previously set

# Componere\Value::setStatic

(Componere 2 >= 2.1.0)

Componere\Value::setStatic — Accessibility Modification

### 说明

public function Componere\Value::setStatic(): Value

### 返回值

The current Value

# Componere\Value::isPrivate

(Componere 2 >= 2.1.0)

Componere\Value::isPrivate — Accessibility Detection

### 说明

public function Componere\Value::isPrivate(): bool

# Componere\Value::isProtected

(Componere 2 >= 2.1.0)

Componere\Value::isProtected — Accessibility Detection

### 说明

public function Componere\Value::isProtected(): bool

# Componere\Value::isStatic

(Componere 2 >= 2.1.0)

Componere\Value::isStatic — Accessibility Detection

### 说明

public function Componere\Value::isStatic(): bool

# Componere\Value::hasDefault

(Componere 2 >= 2.1.0)

Componere\Value::hasDefault — Value Interaction

### 说明

public function Componere\Value::hasDefault(): bool

## 目录

- 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 函数

# Componere\cast

(Componere 2 >= 2.1.2)

Componere\cast — Casting

### 说明

function Componere\cast(string `$type`, object `$object`): object

### 参数

`type`
  A user defined type
`object`
  An object with a user defined type compatible with Type

### 返回值

An object of type Type, cast from `object`

### 错误／异常

警告

Shall throw InvalidArgumentException if the type of `object` is or is derived from an internal class

警告

Shall throw InvalidArgumentException if Type is an interface

警告

Shall throw InvalidArgumentException if Type is a trait

警告

Shall throw InvalidArgumentException if Type is an abstract

警告

Shall throw InvalidArgumentException if Type is not compatible with the type of `object`

### 参见

- Componere\cast_by_ref

# Componere\cast_by_ref

(Componere 2 >= 2.1.2)

Componere\cast_by_ref — Casting

### 说明

function Componere\cast_by_ref(string `$type`, object `$object`): object

### 参数

type
  A user defined type
`object`
  An object with a user defined type compatible with Type

### 返回值

An object of type Type, cast from `object`, where members are references to `object` members

### 错误／异常

警告

Shall throw InvalidArgumentException if the type of `object` is or is derived from an internal class

警告

Shall throw InvalidArgumentException if Type is an interface

警告

Shall throw InvalidArgumentException if Type is a trait

警告

Shall throw InvalidArgumentException if Type is an abstract

警告

Shall throw InvalidArgumentException if Type is not compatible with the type of `object`

### 参见

- Componere\cast

## 目录

- Componere\cast — Casting
- Componere\cast_by_ref — Casting

- 安装/配置
  - 需求
  - 安装
- 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 函数
  - Componere\cast — Casting
  - Componere\cast_by_ref — Casting

# 错误处理和日志记录

# 简介

这些是错误处理和日志记录的函数。这些函数允许定义自己的错误处理规则，以及修改错误记录的方式。这样就可以更改和加强错误报告以满足需要。

通过日志记录函数，可以将信息直接发送到其他机器、电子邮件（邮件到 pager 网关！）、系统日志等，从而可以有选择的记录和监视应用程序和网站的最重要的部分。

错误报告函数允许自定义错误反馈级别和类型，范围从简单的通知到错误时自定义函数返回。

# 安装/配置

## 目录

- 运行时配置

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

错误和日志记录配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
error_reporting | NULL | `INI_ALL` |
display_errors | "1" | `INI_ALL` |
display_startup_errors | "1" | `INI_ALL` | PHP 8.0.0 之前，默认值是 `"0"`。
log_errors | "0" | `INI_ALL` |
log_errors_max_len | "1024" | `INI_ALL` | PHP 8.0.0 起弃用，PHP 8.1.0 起移除。
ignore_repeated_errors | "0" | `INI_ALL` |
ignore_repeated_source | "0" | `INI_ALL` |
report_memleaks | "1" | `INI_ALL` |
track_errors | "0" | `INI_ALL` | PHP 7.2.0 起弃用，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` | 自 PHP 8.2.0 起有效
syslog.facility | "LOG_USER" | `INI_SYSTEM` | 自 PHP 7.3.0 起可用。
syslog.filter | "no-ctrl" | `INI_ALL` | 自 PHP 7.3.0 起可用。
syslog.ident | "php" | `INI_SYSTEM` | 自 PHP 7.3.0 起可用。

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`error_reporting` int

  设置错误报告级别。该参数可以是表示二进制位字段的任意整数或者常量名称。error_reporting 级别和常量是在预定义常量和 php.ini 中进行了说明。在程序运行时可以通过 error_reporting() 进行设置。另请查看 display_errors 指令。

  默认值为 `E_ALL`。

  PHP 8.0.0 之前，默认值是：``E_ALL` & ~`E_NOTICE` & ~`E_STRICT` & ~`E_DEPRECATED``。这意味着不会显示 `E_NOTICE`、 `E_STRICT`、`E_DEPRECATED` 级别的错误提示。

  > 注意: PHP外的PHP常量

  > 在 PHP 以外（如 httpd.conf）使用 PHP 常量将没有意义，因此在这种情况下需要 int 值来取代。由于错误级别会随着时间的推移而增长，错误级别的最大值（`E_ALL`）可能会改变。所以考虑使用更大的值来代替 `E_ALL` 从而覆盖从现在到未来的所有二进制位字段，例如数值 `2147483647`（将包含所有错误，而不仅仅是 `E_ALL`）。

`display_errors` string

  该选项设置是否将错误信息作为输出的一部分打印到屏幕，或者对用户隐藏。

  值 `"stderr"` 将错误发送到 `stderr` 而不是 `stdout`。

  > 注意:

  > 这是辅助开发的功能，不应在生产系统中使用 (例如连接到互联网的系统)。

  > 注意:

  > 尽管 display_errors 也可以在运行时设置 (使用 ini_set())， 但是如果脚本出现致命错误，它不会起到任何作用。因为还没执行所需的运行时操作。

`display_startup_errors` bool

  即使 display_errors 设置为开启，PHP 也不会显示启动过程中的错误。强烈建议除调试外，都将 display_startup_errors 设置为关闭。

`log_errors` bool

  设置是否将脚本运行的错误信息记录到服务器错误日志或者 error_log。注意，这是与服务器相关的特定配置项。

  > 注意:

  > 在生产环境 web 网站中，强烈建议使用错误日志记录代替错误显示。

`log_errors_max_len` int

  设置 log_errors 的最大字节数. 在 error_log 中添加有关错误源的信息。默认值为 1024，如果设置为 0 表示不限长度。该长度适用于记录的错误，显示的错误，以及 $php_errormsg，但不适用于显式调用的函数，例如 error_log()。

  当使用 int 时, 其值以字节来衡量。还可以使用在 FAQ 中描述的速记符。
`ignore_repeated_errors` bool

  不记录重复的信息。重复的错误必须出现在同一个文件中的同一行代码上，除非 ignore_repeated_source 设置为 true。

`ignore_repeated_source` bool

  忽略重复消息时，也忽略消息的来源。当该设置开启时，重复信息将不会记录它是由不同的文件还是不同的源代码行产生的。

`report_memleaks` bool

  如果这个参数设置为开启（默认），此参数将会显示 Zend 内存管理器检测到的内存泄露报告。此报告将会发送到 Posix 平台上的 stderr。在 Windows 上，将使用 OutputDebugString() 发送到调试器并可以使用 » DbgView 等工具查看。此参数进在调试版本中有效并且需要 error_reporting 包含 `E_WARNING`。

`track_errors` bool

  如果开启，最后的一个错误将永远存在于变量 $php_errormsg 中。

`html_errors` bool

  如果启用，错误消息将包含 HTML 标记。HTML 错误格式会生成可点击的消息，将用户引导至描述错误页面或者导致错误的函数。这些引用跟 docref_root 和 docref_ext 的有关。

  如果禁用，错误消息将完全是纯文本。

`xmlrpc_errors` bool

  如果启用，则关闭正常的错误报告，并将错误格式格式化为 XML-RPC 错误信息。

`xmlrpc_error_number` int

  用作 XML-RPC faultCode 元素的值。

`docref_root` string

  新的错误信息格式包含了对描述错误或者导致错误的函数的页面引用。为了提供手册的页面，你可以在 PHP 官方站点下载对应语言的手册，并在 ini 中设置网址到本地对应的地址。如果你的本地手册拷贝可以使用 `"/manual/"` 访问，你就可以简单的设置 `docref_root=/manual/`。另外你还需要设置 docref_ext 匹配你本地文件的后缀名 `docref_ext=.html`。当然也可以设置一个外部的参考地址。例如你可以设置 `docref_root=http://manual/en/` 或者 `docref_root="http://landonize.it/?how=url&theme=classic&filter=Landon &url=http%3A%2F%2Fwww.php.net%2F"`

  通常需要在 docref_root 后面以 `"/"`结尾， 但是在以上的第二种示例情况中不必这么设置。

  > 注意:

  > 这是辅助开发的功能，因为可以快速定位和查看到函数的说明。不应在生产系统中使用 (例如连接到互联网的系统)。

`docref_ext` string

  参见 docref_root。

  > 注意:

  > docref_ext 的值必须以 `"."` 开头。

`error_prepend_string` string

  错误信息之前输出的字符串。仅在屏幕上显示错误消息时使用。主要是目的是能够为错误消息添加额带的 HTML 标记。

`error_append_string` string

  错误信息之后输出的字符串。仅在屏幕上显示错误消息时使用。主要是目的是能够为错误消息添加额带的 HTML 标记。

`error_log` string

  设置脚本错误将被记录到的文件名称。该文件应该由 Web 服务器用户写入。如果使用特殊值 `syslog`，则将错误信息发送到系统日志记录器。在 Unix 系统上，使用的是 syslog(3)，而在 Windows 上则为事件日志。参见：syslog()。如果该配置没有设置，则错误信息会被发送到 SAPI 错误记录器。例如，出现在 Apache 的错误日志中，或者在 CLI 中的 `stderr`。参阅 error_log()。

`error_log_mode` int

  File mode for the file described set in error_log.

`syslog.facility` string

  指定记录日志信息的程序类型，仅在 error_log 设置为 "syslog" 时有效。

`syslog.filter` string

  指定过滤器类型以过滤纪录的消息。允许不加修改的传递字符；all others are written in their hexadecimal representation prefixed with `\x`.

  - `all`——记录的字符串在换行符处拆分，并且所有字符都原封不动的传递
  - `ascii`——纪录的字符串在换行符处拆分，且转义任何不可打印的 7 位 ASCII 字符
  - `no-ctrl`——纪录的字符串在换行符处拆分，且转义任何不可打印字符
  - `raw`——所有字符都原封不动的传递给系统记录器，换行符处不会拆分 (identical to PHP before 7.3)
  此设置通过 error_log 设置为 “syslog” 并调用 syslog() 影响日志记录。

  > 注意:

  > `raw` 过滤器从 PHP 7.3.8 和 PHP 7.4.0 起可以使用。

  Windows 上不支持该指令。
`syslog.ident` string

  设置每条日志消息前缀的识别字符串（ident string），仅在 error_log 为 "syslog" 时有效。

# 预定义常量

下列常量作为 PHP 核心的一部分总是可用的。

以下常量（相应的数值或其符号名称）用作位掩码来指定要报告的错误。可以使用按位运算符来组合这些值或屏蔽某些类型的错误。

小技巧

常量的名称可以在 php.ini 中使用，而不是它们对应的原始数值。但是，php.ini 中只能理解 `|`、`~`、`^`、`!`、`&` 运算符。

警告

无法在 PHP 之外使用符号名称。例如，在 httpd.conf 中，必须使用计算出的位掩码值。

`E_ERROR` (int)
  致命的运行时错误。这类错误一般是不可恢复的情况，例如内存分配导致的问题。后果是导致脚本终止不再继续运行。 常量值 `1`
`E_WARNING` (int)
  运行时警告 (非致命错误)。仅给出提示信息，但是脚本不会终止运行。 常量值：`2`
`E_PARSE` (int)
  编译时解析错误。解析错误只由解析器产生。 常量值：`4`
`E_NOTICE` (int)
  运行时通知。表示脚本遇到可能会表现为错误的情况，但是在可以正常运行的脚本里面也可能会有类似的通知。 常量值：`8`
`E_CORE_ERROR` (int)
  在 PHP 初始化启动过程中发生的致命错误。该错误类似 `E_ERROR`，但是是由 PHP 引擎核心产生。 常量值：`16`
`E_CORE_WARNING` (int)
  PHP 初始化启动过程中发生的警告 (非致命错误) 。类似 `E_WARNING`，但是是由 PHP 引擎核心产生。 常量值：`32`
`E_COMPILE_ERROR` (int)
  致命编译时错误。类似 `E_ERROR`，但是是由 Zend 脚本引擎产生。 常量值：`64`
`E_COMPILE_WARNING` (int)
  编译时警告 (非致命错误)。类似 `E_WARNING`，但是是由 Zend 脚本引擎产生。 常量值：`128`
`E_DEPRECATED` (int)
  运行时弃用通知。启用后将会对在未来版本中可能无法正常工作的代码给出警告。 常量值：`8192`
`E_USER_ERROR` (int)
  用户产生的错误信息。类似 `E_ERROR`，但是是由用户自己在代码中使用 PHP 函数 trigger_error() 来产生。 常量值：`256`
  警告

  自 PHP 8.4.0 起，已弃用此常量与 trigger_error() 一起使用的用法。建议改为 `throw` Exception 或调用 exit()。

`E_USER_WARNING` (int)
  用户产生的警告信息。类似 `E_WARNING`，由用户自己在代码中使用 PHP 函数 trigger_error() 来产生。 常量值：`512`
`E_USER_NOTICE` (int)
  用户产生的通知信息。类似 `E_NOTICE`，由用户自己在代码中使用 PHP 函数 trigger_error() 来产生。 常量值：`1024`
`E_USER_DEPRECATED` (int)
  用户产生的警告信息。 类似 `E_DEPRECATED`, 由用户自己在代码中使用 PHP 函数 trigger_error() 来产生。 常量值：`16384`
`E_STRICT` (int)
  PHP 发出有关执行代码的运行时建议，以确保向前兼容。 常量值：`2048`
  警告

  此错误级别未使用，且自 PHP 8.4.0 起已弃用。

`E_RECOVERABLE_ERROR` (int)
  旧引擎“exception”对应于可捕获的致命错误。与 Error 类似，但必须通过用户定义的错误处理程序捕获（请参阅 set_error_handler()）。如果不处理，则其行为类似于 `E_ERROR`。 常量值：`4096`

  > 注意: 此错误级别实际上未使用，唯一可能发生这种情况的情况是将 object 解释为 bool 失败。这只会发生在内部对象中。 PHP 8.4.0 之前，最常见的示例是在条件中使用 GMP 实例。

`E_ALL` (int)
  包含每个错误、警告和通知的位掩码。 常量值：`30719`
  警告

  在 PHP 8.4 之前，常量值是：`32767`

# 示例

下面我们可以看到错误处理功能在 PHP 中的使用的示例。定义错误处理函数，记录错误信息到文件中（使用 XML 格式），并在发生严重错误时向开发人员发送电子邮件。

示例 #1 在脚本中使用错误句柄

    <?php
    // 我们将要定义自己的错误处理
    error_reporting(0);

    // 用户自定义错误处理函数
    function userErrorHandler($errno, $errmsg, $filename, $linenum, $vars)
    {
        // 错误发生的时间
        $dt = date("Y-m-d H:i:s (T)");

        // 定义错误字符串的关联数组
        // 在这里我们只考虑
        // E_WARNING, E_NOTICE, E_USER_ERROR,
        // E_USER_WARNING 和 E_USER_NOTICE
        $errortype = array (
                    E_ERROR              => 'Error',
                    E_WARNING            => 'Warning',
                    E_PARSE              => 'Parsing Error',
                    E_NOTICE             => 'Notice',
                    E_CORE_ERROR         => 'Core Error',
                    E_CORE_WARNING       => 'Core Warning',
                    E_COMPILE_ERROR      => 'Compile Error',
                    E_COMPILE_WARNING    => 'Compile Warning',
                    E_USER_ERROR         => 'User Error',
                    E_USER_WARNING       => 'User Warning',
                    E_USER_NOTICE        => 'User Notice',
                    E_STRICT             => 'Runtime Notice',
                    E_RECOVERABLE_ERROR  => 'Catchable Fatal Error'
                    );
        // 设置要保存变量跟踪信息的错误类别
        $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, "Variables") . "</vartrace>\n";
        }
        $err .= "</errorentry>\n\n";

        // for testing
        // echo $err;

        // 记录错误信息到错误日志，并在发生关键用户错误时发送电子邮件
        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("Incorrect parameters, arrays expected", E_USER_ERROR);
            return NULL;
        }

        if (count($vect1) != count($vect2)) {
            trigger_error("Vectors need to be of the same size", 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("Coordinate $i in vector 1 is not a number, using zero",
                                E_USER_WARNING);
                $c1 = 0.0;
            }
            if (!is_numeric($c2)) {
                trigger_error("Coordinate $i in vector 2 is not a number, using zero",
                                E_USER_WARNING);
                $c2 = 0.0;
            }
            $d += $c2*$c2 - $c1*$c1;
        }
        return sqrt($d);
    }

    $old_error_handler = set_error_handler("userErrorHandler");

    // 未定义的常量，将产生一个警告
    $t = I_AM_NOT_DEFINED;

    // 定义一些 "载体"
    $a = array(2, 3, "foo");
    $b = array(5.5, 4.3, -1.6);
    $c = array(1, -3);

    // 引发一个用户错误
    $t1 = distance($c, $b) . "\n";

    // 再次引发一个用户错误
    $t2 = distance($b, "i am not an array") . "\n";

    // 引发一个警告
    $t3 = distance($a, $b) . "\n";

    ?>

# 错误处理 函数

# 参见

参见 syslog()。

# debug_backtrace

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

debug_backtrace — 产生一条回溯跟踪(backtrace)

### 说明

function debug_backtrace(int `$options` = `DEBUG_BACKTRACE_PROVIDE_OBJECT`, int `$limit` = 0): array

debug_backtrace() 产生一条 PHP 的回溯跟踪(backtrace)。

### 参数

`options`

  这个参数是以下选项的位掩码：

  debug_backtrace() 选项
  DEBUG_BACKTRACE_PROVIDE_OBJECT | 是否填充 "object" 的索引。
  DEBUG_BACKTRACE_IGNORE_ARGS | 是否忽略 "args" 的索引，包括所有的 function/method 的参数，能够节省内存开销。

  > 注意:

  > 有四种可能的组合：

  > debug_backtrace() 选项
  > `debug_backtrace()` | 两个索引都有
  > `debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT)`
  > `debug_backtrace(1)`
  > `debug_backtrace(0)` | 忽略索引 `"object"` 和填充索引 `"args"`。
  > `debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS)` | 忽略索引 `"object"` 和 索引 `"args"`。
  > `debug_backtrace(2)`
  > `debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT|DEBUG_BACKTRACE_IGNORE_ARGS)` | 填充索引 `"object"` 和忽略索引 `"args"`。
  > `debug_backtrace(3)`

`limit`

  这个参数能够用于限制返回堆栈帧的数量。默认为（`limit`=`0`），返回所有的堆栈帧。

### 返回值

返回一个包含众多关联数组的 array。 以下为有可能返回的元素：

有可能从 debug_backtrace() 返回的元素
名字 | 类型 | 说明
--- | --- | ---
function | string | 当前的函数名，参见：__FUNCTION__。
line | int | 当前的行号。参见：__LINE__。
file | string | 当前的文件名。参见：__FILE__。
class | string | 当前 class 的名称。参见__CLASS__
object | object | 当前的 object。
type | string | 当前调用的类型。如果是一个方法，会返回 "->"。如果是一个静态方法，会返回 "::"。如果是一个函数调用，则返回空。
args | array | 如果在一个函数里，这会列出函数的参数。如果是在一个被包含的文件里，会列出包含的文件名。

### 示例

示例 #1 debug_backtrace() 范例

    <?php
    // filename: /tmp/a.php

    function a_test($str)
    {
        echo "\nHi: $str";
        var_dump(debug_backtrace());
    }

    a_test('friend');
    ?>

    <?php
    // filename: /tmp/b.php
    include_once '/tmp/a.php';
    ?>

执行 /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"
      }
    }

### 参见

- trigger_error() - 产生一个用户级别的 error/warning/notice 信息
- debug_print_backtrace() - 打印一条回溯。

# debug_print_backtrace

(PHP 5, PHP 7, PHP 8)

debug_print_backtrace — 打印一条回溯。

### 说明

function debug_print_backtrace(int `$options` = 0, int `$limit` = 0): void

debug_print_backtrace() 打印了一条 PHP 回溯。它打印了函数调用、被 included/required 的文件和 eval() 的代码。

### 参数

`options`

  这个参数是以下选项的位掩码：

  debug_print_backtrace() 选项
  DEBUG_BACKTRACE_IGNORE_ARGS | 是否忽略 "args" 的索引，包括所有的 function/method 的参数，能够节省内存开销。

`limit`

  这个参数能够用于限制返回堆栈帧的数量。 默认为 (`limit`=`0`) ，返回所有的堆栈帧。

### 返回值

没有返回值。

### 示例

示例 #1 debug_print_backtrace() 范例

    <?php
    // include.php file

    function a() {
        b();
    }

    function b() {
        c();
    }

    function c(){
        debug_print_backtrace();
    }

    a();

    ?>

    <?php
    // 文件 test.php
    // 这是你应该运行的文件

    include 'include.php';
    ?>

以上示例的输出类似于：

    #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]

### 参见

- debug_backtrace() - 产生一条回溯跟踪(backtrace)

# error_clear_last

(PHP 7, PHP 8)

error_clear_last — 清除最近一次错误

### 说明

function error_clear_last(): void

### 参数

此函数没有参数。

### 返回值

清除最近一次错误，使它无法通过 error_get_last() 获取。

### 示例

示例 #1 error_clear_last() 例子

    <?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());
    ?>

以上示例的输出类似于：

    NULL
    NULL
    array(4) {
      ["type"]=>
      int(8)
      ["message"]=>
      string(21) "Undefined variable: b"
      ["file"]=>
      string(9) "%s"
      ["line"]=>
      int(6)
    }
    NULL

### 参见

- Error 常量

# error_get_last

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

error_get_last — 获取最后发生的错误

### 说明

function error_get_last(): ?array

获取关于最后一个发生的错误的信息。

### 参数

此函数没有参数。

### 返回值

返回了一个关联数组，描述了最后错误的信息，以该错误的 "type"、 "message"、"file" 和 "line" 为数组的键。 如果该错误由 PHP 内置函数导致的，"message"会以该函数名开头。 如果还没有错误则返回 `null`。

### 示例

示例 #1 An error_get_last() 范例

    <?php
    echo $a;
    print_r(error_get_last());
    ?>

以上示例的输出类似于：

    Array
    (
        [type] => 8
        [message] => Undefined variable: a
        [file] => C:\WWW\index.php
        [line] => 2
    )

### 参见

- Error 常量
- $php_errormsg 变量
- error_clear_last() - 清除最近一次错误
- `display_errors` 指令
- `html_errors` 指令
- `xmlrpc_errors` 指令

# error_log

(PHP 4, PHP 5, PHP 7, PHP 8)

error_log — 发送错误信息到某个地方

### 说明

function error_log(
string `$message`,
int `$message_type` = 0,
?string `$destination` = `null`,
?string `$additional_headers` = `null`
): bool

把错误信息发送到 web 服务器的错误日志，或者到一个文件里。

### 参数

`message`

  应该被记录的错误信息。

`message_type`

  设置错误应该发送到何处。可能的信息类型有以下几个：

  error_log() 日志类型
  0 | `message` 发送到 PHP 的系统日志，使用 操作系统的日志机制或者一个文件，取决于 error_log 指令设置了什么。 这是个默认的选项。
  1 | `message` 发送到参数 `destination` 设置的邮件地址。 第四个参数 `additional_headers` 只有在这个类型里才会被用到。
  2 | 不再是一个选项。
  3 | `message` 被发送到位置为 `destination` 的文件里。 字符 `message` 不会默认被当做新的一行。
  4 | `message` 直接发送到 SAPI 的日志处理程序中。

`destination`

  目标。它的含义描述于以上，由 `message_type` 参数所决定。

`additional_headers`

  额外的头。当 `message_type` 设置为 `1` 的时候使用。 该信息类型使用了 mail() 的同一个内置函数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。如果 `message_type` 是 0，此函数始终返回 `true`，无论是否可以记录错误。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `destination` 和 `additional_headers` 允许为 null。

### 示例

示例 #1 error_log() 范例

    <?php
    // 如果无法连接到数据库，发送通知到服务器日志
    if (!Ora_Logon($username, $password)) {
        error_log("Oracle database not available!", 0);
    }

    // 如果用尽了 FOO，通过邮件通知管理员
    if (!($foo = allocate_new_foo())) {
        error_log("Big trouble, we're all out of FOOs!", 1,
                   "operator@example.com");
    }

    // 调用 error_log() 的另一种方式:
    error_log("You messed up!", 3, "/var/tmp/my-errors.log");
    ?>

### 注释

警告

error_log() 并非二进制安全的。null 字符可能截断 `message`。

小技巧

`message` 不能包含 null 字符。注意，`message` 可能会发送到文件、邮件、syslog 等。所以在调用 error_log() 前需要使用适合的转换/转义函数：base64_encode()、rawurlencode() 或 addslashes()。

# error_reporting

(PHP 4, PHP 5, PHP 7, PHP 8)

error_reporting — 设置应该报告何种 PHP 错误

### 说明

function error_reporting(?int `$error_level` = `null`): int

error_reporting() 函数能够在运行时设置 error_reporting 指令。 PHP 有诸多错误级别，使用该函数可以设置在脚本运行时的级别。 如果没有设置可选参数 `error_level`， error_reporting() 仅会返回当前的错误报告级别。

### 参数

`error_level`

  新的 error_reporting 级别。 可以是一个位掩码也可以是一个已命名的常量。 强烈建议使用已命名的常量，以确保兼容将来的版本。 由于错误级别的添加、整数取值范围的增加， 较久的基于整数的错误级别不会总是和预期的表现一致。

  可用的错误级别常量及其实际含义描述在了 predefined constants 中。

### 返回值

在更改为 `error_level` 之前返回 error_reporting 级别。

> 注意: 错误控制 `@` 运算符在错误处理期间会更改错误级别。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `error_level` 现在可以为空。

### 示例

示例 #1 error_reporting() 范例

    <?php

    // 关闭所有PHP错误报告
    error_reporting(0);

    // Report simple running errors
    error_reporting(E_ERROR | E_WARNING | E_PARSE);

    // 报告 E_NOTICE也挺好 (报告未初始化的变量
    // 或者捕获变量名的错误拼写)
    error_reporting(E_ERROR | E_WARNING | E_PARSE | E_NOTICE);

    // 除了 E_NOTICE，报告其他所有错误
    error_reporting(E_ALL ^ E_NOTICE);

    // 报告所有 PHP 错误
    error_reporting(E_ALL);

    // 报告所有 PHP 错误
    error_reporting(-1);

    // 和 error_reporting(E_ALL); 一样
    ini_set('error_reporting', E_ALL);

    ?>

### 注释

小技巧

传入 `-1` 的值将尽可能显示所有错误，甚至包括将来 PHP 可能加入的新的错误级别和常量。常量 `E_ALL` 有同样的行为。

### 参见

- display_errors 指令
- html_errors 指令
- xmlrpc_errors 指令
- 错误控制运算符
- ini_set() - 为一个配置选项设置值

# get_error_handler

(PHP 8 >= 8.5.0)

get_error_handler — 获取用户定义的错误处理函数

### 说明

function get_error_handler(): ?callable

返回当前错误处理函数（如果存在）。

### 参数

此函数没有参数。

### 返回值

返回当前定义的错误处理程序（如果存在）。如果使用内置错误处理程序，则返回 `null`。

返回的处理程序是传递给 set_error_handler() 以定义它的精确可调用值。

### 示例

示例 #1 get_error_handler() 示例

    <?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)

    ?>

### 注释

小技巧

在 PHP 8.5.0 之前，以下 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;
        }
    }
    ?>

### 参见

- error_reporting() - 设置应该报告何种 PHP 错误
- set_error_handler() - 设置用户自定义的错误处理函数
- restore_error_handler() - 还原之前的错误处理函数
- trigger_error() - 产生一个用户级别的 error/warning/notice 信息
- 错误级别常量

# get_exception_handler

(PHP 8 >= 8.5.0)

get_exception_handler — 获取用户定义的异常处理函数

### 说明

function get_exception_handler(): ?callable

返回当前异常处理函数（如果存在）。

### 参数

此函数没有参数。

### 返回值

返回当前定义的异常处理程序（如果存在）。如果没有定义处理程序，则返回 `null`。

返回的处理程序是传递给 set_exception_handler() 以定义它的精确可调用值。

### 示例

示例 #1 get_exception_handler() 示例

    <?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)

    ?>

### 注释

小技巧

在 PHP 8.5.0 之前，以下 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;
        }
    }
    ?>

### 参见

- set_exception_handler() - 设置用户自定义的异常处理函数
- restore_exception_handler() - 恢复之前定义过的异常处理函数。
- restore_error_handler() - 还原之前的错误处理函数
- error_reporting() - 设置应该报告何种 PHP 错误
- 异常

# restore_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

restore_error_handler — 还原之前的错误处理函数

### 说明

function restore_error_handler(): true

在使用 set_error_handler() 改变错误处理函数之后，此函数可以 用于还原之前的错误处理程序(可以是内置的或者也可以是用户所定义的函数)。

### 参数

此函数没有参数。

### 返回值

总是返回 `true`。

### 示例

示例 #1 restore_error_handler() 范例

如果是 unserialize() 导致了一个错误，接下来 会恢复原来的错误处理函数。

    <?php
    function unserialize_handler($errno, $errstr)
    {
        echo "Invalid serialized value.\n";
    }

    $serialized = 'foo';
    set_error_handler('unserialize_handler');
    $original = unserialize($serialized);
    restore_error_handler();
    ?>

以上示例会输出：

    Invalid serialized value.

### 参见

- error_reporting() - 设置应该报告何种 PHP 错误
- set_error_handler() - 设置用户自定义的错误处理函数
- get_error_handler() - 获取用户定义的错误处理函数
- restore_exception_handler() - 恢复之前定义过的异常处理函数。
- trigger_error() - 产生一个用户级别的 error/warning/notice 信息

# restore_exception_handler

(PHP 5, PHP 7, PHP 8)

restore_exception_handler — 恢复之前定义过的异常处理函数。

### 说明

function restore_exception_handler(): true

在使用 set_exception_handler() 改变异常处理函数之后，此函数可以 用于还原之前的异常处理程序(可以是内置的或者也可以是用户所定义的函数)。

### 参数

此函数没有参数。

### 返回值

总是返回 `true`。

### 示例

示例 #1 restore_exception_handler() 范例

    <?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('This triggers the first exception handler...');
    ?>

以上示例会输出：

    [exception_handler_1] This triggers the first exception handler...

### 参见

- set_exception_handler() - 设置用户自定义的异常处理函数
- get_exception_handler() - 获取用户定义的异常处理函数
- set_error_handler() - 设置用户自定义的错误处理函数
- restore_error_handler() - 还原之前的错误处理函数
- error_reporting() - 设置应该报告何种 PHP 错误

# set_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

set_error_handler — 设置用户自定义的错误处理函数

### 说明

function set_error_handler(?callable `$callback`, int `$error_levels` = `E_ALL`): ?callable

设置用户的函数 (`callback`) 来处理脚本中出现的错误。

本函数可用于在运行时定义自定义错误处理程序，例如，在应用程序中发生严重错误，或者在特定条件下触发了错误（使用 trigger_error()），应用程序需要执行文件/数据清理。

重要的是要记住 `error_levels` 里指定的错误类型都会绕过 PHP 标准错误处理程序， 除非回调函数返回了 `false`。 error_reporting() 设置将不会起到作用而继续会调用错误处理函数 —— 不过仍然可以获取 error_reporting 的当前值，并做适当处理。

同时注意，处理程序有责任在必要时使用 exit() 停止脚本执行。 如果错误处理程序返回了，脚本将会在发生错误的后一行继续执行。

以下级别的错误不能由用户定义的函数来处理，独立于发生错误的地方： `E_ERROR`、 `E_PARSE`、 `E_CORE_ERROR`、 `E_CORE_WARNING`、 `E_COMPILE_ERROR`、 `E_COMPILE_WARNING`，和在 调用 set_error_handler() 函数所在文件中产生的大多数 `E_STRICT`。

如果错误发生在脚本执行之前（比如文件上传时），将不会 调用自定义的错误处理程序因为它尚未在那时注册。

### 参数

`callback`

  如果传递 `null`，则处理程序重置为默认状态。否则，处理程序是具有以下签名的回调。

  function handler(
  int `$errno`,
  string `$errstr`,
  string `$errfile` = ?,
  int `$errline` = ?,
  array `$errcontext` = ?
  ): bool
  `errno`
    第一个参数 `errno`，将会以 int 形式传递错误的级别。
  `errstr`
    第二个参数 `errstr`，将会以 string 形式传递错误的信息。
  `errfile`
    如果回调接受第三个参数，`errfile`，将会以 string 形式传递错误的文件名。
  `errline`
    如果回调接受第四个参数，`errline`，将会以 int 形式传递错误发生的行号。
  `errcontext`
    如果回调接受第五个参数，`errcontext` 将会传递数组，该数组指向错误发生时活动符号表。也就是说，`errcontext` 会包含错误触发处作用域内所有变量的数组。用户的错误处理程序不应该修改错误上下文（context）。
    警告

    此参数自 PHP 7.2.0 后弃用并自 PHP 8.0.0 移除。如果函数没有为该参数定义默认值，那么在调用时会出现“too few arguments”的错误。

  如果函数返回 `false`，标准错误处理处理程序将会继续调用。

`error_levels`

  就像 error_reporting 的 ini 设置能够控制错误的显示一样，此参数能够用于屏蔽 `callback` 的触发。如果没有该掩码，无论 error_reporting 是如何设置的，`callback` 都会在每个错误发生时被调用。

### 返回值

Returns the previously defined error handler (if any) as a callable. If the built-in error handler is used `null` is returned.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 删除 `errcontext` 并不再传递给用户回调。
7.2.0 | `errcontext` 被废弃。使用此参数时会导致 `E_DEPRECATED` 提醒。

### 示例

示例 #1 用 set_error_handler() 和 trigger_error() 进行错误处理

以下示例展示了通过触发错误并以用户自定义的程序来进行内部异常的处理。

    <?php
    // error handler function
    function myErrorHandler($errno, $errstr, $errfile, $errline)
    {
        if (!(error_reporting() & $errno)) {
            // This error code is not included in error_reporting, so let it fall
            // through to the standard PHP error handler
            return false;
        }

        // $errstr may need to be escaped:
        $errstr = htmlspecialchars($errstr);

        switch ($errno) {
        case E_USER_ERROR:
            echo "<b>My ERROR</b> [$errno] $errstr<br />\n";
            echo "  Fatal error on line $errline in file $errfile";
            echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
            echo "Aborting...<br />\n";
            exit(1);

        case E_USER_WARNING:
            echo "<b>My WARNING</b> [$errno] $errstr<br />\n";
            break;

        case E_USER_NOTICE:
            echo "<b>My NOTICE</b> [$errno] $errstr<br />\n";
            break;

        default:
            echo "Unknown error type: [$errno] $errstr<br />\n";
            break;
        }

        /* Don't execute PHP internal error handler */
        return true;
    }

    // function to test the error handling
    function scale_by_log($vect, $scale)
    {
        if (!is_numeric($scale) || $scale <= 0) {
            trigger_error("log(x) for x <= 0 is undefined, you used: scale = $scale", E_USER_ERROR);
        }

        if (!is_array($vect)) {
            trigger_error("Incorrect input vector, array of values expected", E_USER_WARNING);
            return null;
        }

        $temp = array();
        foreach($vect as $pos => $value) {
            if (!is_numeric($value)) {
                trigger_error("Value at position $pos is not a number, using 0 (zero)", E_USER_NOTICE);
                $value = 0;
            }
            $temp[$pos] = log($scale) * $value;
        }

        return $temp;
    }

    // set to the user defined error handler
    $old_error_handler = set_error_handler("myErrorHandler");

    // trigger some errors, first define a mixed array with a non-numeric item
    echo "vector a\n";
    $a = array(2, 3, "foo", 5.5, 43.3, 21.11);
    print_r($a);

    // now generate second array
    echo "----\nvector b - a notice (b = log(PI) * a)\n";
    /* Value at position $pos is not a number, using 0 (zero) */
    $b = scale_by_log($a, M_PI);
    print_r($b);

    // this is trouble, we pass a string instead of an array
    echo "----\nvector c - a warning\n";
    /* Incorrect input vector, array of values expected */
    $c = scale_by_log("not array", 2.3);
    var_dump($c); // NULL

    // this is a critical error, log of zero or negative number is undefined
    echo "----\nvector d - fatal error\n";
    /* log(x) for x <= 0 is undefined, you used: scale = $scale" */
    $d = scale_by_log($a, -2.5);
    var_dump($d); // Never reached
    ?>

以上示例的输出类似于：

    vector a
    Array
    (
        [0] => 2
        [1] => 3
        [2] => foo
        [3] => 5.5
        [4] => 43.3
        [5] => 21.11
    )
    ----
    vector b - a notice (b = log(PI) * a)
    <b>My NOTICE</b> [1024] Value at position 2 is not a number, using 0 (zero)<br />
    Array
    (
        [0] => 2.2894597716988
        [1] => 3.4341896575482
        [2] => 0
        [3] => 6.2960143721717
        [4] => 49.566804057279
        [5] => 24.165247890281
    )
    ----
    vector c - a warning
    <b>My WARNING</b> [512] Incorrect input vector, array of values expected<br />
    NULL
    ----
    vector d - fatal error
    <b>My ERROR</b> [256] log(x) for x <= 0 is undefined, you used: scale = -2.5<br />
      Fatal error on line 35 in file trigger_error.php, PHP 5.2.1 (FreeBSD)<br />
    Aborting...<br />

### 参见

- ErrorException
- error_reporting() - 设置应该报告何种 PHP 错误
- get_error_handler() - 获取用户定义的错误处理函数
- trigger_error() - 产生一个用户级别的 error/warning/notice 信息
- error level constants

# set_exception_handler

(PHP 5, PHP 7, PHP 8)

set_exception_handler — 设置用户自定义的异常处理函数

### 说明

function set_exception_handler(?callable `$callback`): ?callable

设置默认的异常处理程序，用于没有用 try/catch 块来捕获的异常。 在 `callback` 调用后异常会中止。

### 参数

`callback`

  当一个未捕获的异常发生时所调用的函数。该处理函数需要接受一个参数，该参数是抛出的 Throwable 对象。Error 和 Exception 都实现了 Throwable 接口。这是处理程序签名：

  function handler(Throwable `$ex`): void

  也可以传递 `null` 值用于重置异常处理函数为默认值。

### 返回值

返回之前定义的异常处理程序，或者在错误时返回 `null`。如果之前没有定义错误处理程序，也会返回 `null`。

### 示例

示例 #1 set_exception_handler() 范例

    <?php
    function exception_handler(Throwable $exception) {
      echo "Uncaught exception: " , $exception->getMessage(), "\n";
    }

    set_exception_handler('exception_handler');

    throw new Exception('Uncaught Exception');
    echo "Not Executed\n";
    ?>

### 参见

- get_exception_handler() - 获取用户定义的异常处理函数
- restore_exception_handler() - 恢复之前定义过的异常处理函数。
- restore_error_handler() - 还原之前的错误处理函数
- error_reporting() - 设置应该报告何种 PHP 错误
- 异常

# trigger_error

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

trigger_error — 产生一个用户级别的 error/warning/notice 信息

### 说明

function trigger_error(string `$message`, int `$error_level` = `E_USER_NOTICE`): true

用于触发一个用户级别的错误条件，它能结合内置的错误处理器所关联，或者可以使用用户定义的函数作为新的错误处理程序(set_error_handler())。

该函数在你运行出现异常时，需要产生一个特定的响应时非常有用。

### 参数

`message`

  该 error 的特定错误信息，长度限制在了 1024 个字节。超过 1024 字节的字符都会被截断。

`error_level`

  该 error 所特定的错误类型。仅 `E_USER_*` 系列常量对其有效，默认是 `E_USER_NOTICE`。

  警告

  现已弃用传递 `E_USER_ERROR` 作为 `error_level`。抛出 Exception 或调用 exit()。

### 返回值

总是返回 `true`。

### 错误／异常

如果 `error_level` 不是 `E_USER_ERROR`、`E_USER_WARNING`、`E_USER_NOTICE` 或 `E_USER_DEPRECATED`，此函数将抛出 ValueError。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 现已弃用传递 `E_USER_ERROR` 作为 `error_level`。抛出 Exception 或调用 exit()。
8.4.0 | 此函数现在返回类型是 true 而不是 bool。
8.0.0 | 如果指定 `error_level` 无效，此函数现在将抛出 ValueError。之前返回 `false`。

### 示例

示例 #1 trigger_error() 示例

set_error_handler() 可见到更多详细的例子。

    <?php
    $password = $_POST['password'] ?? '';
    if ($password === '') {
      trigger_error("Using an empty password is unsafe", E_USER_WARNING);
    }
    $hash = password_hash($password, PASSWORD_DEFAULT);
    ?>

### 注释

警告

在 `message` 里的 HTML 实体，并不会被转义。如果错误消息要显示在浏览器里，需要对错误消息使用 htmlentities()。

### 参见

- error_reporting() - 设置应该报告何种 PHP 错误
- set_error_handler() - 设置用户自定义的错误处理函数
- restore_error_handler() - 还原之前的错误处理函数
- 错误级别常量
- Deprecated 注解

# user_error

(PHP 4, PHP 5, PHP 7, PHP 8)

user_error — 别名 trigger_error()

### 说明

此函数是该函数的别名： trigger_error().

## 目录

- debug_backtrace — 产生一条回溯跟踪(backtrace)
- debug_print_backtrace — 打印一条回溯。
- error_clear_last — 清除最近一次错误
- error_get_last — 获取最后发生的错误
- error_log — 发送错误信息到某个地方
- error_reporting — 设置应该报告何种 PHP 错误
- get_error_handler — 获取用户定义的错误处理函数
- get_exception_handler — 获取用户定义的异常处理函数
- restore_error_handler — 还原之前的错误处理函数
- restore_exception_handler — 恢复之前定义过的异常处理函数。
- set_error_handler — 设置用户自定义的错误处理函数
- set_exception_handler — 设置用户自定义的异常处理函数
- trigger_error — 产生一个用户级别的 error/warning/notice 信息
- user_error — 别名 trigger_error

- 安装/配置
  - 运行时配置
- 预定义常量
- 示例
- 错误处理 函数
  - debug_backtrace — 产生一条回溯跟踪(backtrace)
  - debug_print_backtrace — 打印一条回溯。
  - error_clear_last — 清除最近一次错误
  - error_get_last — 获取最后发生的错误
  - error_log — 发送错误信息到某个地方
  - error_reporting — 设置应该报告何种 PHP 错误
  - get_error_handler — 获取用户定义的错误处理函数
  - get_exception_handler — 获取用户定义的异常处理函数
  - restore_error_handler — 还原之前的错误处理函数
  - restore_exception_handler — 恢复之前定义过的异常处理函数。
  - set_error_handler — 设置用户自定义的错误处理函数
  - set_exception_handler — 设置用户自定义的异常处理函数
  - trigger_error — 产生一个用户级别的 error/warning/notice 信息
  - user_error — 别名 trigger_error

# 外部函数接口

# 简介

此扩展允许在纯 PHP 中加载共享库（.DLL 或 .so）、调用 C 函数、访问 C 数据结构，而无需深入了解 Zend 扩展 API，也无需学习第三方“中间”语言。公共 API 是使用包含几个静态方法（有几个可以动态调用）和对象重载方法（执行与 C 数据的实际交互）的 FFI 类实现的。

警告

FFI 有危险，因为它允许在系统上进行底层交互。FFI 扩展应该仅供有 C 和使用 C API 经验的开发者使用。为了最大限度降低风险，ffi.enable php.ini 指令会限制 FFI API 的使用。

> 注意: FFI 扩展不会提供讨厌的过时 PHP 扩展 API，它仅仅是提供了用于 C 函数和数据结构的特殊接口。

小技巧

目前，访问 FFI 数据结构比访问原生 PHP 数组和对象慢很多（大约 2 倍）。 因此使用 FFI 扩展来提高速度没有意义；减少内存消耗可能有意义。

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置

## 需求

This extension requires the » libffi library to be installed.

## 安装

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.

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

FFI 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
ffi.enable | "preload" | `INI_SYSTEM` |
ffi.preload | "" | `INI_SYSTEM` |

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`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().

# 示例

## 目录

- 基础 FFI 用法
- PHP 回调
- 完整 PHP/FFI/preloading 示例

## 基础 FFI 用法

在深入了解 FFI API 细节之前，先看几个示例，展示 FFI API 在常规任务中的简单使用。

> 注意: 其中一些示例需要 libc.so.6，因此在没有该库的系统上无法运行。

示例 #1 从共享库中调用函数

    <?php
    // 创建 FFI 对象，加载 libc 和输出函数 printf()
    $ffi = FFI::cdef(
        "int printf(const char *format, ...);", // 这是普遍的 C 声明
        "libc.so.6");
    // call C's printf()
    $ffi->printf("Hello %s!\n", "world");
    ?>

以上示例会输出：

    Hello world!

> 注意: 请注意，一些 C 函数需要特定的调用规则，例如 `__fastcall`、`__stdcall` 或 `__vectorcall`。

示例 #2 调用函数，通过参数返回结构体

    <?php
    // 创建 gettimeofday() 绑定
    $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");
    // 创建 C 数据结构
    $tv = $ffi->new("struct timeval");
    $tz = $ffi->new("struct timezone");
    // 调用 C 的 gettimeofday()
    var_dump($ffi->gettimeofday(FFI::addr($tv), FFI::addr($tz)));
    // 访问 C 数据结构的字段
    var_dump($tv->tv_sec);
    // 打印完整数据结构
    var_dump($tz);
    ?>

以上示例的输出类似于：

    int(0)
    int(1555946835)
    object(FFI\CData:struct timezone)#3 (2) {
      ["tz_minuteswest"]=>
      int(0)
      ["tz_dsttime"]=>
      int(0)
    }

示例 #3 访问已存在的 C 变量

    <?php
    // 创建 FFI 对象，加载 libc 和输出 errno 变量
    $ffi = FFI::cdef(
        "int errno;", // 这是普遍的 C 声明
        "libc.so.6");
    // print C's errno
    var_dump($ffi->errno);
    ?>

以上示例会输出：

    int(0)

示例 #4 创建和修改 C 变量

    <?php
    // 创建新的 C int 变量
    $x = FFI::new("int");
    var_dump($x->cdata);

    // 简单赋值
    $x->cdata = 5;
    var_dump($x->cdata);

    // 复合赋值
    $x->cdata += 2;
    var_dump($x->cdata);
    ?>

以上示例会输出：

    int(0)
    int(5)
    int(7)

示例 #5 使用 C 数组

    <?php
    // 创建 C 数据结构
    $a = FFI::new("long[1024]");
    // 使用它就像使用常规数组
    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));
    ?>

以上示例会输出：

    int(25)
    int(523776)
    int(1024)
    int(8192)

示例 #6 使用 C 枚举

    <?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);
    ?>

以上示例会输出：

    int(0)
    int(2)
    int(3)

## PHP 回调

可以将 PHP 闭包分配给函数指针类型的原生变量，或将其作为函数参数传递。

示例 #1 将 PHP Closure 指派给 C 函数指针

    <?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";
    ?>

以上示例会输出：

    Hello World 1!
    {
            Hello World 2!
    }
    Hello World 3!

虽然这样可以运行，但并非所有的 libffi 平台都支持这个功能，而且效率不高，并且在请求结束时会泄漏资源。
小技巧

因此，建议尽量减少使用 PHP 回调函数。

## 完整 PHP/FFI/preloading 示例

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");
    ?>

# C 代码和数据的主接口

(PHP 7 >= 7.4.0, PHP 8)

## 简介

通过工厂方法 FFI::cdef()、FFI::load() 或 FFI::scope() 创建该类的对象。定义的 C 变量作为有效的 FFI 实例属性，定义的 C 函数作为有效的 FFI 实例方法。声明的 C 类型可以用于 FFI::new() 和 FFI::type() 创建新的 C 数据结构。

FFI 定义解析和共享库加载可能需要较长时间。在 Web 环境中，每个 HTTP 请求都进行这些操作是没有意义的。然而，在 PHP 启动时预加载 FFI 定义和库，并在需要时实例化 FFI 对象是可能的。header 文件可以使用特殊的 `FFI_SCOPE` 定义进行扩展（例如 `#define FFI_SCOPE "foo"`），然后在预加载期间由 FFI::load() 加载。这将创建持久绑定，将通过 FFI::scope() 在所有后续请求中可用。有关详细信息，请参阅完整的 PHP/FFI/preloading 示例。

可以将多个 C header 文件预加载到同一作用域中。

## 类摘要

final class FFI {
/* 常量 */
public const int __BIGGEST_ALIGNMENT__;
/* 方法 */
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
}

## 预定义常量

`FFI::__BIGGEST_ALIGNMENT__`

# FFI::addr

(PHP 7 >= 7.4.0, PHP 8)

FFI::addr — Creates an unmanaged pointer to C data

### 说明

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.

### 参数

`ptr`
  The handle of the pointer to a C data structure.

### 返回值

Returns the freshly created FFI\CData object.

# FFI::alignof

(PHP 7 >= 7.4.0, PHP 8)

FFI::alignof — Gets the alignment

### 说明

public static function FFI::alignof(FFI\CData|FFI\CType `&$ptr`): int

Gets the alignment of the given FFI\CData or FFI\CType object.

### 参数

`ptr`
  The handle of the C data or type.

### 返回值

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

### 说明

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]);
    ?>

### 参数

`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.

### 返回值

Returns the freshly created FFI\CType object.

# FFI::cast

(PHP 7 >= 7.4.0, PHP 8)

FFI::cast — Performs a C type cast

### 说明

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.

### 参数

`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.

### 返回值

Returns the freshly created FFI\CData object.

### 更新日志

版本 | 说明
--- | ---
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

### 说明

public static function FFI::cdef(string `$code` = "", ?string `$lib` = `null`): FFI

Creates a new FFI object.

### 参数

`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.

  > 注意: 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.

  > 注意: 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.

### 返回值

Returns the freshly created FFI object.

### 更新日志

版本 | 说明
--- | ---
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

### 说明

public static function FFI::free(FFI\CData `&$ptr`): void

Manually releases a previously created unmanaged data structure.

### 参数

`ptr`
  The handle of the unmanaged pointer to a C data structure.

### 返回值

没有返回值。

# FFI::isNull

(PHP 7 >= 7.4.0, PHP 8)

FFI::isNull — Checks whether a FFI\CData is a null pointer

### 说明

public static function FFI::isNull(FFI\CData `&$ptr`): bool

Checks whether a FFI\CData is a null pointer.

### 参数

`ptr`
  The handle of the pointer to a C data structure.

### 返回值

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

### 说明

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.

### 参数

`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"`.

### 返回值

Returns the freshly created FFI object, or `null` on failure.

### 更新日志

版本 | 说明
--- | ---
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.

### 参见

- 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

### 说明

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.

### 参数

`ptr1`
  The start of one memory area.
`ptr2`
  The start of another memory area.
`size`
  The number of bytes to compare.

### 返回值

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

### 说明

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`.

### 参数

`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.

### 返回值

没有返回值。

# FFI::memset

(PHP 7 >= 7.4.0, PHP 8)

FFI::memset — Fills a memory area

### 说明

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`.

### 参数

`ptr`
  The start of the memory area to fill.
`value`
  The byte to fill with.
`size`
  The number of bytes to fill.

### 返回值

没有返回值。

# FFI::new

(PHP 7 >= 7.4.0, PHP 8)

FFI::new — Creates a C data structure

### 说明

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.

### 参数

`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()).

### 返回值

Returns the freshly created FFI\CData object, or `null` on failure.

### 更新日志

版本 | 说明
--- | ---
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

### 说明

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.

### 参数

`name`
  The scope name defined by a special `FFI_SCOPE` define.

### 返回值

Returns the freshly created FFI object.

### 参见

- 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

### 说明

public static function FFI::sizeof(FFI\CData|FFI\CType `&$ptr`): int

Returns the size of the given FFI\CData or FFI\CType object.

### 参数

`ptr`
  The handle of the C data or type.

### 返回值

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

### 说明

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`.

### 参数

`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`.

### 返回值

The freshly created PHP string.

### 更新日志

版本 | 说明
--- | ---
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

### 说明

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.

### 参数

`type`
  A valid C declaration as string.

### 返回值

Returns the freshly created FFI\CType object, or `null` on failure.

### 更新日志

版本 | 说明
--- | ---
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

### 说明

public static function FFI::typeof(FFI\CData `&$ptr`): FFI\CType

Gets the FFI\CType object representing the type of the given FFI\CData object.

### 参数

`ptr`
  The handle of the pointer to a C data structure.

### 返回值

Returns the FFI\CType object representing the type of the given FFI\CData object.

## 目录

- 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)

## 简介

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.

> 注意: 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.

## 类摘要

namespace FFI;
final class CData {
}

## 更新日志

版本 | 说明
--- | ---
8.3.0 | FFI\CData can now be assigned to structs and fields.

# C Type Handles

(PHP 7 >= 7.4.0, PHP 8)

## 简介

## 类摘要

namespace FFI;
final class CType {
/* 常量 */
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;
/* 方法 */
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
}

## 预定义常量

`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

### 说明

public function FFI\CType::getAlignment(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# FFI\CType::getArrayElementType

(PHP 8 >= 8.1.0)

FFI\CType::getArrayElementType — Description

### 说明

public function FFI\CType::getArrayElementType(): FFI\CType

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# FFI\CType::getArrayLength

(PHP 8 >= 8.1.0)

FFI\CType::getArrayLength — Description

### 说明

public function FFI\CType::getArrayLength(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# FFI\CType::getAttributes

(PHP 8 >= 8.1.0)

FFI\CType::getAttributes — Description

### 说明

public function FFI\CType::getAttributes(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# FFI\CType::getEnumKind

(PHP 8 >= 8.1.0)

FFI\CType::getEnumKind — Description

### 说明

public function FFI\CType::getEnumKind(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# FFI\CType::getFuncABI

(PHP 8 >= 8.1.0)

FFI\CType::getFuncABI — Description

### 说明

public function FFI\CType::getFuncABI(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# FFI\CType::getFuncParameterCount

(PHP 8 >= 8.1.0)

FFI\CType::getFuncParameterCount — Retrieve the count of parameters of a function type

### 说明

public function FFI\CType::getFuncParameterCount(): int

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function FFI\CType::getFuncParameterType(int `$index`): FFI\CType

Returns the type of a parameter for the underlying function type.

### 参数

`index`
  Index of the function parameter, zero-based.

### 返回值

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

### 说明

public function FFI\CType::getFuncReturnType(): FFI\CType

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# FFI\CType::getKind

(PHP 8 >= 8.1.0)

FFI\CType::getKind — Description

### 说明

public function FFI\CType::getKind(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# FFI\CType::getName

(PHP 7 >= 7.4.0, PHP 8)

FFI\CType::getName — Description

### 说明

public function FFI\CType::getName(): string

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# FFI\CType::getPointerType

(PHP 8 >= 8.1.0)

FFI\CType::getPointerType — Description

### 说明

public function FFI\CType::getPointerType(): FFI\CType

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# FFI\CType::getSize

(PHP 8 >= 8.1.0)

FFI\CType::getSize — Description

### 说明

public function FFI\CType::getSize(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# FFI\CType::getStructFieldNames

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldNames — Description

### 说明

public function FFI\CType::getStructFieldNames(): array

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# FFI\CType::getStructFieldOffset

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldOffset — Description

### 说明

public function FFI\CType::getStructFieldOffset(string `$name`): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

`name`

### 返回值

# FFI\CType::getStructFieldType

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldType — Description

### 说明

public function FFI\CType::getStructFieldType(string `$name`): FFI\CType

警告

本函数还未编写文档，仅有参数列表。

### 参数

`name`

### 返回值

## 目录

- 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)

## 简介

## 类摘要

namespace FFI;
class Exception extends Error {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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)

## 简介

## 类摘要

namespace FFI;
final class ParserException extends FFI\Exception {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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 用法
  - PHP 回调
  - 完整 PHP/FFI/preloading 示例
- FFI — C 代码和数据的主接口
  - 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

# 简介

OPcache 通过将 PHP 脚本预编译的字节码存储到共享内存中来提升 PHP 的性能，存储预编译字节码的好处就是省去了每次加载和解析 PHP 脚本的开销。

PHP 5.5.0 及后续版本中已经绑定了 OPcache 扩展。对于 PHP 5.2，5.3 和 5.4 版本可以使用 » PECL 扩展中的 OPcache 库。

# 安装/配置

## 目录

- 安装
- 运行时配置

## 安装

OPcache 只能编译为共享扩展。 如果你使用 --disable-all 参数 禁用了默认扩展的构建， 那么必须使用 --enable-opcache 选项来开启 OPcache。

编译之后，就可以使用 zend_extension 指令来将 OPcache 扩展加载到 PHP 中。在非 Windows 平台使用 `zend_extension=/full/path/to/opcache.so`， Windows 平台使用 `zend_extension=C:\path\to\php_opcache.dll`。

> 注意: 如果想将 » Xdebug 与 OPcache 一起使用，必须在 Xdebug 之前加载 OPcache。

### 推荐的 php.ini 设置

使用下列推荐设置来获得较好的 性能：

    opcache.memory_consumption=128
    opcache.interned_strings_buffer=8
    opcache.max_accelerated_files=4000
    opcache.revalidate_freq=60
    opcache.fast_shutdown=1
    opcache.enable_cli=1 ; prior to PHP 7.2.0

你也可以禁用 opcache.save_comments 并且启用 opcache.enable_file_override。 需要提醒的是，在生产环境中使用上述配置之前，必须经过严格测试。 因为上述配置存在一个已知问题，它会引发一些框架和应用的异常， 尤其是在存在文档使用了备注注解的时候。

在 Windows 上，应该启用 opcache.file_cache_fallback，以及应该将 opcache.file_cache 设置为存在且可写的目录。

这里是 OPcache 可用的配置指令完整列表。

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

OPcache 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
opcache.enable | 1 | `INI_ALL` |
opcache.enable_cli | 0 | `INI_SYSTEM` | 在 PHP 7.1.2 至 7.1.6（含）的版本，默认值是 `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` | 从 PHP 7.2.0 开始被移除
opcache.enable_file_override | 0 | `INI_SYSTEM` |
opcache.optimization_level | 0x7FFEBFFF | `INI_SYSTEM` | 从 PHP 7.3.0 起修改为 `0x7FFFBFFF`
opcache.inherited_hack | 1 | `INI_SYSTEM` | 自 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` | 自 8.1.18 和 8.2.5 起禁用。从 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` | 自 PHP 8.0.0 起有效
opcache.preferred_memory_model | "" | `INI_SYSTEM` |
opcache.protect_memory | 0 | `INI_SYSTEM` |
opcache.mmap_base | `null` | `INI_SYSTEM` | 仅限 Windows。
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` | 自 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 平台
opcache.validate_permission | 0 | `INI_SYSTEM` | 从 PHP 7.0.14 开始支持
opcache.validate_root | 0 | `INI_SYSTEM` | 从 PHP 7.0.14 开始支持
opcache.preload | "" | `INI_SYSTEM` | 从 PHP 7.4.0 开始支持
opcache.preload_user | "" | `INI_SYSTEM` | 从 PHP 7.4.0 开始支持
opcache.cache_id | "" | `INI_SYSTEM` | 仅支持 Windows。自 PHP 7.4.0 起有效
opcache.jit | "disable" | `INI_ALL` | 自 PHP 8.0.0 起有效，PHP 8.4.0 之前，默认值为“tracing”。
opcache.jit_buffer_size | 64M | `INI_SYSTEM` | 自 PHP 8.0.0 起有效，PHP 8.4.0 之前，默认值为 0。
opcache.jit_debug | 0 | `INI_ALL` | 自 PHP 8.0.0 起有效
opcache.jit_bisect_limit | 0 | `INI_ALL` | 自 PHP 8.0.0 起有效
opcache.jit_prof_threshold | 0.005 | `INI_ALL` | 自 PHP 8.0.0 起有效
opcache.jit_max_root_traces | 1024 | `INI_SYSTEM` | 自 PHP 8.0.0 起有效
opcache.jit_max_side_traces | 128 | `INI_SYSTEM` | 自 PHP 8.0.0 起有效
opcache.jit_max_exit_counters | 8192 | `INI_SYSTEM` | 自 PHP 8.0.0 起有效
opcache.jit_hot_loop | 64 | `INI_SYSTEM` | 自 PHP 8.0.0 起有效
opcache.jit_hot_func | 127 | `INI_SYSTEM` | 自 PHP 8.0.0 起有效
opcache.jit_hot_return | 8 | `INI_SYSTEM` | 自 PHP 8.0.0 起有效
opcache.jit_hot_side_exit | 8 | `INI_SYSTEM` | 自 PHP 8.0.0 起有效
opcache.jit_blacklist_root_trace | 16 | `INI_ALL` | 自 PHP 8.0.0 起有效
opcache.jit_blacklist_side_trace | 8 | `INI_ALL` | 自 PHP 8.0.0 起有效
opcache.jit_max_loop_unrolls | 8 | `INI_ALL` | 自 PHP 8.0.0 起有效
opcache.jit_max_recursive_calls | 2 | `INI_ALL` | 自 PHP 8.0.0 起有效
opcache.jit_max_recursive_returns | 2 | `INI_ALL` | 自 PHP 8.0.0 起有效
opcache.jit_max_polymorphic_calls | 2 | `INI_ALL` | 自 PHP 8.0.0 起有效

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`opcache.enable` bool
  启用操作码缓存。如果禁用此选项，则不会优化和缓存代码。 在运行期使用 ini_set() 函数只能禁用 `opcache.enable` 设置，不可以启用此设置。 如果在脚本中尝试启用此设置项会产生警告。
`opcache.enable_cli` bool
  仅针对 CLI 版本的 PHP 启用操作码缓存。 通常被用来测试和调试。
`opcache.memory_consumption` int
  OPcache 的共享内存大小，以兆字节为单位。最小允许值为 `"8"`。如果设置的值小于最小值，则强制设置为允许的最小值。
`opcache.interned_strings_buffer` int
  用来存储预留字符串的内存大小，以 MB 为单位。最大值在 64 位架构上为 32767，在 32 位架构上为 4095。

  > 注意: PHP 8.4.0 之前，所有架构上的最大值都是 4095 MB。

`opcache.max_accelerated_files` int
  OPcache 哈希表中可存储的脚本文件数量上限。真实的取值是在质数集合`{ 223, 463, 983, 1979, 3907, 7963, 16229, 32531, 65407, 130987, 262237, 524521, 1048793 }` 中找到的第一个大于等于设置值的质数。设置值取值范围最小值是 200，最大值是 1000000。超出范围的值将限制为允许的值。
`opcache.max_wasted_percentage` int
  如果可用内存不足，在计划重新启动之前，允许浪费的最大内存百分比。最大允许值是 `"50"`，如果设置了更大的值，则强制设置为允许的最大值。
`opcache.use_cwd` bool
  如果启用，OPcache 将在哈希表的脚本键之后附加改脚本的工作目录， 以避免同名脚本冲突的问题。 禁用此选项可以提高性能，但是可能会导致应用崩溃。
`opcache.validate_timestamps` bool

  如果启用，那么 OPcache 会每隔 opcache.revalidate_freq 设定的秒数 检查脚本是否更新。 如果禁用此选项，你必须使用 opcache_reset() 或者 opcache_invalidate() 函数来手动重置 OPcache，也可以 通过重启 Web 服务器来使文件系统更改生效。

  > 注意: 如果将 opcache.file_update_protection 或 opcache.max_file_size 选项设置为非零值，OPcache 仍可能在编译时验证文件的时间戳。

`opcache.revalidate_freq` int
  检查脚本时间戳是否有更新的周期，以秒为单位。 设置为 `0` 会导致针对每个请求， OPcache 都会检查脚本更新。 如果 opcache.validate_timestamps 配置指令设置为禁用，那么此设置项将会被忽略。
`opcache.revalidate_path` bool
  如果禁用此选项，在同一个 include_path 已存在的缓存文件会被重用。 因此，将无法找到不在包含路径下的同名文件。
`opcache.save_comments` bool
  如果禁用，脚本文件中的注释内容将不会被包含到操作码缓存文件， 这样可以有效减小优化后的文件体积。 禁用此配置指令可能会导致一些依赖注释或注解的 应用或框架无法正常工作， 比如： Doctrine， Zend Framework 2 以及 PHPUnit。
`opcache.fast_shutdown` bool
  如果启用，则会使用快速停止续发事件。 所谓快速停止续发事件是指依赖 Zend 引擎的内存管理模块 一次释放全部请求变量的内存，而不是依次释放每一个已分配的内存块。 从 PHP 7.2.0 开始，此配置指令被移除。 快速停止的续发事件的处理已经集成到 PHP 中， 只要有可能，PHP 会自动处理这些续发事件。
`opcache.enable_file_override` bool
  如果启用，则在调用函数 file_exists()， is_file() 以及 is_readable() 的时候， 都会检查操作码缓存，无论文件是否已经被缓存。 如果应用中包含检查 PHP 脚本存在性和可读性的功能，这样可以提升性能。 但是如果禁用了 opcache.validate_timestamps 选项， 可能存在返回过时数据的风险。
`opcache.optimization_level` int
  控制执行哪些优化的二进制位掩码。默认是应用所有安全优化。更改默认值对于调试/开发优化器非常有用（参见 opcache.opt_debug_level）。
`opcache.inherited_hack` bool
  该配置指令已被忽略。
`opcache.dups_fix` bool
  仅作为针对 “不可重定义类”错误的一种解决方案。
`opcache.blacklist_filename` string
  OPcache 黑名单文件位置。 黑名单文件为文本文件，包含了不进行预编译优化的文件名，每行一个文件名。 黑名单中的文件名可以使用通配符，也可以使用前缀。 此文件中以分号（;）开头的行将被视为注释。 简单的黑名单文件可能如下所示：

      ; 将特定文件加入到黑名单
      /var/www/broken.php
      ; 以字符 x 文件打头的文件
      /var/www/x
      ; 通配符匹配
      /var/www/*-broken.php

`opcache.max_file_size` int
  以字节为单位的缓存的文件大小上限。设置为 `0` 表示缓存全部文件。
`opcache.consistency_checks` int
  如果是非 0 值，OPcache 将会每隔 N 次请求检查缓存校验和。 N 即为此配置指令的设置值。 由于此选项对于性能有较大影响，请尽在调试环境使用。

  > 注意: 自 8.1.18 和 8.2.5 起禁用。从 PHP 8.3.0 起已删除。

`opcache.force_restart_timeout` int
  如果缓存处于非激活状态，等待多少秒之后计划重启。 如果超出了设定时间，则 OPcache 模块将杀除持有缓存锁的进程， 并进行重启。 如果选项 opcache.log_verbosity_level 设置为 2 或者 2 以上的数值，当发生重启时将在日志中记录一条警告信息。 Windows 不支持该指令。
`opcache.error_log` string
  OPcache 模块的错误日志文件。 如果留空，则视为 `stderr`， 错误日志将被送往标准错误输出 （通常情况下是 Web 服务器的错误日志文件）。
`opcache.log_verbosity_level` int
  OPcache 模块的日志级别。 默认情况下，仅有致命级别（0）及错误级别（1）的日志会被记录。 其他可用的级别有：警告（2），信息（3）和调试（4）。
`opcache.record_warnings` bool
  如果启用，OPcache 将记录编译时警告并在下次对其重播，即使是从缓存中提供的。
`opcache.preferred_memory_model` string
  OPcache 首选的内存模块。 如果留空，OPcache 会选择适用的模块， 通常情况下，自动选择就可以满足需求。 可选值包括： `mmap`，`shm`, `posix` 以及 `win32`。
`opcache.protect_memory` bool
  保护共享内存，以避免执行脚本时发生非预期的写入。 仅用于内部调试。
`opcache.mmap_base` string
  在 Windows 平台上共享内存段的基地址。 所有的 PHP 进程都将共享内存映射到同样的地址空间。 使用此配置指令避免“无法重新附加到基地址”的错误。
`opcache.restrict_api` string
  仅允许路径是以指定字符串开始的 PHP 脚本调用 OPcache API 函数。 默认值为空字符串 `""`，表示不做限制。
`opcache.file_update_protection` string
  如果文件的最后修改时间距现在不足此项配置指令所设定的秒数，那么这个文件不会进入到缓存中。 这是为了防止尚未完全修改完毕的文件进入到缓存。如果所有文件更新都是原子的，则可以通过将其设置为 `0` 来提高性能。这将允许文件立即缓存。
`opcache.huge_code_pages` bool
  启用或者禁用将 PHP 代码（文本段）拷贝到 HUGE PAGES 中。这应该会提高性能，但是需要适当的 OS 配置。自 PHP 7.0.0 起可在 Linux 上使用，自 PHP 7.4.0 上可在 FreeBSD 上使用。
`opcache.lockfile_path` string
  用来存储共享锁文件的绝对路径（仅适用于 *nix 操作系统）。
`opcache.opt_debug_level` string
  出于对不同阶段的优化情况进行调试的目的，生成操作码转储。 设置为 0x10000 会在进行优化之前输出编译器编译后的操作码， 设置为 0x20000 会输出优化后的操作码。
`opcache.file_cache` string
  配置二级缓存目录并启用二级缓存。 启用二级缓存可以在 SHM 内存满了、服务器重启或者重置 SHM 的时候提高性能。 默认值为空字符串 `""`，表示禁用基于文件的缓存。
`opcache.file_cache_only` bool
  启用或禁用在共享内存中的 opcode 缓存。

  > 注意: 在 PHP 8.1.0 之前，已经存在文件缓存时禁用此指令需要手动清除文件缓存。

`opcache.file_cache_consistency_checks` bool
  当从文件缓存中加载脚本的时候，是否对文件的校验和进行验证。
`opcache.file_cache_fallback` bool
  在 Windows 平台上，当一个进程无法附加到共享内存的时候， 使用基于文件的缓存，也即：`opcache.file_cache_only=1`。 需要显示的启用文件缓存。
  警告

  不鼓励禁用此配置项， 禁用它可能会导致进程无法启动。

`opcache.validate_permission` bool
  针对当前用户，验证缓存文件的访问权限。
`opcache.validate_root` bool
  在 chroot 的环境中避免命名冲突。 为了防止进程访问到 chroot 环境之外的文件，应该在 chroot 的情况下启用这个选项。
`opcache.preload` string
  指定要在服务器启动时期进行编译和缓存的 PHP 脚本文件， 这些文件也可能通过 include 或者 opcache_compile_file() 函数 来预加载其他文件。 所有这些文件中包含的实体，包括函数、类等，在服务器启动的时候就被加载和缓存， 对于用户代码来讲是“开箱可用”的。

  > 注意: Windows 不支持预加载。

`opcache.preload_user` string
  预加载以指定系统用户身份运行。这对于切换到非特权系统用户之前以 root 身份启动的服务器很有用。考虑到安全因素，默认禁止以 root 身份预加载代码，除非该指令明确设置为 `root`。自 PHP 8.3.0 起，当使用 CLI SAPI 或 phpdbg SAPI 以 root 身份运行时，无需设置此指令即可允许预加载。
`opcache.cache_id` string

  在 Windwos 上，运行在相同 PHP SAPI 且相同的用户账户使用相同缓存 ID 上的所有进程，会共享单个 OPcache 实例。缓存 ID 的值可以自由选择。

  小技巧

  对于 IIS，使用环境变量 APP_POOL_ID 作为 `opcache.cache_id`，可以让不同的应用池拥有自己的 OPcache 实例。

`opcache.jit` string|int
  针对经典用法，此选项接受以下四个字符串值之一：
  - `disable`：完全禁用，无法在运行时启用。
  - `off`：禁用，但可以在运行时启用。
  - `tracing`/`on`：使用追踪 JIT。默认启用并推荐给大部分用户。
  - `function`：使用函数 JIT。

  针对高级用法，此选项接受 4 位整数 `CRTO`，其中的位分别是：

  `C`（特定 CPU 优化 flag）
    - `0`：禁用特定 CPU 优化。
    - `1`：如果 CPU 支持则启用 AVX。
  `R`（寄存器分配）
    - `0`：不执行寄存器分配。
    - `1`：执行局部域寄存器分配。
    - `2`：执行全局寄存器分配。
  `T`（触发）
    - `0`: 在脚本加载时编译所有函数。
    - `1`: 在第一次执行时编译函数。
    - `2`：第一次请求时分析函数，然后编译最热门函数。
    - `3`：动态分析和编译热门函数。
    - `4`：目前未使用。
    - `5`：使用追踪 JIT。动态分析和为热门代码段编译追踪。
  `O`（优化级别）
    - `0`：不 JIT。
    - `1`：最小 JIT（调用标准 VM 处理程序）。
    - `2`：内联 VM 处理程序。
    - `3`：使用类型推断。
    - `4`：使用调用图。
    - `5`：优化整个脚本。
  `"tracing"` 模式对应 `CRTO = 1254`，`"function"` 模式对应 `CRTO = 1205`。
`opcache.jit_buffer_size` int
  为编译 JIT 代码保留的共享内存量。值 0 表示禁用 JIT。 当使用 int 时, 其值以字节来衡量。还可以使用在 FAQ 中描述的速记符。
`opcache.jit_debug` int
  指定位掩码，用于启动哪个 JIT 调试输出。参阅 » zend_jit.h （搜索以 `ZEND_JIT_DEBUG` 开头的宏定义）。
`opcache.jit_bisect_limit` int
  调试选项，在编译一定数量的函数之后禁用 JIT 编译。这对于定位 JIT 错误编译的源代码可能很有帮助。注意：此选项仅在 JIT 触发设置为 0（在脚本加载时编译）或1（第一次执行时编译）时起作用，例如 `opcache.jit=1215`。更多详细信息请参阅 opcache.jit 选项。
`opcache.jit_prof_threshold` float
  当使用“首次请求时分析”触发模式时，此阈值确定是否视函数为热点。对该函数的调用次数除以所有函数的调用次数必须高于该阈值。例如，阈值为 0.005 表示占所有调用次数超过 0.5% 的函数将被进行 JIT 编译。
`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.
`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
  在将 root trace 列入黑名单之前，尝试编译 side trace 的最大次数。
`opcache.jit_blacklist_side_trace` int
  在将 side trace 列入黑名单之前，尝试编译 side trace 的最大次数。
`opcache.jit_max_loop_unrolls` int
  在 side trace 中展开循环的最大尝试次数，试图到达 root trace 并关闭外循环。
`opcache.jit_max_recursive_calls` int
  递归调用循环的最大展开次数。
`opcache.jit_max_recursive_returns` int
  递归返回循环的最大展开次数。
`opcache.jit_max_polymorphic_calls` int
  内联 polymorphic（动态或方法）调用的最大尝试次数。超过此限制的调用被视为 megamorphic，不会进行内联处理。

# 预加载

从 PHP 7.4.0 起，PHP 可以被配置为在引擎启动时将一些脚本预加载进 opcache 中。在那些文件中的任何函数、类、 接口或者 trait （但不包括常量）将在接下来的所有请求中变为全局可用，不再需要显示地包含它们。这牺牲了基准的 内存占用率但换来了方便和性能（因为这些代码将始终可用）。它还需要通过重启 PHP 进程来清除预加载的脚本， 这意味着这个功能仅在生产环境中有实用价值，而非开发环境。

需要注意的是，性能和内存之间的最佳平衡因应用而异。 “预加载一切” 可能是最简单的策略，但不一定是最好的策略。 此外，只有当不同的请求间有持久化的进程时，预加载才有用。这意味着，虽然在启用了 opcache 的命令行脚本中可以使用预加载， 但这通常是没有意义的。例外情况是在使用预加载时的 FFI 库。

> 注意: Windows 上不支持预加载。

配置预加载需要两步，并且要求开启 opcache。首先，在php.ini 中设置 opcache.preload 的值：

    opcache.preload=preload.php

preload.php 是一个在服务器启动时会运行一次（PHP-FPM、mod_php 等）的任意文件， 它的代码会加载到持久化内存中。在以 root 用户启动后切换到非特权系统用户的服务器上，又或者是以 root 用户身份运行 PHP 的情况（不建议这样做），可以通过opcache.preload_user 来指定进行预加载的系统用户。 默认情况下，不允许以 root 用户身份进行预加载。通过设置 `opcache.preload_user=root` 来显示地允许它。

在 preload.php 脚本中， 任何被 include、 include_once、require、require_once或 opcache_compile_file() 引用的文件将被解析到持久化内存中。 在下面的这个例子中， 所有在 src 目录下的 .php 文件将被预加载，除非那是一个 `Test` 文件。

    <?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];
    }
    ?>

include 和 opcache_compile_file() 都会生效，但对代码处理方式有不同的影响。 Both include and opcache_compile_file() will work, but have different implications for how code gets handled.

- include 将执行文件中的代码，而 opcache_compile_file() 不会执行代码。这意味着只有前者支持条件声明（在 if 块中声明函数）。
- 由于 include 会执行代码，因此所有被 include 的文件也将被解析， 其中的定义也将被预加载。
- opcache_compile_file() 可以按任何顺序加载文件。也就是说，如果 a.php 定义了类 `A`，而 b.php 定义了一个继承类 `A` 的类 `B`， 则 opcache_compile_file() 可以按任何顺序来加载这两个文件。然而，当使用 include 时， a.php 必须 先被包含。
- 不管在哪种情况下，如果一个脚本包含了一个已经被预加载的文件，那么这个已经被预加载的文件里的内容仍将被执行， 但其中定义的任何符号将不会被重新定义。使用 include_once 不会阻止文件被二次包含。有时候可能仍需要重新加载文件 来包含其中定义的全局常量，因为这些常量预加载并不会处理。

因此，哪种方式更好取决于所需的行为。对于本来会使用自动加载器的代码，opcache_compile_file() 有更高的灵活性。而对于本来会需要手动加载的代码，include 会更健壮。

# OPcache 函数

# opcache_compile_file

(PHP 5 >= 5.5.5, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_compile_file — 无需运行，即可编译并缓存 PHP 脚本

### 说明

function opcache_compile_file(string `$filename`): bool

该函数可以用于在不用运行某个 PHP 脚本的情况下，编译该 PHP 脚本并将其添加到字节码缓存中去。 该函数可用于在 Web 服务器重启之后初始化缓存，以供后续请求调用。

### 参数

`filename`
  被编译的 PHP 脚本的路径。

### 返回值

如果 `filename` 被成功编译，则返回 `true` 或者在失败时返回 `false`。

### 错误／异常

如果 `filename` 不能被载入或者不能被编译，则会生成 `E_WARNING` 级别的错误。 可以使用 @ 来抑制该警告。

### 参见

- opcache_invalidate() - 废除脚本缓存

# opcache_get_configuration

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_get_configuration — 获取缓存的配置信息

### 说明

function opcache_get_configuration(): array|false

该函数将返回缓存实例的配置信息。

### 参数

此函数没有参数。

### 返回值

返回一个数组，该数组里包含了缓存的初始化信息，黑名单和版本号。

### 错误／异常

在启用了 `opcache.restrict_api` 的情况下，如果当前路径在禁止规则里，将会出现 E_WARNING ；不会返回任何状态信息。

### 参见

- opcache_get_status() - 获取缓存的状态信息

# opcache_get_status

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_get_status — 获取缓存的状态信息

### 说明

function opcache_get_status(bool `$include_scripts` = `true`): array|false

该函数将返回内存中缓存实例的状态信息。不会返回有关文件缓存的任何信息。

### 参数

`include_scripts`
  包含脚本的具体声明信息。

### 返回值

返回可能包含脚本特定状态信息的数组， 或者在失败时返回 `false`。

### 错误／异常

在启用了 `opcache.restrict_api` 的情况下，如果当前路径在禁止规则里，将会出现 E_WARNING ；不会返回任何状态信息。

### 更新日志

版本 | 说明
--- | ---
PHP 8.3.0 | `opcache_get_status()['scripts'][n]['revalidate']` 现在包含 Unix 时间戳，表示下次重新验证脚本时间戳的时间，由 `opcache.revalidate_freq` INI 指令指定。

### 示例

示例 #1 opcache_get_status() 示例

    <?php
    var_dump(opcache_get_status());
    ?>

以上示例的输出类似于：

    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)
      }
    }

### 参见

- opcache_get_configuration() - 获取缓存的配置信息

# opcache_invalidate

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)

opcache_invalidate — 废除脚本缓存

### 说明

function opcache_invalidate(string `$filename`, bool `$force` = `false`): bool

该函数的作用是使得指定脚本的字节码缓存失效。如果 `force` 没有设置或者传入的是 `false`，那么只有当脚本的修改时间比对应字节码的时间更新，脚本的缓存才会失效。此函数仅使内存缓存无效，而不是文件缓存。

### 参数

`filename`
  缓存需要被作废对应的脚本路径
`force`
  如果该参数设置为`true`，那么不管是否必要，该脚本的缓存都将被废除。

### 返回值

如果 `filename` 的字节码缓存失效设置成功或者该脚本本来就没有缓存，则返回 `true`；如果字节码缓存被禁用，则返回`false`。

### 参见

- opcache_compile_file() - 无需运行，即可编译并缓存 PHP 脚本
- opcache_reset() - 重置字节码缓存的内容

# opcache_is_script_cached

(PHP 5 >= 5.5.11, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.4)

opcache_is_script_cached — 用于判断脚本是否已缓存在 OPCache 中

### 说明

function opcache_is_script_cached(string `$filename`): bool

此函数用于检查 PHP 脚本是否已缓存在 OPCache 中。可更方便地判断特定脚本的缓存“预热”状态。该函数仅检查内存缓存，不检查文件缓存；若需检查文件缓存，请使用 opcache_is_script_cached_in_file_cache()。

### 参数

`filename`
  待检查的 PHP 脚本路径。

### 返回值

如果 `filename` 已缓存在 OPCache 的内存缓存中，则返回 `true`，否则返回 `false`。

### 参见

- opcache_compile_file() - 无需运行，即可编译并缓存 PHP 脚本
- opcache_is_script_cached_in_file_cache() - 用于判断脚本是否已缓存在 OPCache 文件缓存中

# opcache_is_script_cached_in_file_cache

(PHP 8 >= 8.5.0)

opcache_is_script_cached_in_file_cache — 用于判断脚本是否已缓存在 OPCache 文件缓存中

### 说明

function opcache_is_script_cached_in_file_cache(string `$filename`): bool

此函数用于检查 PHP 脚本是否已缓存在 OPCache 中，可更方便地判断特定脚本的缓存“预热”状态。该函数仅检查文件缓存，不检查内存缓存；若需检查内存缓存，请使用 opcache_is_script_cached()。

### 参数

`filename`
  待检查的 PHP 脚本路径。

### 返回值

如果 `filename` 已缓存在 OPCache 中，则返回 `true`，否则返回 `false`。

### 参见

- opcache_compile_file() - 无需运行，即可编译并缓存 PHP 脚本
- opcache_is_script_cached() - 用于判断脚本是否已缓存在 OPCache 中

# opcache_jit_blacklist

(PHP 8 >= 8.4.0)

opcache_jit_blacklist — 将某个函数加入黑名单，使其不参与 JIT 编译

### 说明

function opcache_jit_blacklist( Closure `$closure` ): void

此函数在启用追踪 JIT 时，将指定的函数加入黑名单，使其不参与 JIT 编译。函数通过 Closure 指定。

警告

函数中已 JIT 编译的部分不受影响，仍会继续使用 JIT 编译。

### 参数

`closure`
  要加入黑名单的函数，以一级可调用形式表示。也可传入匿名函数，此时匿名函数自身会加入黑名单。

### 返回值

没有返回值。

### 示例

示例 #1 opcache_jit_blacklist() 基础示例

    <?php
    function foo() {
        $x = 1;
        $x += 0;
        ++$x;
        var_dump($x);
    }
    opcache_jit_blacklist(foo(...));
    foo();
    ?>

### 参见

- opcache_invalidate() - 废除脚本缓存
- opcache_reset() - 重置字节码缓存的内容

# opcache_reset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)

opcache_reset — 重置字节码缓存的内容

### 说明

function opcache_reset(): bool

该函数将重置整个字节码缓存。在调用 opcache_reset() 之后，所有的脚本将会重新载入并且在下次命中的时候重新解析。此函数仅重置内存中的缓存，不会重置文件缓存。

### 参数

此函数没有参数。

### 返回值

如果重置字节码缓存成功，则返回 `true`；如果字节码缓存被禁用或等待重启或正在重启（参阅 opcache_get_status()），则返回 `false`。

### 参见

- opcache_invalidate() - 废除脚本缓存
- opcache_get_status() - 获取缓存的状态信息

## 目录

- opcache_compile_file — 无需运行，即可编译并缓存 PHP 脚本
- opcache_get_configuration — 获取缓存的配置信息
- opcache_get_status — 获取缓存的状态信息
- opcache_invalidate — 废除脚本缓存
- opcache_is_script_cached — 用于判断脚本是否已缓存在 OPCache 中
- opcache_is_script_cached_in_file_cache — 用于判断脚本是否已缓存在 OPCache 文件缓存中
- opcache_jit_blacklist — 将某个函数加入黑名单，使其不参与 JIT 编译
- opcache_reset — 重置字节码缓存的内容

- 安装/配置
  - 安装
  - 运行时配置
- 预加载
- OPcache 函数
  - opcache_compile_file — 无需运行，即可编译并缓存 PHP 脚本
  - opcache_get_configuration — 获取缓存的配置信息
  - opcache_get_status — 获取缓存的状态信息
  - opcache_invalidate — 废除脚本缓存
  - opcache_is_script_cached — 用于判断脚本是否已缓存在 OPCache 中
  - opcache_is_script_cached_in_file_cache — 用于判断脚本是否已缓存在 OPCache 文件缓存中
  - opcache_jit_blacklist — 将某个函数加入黑名单，使其不参与 JIT 编译
  - opcache_reset — 重置字节码缓存的内容

# 输出缓冲控制

# 简介

输出控制函数能够控制何时从脚本发送输出。对以下几种情况中很有用，尤其是当需要在脚本开始输出数据后将消息头发送到浏览器时。输出控制函数不会影响使用 header() 或 setcookie() 发送的消息头，只会影响 PHP 代码中的函数（比如 echo）和数据。

# 安装/配置

## 目录

- 运行时配置

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

输出控制配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
output_buffering | `"0"` | `INI_PERDIR` |
output_handler | `null` | `INI_PERDIR` |
implicit_flush | `"0"` | `INI_ALL` |
url_rewriter.tags | `"form="` | `INI_ALL` | 从 PHP 7.1.0 起，此 INI 设置仅影响 output_add_rewrite_var()。在 PHP 7.1.0 之前，此 INI 设置启用透明会话 id 支持（请参阅 session.trans_sid_tags）。
url_rewriter.hosts | `$_SERVER['HTTP_HOST']` 用作默认值。 | `INI_ALL` | 自 PHP 7.1.0 起可用

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`output_buffering` bool/int

  通过设置该选项为 `"On"`，来启用所有文件的输出缓冲。如果要限制缓冲区的大小，可以使用允许的最大字节数相对应的数字/数量来代替该指令的值 `"On"`。例如 `output_buffering=4096`。该选项在 PHP-CLI 下始终关闭。

`output_handler` string

  脚本的输出可以重定向到函数。例如设置 `output_handler` 为 mb_output_handler() 时，字符编码将会明确转换为指定编码。设置任何输出处理程序都会自动打开输出缓冲。

  > 注意:

  > mb_output_handler() 和 ob_iconv_handler() 不能一起使用，并且 ob_gzhandler() 和 zlib.output_compression 不能与以下函数一起使用 mb_output_handler()、ob_gzhandler()、zlib.output_compression、“URL 重写器”处理程序（请参阅 session.use_trans_sid 和 output_add_rewrite_var())。

  > 注意:

  > 只有内置函数可以使用此指令。对于用户定义的函数，使用 ob_start()。

`implicit_flush` bool

  默认为 `false`。如将该选项改为 `true`，PHP 将使输出层在每段信息块输出后自动刷新。这等同于在每次调用任何产出输出的函数（比如 print、echo）以及每个 HTML 块之后，调用 PHP 函数 flush()。

  在 Web 环境中使用 PHP 时，打开这个选项会严重影响性能，通常只推荐在调试时使用。在 `CLI SAPI` 操作时，此值默认为 `true`。

  参见 ob_implicit_flush()。

`url_rewriter.tags` string
  `url_rewriter.tags` 指定 HTML 标记和属性，其中 URL 由 output_add_rewrite_var() 值重写。默认为 `"form="`。 添加 `"form="` 或任何 `form` 属性将向 `form` 添加隐藏的 `input` 元素，并为传递给 output_add_rewrite_var() 的每个名值对（name-value pair）添加名和值属性。
  警告

  在 `url_rewriter.tags` 中多次添加相同的标签将仅在 URL 重写过程中使用第一次出现的标签。

  > 注意: PHP 7.1.0 之前，使用 url_rewriter.tags 指定 session.trans_sid_tags。

`url_rewriter.hosts` string
  `url_rewriter.hosts` 可以指定重写那些主机包含 output_add_rewrite_var() 值。默认是 `$_SERVER['HTTP_HOST']`。通过不包含空格的逗号分隔列表指定多个主机。例如 `"php.net,wiki.php.net,bugs.php.net"`。

# 预定义常量

下列常量作为 PHP 核心的一部分总是可用的。

传递给输出处理程序的状态 flag

下列 flag 作为位掩码的一部分传递给由 ob_start() 设置的输出处理程序的第二个（`phase`）参数：

`PHP_OUTPUT_HANDLER_START` (int)

  表示输出缓冲已经开始。

`PHP_OUTPUT_HANDLER_WRITE` (int)

  表示输出缓冲区正在刷新，并且有数据要输出。

`PHP_OUTPUT_HANDLER_FLUSH` (int)

  表示缓冲区已清空。

`PHP_OUTPUT_HANDLER_CLEAN` (int)

  表示输出缓冲已清空。

`PHP_OUTPUT_HANDLER_FINAL` (int)

  表示这是最后一次输出缓冲操作。

`PHP_OUTPUT_HANDLER_CONT` (int)

  表示缓冲区已清空，但输出缓冲将继续。

  这是 `PHP_OUTPUT_HANDLER_WRITE` 的别名。

`PHP_OUTPUT_HANDLER_END` (int)

  表示输出缓冲已结束。

  这是 `PHP_OUTPUT_HANDLER_FINAL` 的别名。

输出缓冲区控制 flag

下列 flag 作为位掩码的一部分传递给由 ob_start() 设置的输出处理程序的第三个（`flags`）参数：

`PHP_OUTPUT_HANDLER_CLEANABLE` (int)

  控制 ob_start() 创建的输出缓冲区是否可以由 ob_clean() 清除。这个 flag 不能控制 ob_end_clean() 或 ob_get_clean() 的行为。

`PHP_OUTPUT_HANDLER_FLUSHABLE` (int)

  控制 ob_start() 创建的输出缓冲区是否可以由 ob_flush() 刷新。这个 flag 不能控制 ob_end_flush() 或 ob_get_flush() 的行为。

`PHP_OUTPUT_HANDLER_REMOVABLE` (int)

  控制 ob_start() 创建的输出缓冲区是否可以在脚本结束前或者调用 ob_end_clean()、ob_end_flush()、ob_get_clean() 或 ob_get_flush() 移除。

`PHP_OUTPUT_HANDLER_STDFLAGS` (int)

  输出缓冲区 flag 的默认设置；当前等同于 `PHP_OUTPUT_HANDLER_CLEANABLE` | `PHP_OUTPUT_HANDLER_FLUSHABLE` | `PHP_OUTPUT_HANDLER_REMOVABLE`.

输出处理程序状态 flag

下列 flag 是由 ob_get_status() 返回的 `flags` 位掩码的一部分：

`PHP_OUTPUT_HANDLER_STARTED` (int)

  表示输出处理程序已调用。

`PHP_OUTPUT_HANDLER_DISABLED` (int)

  表示输出处理程序已禁用。当输出处理程序返回 `false` 或者处理缓冲区失败时设置此 flag。 在 PHP 8.4.0 之前，此 flag 可以在启动输出缓冲区时设置。

`PHP_OUTPUT_HANDLER_PROCESSED` (int)

  表示输出处理程序已经成功处理了缓冲区。 自 PHP 8.4.0 起可用。

# 输出缓冲

输出缓冲是在将输出冲刷（发送和丢弃）到浏览器（在 Web 上下文中）或 shell（在命令行上）之前对输出进行缓冲（临时存储）。当输出缓冲处于活动状态时，脚本不会发送任何输出，而是将输出存储在内部缓冲区中。

## 缓冲影响 PHP

PHP 在冲刷输出时依赖底层软件/硬件基础设施。由命令行上（例如行缓冲）的控制台或 Web 上下文中的 Web 服务器和浏览器（例如完全缓冲）实现的缓冲确实会影响向终端用户显示输出的时间。其中一些影响可以通过微调服务器设置和/或调整各层的缓冲区大小来排除。

## PHP 中的输出缓冲控制

PHP 提供了全缓冲的用户级输出缓冲区，包含启动、操作和关闭缓冲区的函数（大多数 ob_* 函数），以及两个刷新底层系统缓冲区的函数（flush() 和 ob_implicit_flush()）。其中一些功能也可以使用合适的 php.ini 配置来设置。

## 用例

输出缓冲通常在修改或检查缓冲的输出或者在请求中多次使用时有用；或者当需要控制输出的冲刷时。具体用例包括：

- 通过生成静态 `HTML` 页面来缓存计算/时间密集型脚本的结果
- 通过显示、保存到文件或通过电子邮件发送来重新使用生成的输出
- 将 `HTML` 页面的 `head` 与 `body` 分开冲刷，允许浏览器在脚本执行潜在的更耗时的任务（例如数据库/文件访问、外部网络连接）时加载外部资源。这只有在发送 header 后 `HTTP` 状态代码不能更改时才有用
- 从原本会产生输出的函数中提取信息（例如 phpinfo()）
- 通过修改/使用部分（例如提取数据、替换字/词组、添加缺失的 `HTML` 标签）来控制第三方代码的输出，或在某些条件下（例如错误）完全丢弃它
- 填充某些不可用的 Web 服务器功能（例如压缩或编码输出）

# 冲刷系统缓冲区

PHP 提供了两种相关的方式来冲刷系统缓冲区（发送并丢弃内容）：通过调用 flush() 以及通过 ob_implicit_flush() 或 php.ini 文件中的 implicit_flush 设置来启用自动冲刷。

## 输出冲刷行为

如果禁用了自动冲刷，PHP 仅在调用 flush() 或脚本结束时才会冲刷输出。

如果启用了自动冲刷，PHP 将尝试在每段代码块产生输出之后进行冲刷。在此上下文中，输出是指非零长度的数据，即：

- `<?php ?>` 标签之外的内容
- 由语言结构和函数打印，其明确目的是打印用户提供的变量或字符串，例如 echo、print、printf()、var_dump()、var_export()、vprintf()
- 由函数打印，其明确目的是收集和输出有关正在运行的脚本或者 PHP 的数据/信息，例如 debug_print_backtrace()、phpcredits()、phpinfo()
- 当 PHP 出现未捕获的异常或未处理的错误时（取决于 display_errors 和 error_reporting 的设置），会打印出相关信息。
- 任何写入到 `php://output` 的内容

> 注意: 打印空字符串或发送头部信息不会视为输出，因此不会导致冲刷操作。

警告

如果启用了自动冲刷，控制字符（如 `"\n"`、`"\r"`、`"\0"`）也将触发冲刷操作。

## 限制

此功能无法冲刷用户级输出缓冲区。要一起使用的话，必须在冲刷系统缓冲区之前冲刷用户级输出缓冲区，以便 PHP 生成任何输出。

警告

调用 flush() 或启用绝对刷新可能会干扰用户级输出缓冲区的输出处理程序，这些输出处理程序在 Web 上下文中设置和发送 header（例如 ob_gzhandler()），因为在这些处理程序能够发送 header 之前，flush() 或绝对刷新就已经发送了 header 信息。

PHP 不能完整覆盖由底层软件/硬件实现的缓冲，在使用 PHP 的缓冲控制函数时应考虑到这一点。检查 Web 服务器/浏览器/控制台缓冲设置并进行相应的处理可以缓解可能的问题。在 Web 环境中工作时，可以调整 Web 服务器的缓冲设置或脚本的缓冲以协同工作，而调整 PHP 脚本中的缓冲设置可以解决各种浏览器的缓冲策略。在实现行缓冲的控制台上，可以在刷新输出之前将换行符插入到适当的位置。

## SAPI 在冲刷方面的不同

尽管每个 SAPI 实现冲刷的方式略有不同，但这些实现都属于以下两类中的一个：

- Web 上下文中使用的 SAPI 将首先冲刷 header，然后冲刷输出。`Apache2Handler`、`CGI`、`FastCGI` 和 `FPM` 都是此类 SAPI
- 其它 SAPI（比如 `CLI` 和 `embed`）仅冲刷输出

# 用户级输出缓冲区

## 目录

- 什么输出会被缓冲？
- 嵌套输出缓冲区
- 缓冲区大小
- 缓冲区中允许的操作
- 输出处理程序
- 使用输出处理程序
- 传递给输出处理程序的 flag
- 输出处理程序的返回值

用户级输出缓冲区可以从 PHP 代码中启动、操作和终止。 每个缓冲区都包括一个输出缓冲区和一个关联的输出处理程序函数。

## 什么输出会被缓冲？

PHP 的用户级输出缓冲区在启动后缓冲所有输出，直到关闭或脚本结束。 在 PHP 的用户级输出缓冲区的上下文中，输出是指 PHP 将显示或发送回浏览器的所有内容。 在实际应用中，输出为非零长度的数据，即：

- `<?php ?>` 标签之外的内容
- 由语言结构和函数打印，其明确目的是打印用户提供的变量或字符串，例如 echo、print、printf()、var_dump()、var_export()、vprintf()
- 由函数打印，其明确目的是收集和输出有关正在运行的脚本或者 PHP 的数据/信息，例如 debug_print_backtrace()、phpcredits()、phpinfo()
- 当 PHP 出现未捕获的异常或未处理的错误时（取决于 display_errors 和 error_reporting 的设置），会打印出相关信息。
- 任何写入到 `php://output` 的内容

> 注意: 用户级输出缓冲区不会捕获直接写入 `stdout` 或传递给具有类似功能的 SAPI 函数的数据。这包括使用 fwrite() 将数据写入 `stdout` 或使用 header() 或 setcookie() 发送的 header。

## 打开输出缓冲

可以通过使用 ob_start() 函数或设置 output_buffering 和 output_handler php.ini 配置来启用输出缓冲。虽然两者都可以创建输出缓冲区，但 ob_start() 更加灵活，因为接受用户定义的函数作为输出处理程序，并且还可以设置对缓冲区允许的操作（冲刷、清空、移除）。通过 ob_start() 开始的缓冲区将从调用该函数的行开始生效，而通过 output_buffering 开始的缓冲区将从脚本的第一行开始缓冲输出。

PHP 还自带了内置的 `"URL-Rewriter"` 输出处理程序，它会启动自己的输出缓冲区，并且任何时候最多只允许有两个实例运行（一个用于用户级别的 URL 重写，另一个用于透明 Session ID 支持）。这些缓冲区可以通过调用 output_add_rewrite_var() 函数或启用 session.use_trans_sid php.ini 设置来启动。

捆绑的 `zlib` 扩展有自己的输出缓冲区，可以使用 zlib.output_compression php.ini 设置启用。

> 注意: `"URL-Rewriter"` 的特殊之处在于同时只允许运行最多两个实例，但所有用户级输出缓冲区都使用 ob_start() 所使用的相同底层缓冲区，并通过自定义的输出处理函数来实现其功能。因此，它们的所有功能都可以由用户级代码模拟。

## 嵌套输出缓冲区

如果在启动新的缓冲区时已经存在一个活跃的输出缓冲区，那么新的缓冲区将会嵌套在先前活跃的缓冲区内。无论是否嵌套，内部缓冲区的行为都将保持一致，外部缓冲区不会再次缓冲内部的缓冲输出。只有当内部缓冲区冲刷的输出才会被外部缓冲区缓冲。

大多数 `ob_*` 函数只能与活跃的输出缓冲区（最后一个启动的）一起使用， 因此只能冲刷、清空和关闭活跃的缓冲区。可以使用的函数有 ob_list_handlers()，它返回所有正在使用的输出处理程序的列表， 以及 ob_get_status()，它可以返回活跃缓冲区的信息或所有正在使用的缓冲区的信息。

调用 ob_get_level() 或 ob_get_status() 将返回活跃输出缓冲区的嵌套级别。

警告

ob_get_level() 和 ob_get_status() 之间相同级别的值相差一。 对于 ob_get_level()，第一个级别是 `1`， 而对于 ob_get_status()，第一个级别是 `0`。

## 缓冲区大小

缓冲区大小由整数表示，表示缓冲区可以存储的字节数，而不会刷新。 当缓冲区中的输出大小超过缓冲区的大小时，缓冲区的内容将被发送到输出处理程序，其返回值将被刷新，缓冲区将被清除。

除了 `"URL-Rewriter"` 之外，输出缓冲区的大小可以在启动缓冲区时设置。 如果设置为 `0`，则输出缓冲区仅受 PHP 可用内存的限制。 如果设置为 `1`，则在生成任何非零长度输出的代码块后，缓冲区将被刷新。

输出缓冲区的大小可通过调用 ob_get_status() 来获取。

使用 ob_start() 启动的输出缓冲区将其缓冲区大小设置为传递给函数的第二个 `chunk_size` 参数的整数值。 如果省略，则设置为 `0`。

以 `"On"` 设置 output_buffering 启动的输出缓冲区将其缓冲区大小设置为 `0`。 如果设置为整数，则缓冲区大小将与该数字对应。

`"URL-Rewriter"` 的缓冲区大小设置为 `0`， 因此仅受 PHP 可用内存的限制。

`zlib` 的输出缓冲区大小由 zlib.output_compression php.ini 设置控制。 如果设置为 `"On"`，缓冲区大小将为 `"16K"`/`16384`。 如果设置为整数，则缓冲区大小将与该数字（字节）对应。

## 缓冲区中允许的操作

可以通过将 缓冲区控制标志 之一传递给 ob_start() 的第三个 `flags` 参数来控制缓冲区上允许的操作。 如果省略，则默认情况下允许所有操作。 如果使用 `0`，则缓冲区不能被刷新、清空或移除，但仍然可以检索其内容。

`PHP_OUTPUT_HANDLER_CLEANABLE` 允许 ob_clean() 清空缓冲区的内容。

警告

缺少 `PHP_OUTPUT_HANDLER_CLEANABLE` 标志 不会阻止 ob_end_clean() 或 ob_get_clean() 清空缓冲区的内容。

`PHP_OUTPUT_HANDLER_FLUSHABLE` 允许 ob_flush() 刷新缓冲区的内容。

警告

缺少 `PHP_OUTPUT_HANDLER_FLUSHABLE` 标志 不会阻止 ob_end_flush() 或 ob_get_flush() 刷新缓冲区的内容。

`PHP_OUTPUT_HANDLER_REMOVABLE` 允许 ob_end_clean()、ob_end_flush()、 ob_get_clean() 或 ob_get_flush() 关闭缓冲区。

`PHP_OUTPUT_HANDLER_STDFLAGS` 这三个标志的组合将允许对缓冲区执行这三个操作。

## 冲刷、访问和清理缓冲区内容

冲刷会发送并丢弃活动缓冲区中的内容。当输出的大小超过缓冲区大小时，或者在脚本结束时，又或者是调用了 ob_flush()、ob_end_flush() 或 ob_get_flush() 函数时，会冲刷输出缓冲区。

警告

调用 ob_end_flush() 或 ob_get_flush() 将关闭活跃的缓冲区。

警告

冲刷缓冲区将冲刷输出处理程序的返回值，这可能与缓冲区的内容不同。 例如，使用 ob_gzhandler() 将压缩输出并冲刷压缩后的输出。

可以通过调用 ob_get_contents()、ob_get_clean() 或 ob_get_flush() 来检索活动缓冲区的内容。

如果只需要缓冲区内容的长度，ob_get_length() 或 ob_get_status() 将返回内容的字节长度。

警告

调用 ob_get_clean() 或 ob_get_flush() 将在返回其内容后关闭活跃的缓冲区。

可以通过调用 ob_clean()、ob_end_clean() 或 ob_get_clean() 来清理活动缓冲区的内容。

警告

调用 ob_end_clean() 或 ob_get_clean() 将关闭活跃的缓冲区。

## 关闭缓冲区

可以通过调用 ob_end_clean()、ob_end_flush()、 ob_get_flush() 或 ob_get_clean() 来关闭输出缓冲区。

警告

没有使用 `PHP_OUTPUT_HANDLER_REMOVABLE` 标志启动的输出缓冲区不能关闭，可能会生成一个 `E_NOTICE`。

脚本结束时或调用 exit() 时，所有未关闭的输出缓冲区都将被冲刷并关闭。 缓冲区将按照它们启动的相反顺序被冲刷并关闭。 最后启动的缓冲区将首先被冲刷，最先启动的缓冲区将最后被冲刷并关闭。

警告

如果不希望冲刷缓冲区的内容，应该使用自定义的输出处理程序来防止在关闭期间冲刷缓冲区的内容。

## 输出处理程序

输出处理程序是与输出缓冲区关联的 callable，通过调用 ob_clean()、ob_flush()、ob_end_flush()、 ob_get_flush()、ob_end_clean()、ob_get_clean() 或 PHP 的关闭过程来调用。

> 注意: 关闭过程将冲刷处理程序的返回值。

如果省略或在启动输出缓冲区时传递 `null`，则将使用内部的 `"default output handler"`，当调用时返回缓冲区的未修改内容。 输出处理程序可用于返回缓冲区内容的修改版本和/或具有副作用（例如发送头部）。

PHP 自带两个内部输出处理程序： `"default output handler"` 和 `"URL-Rewriter"` （它集成到自己的输出缓冲区中，最多只能启动两个实例）。

捆绑的扩展包括四个额外的输出处理程序： mb_output_handler()、ob_gzhandler()、 ob_iconv_handler()、ob_tidyhandler()。

## 使用输出处理程序

调用输出处理程序时，将缓冲区的内容和一个位掩码传递给输出处理程序。

function handler ( string `$buffer` , int `$phase` = ?): string

`buffer`
  输出缓冲区的内容。
`phase`
  `PHP_OUTPUT_HANDLER_*` 常量 的位掩码。

警告

从输出处理程序中调用以下任何函数都会导致致命错误： ob_clean()、ob_end_clean()、 ob_end_flush()、ob_flush()、 ob_get_clean()、ob_get_flush()、 ob_start()。

> 注意: 如果设置了处理程序的 `PHP_OUTPUT_HANDLER_DISABLED`， 那么调用 ob_end_clean()、ob_end_flush()、 ob_get_clean()、ob_get_flush()、 ob_clean()、ob_flush() 或 PHP 的关闭过程将不会调用处理程序。 在 PHP 8.4.0 之前，调用 ob_clean() 或 ob_flush() 时，此标志不起作用。

> 注意: 脚本的工作目录可能会在某些 Web 服务器（例如 Apache 或内置 Web 服务器）的关闭函数中发生变化。

## 传递给输出处理程序的 flag

传递给输出处理程序的第二个 `phase` 参数的位掩码提供了关于处理程序调用的信息。

> 注意: 位掩码可以包含多个标志，应使用按位 `&` 运算符来检查是否设置了标志。

警告

`PHP_OUTPUT_HANDLER_WRITE` 和其别名 `PHP_OUTPUT_HANDLER_CONT` 的值为 `0`， 因此只能通过使用 等号运算符 （`==` 或 `===`）来确定是否设置了它。

下面的标志在处理程序的生命周期的特定阶段设置： `PHP_OUTPUT_HANDLER_START` 在第一次调用处理程序时设置。 `PHP_OUTPUT_HANDLER_FINAL` 或其别名 `PHP_OUTPUT_HANDLER_END` 在最后一次调用处理程序时设置， 即关闭处理程序。此标志也在 PHP 的关闭过程中关闭缓冲区时设置。

下面的标志由特定调用处理程序设置： `PHP_OUTPUT_HANDLER_FLUSH` 在调用 ob_flush() 时设置。 `PHP_OUTPUT_HANDLER_WRITE` 或其别名 `PHP_OUTPUT_HANDLER_CONT` 在其内容的大小等于或超过缓冲区的大小时设置， 并且在缓冲区自动刷新时调用处理程序。 `PHP_OUTPUT_HANDLER_FLUSH` 在调用 ob_clean()、 ob_end_clean() 或 ob_get_clean() 时设置。 当调用 ob_end_clean() 或 ob_get_clean() 时， `PHP_OUTPUT_HANDLER_FINAL` 也会设置。

> 注意: 当调用 ob_end_flush() 或 ob_get_flush() 时， 设置 `PHP_OUTPUT_HANDLER_FINAL` 但未设置 `PHP_OUTPUT_HANDLER_FLUSH`。

## 输出处理程序的返回值

输出处理程序的返回值在内部转换为字符串，遵循标准 PHP 类型语义， 但有两个例外：arrays 和 booleans。

Arrays 被转换为字符串 `"Array"`， 但不会触发 `Array to string conversion` 警告。

如果处理程序返回 `false` 则返回缓冲区的内容。 如果处理程序返回 `true` 则返回一个空字符串。

> 注意: 如果处理程序返回 `false` 或抛出异常，则设置其 `PHP_OUTPUT_HANDLER_DISABLED` 状态标志。

## 输出处理程序中抛出异常

如果在输出处理程序中抛出未捕获的异常，则程序将终止，并在关闭过程中调用处理程序后刷新 `"Uncaught Exception"` 错误消息。

如果未捕获的异常是在由 ob_flush()、ob_end_flush() 或 ob_get_flush() 调用的处理程序中引发的， 则在错误消息之前刷新缓冲区的内容。

如果在关闭过程中的输出处理程序中引发未捕获的异常，则程序终止，而不刷新缓冲区或错误消息。

> 注意: 如果处理程序抛出异常，则设置其 `PHP_OUTPUT_HANDLER_DISABLED` 状态标志。

## 输出处理程序中引发错误

如果在输出处理程序中引发非致命错误，则程序继续执行。

如果非致命错误是在由 ob_flush()、ob_end_flush() 或 ob_get_flush() 调用的处理程序中引发的， 则根据处理程序的返回值刷新特定的数据。 如果处理程序返回 `false` 则刷新缓冲区和错误消息。 如果返回其他任何值，则刷新处理程序的返回值，但不刷新错误消息。

> 注意: 如果处理程序返回 `false`，则设置其 `PHP_OUTPUT_HANDLER_DISABLED` 状态标志。

如果输出处理程序中出现致命错误，则程序终止，并在关闭过程中调用处理程序后刷新错误消息。

如果致命错误是在由 ob_flush()、ob_end_flush() 或 ob_get_flush() 调用的处理程序中引发的， 则在错误消息之前刷新缓冲区的内容。

如果在关闭过程中的输出处理程序中引发致命错误，则程序终止，而不刷新缓冲区或错误消息。

## 输出处理程序中输出

在特定情况下，处理程序中生成的输出与缓冲区的内容一起刷新。 此输出不会附加到缓冲区，也不是由 ob_get_flush() 返回的字符串的一部分。

在冲刷操作（调用 ob_flush()、ob_end_flush()、 ob_get_flush() 和关闭过程中）期间， 如果处理程序的返回值为 `false`，则缓冲区的内容将被刷新，然后输出。 如果处理程序在关闭过程中被调用，则抛出异常或调用 exit() 会导致相同的行为。

> 注意: 如果处理程序返回 `false`，则设置其 `PHP_OUTPUT_HANDLER_DISABLED` 状态标志。

## 输出处理程序状态 flag

每次调用输出处理程序时，缓冲区的 `flags` 位掩码的 处理程序状态标志 都会被设置，并且是由 ob_get_status() 返回的 `flags` 的一部分。 如果处理程序成功执行且未返回 `false`，则设置 `PHP_OUTPUT_HANDLER_STARTED` 和 `PHP_OUTPUT_HANDLER_PROCESSED`。 如果处理程序在执行时返回 `false` 或引发异常，则设置 `PHP_OUTPUT_HANDLER_STARTED` 和 `PHP_OUTPUT_HANDLER_DISABLED`。

> 注意: 如果处理程序设置了 `PHP_OUTPUT_HANDLER_DISABLED` 标志， 则不会调用 ob_end_clean()、ob_end_flush()、 ob_get_clean()、ob_get_flush()、 ob_clean()、ob_flush() 或 PHP 的关闭过程。 在 PHP 8.4.0 之前，调用 ob_clean() 或 ob_flush() 时，此标志不起作用。

# 示例

## 目录

- 基本用法
- 输出重写用法

## 基本用法

示例 #1 输出控制举例

    <?php

    ob_start();
    echo "Hello\n";

    setcookie("cookiename", "cookiedata");

    ob_end_flush();

    ?>

在上面的例子中，echo 函数的输出将一直被保存在输出缓冲区中直到调用 ob_end_flush()。同时对 setcookie() 的调用也成功存储了 cookie，而不会引起错误。（数据已发送到浏览器后，消息头通常无法发送。）

## 输出重写用法

自 PHP 7.1.0 起，output_add_rewrite_var()、output_reset_rewrite_vars() 使用专用的输出缓冲区。即不使用 trans sid 输出缓冲区。

示例 #1 输出重写示例

    <?php
    // 此代码仅适用于 PHP 7.1.0、7.0.10、5.6.25 及更高版本。

    // HTTP_HOST 是默认目标主机。手动设置以使示例代码工作。
    $_SERVER['HTTP_HOST'] = 'php.net';

    // 输出重写仅重写表单。添加 a=href.
    // 可以指定标签 tag_name=url_attr, e.g. img=src,iframe=src
    // 设置间不允许有空格。
    // 表单标签是添加隐藏输入的特殊标签。
    ini_set('url_rewriter.tags','a=href,form=');
    var_dump(ini_get('url_rewriter.tags'));

    // This is added to URL and form
    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>

以上示例会输出：

    <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>

自 PHP 7.1.0 起，输出重写函数有自己的 INI 设置：url_rewriter.tags 和 url_rewriter.hosts。

# 输出控制 函数

# 参见

参阅 header() 和 setcookie()。

# flush

(PHP 4, PHP 5, PHP 7, PHP 8)

flush — 冲刷系统输出缓冲区

### 说明

function flush(): void

冲刷 PHP 的系统写入缓冲区以及 PHP 使用的后端（CGI、Web 服务器）。在命令行环境中，flush() 将仅尝试冲刷缓冲区的内容，而在 Web 上下文中，将冲刷 header 和缓冲区的内容。

> 注意: flush() 可能无法重写 Web 服务器的缓冲方案，并且它对浏览器中的任何客户端缓冲没有影响。

> 注意: 此函数对用户级输出处理程序（例如由 ob_start() 或 output_add_rewrite_var() 启动的处理程序）没有任何影响。

警告

flush() 会干扰在 Web 上下文中设置和发送 header 的输出处理程序（例如 ob_gzhandler()），因为它会在这些处理程序之前发送 header。

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 现在在 FastCGI 中，可以成功冲刷没有主体的 header。

### 参见

- ob_flush() - 冲刷（发送）活动输出处理程序的返回值
- ob_clean() - 清空（擦掉）活动输出缓冲区的内容
- ob_end_flush() - 冲刷（发送）活动输出处理程序的返回值，并关闭活动输出缓冲区
- ob_end_clean() - 清空（擦除）活动缓冲区的内容并关闭它

# ob_clean

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_clean — 清空（擦掉）活动输出缓冲区的内容

### 说明

function ob_clean(): bool

此函数调用输出处理程序（使用 `PHP_OUTPUT_HANDLER_CLEAN` flag），丢弃返回值并清除（擦除）活动输出区的内容。

此函数不会像 ob_end_clean() 或 ob_get_clean() 那样关闭输出缓冲区。

如果没有以 `PHP_OUTPUT_HANDLER_CLEANABLE` flag 启动的活动输出缓冲区，ob_clean() 将失败。

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

如果函数失败会生成 `E_NOTICE`。

### 参见

- ob_start() - 打开输出控制缓冲
- ob_get_contents() - 返回输出缓冲区的内容
- ob_end_clean() - 清空（擦除）活动缓冲区的内容并关闭它
- ob_get_clean() - 获取活动缓冲区的内容并将其关闭
- ob_flush() - 冲刷（发送）活动输出处理程序的返回值

# ob_end_clean

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_end_clean — 清空（擦除）活动缓冲区的内容并关闭它

### 说明

function ob_end_clean(): bool

该函数调用输出处理程序（使用 `PHP_OUTPUT_HANDLER_CLEAN` 和 `PHP_OUTPUT_HANDLER_FINAL` flag），丢弃它的返回值，丢弃活动输出缓冲区的内容并关闭活动输出缓冲区。

如果没有以 `PHP_OUTPUT_HANDLER_REMOVABLE` flag 启动的活动输出缓冲区，ob_end_clean() 将失败。

ob_end_clean() 将丢弃活动输出缓冲区的内容，即使是在没有 `PHP_OUTPUT_HANDLER_CLEANABLE` flag 的情况下启动的。

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

如果函数失败了，将生成 `E_NOTICE` 异常。

### 示例

下面的示例展示了去除活动输出缓冲内容的简单方法：

示例 #1 ob_end_clean() 示例

    <?php
    ob_start();
    echo 'Text that won\'t get displayed.';
    ob_end_clean();
    ?>

### 参见

- ob_start() - 打开输出控制缓冲
- ob_get_contents() - 返回输出缓冲区的内容
- ob_clean() - 清空（擦掉）活动输出缓冲区的内容
- ob_get_clean() - 获取活动缓冲区的内容并将其关闭
- ob_end_flush() - 冲刷（发送）活动输出处理程序的返回值，并关闭活动输出缓冲区

# ob_end_flush

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_end_flush — 冲刷（发送）活动输出处理程序的返回值，并关闭活动输出缓冲区

### 说明

function ob_end_flush(): bool

该函数调用输出处理程序（使用 `PHP_OUTPUT_HANDLER_FINAL` flag），冲刷（发送）其返回值，丢弃活动输出缓冲区的内容并关闭活动输出缓冲区。

如果没有以 `PHP_OUTPUT_HANDLER_REMOVABLE` flag 启动活动输出缓冲区，ob_end_flush() 将失败。

ob_end_flush() 将冲刷（发送）输出处理程序的返回值，即使活动输出缓冲区是在没有 `PHP_OUTPUT_HANDLER_FLUSHABLE` flag 的情况下启动的。

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

如果函数失败将生成 `E_NOTICE` 异常。

### 示例

示例 #1 ob_end_flush() 示例

下面的例子给出了一种送出缓冲区内容并关闭所有输出缓冲区的容易的方法：

    <?php
      while (@ob_end_flush());
    ?>

### 参见

- ob_start() - 打开输出控制缓冲
- ob_get_contents() - 返回输出缓冲区的内容
- ob_flush() - 冲刷（发送）活动输出处理程序的返回值
- ob_get_flush() - 冲刷（发送）活动输出处理程序的返回值，返回活动输出缓冲区的内容并将其关闭
- ob_end_clean() - 清空（擦除）活动缓冲区的内容并关闭它

# ob_flush

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_flush — 冲刷（发送）活动输出处理程序的返回值

### 说明

function ob_flush(): bool

该函数调用输出处理程序（使用 `PHP_OUTPUT_HANDLER_FLUSH` flag），冲刷（发送）其返回值并丢弃活动输出缓冲区的内容。

该函数不会像 ob_end_flush() 或 ob_get_flush() 那样关闭活动输出缓冲区。

如果没有以 `PHP_OUTPUT_HANDLER_FLUSHABLE` flag 启动的活动输出缓冲区，ob_flush() 将失败。

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

如果函数失败会生成 `E_NOTICE`。

### 参见

- ob_start() - 打开输出控制缓冲
- ob_get_contents() - 返回输出缓冲区的内容
- ob_end_flush() - 冲刷（发送）活动输出处理程序的返回值，并关闭活动输出缓冲区
- ob_get_flush() - 冲刷（发送）活动输出处理程序的返回值，返回活动输出缓冲区的内容并将其关闭
- ob_clean() - 清空（擦掉）活动输出缓冲区的内容

# ob_get_clean

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_get_clean — 获取活动缓冲区的内容并将其关闭

### 说明

function ob_get_clean(): string|false

该函数调用输出处理程序（使用 `PHP_OUTPUT_HANDLER_CLEAN` 和 `PHP_OUTPUT_HANDLER_FINAL` flag），丢弃其返回值，返回活动输出缓冲区的内容并关闭活动输出缓冲区。

如果没有以 `PHP_OUTPUT_HANDLER_REMOVABLE` flag 启动的活动输出缓冲区，ob_get_clean() 将失败。

ob_get_clean() 将丢弃活动输出缓冲区的内容，即使是在没有 `PHP_OUTPUT_HANDLER_CLEANABLE` flag 的情况下启动的。

### 返回值

成功时返回活动输出缓冲区的内容，失败时返回 `false`。

警告

如果没有活动输出缓冲区，ob_get_clean() 将返回 false，但不会生成 `E_NOTICE`。

### 错误／异常

如果函数失败生成 `E_NOTICE`。

### 示例

示例 #1 ob_get_clean() 的简单示例

    <?php

    ob_start();

    echo "Hello World";

    $out = ob_get_clean();
    $out = strtolower($out);

    var_dump($out);
    ?>

以上示例会输出：

    string(11) "hello world"

### 参见

- ob_start() - 打开输出控制缓冲
- ob_get_contents() - 返回输出缓冲区的内容
- ob_clean() - 清空（擦掉）活动输出缓冲区的内容
- ob_end_clean() - 清空（擦除）活动缓冲区的内容并关闭它
- ob_get_flush() - 冲刷（发送）活动输出处理程序的返回值，返回活动输出缓冲区的内容并将其关闭

# ob_get_contents

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_get_contents — 返回输出缓冲区的内容

### 说明

function ob_get_contents(): string|false

只是得到输出缓冲区的内容，但不清除它。

### 参数

此函数没有参数。

### 返回值

此函数返回输出缓冲区的内容，或者如果输出缓冲区无效将返回 `false`。

### 示例

示例 #1 ob_get_contents() 简单示例

    <?php

    ob_start();

    echo "Hello ";

    $out1 = ob_get_contents();

    echo "World";

    $out2 = ob_get_contents();

    ob_end_clean();

    var_dump($out1, $out2);
    ?>

以上示例会输出：

    string(6) "Hello "
    string(11) "Hello World"

### 参见

- ob_start() - 打开输出控制缓冲
- ob_get_length() - 返回输出缓冲区内容的长度

# ob_get_flush

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_get_flush — 冲刷（发送）活动输出处理程序的返回值，返回活动输出缓冲区的内容并将其关闭

### 说明

function ob_get_flush(): string|false

该函数调用输出处理程序（使用 `PHP_OUTPUT_HANDLER_FINAL` flag），冲刷（发送）其返回值，返回活动输出缓冲区的内容并关闭活动输出缓冲区。

如果没有以 `PHP_OUTPUT_HANDLER_REMOVABLE` flag 启动的活动输出缓冲区，ob_get_flush() 将失败。

ob_get_flush() 将冲刷（发送）输出处理程序的返回值，即使活动输出缓冲区是在没有 `PHP_OUTPUT_HANDLER_FLUSHABLE` flag 的情况下启动的。

### 参数

此函数没有参数。

### 返回值

成功时返回活动输出缓冲区的内容，失败时返回 `false`。

### 错误／异常

如果函数失败生成 `E_NOTICE`。

### 示例

示例 #1 ob_get_flush() 示例

    <?php
    // 使用 output_buffering=On
    print_r(ob_list_handlers());

    // 保存缓冲区到文件
    $buffer = ob_get_flush();
    file_put_contents('buffer.txt', $buffer);

    print_r(ob_list_handlers());
    ?>

以上示例会输出：

    Array
    (
        [0] => default output handler
    )
    Array
    (
    )

### 参见

- ob_start() - 打开输出控制缓冲
- ob_get_contents() - 返回输出缓冲区的内容
- ob_flush() - 冲刷（发送）活动输出处理程序的返回值
- ob_end_flush() - 冲刷（发送）活动输出处理程序的返回值，并关闭活动输出缓冲区
- ob_get_clean() - 获取活动缓冲区的内容并将其关闭

# ob_get_length

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

ob_get_length — 返回输出缓冲区内容的长度

### 说明

function ob_get_length(): int|false

将返回输出缓冲区内容的长度，单位为字节。

### 参数

此函数没有参数。

### 返回值

返回输出缓冲区内容的长度，单位为字节；如果缓冲区无效，则返回 `false`。

### 示例

示例 #1 ob_get_length() 的简单示例

    <?php

    ob_start();

    echo "Hello ";

    $len1 = ob_get_length();

    echo "World";

    $len2 = ob_get_length();

    ob_end_clean();

    echo $len1 . ", " . $len2;
    ?>

以上示例会输出：

    6, 11

### 参见

- ob_start() - 打开输出控制缓冲
- ob_get_contents() - 返回输出缓冲区的内容

# ob_get_level

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_get_level — 返回输出缓冲机制的嵌套级别

### 说明

function ob_get_level(): int

返回输出缓冲机制的嵌套级别。

### 参数

此函数没有参数。

### 返回值

返回嵌套的输出缓冲处理程序的级别；或者是，如果输出缓冲区不起作用，返回零。

警告

ob_get_level() 和 ob_get_status() 之间相同级别的值相差 1。对于 ob_get_level()，第一级为 `1`。而对于 ob_get_status()，第一级为 `0`。

### 参见

- ob_start() - 打开输出控制缓冲
- ob_get_status() - 得到所有输出缓冲区的状态
- ob_get_contents() - 返回输出缓冲区的内容

# ob_get_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_get_status — 得到所有输出缓冲区的状态

### 说明

function ob_get_status(bool `$full_status` = `false`): array

ob_get_status() 返回最顶层输出缓冲区的状态信息；或者如果 `full_status` 设为 `true`，返回所有有效的输出缓冲级别。

### 参数

`full_status`

  设为 `true` 返回所有有效的输出缓冲区级别的状态信息。如果设为 `false` 或者没有设置，仅返回最顶层输出缓冲区的状态信息。

### 返回值

如果省略了 `full_status` 或传递 `false`，则返回简单的数组，该数组保存有关活动输出级别的状态信息。

如果 `full_status` 为 `true`，则返回数组，其中每个元素都包含活动输出缓冲区级别。输出级别用作顶级数组的 key，每个数组元素本身又是另一个数组，包含活动输出级别的状态信息。

如果未打开输出缓冲，则返回空数组。

ob_get_status() 返回的数组元素
Key | 值
--- | ---
name | 活动输出处理程序的名称（有关详细信息，请参阅 ob_list_handlers() 的返回值）
type | `0`（内部处理程序）或 `1`（用户提供的处理程序）
flags | ob_start() 设置的 flag 掩码、输出处理程序的类型（见上文）和缓冲过程的状态（ `PHP_OUTPUT_HANDLER_*` 常量）。如果处理程序成功处理缓冲并且没有返回 `false`，则将会设置 `PHP_OUTPUT_HANDLER_STARTED` 和 `PHP_OUTPUT_HANDLER_PROCESSED`。如果处理程序在处理缓冲时失败或返回 `false`，则将设置 `PHP_OUTPUT_HANDLER_STARTED` 和 `PHP_OUTPUT_HANDLER_DISABLED`。
level | 输出嵌套级别（从 0 开始）。注意 ob_get_level() 对于相同级别返回的值相差 1。ob_get_status() 的第一级为 `0`，ob_get_level() 的第一级为 `1`。
chunk_size | 块大小（以字节为单位）。通过 ob_start() 设置或启用 output_buffering 并将其值设置为正整数
buffer_size | 输出缓冲区字节大小
buffer_used | 输出缓冲区中数据的字节大小（与 ob_get_length() 的整数返回值相同）

### 示例

示例 #1 当 `full_status` 是 `false` 的返回数组

    Array
    (
        [name] => URL-Rewriter
        [type] => 0
        [flags] => 112
        [level] => 2
        [chunk_size] => 0
        [buffer_size] => 16384
        [buffer_used] => 1024
    )

示例 #2 当 `full_status` 是 `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
            )

    )

### 参见

- ob_get_level() - 返回输出缓冲机制的嵌套级别
- ob_list_handlers() - 列出所有使用的输出处理程序
- ob_get_length() - 返回输出缓冲区内容的长度
- ob_start() - 打开输出控制缓冲

# ob_implicit_flush

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_implicit_flush — 打开/关闭绝对刷送

### 说明

function ob_implicit_flush(bool `$enable` = `true`): void

ob_implicit_flush() 将打开或关闭绝对（隐式）刷送。绝对（隐式）刷送将在每个代码块产生输出后执行刷新操作，以便不再手动调用 flush()。

> 注意: 打印空字符串或发送 header 不会视为输出，因此不会产生刷新操作。

> 注意: 此函数对用户级输出处理程序（例如由 ob_start() 或 output_add_rewrite_var() 启动的处理程序）没有任何影响。

### 参数

`enable`

  设为 `true` 打开绝对刷送，反之是 `false`。

### 返回值

没有返回值。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `enable` 现在需要 bool 值；之前，需要 int。

### 参见

- flush() - 冲刷系统输出缓冲区
- ob_start() - 打开输出控制缓冲
- ob_end_flush() - 冲刷（发送）活动输出处理程序的返回值，并关闭活动输出缓冲区

# ob_list_handlers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_list_handlers — 列出所有使用的输出处理程序

### 说明

function ob_list_handlers(): array

列出所有使用的输出处理程序。

### 参数

此函数没有参数。

### 返回值

这将返回数组，其中包含正在使用的输出处理程序（如果有）。

如果启用了 output_buffering 并且未设置 output_handler，或者没有回调或 `null` 传递给 ob_start()，则返回`"default output handler"`。启用 output_buffering 并设置 output_handler相当于将内部（内置）函数传递给 ob_start()。

如果将 callable 传递给 ob_start()，则返回 callable 的完全限定名称。如果 callable 是实现 __invoke() 的对象，则返回该对象的 __invoke() 方法的完全限定名称。如果 callable 是 Closure，则返回 `"Closure::__invoke"`。

### 示例

示例 #1 ob_list_handlers() 示例

    <?php
    // 使用 output_buffering=On，没有设置 output_handler
    var_dump(ob_list_handlers());
    ob_end_flush();

    // 没有 callback 或为 null
    ob_start();
    var_dump(ob_list_handlers());
    ob_end_flush();

    // 匿名函数
    ob_start(function($string) { return $string; });
    var_dump(ob_list_handlers());
    ob_end_flush();

    // 箭头函数
    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();

    // 内部（内置）函数
    ob_start('print_r');
    var_dump(ob_list_handlers());
    ob_end_flush();

    // 用户定义函数
    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;
        }
    }

    // 类或静态方法
    ob_start(['MyClass','staticHandle']);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // 对象或非静态方法
    ob_start([new MyClass,'handle']);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // 可调用对象
    ob_start(new MyClass);
    var_dump(ob_list_handlers());
    ob_end_flush();
    ?>

以上示例会输出：

    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"
    }

### 参见

- ob_end_clean() - 清空（擦除）活动缓冲区的内容并关闭它
- ob_end_flush() - 冲刷（发送）活动输出处理程序的返回值，并关闭活动输出缓冲区
- ob_get_flush() - 冲刷（发送）活动输出处理程序的返回值，返回活动输出缓冲区的内容并将其关闭
- ob_start() - 打开输出控制缓冲

# ob_start

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_start — 打开输出控制缓冲

### 说明

function ob_start(?callable `$callback` = `null`, int `$chunk_size` = 0, int `$flags` = `PHP_OUTPUT_HANDLER_STDFLAGS`): bool

此函数将打开输出缓冲。当输出缓冲激活后，脚本将不会输出内容，相反需要输出的内容被存储在内部缓冲区中。参阅什么输出会被缓冲？以了解哪些输出受到影响。

输出缓冲区是可堆叠的，也就是说，当一个缓冲区处于活动状态时也可以调用 ob_start()。如果有多重输出缓冲区是活跃的，输出内容会一直按嵌套的顺序依次过滤。参阅嵌套输出缓冲区获取更多详情。

有关输出缓冲区的详细信息，请参阅用户级输出缓冲区

### 参数

`callback`

  可以指定可选的 `callback` callable。也可以通过传递 `null` 来绕过它。

  当冲刷（发送）、清理输出缓冲区或在脚本末尾冲刷输出缓冲区时，将调用 `callback`。

  `callback` 的签名如下：

  function handler(string `$buffer`, int `$phase` = ?): string
  `buffer`
    输出缓冲区中的内容。
  `phase`
    `PHP_OUTPUT_HANDLER_*` 常量。`PHP_OUTPUT_HANDLER_*` 常量的位掩码。有关更多详细信息，请参阅传递给输出处理程序的 flag。

  如果 `callback` 返回 `false`，则返回缓冲区的内容。有关更多详细信息，请参阅 输出处理程序的返回值。

  警告

  从输出处理程序中调用以下任何函数都将导致 fatal 错误 ob_clean()、ob_end_clean()、ob_end_flush()、ob_flush()、ob_get_clean()、ob_get_flush()、ob_start()。

  有关 `callback`（输出处理程序）的更多详细信息，请参阅输出处理程序和使用输出处理程序。

`chunk_size`

  如果传递了可选参数 chunk_size，则在任何导致缓冲区长度等于或大于 `chunk_size` 的代码块的输出之后，都会冲刷缓冲区。默认值 `0` 表示缓冲所有输出，直到缓冲区关闭。更多详细信息，请参阅缓冲区大小。

`flags`

  `flags` 参数是位掩码，用于控制可以在输出缓冲区上执行的操作。默认是允许清理、冲刷和移除输出缓冲区，可以通过缓冲区控制 flag手动设置。参阅缓冲区中允许的操作获取更多详细信息。

  每个标志都控制着对一组功能的访问，详细介绍如下：

  常量 | 函数
  --- | ---
  `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()

  > 注意: 在 PHP 8.4.0 之前，flags 参数还可以设置 输出处理程序状态标志。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 用户自定义回调函数的示例

    <?php

    function callback($buffer)
    {
      // replace all the apples with oranges
      return (str_replace("apples", "oranges", $buffer));
    }

    ob_start("callback");

    ?>
    <html>
    <body>
    <p>It's like comparing apples to oranges.</p>
    </body>
    </html>
    <?php

    ob_end_flush();

    ?>

以上示例会输出：

    <html>
    <body>
    <p>It's like comparing oranges to oranges.</p>
    </body>
    </html>

示例 #2 创建不可擦除的输出缓冲区

    <?php

    ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^ PHP_OUTPUT_HANDLER_REMOVABLE);

    ?>

### 参见

- ob_get_contents() - 返回输出缓冲区的内容
- ob_end_clean() - 清空（擦除）活动缓冲区的内容并关闭它
- ob_end_flush() - 冲刷（发送）活动输出处理程序的返回值，并关闭活动输出缓冲区
- ob_implicit_flush() - 打开/关闭绝对刷送
- ob_gzhandler() - ob_start 回调函数压缩输出缓冲区
- ob_iconv_handler() - 以输出缓冲处理程序转换字符编码
- mb_output_handler() - 在输出缓冲中转换字符编码的回调函数
- 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 — 添加 URL 重写器的值

### 说明

function output_add_rewrite_var(string `$name`, string `$value`): bool

如果“URL-Rewriter”输出缓冲处理程序未激活，此函数将启动它，存储 `name` 和 `value` 参数，并在缓冲区刷新时根据有效的 ini 设置重写 URL 和表单。此函数后续的调用将存储所有附加的名/值对，直到处理程序关闭。

当冲刷输出缓冲区（调用 ob_flush()、ob_end_flush()、ob_get_flush() 或在脚本结束时）时，`'URL-Rewriter'` 处理程序会将名/值对作为查询参数添加到 HTML 标签属性的 URL 中，并根据 url_rewriter.tags 和 url_rewriter.hosts 配置指令的值向表单添加隐藏字段。

添加到 `'URL-Rewriter'` 处理程序的每个名/值对都会添加到 URL 或表单，即使这会导致重复的 URL 查询参数或具有相同名称属性的元素。

> 注意: 一旦关闭了 `'URL-Rewriter'` 处理程序，就无法再次启动。

警告

在 PHP 8.4.0 之前，要重写的主机设置在 session.trans_sid_hosts 中，而不是 url_rewriter.hosts 中。

### 参数

`name`

  变量名。

`value`

  变量值。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
7.1.0 | 自 PHP 7.1.0 起，使用专用的输出缓冲区， url_rewriter.tags 仅用于输出函数，并且 url_rewriter.hosts 可用。在 PHP 7.1.0 之前，由 output_add_rewrite_var() 设置的重写变量共享具有透明 session id 支持的输出缓冲区（请参阅 session.trans_sid_tags）。

### 示例

示例 #1 output_add_rewrite_var() 示例

    <?php
    ini_set('url_rewriter.tags', 'a=href,form=');

    output_add_rewrite_var('var', 'value');

    // 一些链接
    echo '<a href="file.php">link</a>
    <a href="http://example.com">link2</a>';

    // 表单
    echo '<form action="script.php" method="post">
    <input type="text" name="var2" />
    </form>';

    print_r(ob_list_handlers());
    ?>

以上示例会输出：

    <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
    )

### 参见

- output_reset_rewrite_vars() - 重设 URL 重写器的值
- ob_flush() - 冲刷（发送）活动输出处理程序的返回值
- ob_list_handlers() - 列出所有使用的输出处理程序
- 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 — 重设 URL 重写器的值

### 说明

function output_reset_rewrite_vars(): bool

此函数移除所有先前由 output_add_rewrite_var() 函数设置的重写变量。

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
7.1.0 | 在 PHP 7.1.0 之前，使用 output_add_rewrite_var() 设置重写变量使用相同的 Session 模块 trans sid 输出缓冲区。从 PHP 7.1.0 起，使用专用的输出缓冲区，output_reset_rewrite_vars() 仅删除由 output_add_rewrite_var() 定义的重写变量。

### 示例

示例 #1 output_reset_rewrite_vars() 示例

    <?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>';
    ?>

以上示例会输出：

    <a href="file.php?var=value">link</a>
    <a href="file.php">link</a>

### 参见

- output_add_rewrite_var() - 添加 URL 重写器的值
- ob_flush() - 冲刷（发送）活动输出处理程序的返回值
- ob_list_handlers() - 列出所有使用的输出处理程序
- session_start() - 启动新会话或者重用现有会话

## 目录

- flush — 冲刷系统输出缓冲区
- ob_clean — 清空（擦掉）活动输出缓冲区的内容
- ob_end_clean — 清空（擦除）活动缓冲区的内容并关闭它
- ob_end_flush — 冲刷（发送）活动输出处理程序的返回值，并关闭活动输出缓冲区
- ob_flush — 冲刷（发送）活动输出处理程序的返回值
- ob_get_clean — 获取活动缓冲区的内容并将其关闭
- ob_get_contents — 返回输出缓冲区的内容
- ob_get_flush — 冲刷（发送）活动输出处理程序的返回值，返回活动输出缓冲区的内容并将其关闭
- ob_get_length — 返回输出缓冲区内容的长度
- ob_get_level — 返回输出缓冲机制的嵌套级别
- ob_get_status — 得到所有输出缓冲区的状态
- ob_implicit_flush — 打开/关闭绝对刷送
- ob_list_handlers — 列出所有使用的输出处理程序
- ob_start — 打开输出控制缓冲
- output_add_rewrite_var — 添加 URL 重写器的值
- output_reset_rewrite_vars — 重设 URL 重写器的值

- 安装/配置
  - 运行时配置
- 预定义常量
- 输出缓冲
- 冲刷系统缓冲区
- 用户级输出缓冲区
  - 什么输出会被缓冲？
  - 嵌套输出缓冲区
  - 缓冲区大小
  - 缓冲区中允许的操作
  - 输出处理程序
  - 使用输出处理程序
  - 传递给输出处理程序的 flag
  - 输出处理程序的返回值
- 示例
  - 基本用法
  - 输出重写用法
- 输出控制 函数
  - flush — 冲刷系统输出缓冲区
  - ob_clean — 清空（擦掉）活动输出缓冲区的内容
  - ob_end_clean — 清空（擦除）活动缓冲区的内容并关闭它
  - ob_end_flush — 冲刷（发送）活动输出处理程序的返回值，并关闭活动输出缓冲区
  - ob_flush — 冲刷（发送）活动输出处理程序的返回值
  - ob_get_clean — 获取活动缓冲区的内容并将其关闭
  - ob_get_contents — 返回输出缓冲区的内容
  - ob_get_flush — 冲刷（发送）活动输出处理程序的返回值，返回活动输出缓冲区的内容并将其关闭
  - ob_get_length — 返回输出缓冲区内容的长度
  - ob_get_level — 返回输出缓冲机制的嵌套级别
  - ob_get_status — 得到所有输出缓冲区的状态
  - ob_implicit_flush — 打开/关闭绝对刷送
  - ob_list_handlers — 列出所有使用的输出处理程序
  - ob_start — 打开输出控制缓冲
  - output_add_rewrite_var — 添加 URL 重写器的值
  - output_reset_rewrite_vars — 重设 URL 重写器的值

# PHP 选项和信息

# 简介

这些函数允许你获得许多关于PHP本身的参数，例如：运行时的配置，被加载的扩展，版本等。 你也将找到设置你的运行中的PHP的选项的函数。可能最好用的 PHP- 函数 phpinfo() 可以在这里找到。

# 安装/配置

## 目录

- 运行时配置

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

PHP 选项 / Info 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
assert.active | "1" | `INI_ALL` | 自 PHP 8.3.0 起弃用
assert.bail | "0" | `INI_ALL` | 自 PHP 8.3.0 起弃用
assert.warning | "1" | `INI_ALL` | 自 PHP 8.3.0 起弃用
assert.callback | NULL | `INI_ALL` | 自 PHP 8.3.0 起弃用
assert.quiet_eval | "0" | `INI_ALL` | 从 PHP 8.0.0 移除
assert.exception | "1" | `INI_ALL` | 在 PHP 8.0.0 之前，默认是 `"0"`，自 PHP 8.3.0 起弃用
enable_dl | "1" | `INI_SYSTEM` | 本过时特性将肯定会在未来被移除。
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` | 自 PHP 8.3.0 起可用。
zend.reserved_stack_size | "0" | `INI_SYSTEM` | 自 PHP 8.3.0 起可用。
fiber.stack_size |  | `INI_ALL` | 自 PHP 8.1.0 起可用。

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`assert.active` bool

  激活 assert() 断言评测。应该使用 zend.assertions 来控制 assert() 的行为。

  警告

  本特性已自 PHP 8.3.0 起废弃。强烈建议不要使用本特性。

`assert.bail` bool

  失败的断言将中止脚本。

  警告

  本特性已自 PHP 8.3.0 起废弃。强烈建议不要使用本特性。

`assert.warning` bool

  为每个失败的断言产生一条 PHP 警告信息。

  警告

  本特性已自 PHP 8.3.0 起废弃。强烈建议不要使用本特性。

`assert.callback` string

  断言失败后要调用的回调函数。

  警告

  本特性已自 PHP 8.3.0 起废弃。强烈建议不要使用本特性。

`assert.quiet_eval` bool
  警告

  此功能自 PHP 8.0.0 起移除。

  在断言表达式执行时 error_reporting() 使用当前的设置。如果启用了，在执行时错误将不会被显示（隐式的 error_reporting(0)）。如果禁用了，错误将根据 error_reporting() 的设置来显示。

`assert.exception` bool

  在断言（assert）失败时产生 AssertionError 异常。

  警告

  本特性已自 PHP 8.3.0 起废弃。强烈建议不要使用本特性。

`enable_dl` bool

  该指令允许开启或关闭使用 dl() 动态加载 PHP 模块。

  关闭动态加载的主要原因是为了安全。通过动态加载，有可能忽略所有 open_basedir 限制。默认允许动态加载。

`max_execution_time` int

  这设置了脚本被解析器中止之前允许的最大执行时间，单位秒。这有助于防止写得不好的脚本占尽服务器资源。默认设置为 `30`。从命令行运行 PHP 时，默认设置为 `0`。

  在非 Windows 系统上，最大执行时间不会影响系统调用和系统操作等。更多细节参见 set_time_limit()。

  你的 web 服务器也可以有其他超时设置，也有可能中断 PHP 的执行。Apache 有一个 `Timeout` 指令，IIS 有一个 CGI 超时功能。他们默认都是 300 秒。更多具体信息参见你的 web 服务器的文档。

`max_input_time` int

  脚本解析输入数据（类似 POST 和 GET）允许的最大时间，单位是秒。它从接收所有数据到开始执行脚本进行测量的。默认设置为 `-1`，意味着使用 max_execution_time 的值做为默认值，如果不想限制，请设置为 `0`。

`max_input_nesting_level` int

  设置 输入变量 的最大允许嵌套的深度。（例如 $_GET、$_POST）

`max_input_vars` int

  接受多少 输入的变量（限制分别应用于 $_GET、$_POST 和 $_COOKIE 超全局变量）指令的使用减轻了以哈希碰撞来进行拒绝服务攻击的可能性。如有超过指令指定数量的输入变量，将会导致 `E_WARNING` 的产生，更多的输入变量将会从请求中截断。

`zend.enable_gc` bool

  启用或禁用循环引用记数收集器。

`zend.max_allowed_stack_size` int

  程序允许消耗的操作系统原生堆栈空间的最大值。 尝试消耗超过操作系统允许的堆栈空间通常会导致硬崩溃，没有易于获得的调试信息。 为了使调试更容易，引擎在发生之前（当程序使用超过 zend.max_allowed_stack_size-zend.reserved_stack_size 字节的堆栈时）抛出一个 Error。

  用户定义代码中的递归不会消耗原生堆栈空间。 但是，内部函数和魔术方法会。 涉及这些函数的非常深的递归可能会导致程序耗尽所有可用的原生堆栈空间。

  可能的值为：

  - `0`： 自动检测操作系统允许程序消耗的最大原生堆栈空间。 这是默认值。 当无法检测时，使用已知的系统默认值。
  - `-1`： 禁用引擎中的堆栈大小检查。
  - 正整数：固定大小，以字节为单位。 设置此值过高会导致与禁用堆栈大小检查相同的效果。

  由于 Fiber 的堆栈大小由 fiber.stack_size 决定， 在执行 Fiber 时检查堆栈使用情况时，使用此参数的值而不是 zend.max_allowed_stack_size。

  > 注意:

  > 这与堆栈 缓冲区 溢出无关，也不是安全功能。

`zend.reserved_stack_size` int

  保留的堆栈大小，以字节为单位。 在检查堆栈大小时，从 max allowed stack size 减去此值作为缓冲区。

  可能的值为：

  - `0`：自动检测合理大小。
  - 正整数：固定大小，以字节为单位。
`fiber.stack_size` int

  为每个 Fiber 分配的本地堆栈大小，以字节为单位。

  默认值是系统指针大小小于 8 字节的系统上的 1MiB，否则为 2MiB。

# 预定义常量

下列常量作为 PHP 核心的一部分总是可用的。

常量 | 描述
--- | ---
预定义 phpcredits() 常量
`CREDITS_GROUP` (int) | 核心开发者名单
`CREDITS_GENERAL` (int) | 总的贡献：语言设计和理念，PHP 作者 和 SAPI 模块。
`CREDITS_SAPI` (int) | PHP 的服务器 API 模块列表，以及它们的作者。
`CREDITS_MODULES` (int) | PHP 扩展的列表，以及它们的作者。
`CREDITS_DOCS` (int) | 文档组的贡献。
`CREDITS_FULLPAGE` (int) | 通常与其他标志组合使用。通过其他标志指示了完整独立的 HTML 页面，用于打印包含信息。
`CREDITS_QA` (int) | 质量保证团队的贡献。
`CREDITS_ALL` (int) | 所有的贡献者，等于使用 `CREDITS_DOCS | CREDITS_GENERAL | CREDITS_GROUP | CREDITS_MODULES | CREDITS_QA | CREDITS_FULLPAGE`。 它以合适的标签产生了完整的独立 HTML 页面。这是默认的值。

常量 | 描述
--- | ---
phpinfo() 常量
`INFO_GENERAL` (int) | 配置行，php.ini 的位置、构建日期，Web 服务器、操作系统及其他。
`INFO_CREDITS` (int) | PHP 贡献者。参见 phpcredits()。
`INFO_CONFIGURATION` (int) | 当前 PHP 指令的本地（Local）和主（Master）值。参见 ini_get()。
`INFO_MODULES` (int) | 已加载的模块和各自的设置。
`INFO_ENVIRONMENT` (int) | 环境变量信息在 $_ENV 中亦有效。
`INFO_VARIABLES` (int) | 显示所有 `EGPCS` （环境变量、GET、POST、Cookie、Server）中的预定义变量。
`INFO_LICENSE` (int) | PHP 版权信息。参见 » license faq。
`INFO_ALL` (int) | 显示以上所有。这是默认值。

常量 | 描述
--- | ---
INI 模式常量
`INI_USER` (int) | 可以在用户脚本（如使用 ini_set()）或 Windows 注册表中设置条目。可以在 .user.ini 中设置条目
`INI_PERDIR` (int) | 可以在 php.ini、.htaccess、httpd.conf 或 .user.ini 中设置条目
`INI_SYSTEM` (int) | 可以在 php.ini 或 httpd.conf 中设置条目
`INI_ALL` (int) | 条目可以设置在任何地方

断言常量，这些值用于设置 assert_options() 中的断言标记。

常量 | 描述
--- | ---
assert() 常量
`ASSERT_ACTIVE` (int) | 启用 assert()。 警告 本特性已自 PHP 8.3.0 起废弃。强烈建议不要使用本特性。
`ASSERT_CALLBACK` (int) | 失败断言的回调函数。 警告 本特性已自 PHP 8.3.0 起废弃。强烈建议不要使用本特性。
`ASSERT_BAIL` (int) | 断言失败时中止执行。 警告 本特性已自 PHP 8.3.0 起废弃。强烈建议不要使用本特性。
`ASSERT_EXCEPTION` (int) | 为每个失败的断言抛出 AssertionError。 警告 本特性已自 PHP 8.3.0 起废弃。强烈建议不要使用本特性。
`ASSERT_WARNING` (int) | 为每个失败的断言产生一条 PHP 警告。 警告 本特性已自 PHP 8.3.0 起废弃。强烈建议不要使用本特性。
`ASSERT_QUIET_EVAL` (int) | 在执行断言表达式时禁用 `error_reporting`。 警告 此功能自 PHP 8.0.0 起移除。

以下常量仅在主机操作系统是 Windows的情况下有效，能得到不同版本信息，能够检测利用一些功能。

常量 | 描述
--- | ---
Windows 特定常量
`PHP_WINDOWS_VERSION_MAJOR` (int) | windows 主版本，可以是 `4`（NT4/Me/98/95）、`5`（XP/2003 R2/2003/2000）或 `6`（Vista/2008/7/8/8.1）。
`PHP_WINDOWS_VERSION_MINOR` (int) | Windows 副版本号，可以是 `0` (Vista/2008/2000/NT4/95)、`1` (XP)、`2` (2003 R2/2003/XP x64)、`10`（98）或 `90`（ME）。
`PHP_WINDOWS_VERSION_BUILD` (int) | Windows 内部版本号（例如 Windows Vista SP1 是 build 6001）
`PHP_WINDOWS_VERSION_PLATFORM` (int) | PHP 当前运行的平台， Windows Vista/XP/2000/NT4、Server 2008/2003 的值是 `2`，Windows ME/98/95 下值是 `1`。
`PHP_WINDOWS_VERSION_SP_MAJOR` (int) | 安装的 service pack 主版本号，没有安装是 `0`。例如 Windows XP service pack 3 上这个值是 `3`。
`PHP_WINDOWS_VERSION_SP_MINOR` (int) | 安装的 service pack 副版本号，如果没有安装则是 `0`。
`PHP_WINDOWS_VERSION_SUITEMASK` (int) | suitemask 是位掩码，用来判断 Windows 是否安装了各种功能，参阅下表获取可能的位阈值。
`PHP_WINDOWS_VERSION_PRODUCTTYPE` (int) | 包含用于确定 `PHP_WINDOWS_NT_*` 常量的值。该值可能是 `PHP_WINDOWS_NT_*` 常量之一，表示平台类型的值。
`PHP_WINDOWS_NT_DOMAIN_CONTROLLER` (int) | 这是域控制器
`PHP_WINDOWS_NT_SERVER` (int) | 这是一个服务器系统（例如 Server 2008/2003/2000），注意，如果这是一个域控制器，通过 `PHP_WINDOWS_NT_DOMAIN_CONTROLLER` 报告。
`PHP_WINDOWS_NT_WORKSTATION` (int) | 这是一个工作站系统（例如 Vista/XP/2000/NT4）

此功能列表可以通过 `PHP_WINDOWS_VERSION_SUITEMASK` 位掩码检测。

Windows suitemask 位字段
Bits | 描述
--- | ---
`0x00000004` | 安装的是 Microsoft BackOffice 组件。
`0x00000400` | 安装的是 Windows Server 2003 网络版。
`0x00004000` | 安装的是 Windows Server 2003 计算集群版。
`0x00000080` | 安装的是 Windows Server 2008 数据中心版、Windows Server 2003 数据中心版或者 Windows 2000 数据中心服务器。
`0x00000002` | 安装的是 Windows Server 2008 企业版，Windows Server 2003 企业版，Windows 2000 高级服务器版或 Windows NT Server 4.0 企业版 。
`0x00000040` | 安装的是 Windows XP 嵌入版。
`0x00000200` | 安装的是 Windows Vista 家庭高级版，Windows Vista 家庭普通版或 Windows XP 家庭版。
`0x00000100` | 支持远程桌面，但仅支持交互式会话。系统没有在应用服务器模式运行时则会设置此值。
`0x00000001` | Microsoft 小型商业服务器曾经安装在系统上，但可能已经升级到 Windows 的另外一个版本。
`0x00000020` | Microsoft 小型商业服务器安装时具有有效的限制性客户端许可证。
`0x00002000` | 安装的是 Windows 存储服务器 2003 R2 或 Windows 存储服务器 2003。
`0x00000010` | 安装的是终端服务。该值始终设置。如果设置了该值但未设置 `0x00000100`，则系统运行在应用服务器模式。
`0x00008000` | 已安装 Windows Home Server。

# PHP 选项/信息 函数

# assert

(PHP 4, PHP 5, PHP 7, PHP 8)

assert — 断言检测

### 说明

function assert(mixed `$assertion`, Throwable|string|null `$description` = `null`): bool

assert() 允许定义预期（expectations）：在开发和测试环境中生效的断言，但在生产环境中会优化掉以达到零成本。

断言可用于帮助调试。其中一个用例是检查健全性的前提条件，应该始终为 `true`，如果不满足这些条件，则表示存在某些编程错误。 另一个用例是确保某些功能的存在，例如扩展函数或某些系统限制和特性。

由于断言可以配置为已消除，因此不应该用于普通运行时操作，比如检查输入参数。一般来说，代码应该在禁用断言检查的情况下仍然按预期运行。

assert() 将检查 `assertion` 中指定的预期（expectations）是否成立。如果不成立，也就是结果为 `false`，它将根据 assert() 的配置采取适当的操作。

assert() 的行为由以下 INI 设置决定：

断言 配置选项
名字 | 默认 | 说明 | 更新日志
--- | --- | --- | ---
zend.assertions | `1` | `1`：生成并执行代码（开发模式） `0`：生成代码但在运行时跳转 `-1`：生成代码但在运行时跳转（生产模式） |
assert.active | `true` | 为 `false` 时，assert() 将不会检查预期（expectation）并且无条件返回 `true`。 | 自 PHP 8.3.0 起弃用。
assert.callback | `null` | 当断言失败时，将调用用户定义的函数，其签名应该是： function assert_callback( string `$file`, int `$line`, null `$assertion`, string `$description` = ? ): void | 在 PHP 8.0.0 之前，回调的签名应该是： function assert_callback( string `$file`, int `$line`, string `$assertion`, string `$description` = ? ): void 自 PHP 8.3.0 起弃用。
assert.exception | `true` | 如果为 `true`，则如果不能满足预期（expectations），将抛出 AssertionError 异常。 | 自 PHP 8.3.0 起弃用
assert.bail | `false` | 为 `true` 时，如果预期（expectation）不支持，将会中止 PHP 脚本的执行。 | 自 PHP 8.3.0 起弃用
assert.warning | `true` | 为 `true` 时，则如果预期（expectation）不支持，将发出 `E_WARNING` 警告。如果启用了 assert.exception，此 INI 设置将无效。 | 自 PHP 8.3.0 起弃用

### 参数

`assertion`

  可以是任何带返回值的表达式，运行后的结果用于表示断言成功还是失败。

  警告

  在 PHP 8.0.0 之前，如果 `assertion` 是 string，将解释为 PHP 代码，并通过 eval() 执行。这个字符串将作为第三个参数传递给回调函数。这种行为在 PHP 7.2.0 中弃用，并在 PHP 8.0.0 中移除。

`description`

  如果 `description` 是 Throwable 的实例，只有在 `assertion` 执行失败时才会抛出。

  > 注意:

  > 自 PHP 8.0.0 开始，在调用可能定义的断言回调之前执行此操作。

  > 注意:

  > 自 PHP 8.0.0 开始，无论 assert.exception 的配置如何，都将会抛出该 object。

  > 注意:

  > 自 PHP 8.0.0 开始，在这种情况下，assert.bail 设置不起作用。

  如果 `description` 是 string，当发出异常或警告时，将使用该消息。 如果 `assertion` 失败了，可选的 description 将会包括在失败信息里。

  如果省略 `description`， 将在编译时创建默认 description，该 description 等于对 assert() 调用的源代码。

### 返回值

assert() 总是返回 `true`，前提是以下条件中至少有一个为真：

- `zend.assertions=0`
- `zend.assertions=-1`
- `assert.active=0`
- `assert.exception=1`
- `assert.bail=1`
- 将自定义异常对象传递给 `description`。

如果所有条件都不满足， assert() 将在 `assertion` 为真时返回 `true`，否则返回 `false`。urn `true` if `assertion` is truthy and `false` otherwise.

### 更新日志

版本 | 说明
--- | ---
8.3.0 | 弃用所有的 `assert.` INI 设置。
8.0.0 | assert() 将不再对字符串参数求值，而是跟其他参数一样对待。应该使用 `assert($a == $b)` 替代 `assert('$a == $b')`。已移除 `assert.quiet_eval` php.ini 指令和 `ASSERT_QUIET_EVAL` 常量，因为它们不再有任何作用。
8.0.0 | 如果 `description` 是 Throwable 的实例，无论 assert.exception 的值如何，如果断言失败，该对象都会被抛出。
8.0.0 | 如果 `description` 是 Throwable 的实例，即使设置了用户回调，也不会调用该回调。
8.0.0 | 不再允许在命名空间中声明叫做 `assert()` 的函数，并发出 `E_COMPILE_ERROR`。
7.3.0 | 弃用在命名空间中声明 `assert()` 函数。这样声明会发出 `E_DEPRECATED`。
7.2.0 | 弃用使用 string 作为 `assertion`。当 assert.active 和 zend.assertions 都设为 `1` 时，现在会发出 `E_DEPRECATED` 通知。

### 示例

示例 #1 assert() 示例

    <?php
    assert(1 > 2);
    echo 'Hi!';

如果启用断言（`zend.assertions=1`） 以上示例会输出：

    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

如果禁用断言（`zend.assertions=0` 或 `zend.assertions=-1`） 以上示例会输出：

    Hi!

示例 #2 使用自定义信息

    <?php
    assert(1 > 2, "Expected one to be greater than two");
    echo 'Hi!';
    ?>

如果启用断言，以上示例会输出：

    Fatal error: Uncaught AssertionError: Expected one to be greater than two in example.php:2
    Stack trace:
    #0 example.php(2): assert(false, 'Expected one to...')
    #1 {main}
      thrown in example.php on line 2

如果禁用断言，以上示例会输出：

    Hi!

示例 #3 使用自定义异常类

    <?php
    class ArithmeticAssertionError extends AssertionError {}

    assert(1 > 2, new ArithmeticAssertionError("Expected one to be greater than two"));
    echo 'Hi!';

如果启用断言，以上示例会输出：

    Fatal error: Uncaught ArithmeticAssertionError: Expected one to be greater than two in example.php:4
    Stack trace:
    #0 {main}
      thrown in example.php on line 4

如果禁用断言，以上示例会输出：

    Hi!

### 参见

- assert_options() - 设置/获取各种断言 flag

# assert_options

(PHP 4, PHP 5, PHP 7, PHP 8)

assert_options — 设置/获取各种断言 flag

警告

此函数自 PHP 8.3.0 起弃用。强烈建议不要应用此函数。

### 说明

function assert_options(int `$option`, mixed `$value` = ?): mixed

设置 assert() 的各种控制选项，或者是仅仅查询当前的设置。

> 注意: 不鼓励使用 assert_options()，而是分别使用 ini_set() 和 ini_get() 设置和获取 php.ini 指令 zend.assertions 和 assert.exception。

### 参数

`option`

  断言选项
  选项 | INI 设置 | 默认值 | 描述
  --- | --- | --- | ---
  ASSERT_ACTIVE | assert.active | 1 | 启用 assert() 断言
  ASSERT_EXCEPTION | assert.exception | 1 | 每个失败断言，抛出 AssertionError
  ASSERT_WARNING | assert.warning | 1 | 为每个失败的断言产生一个 PHP 警告（warning）
  ASSERT_BAIL | assert.bail | 0 | 在断言失败时中止执行
  ASSERT_QUIET_EVAL | assert.quiet_eval | 0 | 在断言表达式求值时禁用 error_reporting。PHP 8.0.0 起移除。
  ASSERT_CALLBACK | assert.callback | (`null`) | 断言失败时调用回调函数

`value`

  可选的新选项值。

  通过 `ASSERT_CALLBACK` 或 assert.callback 设置的回调函数应该有以下签名：

  function assert_callback(
  string `$file`,
  int `$line`,
  ?string `$assertion`,
  string `$description` = ?
  ): void
  `file`
    调用 assert() 的文件名。
  `line`
    调用 assert() 的行数。
  `assertion`
    在 PHP 8.0.0 之前，传递给 assert() 的断言，仅作为字符串给出。 （如果断言是 boolean 条件，则此参数将为空字符串。）从 PHP 8.0.0 开始，此参数始终为 `null`。
  `description`
    传递给 assert() 的描述。

向 `value` 传递空字符串会重置断言回调。

### 返回值

返回任意选项的原始设置。

### 错误／异常

如果 `option` 是无效选项，抛出 ValueError。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | assert_option() 现在已弃用。
8.0.0 | 如果 `option` 是无效选项，抛出 ValueError。之前返回 `false`。

### 示例

示例 #1 assert_options() 示例

    <?php
    // 处理断言失败时的函数
    function assert_failure($file, $line, $assertion, $message)
    {
        echo "The assertion $assertion in $file on line $line has failed: $message";
    }

    // 我们的测试函数
    function test_assert($parameter)
    {
        assert(is_bool($parameter));
    }

    // 设置断言选项
    assert_options(ASSERT_ACTIVE,   true);
    assert_options(ASSERT_BAIL,     true);
    assert_options(ASSERT_WARNING,  false);
    assert_options(ASSERT_CALLBACK, 'assert_failure');

    // 让一个断言会失败
    test_assert(1);

    // 由于 ASSERT_BAIL 是 true，这里永远也到不了
    echo 'Never reached';
    ?>

### 参见

- assert() - 断言检测

# cli_get_process_title

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

cli_get_process_title — Returns the current process title

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Return a string with the current process title or `null` on error.

### 错误／异常

An `E_WARNING` will be generated if the operating system is unsupported.

### 示例

示例 #1 cli_get_process_title() example

    <?php
    echo "Process title: " . cli_get_process_title() . "\n";
    ?>

### 参见

- 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

### 说明

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.

### 参数

`title`
  The new title.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

An `E_WARNING` will be generated if the operating system is unsupported.

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

    <?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);
    }
    ?>

### 参见

- cli_get_process_title() - Returns the current process title

# dl

(PHP 4, PHP 5, PHP 7, PHP 8)

dl — 运行时载入一个 PHP 扩展

### 说明

function dl(string `$extension_filename`): bool

载入指定参数 `extension_filename` 的 PHP 扩展。

使用 extension_loaded() 来测试指定的扩展是否已经激活。 这既能用于内建的扩展也可以用于动态加载的扩展（既可以通过 php.ini 也可以通过 dl()）。

警告

此函数仅适用于 CLI 和嵌入式 SAPI，以及从命令行运行时的 CGI SAPI。

### 参数

`extension_filename`

  此参数仅仅是要加载的扩展的文件名，依赖于你的平台。 比如，sockets（作为共享模块编译，而不是默认的！）在 Unix 平台上称为 sockets.so 而 在 Windows 平台上是 php_sockets.dll。

  扩展加载的目录依赖于你的平台：

  Windows - 如果没有在 php.ini 里明确设置，扩展默认会从 C:\php5\ 加载。

  Unix - 如果没有在 php.ini 里明确设置，默认的扩展目录依赖于

  - PHP 是否通过 `--enable-debug` 选项构建
  - PHP 是否以 ZTS （Zend 线程安全）支持构建
  - 当前的内部 `ZEND_MODULE_API_NO`（Zend 内部模块 API 数字，基本上是主要模块修改时的日期）
  考虑到上述，目录默认为 `<install-dir>/lib/php/extensions/ <debug-or-not>-<zts-or-not>-ZEND_MODULE_API_NO`，例如 /usr/local/php/lib/php/extensions/debug-non-zts-20010901 或 /usr/local/php/lib/php/extensions/no-debug-zts-20010901。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。 如果加载模块的功能是无效或者禁用的（可以关闭 enable_dl 设置）将导致一个 `E_ERROR` 并中断执行。 如果因为指定的库无法加载而导致 dl() 失败，除了返回 `false`，还会产生一个 `E_WARNING` 的消息。

### 示例

示例 #1 dl() 示例

    <?php
    // 加载一个扩展的示例，基于操作系统
    if (!extension_loaded('sqlite')) {
        if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
            dl('php_sqlite.dll');
        } else {
            dl('sqlite.so');
        }
    }

    // 或者，使用常量 PHP_SHLIB_SUFFIX
    if (!extension_loaded('sqlite')) {
        $prefix = (PHP_SHLIB_SUFFIX === 'dll') ? 'php_' : '';
        dl($prefix . 'sqlite.' . PHP_SHLIB_SUFFIX);
    }
    ?>

### 注释

> 注意:

> 在某些 Unix 平台上，dl() 是大小写敏感的。

### 参见

- 扩展加载指令
- extension_loaded() - 检查一个扩展是否已经加载

# extension_loaded

(PHP 4, PHP 5, PHP 7, PHP 8)

extension_loaded — 检查一个扩展是否已经加载

### 说明

function extension_loaded(string `$extension`): bool

检查一个扩展是否已经加载。

### 参数

`extension`

  扩展名称，大小写不敏感。

  你可以用 phpinfo() 来查看一系列扩展名称，而在 `CGI` 或 `CLI` 的 PHP 版本里你可以使用 -m 参数来列出所有有效的扩展：

      $ php -m
      [PHP Modules]
      xml
      tokenizer
      standard
      sockets
      session
      posix
      pcre
      overload
      mysql
      mbstring
      ctype

      [Zend Modules]

### 返回值

如果 `extension` 指定的扩展已加载，返回 `true`，否则返回 `false`。

### 示例

示例 #1 extension_loaded() 示例

    <?php
    if (!extension_loaded('gd')) {
        if (!dl('gd.so')) {
            exit;
        }
    }
    ?>

### 参见

- get_loaded_extensions() - 返回所有编译并加载模块名的 array
- get_extension_funcs() - 返回模块函数名称的数组
- phpinfo() - 输出关于 PHP 配置的信息
- dl() - 运行时载入一个 PHP 扩展
- function_exists() - 如果给定的函数已经被定义就返回 true

# gc_collect_cycles

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_collect_cycles — 强制收集所有现存的垃圾循环周期

### 说明

function gc_collect_cycles(): int

强制收集所有现存的垃圾循环周期。

### 参数

此函数没有参数。

### 返回值

返回收集的循环数量。

### 参见

- 垃圾回收机制

# gc_disable

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_disable — 停用循环引用收集器

### 说明

function gc_disable(): void

停用循环引用收集器，设置 zend.enable_gc 为 `0`。

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 参见

- 垃圾回收机制

# gc_enable

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_enable — 激活循环引用收集器

### 说明

function gc_enable(): void

设置 zend.enable_gc 为 `1`， 激活循环引用收集器。

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 参见

- 垃圾回收机制

# gc_enabled

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_enabled — 返回循环引用计数器的状态

### 说明

function gc_enabled(): bool

返回循环引用计数器的状态。

### 参数

此函数没有参数。

### 返回值

如果垃圾收集器已启用则返回 `true`，否则返回 `false`。

### 示例

示例 #1 gc_enabled() 示例

    <?php
    if(gc_enabled()) gc_collect_cycles();
    ?>

### 参见

- 垃圾回收机制

# gc_mem_caches

(PHP 7, PHP 8)

gc_mem_caches — Reclaims memory used by the Zend Engine memory manager

### 说明

function gc_mem_caches(): int

Reclaims memory used by the Zend Engine memory manager.

### 参数

此函数没有参数。

### 返回值

Returns the number of bytes freed.

### 参见

- Garbage Collection

# gc_status

(PHP 7 >= 7.3.0, PHP 8)

gc_status — 获取有关垃圾回收的信息

### 说明

function gc_status(): array

获取有关当前垃圾收集状态的信息。

### 参数

此函数没有参数。

### 返回值

返回包含以下元素的关联数组：

- `"runs"`
- `"collected"`
- `"threshold"`
- `"roots"`
- `"running"`
- `"protected"`
- `"full"`
- `"buffer_size"`
- `"application_time"`
- `"collector_time"`
- `"destructor_time"`
- `"free_time"`

### 更新日志

版本 | 说明
--- | ---
8.3.0 | gc_status() 现在会返回以下附加字段： `"running"`、`"protected"`、 `"full"`、`"buffer_size"`、 `"application_time"`、`"collector_time"`、 `"destructor_time"` 和 `"free_time"`。

### 示例

示例 #1 gc_status() 用法

    <?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());

以上示例的输出类似于：

    array(4) {
      ["runs"]=>
      int(5)
      ["collected"]=>
      int(100002)
      ["threshold"]=>
      int(50001)
      ["roots"]=>
      int(0)
    }

上述示例在 PHP 8.3 中的输出类似于：

    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)
    }

### 参见

- 垃圾回收

# get_cfg_var

(PHP 4, PHP 5, PHP 7, PHP 8)

get_cfg_var — 获取 PHP 配置选项的值

### 说明

function get_cfg_var(string `$option`): string|array|false

获取 PHP 配置选项 `option` 的值。

此函数不会返回 PHP 编译的配置信息，或从 Apache 配置文件读取。

检查系统是否使用了一个配置文件，并尝试获取 cfg_file_path 的配置设置的值。如果有效，将会使用一个配置文件。

### 参数

`option`

  配置选项的名称。

### 返回值

返回 `option` 指定的当前 PHP 配置变量的值，错误发生时返回 `false`。

### 参见

- ini_get() - 获取一个配置选项的值
- ini_get_all() - 获取所有配置选项

# get_current_user

(PHP 4, PHP 5, PHP 7, PHP 8)

get_current_user — 获取当前 PHP 脚本所有者名称

### 说明

function get_current_user(): string

返回当前 PHP 脚本所有者名称。

### 参数

此函数没有参数。

### 返回值

以字符串返回用户名。

### 示例

示例 #1 get_current_user() 示例

    <?php
    echo 'Current script owner: ' . get_current_user();
    ?>

以上示例的输出类似于：

    Current script owner: SYSTEM

### 参见

- getmyuid() - 获取 PHP 脚本所有者的 UID
- getmygid() - 获取当前 PHP 脚本拥有者的 GID
- getmypid() - 获取 PHP 进程的 ID
- getmyinode() - 获取当前脚本的索引节点（inode）
- getlastmod() - 获取页面最后修改的时间

# get_defined_constants

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

get_defined_constants — 返回所有常量的关联数组，键是常量名，值是常量值

### 说明

function get_defined_constants(bool `$categorize` = `false`): array

返回当前所有已定义的常量名和值。 这包含 define() 函数所创建的，也包含了所有扩展所创建的。

### 参数

`categorize`

  让此函数返回一个多维数组，分类为第一维的键名，常量和它们的值位于第二维。

      <?php
      define("MY_CONSTANT", 1);
      print_r(get_defined_constants(true));
      ?>

  以上示例的输出类似于：

      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
              )

      )

### 返回值

返回的数组为 常量名 => 常量值，也可以按注册变量的扩展名称来分组。

### 示例

示例 #1 get_defined_constants() 示例

    <?php
    print_r(get_defined_constants());
    ?>

以上示例的输出类似于：

    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
    )

### 参见

- defined() - 检查给定名称的常量是否存在
- constant() - 返回一个常量的值
- get_loaded_extensions() - 返回所有编译并加载模块名的 array
- get_defined_functions() - 返回所有已定义函数的数组
- get_defined_vars() - 返回由所有已定义变量所组成的数组

# get_extension_funcs

(PHP 4, PHP 5, PHP 7, PHP 8)

get_extension_funcs — 返回模块函数名称的数组

### 说明

function get_extension_funcs(string `$extension`): array|false

该函数根据 `extension` 返回模块内定义的所有函数的名称。

### 参数

`extension`

  模块名称。

  > 注意:

  > 这个参数必须是小写（lowercase）的。

### 返回值

返回包含所有函数名的数组，如果 `extension` 不是一个有效的扩展则返回 `false`。

### 示例

示例 #1 打印 XML 函数

    <?php
    print_r(get_extension_funcs("xml"));
    ?>

以上示例的输出类似于：

    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
    )

### 参见

- get_loaded_extensions() - 返回所有编译并加载模块名的 array
- ReflectionExtension::getFunctions() - 获取扩展中的函数

# get_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

get_include_path — 获取当前的 include_path 配置选项

### 说明

function get_include_path(): string|false

获取当前 include_path 配置选项的值。

### 参数

此函数没有参数。

### 返回值

返回字符串的路径， 或者在失败时返回 `false`。

### 示例

示例 #1 get_include_path() 示例

    <?php
    echo get_include_path();

    // 或使用 ini_get()
    echo ini_get('include_path');
    ?>

### 参见

- ini_get() - 获取一个配置选项的值
- restore_include_path() - 还原 include_path 配置选项的值
- set_include_path() - 设置 include_path 配置选项
- include - include

# get_included_files

(PHP 4, PHP 5, PHP 7, PHP 8)

get_included_files — 返回被 include 和 require 文件名的 array

### 说明

function get_included_files(): array

返回所有被 include、 include_once、 require 和 require_once 的文件名。

### 参数

此函数没有参数。

### 返回值

返回所有文件名称的 array。

脚本最初被称为”被包含的文件“，所以脚本自身也会和 include 系列函数引用的脚本列在一起。

被多次 include 和 require 的文件在返回的 array 里只会列出一次。

### 示例

示例 #1 get_included_files() 示例

    <?php
    // 本文件是 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";
    }

    ?>

以上示例会输出：

    /path/to/abc.php
    /path/to/test1.php
    /path/to/test2.php
    /path/to/test3.php
    /path/to/test4.php

### 参见

- include - include
- include_once - include_once
- require - require
- require_once - require_once
- get_required_files() - 别名 get_included_files

# get_loaded_extensions

(PHP 4, PHP 5, PHP 7, PHP 8)

get_loaded_extensions — 返回所有编译并加载模块名的 array

### 说明

function get_loaded_extensions(bool `$zend_extensions` = `false`): array

该函数返回了 PHP 解析器里所有编译并加载的模块名。

### 参数

`zend_extensions`

  只返回 Zend 扩展，并非类似 mysqli 的普通扩展。默认是 `false` (返回普通扩展)。

### 返回值

返回所有模块名的一个索引数组(array)。

### 示例

示例 #1 get_loaded_extensions() 示例

    <?php
    print_r(get_loaded_extensions());
    ?>

以上示例的输出类似于：

    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
    )

### 参见

- get_extension_funcs() - 返回模块函数名称的数组
- extension_loaded() - 检查一个扩展是否已经加载
- dl() - 运行时载入一个 PHP 扩展
- phpinfo() - 输出关于 PHP 配置的信息

# get_magic_quotes_gpc

(PHP 4, PHP 5, PHP 7)

get_magic_quotes_gpc — 获取当前 magic_quotes_gpc 的配置选项设置

警告

本函数已自 PHP 7.4.0 起弃用，自 PHP 8.0.0 起移除。强烈建议不要依赖本函数。

### 说明

function get_magic_quotes_gpc(): false

始终返回 `false`。

### 参数

此函数没有参数。

### 返回值

始终返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 此函数已移除。
7.4.0 | 此函数已废弃。

### 参见

- addslashes() - 使用反斜线引用字符串
- stripslashes() - 反引用一个引用字符串
- get_magic_quotes_runtime() - 获取当前 magic_quotes_runtime 配置选项的激活状态
- ini_get() - 获取一个配置选项的值

# get_magic_quotes_runtime

(PHP 4, PHP 5, PHP 7)

get_magic_quotes_runtime — 获取当前 magic_quotes_runtime 配置选项的激活状态

警告

本函数已自 PHP 7.4.0 起弃用，自 PHP 8.0.0 起移除。强烈建议不要依赖本函数。

### 说明

function get_magic_quotes_runtime(): false

始终返回 `false`。

### 参数

此函数没有参数。

### 返回值

始终返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 此函数已移除。
7.4.0 | 此函数已废弃。

### 参见

- get_magic_quotes_gpc() - 获取当前 magic_quotes_gpc 的配置选项设置

# get_required_files

(PHP 4, PHP 5, PHP 7, PHP 8)

get_required_files — 别名 get_included_files()

### 说明

此函数是该函数的别名： get_included_files().

# get_resources

(PHP 7, PHP 8)

get_resources — Returns active resources

### 说明

function get_resources(?string `$type` = `null`): array

Returns an array of all currently active resources, optionally filtered by resource type.

> 注意: 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).

### 参数

`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.

### 返回值

Returns an array of currently active resources, indexed by resource number.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `type` is nullable now.

### 示例

示例 #1 Unfiltered get_resources()

    <?php
    $fp = tmpfile();
    var_dump(get_resources());
    ?>

以上示例的输出类似于：

    array(1) {
      [1]=>
      resource(1) of type (stream)
    }

示例 #2 Filtered get_resources()

    <?php
    $fp = tmpfile();
    var_dump(get_resources('stream'));
    var_dump(get_resources('curl'));
    ?>

以上示例的输出类似于：

    array(1) {
      [1]=>
      resource(1) of type (stream)
    }
    array(0) {
    }

### 参见

- get_loaded_extensions() - 返回所有编译并加载模块名的 array
- get_defined_constants() - 返回所有常量的关联数组，键是常量名，值是常量值
- get_defined_functions() - 返回所有已定义函数的数组
- get_defined_vars() - 返回由所有已定义变量所组成的数组

# getenv

(PHP 4, PHP 5, PHP 7, PHP 8)

getenv — 获取单个或者全部环境变量

### 说明

function getenv(?string `$name` = `null`, bool `$local_only` = `false`): string|array|false

获取单个或者全部环境变量。

使用 phpinfo() 你可以看到所有环境变量的列表。 这些变量很多都在 » RFC 3875 的范围之内， 尤其是章节4.1，"Request Meta-Variables"。

### 参数

`name`

  string 形式的变量名或为 `null`。

`local_only`

  当设置为 `true` 时，仅返回由操作系统或 putenv() 设置的本地环境变量。这只在 `name` 是 string 时才生效。

### 返回值

返回环境变量 `name` 的值，如果环境变量 `name` 不存在则返回 `false`。如果 `name` 是 `null`，则所有环境变量都将作为关联 array 返回。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `name` 现在可为 null。
7.1.0 | 现在可以省略 `name` 来检索所有环境变量的关联数组 array。
7.0.9 | 添加 `local_only` 参数。

### 示例

示例 #1 getenv() 示例

    <?php
    // getenv() 使用示例
    $ip = getenv('REMOTE_ADDR');

    // 或简单仅使用全局变量（$_SERVER 或 $_ENV）
    $ip = $_SERVER['REMOTE_ADDR'];

    // 安全地获取环境变量，忽略通过 SAPI 或 putenv 修改的值
    $ip = getenv('REMOTE_ADDR', true) ?: getenv('REMOTE_ADDR')
    ?>

### 注释

警告

如果 PHP 在诸如 Fast CGI 之类的 SAPI 中运行，则此函数将始终返回由 SAPI 设置的环境变量的值，即使已使用 putenv() 来设置同名的本地环境变量。使用 `local_only` 参数返回本地设置的环境变量的值。

### 参见

- putenv() - 设置环境变量的值
- apache_getenv() - 获取 Apache subprocess_env 变量
- 超全局变量

# getlastmod

(PHP 4, PHP 5, PHP 7, PHP 8)

getlastmod — 获取页面最后修改的时间

### 说明

function getlastmod(): int|false

获取执行的主脚本的最后修改时间。

如果你对其他文件的最后修改时间的感兴趣，可考虑使用 filemtime()。

### 参数

此函数没有参数。

### 返回值

返回当前页面最后修改的时间。这个值是一个 Unix 时间戳，可以传入 date()。 错误时返回 `false`。

### 示例

示例 #1 getlastmod() 示例

    <?php
    // 输出类似 'Last modified: March 04 1998 20:43:59.'
    echo "Last modified: " . date ("F d Y H:i:s.", getlastmod());
    ?>

### 参见

- date() - 格式化 Unix 时间戳
- getmyuid() - 获取 PHP 脚本所有者的 UID
- getmygid() - 获取当前 PHP 脚本拥有者的 GID
- get_current_user() - 获取当前 PHP 脚本所有者名称
- getmyinode() - 获取当前脚本的索引节点（inode）
- getmypid() - 获取 PHP 进程的 ID
- filemtime() - 取得文件修改时间

# getmygid

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

getmygid — 获取当前 PHP 脚本拥有者的 GID

### 说明

function getmygid(): int|false

获取当前 PHP 脚本拥有者的用户组 ID。

### 参数

此函数没有参数。

### 返回值

返回当前 PHP 脚本拥有者的用户组 ID，或在错误时返回 `false`。

### 参见

- getmyuid() - 获取 PHP 脚本所有者的 UID
- getmypid() - 获取 PHP 进程的 ID
- get_current_user() - 获取当前 PHP 脚本所有者名称
- getmyinode() - 获取当前脚本的索引节点（inode）
- getlastmod() - 获取页面最后修改的时间

# getmyinode

(PHP 4, PHP 5, PHP 7, PHP 8)

getmyinode — 获取当前脚本的索引节点（inode）

### 说明

function getmyinode(): int|false

获取当前脚本的索引节点（inode）。

### 参数

此函数没有参数。

### 返回值

以整型返回当前脚本的索引节点（inode），或在错误时返回 `false`。

### 参见

- getmygid() - 获取当前 PHP 脚本拥有者的 GID
- getmyuid() - 获取 PHP 脚本所有者的 UID
- getmypid() - 获取 PHP 进程的 ID
- get_current_user() - 获取当前 PHP 脚本所有者名称
- getlastmod() - 获取页面最后修改的时间

# getmypid

(PHP 4, PHP 5, PHP 7, PHP 8)

getmypid — 获取 PHP 进程的 ID

### 说明

function getmypid(): int|false

获取当前 PHP 进程 ID。

### 参数

此函数没有参数。

### 返回值

返回当前 PHP 进程 ID，或在错误时返回 `false`。

### 注释

警告

进程 ID 并不是唯一的，所以他们是一个弱熵源。 对安全性有依赖的上下文中我们不推荐依赖于 pid。

### 参见

- getmygid() - 获取当前 PHP 脚本拥有者的 GID
- getmyuid() - 获取 PHP 脚本所有者的 UID
- get_current_user() - 获取当前 PHP 脚本所有者名称
- getmyinode() - 获取当前脚本的索引节点（inode）
- getlastmod() - 获取页面最后修改的时间

# getmyuid

(PHP 4, PHP 5, PHP 7, PHP 8)

getmyuid — 获取 PHP 脚本所有者的 UID

### 说明

function getmyuid(): int|false

获取当前脚本的用户 ID。

### 参数

此函数没有参数。

### 返回值

返回当前脚本的用户 ID，或在错误时返回 `false`。

### 参见

- getmygid() - 获取当前 PHP 脚本拥有者的 GID
- getmypid() - 获取 PHP 进程的 ID
- get_current_user() - 获取当前 PHP 脚本所有者名称
- getmyinode() - 获取当前脚本的索引节点（inode）
- getlastmod() - 获取页面最后修改的时间

# getopt

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

getopt — 从命令行参数列表中获取选项

### 说明

function getopt(string `$short_options`, array `$long_options` = [], int `&$rest_index` = `null`): array|false

解析传入脚本的选项。

### 参数

`short_options`
  该字符串中的每个字符会被当做选项字符，匹配传入脚本的选项以单个连字符 (`-`) 开头。 比如，一个选项字符串 `"x"` 识别了一个选项 `-x`。 只允许 a-z、A-Z 和 0-9。
`long_options`
  选项数组。此数组中的每个元素会被作为选项字符串，匹配了以两个连字符 (`--`) 传入到脚本的选项。 例如，长选项元素 `"opt"` 识别了一个选项 `--opt`。
`rest_index`
  如果传递了 `rest_index` 参数，那么参数解析停止时的索引，将被赋值给此变量。

`short_options` 可能包含了以下元素：

- 单独的字符（不接受值）
- 后面跟随冒号的字符（此选项需要值）
- 后面跟随两个冒号的字符（此选项的值可选）

选项的值是字符串后的第一个参数。如果需要一个值，它不介意值之前是否有前置的空格，参见以下内容。

> 注意: 选项的值不接受空格（`" "`）作为分隔符。

`long_options` 数组可能包含了以下元素：

- 字符串（参数不接受任何值）
- 后面跟随冒号的字符串（此选项需要值）
- 后面跟随两个冒号的字符串（此选项的值可选）

> 注意:

> `short_options` 和 `long_options` 的格式几乎是一样的，唯一的不同之处是 `long_options` 需要是选项的数组（每个元素为一个选项），而 `short_options` 需要一个字符串（每个字符是个选项）。

### 返回值

此函数会返回选项/参数对， 或者在失败时返回 `false`。

> 注意:

> 选项的解析会终止于找到的第一个非选项，之后的任何东西都会被丢弃。

### 更新日志

版本 | 说明
--- | ---
7.1.0 | 添加 `rest_index` 参数。

### 示例

示例 #1 getopt() 示例：基本用法

    <?php
    // Script example.php
    $options = getopt("f:hp:");
    var_dump($options);
    ?>

    shell> php example.php -fvalue -h

以上示例会输出：

    array(2) {
      ["f"]=>
      string(5) "value"
      ["h"]=>
      bool(false)
    }

示例 #2 getopt() 示例：引入长选项

    <?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

以上示例会输出：

    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)
    }

示例 #3 getopt() 示例：传递同一多个选项

    <?php
    // Script example.php
    $options = getopt("abc");
    var_dump($options);
    ?>

    shell> php example.php -aaac

以上示例会输出：

    array(2) {
      ["a"]=>
      array(3) {
        [0]=>
        bool(false)
        [1]=>
        bool(false)
        [2]=>
        bool(false)
      }
      ["c"]=>
      bool(false)
    }

示例 #4 getopt() 示例：使用 `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

以上示例会输出：

    array(1) {
      [0]=>
      string(4) "test"
    }

### 参见

- $argv

# getrusage

(PHP 4, PHP 5, PHP 7, PHP 8)

getrusage — 获取当前资源使用状况

### 说明

function getrusage(int `$mode` = 0): array|false

这是 getrusage(2) 的接口。它返回了调用自系统的数据。

### 参数

`mode`

  如果 `mode` 是 1，getrusage 会使用 `RUSAGE_CHILDREN` 来调用。

### 返回值

返回了一个包含系统返回数据的关联数组。所以条目均可通过文档中字段的名称来访问。失败时返回 `false`。

### 示例

示例 #1 getrusage() 示例

    <?php
    $dat = getrusage();
    echo $dat["ru_oublock"];       // 块输出操作数
    echo $dat["ru_inblock"];       // 块输入操作数
    echo $dat["ru_msgsnd"];        // 发送的 IPC 消息数
    echo $dat["ru_msgrcv"];        // 接收的 IPC 消息数
    echo $dat["ru_maxrss"];        // maximum resident set size
    echo $dat["ru_ixrss"];         // 整数类型的共享内存大小
    echo $dat["ru_idrss"];         // 整数类型的非共享内存大小
    echo $dat["ru_minflt"];        // 页面回收次数（软分页错误）
    echo $dat["ru_majflt"];        // 页面错误次数（硬分页错误）
    echo $dat["ru_nsignals"];      // 接收到的信号数
    echo $dat["ru_nvcsw"];         // number of voluntary context switches
    echo $dat["ru_nivcsw"];        // number of involuntary context switches
    echo $dat["ru_nswap"];         // 交换次数
    echo $dat["ru_utime.tv_usec"]; // 用户使用时间（微秒）
    echo $dat["ru_utime.tv_sec"];  // 用户使用时间（秒）
    echo $dat["ru_stime.tv_usec"]; // 系统使用时间（微秒）
    echo $dat["ru_stime.tv_sec"];  // 系统使用时间（秒）
    ?>

### 注释

> 注意:

> 在 Windows 上 getrusage() 仅会返回以下类型：

> - `"ru_stime.tv_sec"`
> - `"ru_stime.tv_usec"`
> - `"ru_utime.tv_sec"`
> - `"ru_utime.tv_usec"`
> - `"ru_majflt"`（仅当 `mode` 是 `RUSAGE_SELF`）
> - `"ru_maxrss"`（仅当 `mode` 是 `RUSAGE_SELF`）

> 如果使用设置 `mode` 为 `1`（`RUSAGE_CHILDREN`）的情况下调用 getrusage()，则会收集线程的资源使用情况（意味着在内部使用 `RUSAGE_THREAD` 调用此函数）。

> 注意:

> 在 BeOS 2000，仅会返回以下类型：

> - `"ru_stime.tv_sec"`
> - `"ru_stime.tv_usec"`
> - `"ru_utime.tv_sec"`
> - `"ru_utime.tv_usec"`

### 参见

- 系统上 getrusage(2) 的 man 页面

# ini_alter

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_alter — 别名 ini_set()

### 说明

此函数是该函数的别名： ini_set().

# ini_get

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_get — 获取一个配置选项的值

### 说明

function ini_get(string `$option`): string|false

成功时返回配置选项的值。

### 参数

`option`

  配置选项名称。

### 返回值

成功是返回配置选项值的字符串，`null` 的值则返回空字符串。如果配置选项不存在，将会返回 `false`。

### 示例

示例 #1 一些 ini_get() 示例

    <?php

    /*
    我们的 php.ini 包含了以下的设置：

    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'));
    ?>

以上示例的输出类似于：

    display_errors = 1
    opcache.enable_cli = 0
    post_max_size = 8M
    post_max_size+1 = 9
    post_max_size in bytes = 8388608

### 注释

> 注意: 当查询一个 boolean 值

> 一个 `off` 的 boolean ini 值将会以空字符串或者 "0" 返回；`on` 的 ini 值会以 "1" 返回。 此函数也会返回 INI 值的文字字符串。

> 注意: 当查询一个内存尺寸的值

> 许多内存尺寸的 ini 值，类似 upload_max_filesize 是以简写表示法储存在 php.ini 文件里。 ini_get() 会返回 php.ini 文件中储存的确切字符串，而不是它的等量 int。 尝试对这些值进行正常的算术运算将不会得到预期的结果。 ini_parse_quantity() 函数可以用来将简写表示法转换为字节。

> 注意:

> ini_get() 无法读取 "array" 的 ini 选项， 例如 `pdo.dsn.*`， 在这个示例中会返回 `false`。

### 参见

- get_cfg_var() - 获取 PHP 配置选项的值
- ini_get_all() - 获取所有配置选项
- ini_parse_quantity() - Get interpreted size from ini shorthand syntax
- ini_restore() - 恢复配置选项的值
- ini_set() - 为一个配置选项设置值

# ini_get_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ini_get_all — 获取所有配置选项

### 说明

function ini_get_all(?string `$extension` = `null`, bool `$details` = `true`): array|false

获取所有已注册的配置选项

### 参数

`extension`

  可选的扩展名称。如果不是 `null` 或字符串 `core`，此函数仅仅返回指定扩展的选项。

`details`

  获取详细设置或者仅仅是每个设置的当前值。 默认是 `true`（获取详细信息）。

### 返回值

返回一个关联数组，指令名称是数组的键。 如果 `extension` 不存在，返回 `false` 并产生 `E_WARNING` 级错误。

当 `details` 为 `true`（默认），数组会包含 `global_value`（php.ini 中的设置）、`local_value`（可能是 ini_set() 或 .htaccess 中的设置） 以及 `access`（访问级别）。

当 `details` 为 `false`，这个值会是选项的当前值。

参见手册章节中访问级别含义的信息。

> 注意:

> 指令可以有多个访问级别，这也是为什么 `access` 会显示适当的位掩码。

### 示例

示例 #1 ini_get_all() 示例

    <?php
    print_r(ini_get_all("pcre"));
    print_r(ini_get_all());
    ?>

以上示例的输出类似于：

    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
            )

        ...

    )

示例 #2 禁用 `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
    ?>

以上示例的输出类似于：

    Array
    (
        [pcre.backtrack_limit] => 100000
        [pcre.recursion_limit] => 100000
    )
    Array
    (
        [allow_call_time_pass_reference] => 0
        [allow_url_fopen] => 1
        ...
    )

### 注释

> 注意:

> ini_get_all() 忽略 "array" 的 ini 选项，例如 `pdo.dsn.*`。

### 参见

- 怎样修改配置设定
- ini_get() - 获取一个配置选项的值
- ini_restore() - 恢复配置选项的值
- ini_set() - 为一个配置选项设置值
- get_loaded_extensions() - 返回所有编译并加载模块名的 array
- phpinfo() - 输出关于 PHP 配置的信息
- ReflectionExtension::getINIEntries() - 获取 ini 配置

# ini_parse_quantity

(PHP 8 >= 8.2.0)

ini_parse_quantity — Get interpreted size from ini shorthand syntax

### 说明

function ini_parse_quantity(string `$shorthand`): int

Returns the interpreted size in bytes on success from an ini shorthand.

### 参数

`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`)

### 返回值

Returns the interpreted size in bytes as an int.

### 错误／异常

If the value cannot be parsed, or an invalid multiplier is used, an `E_WARNING` is raised.

### 示例

示例 #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'));

    ?>

以上示例会输出：

    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)

### 参见

- ini_get() - 获取一个配置选项的值

# ini_restore

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_restore — 恢复配置选项的值

### 说明

function ini_restore(string `$option`): void

恢复指定的配置选项到它的原始值。

### 参数

`option`

  配置选项名称。

### 返回值

没有返回值。

### 示例

示例 #1 ini_restore() 示例

    <?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;
    ?>

以上示例会输出：

    Current value for 'html_errors': 1
    New value for 'html_errors': 0
    Original value for 'html_errors': 1

### 参见

- ini_get() - 获取一个配置选项的值
- ini_get_all() - 获取所有配置选项
- ini_set() - 为一个配置选项设置值

# ini_set

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_set — 为一个配置选项设置值

### 说明

function ini_set(string `$option`, string|int|float|bool|null `$value`): string|false

设置指定配置选项的值。这个选项会在脚本运行时保持新的值，并在脚本结束时恢复。

### 参数

`option`

  不是所有有效的选项都能够用 ini_set() 来改变的。 这里有个有效选项的清单附录。

`value`

  选项新的值。

### 返回值

成功时返回旧的值，失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | `value` 现在接受任何标量类型（包含 `null`），之前仅接受 string 值。

### 示例

示例 #1 设置一个 ini 选项

    <?php
    echo ini_get('display_errors');

    if (!ini_get('display_errors')) {
        ini_set('display_errors', '1');
    }

    echo ini_get('display_errors');
    ?>

### 参见

- get_cfg_var() - 获取 PHP 配置选项的值
- ini_get() - 获取一个配置选项的值
- ini_get_all() - 获取所有配置选项
- ini_restore() - 恢复配置选项的值
- 如何改变配置选项

# memory_get_peak_usage

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

memory_get_peak_usage — 返回分配给 PHP 内存的峰值

### 说明

function memory_get_peak_usage(bool `$real_usage` = `false`): int

返回分配给你的 PHP 脚本的内存峰值字节数。

### 参数

`real_usage`

  如果设置为 `true` 可以获取从系统分配到的真实内存尺寸。 如果未设置，或者设置为 `false`，仅会报告 `emalloc()` 使用的内存。

### 返回值

返回内存峰值的字节数。

### 参见

- memory_get_usage() - 返回分配给 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 — 返回分配给 PHP 的内存量

### 说明

function memory_get_usage(bool `$real_usage` = `false`): int

返回当前分配给你的 PHP 脚本的内存量，单位是字节（byte）。

### 参数

`real_usage`

  如果设置为 `true`，获取系统分配总的内存尺寸，包括未使用的页。如果未设置或者设置为 `false`，仅仅报告实际使用的内存量。

> 注意:

> PHP 不跟踪非`emalloc()` 分配的内存

### 返回值

返回内存量字节数。

### 示例

示例 #1 一个 memory_get_usage() 示例

    <?php
    //这只是个示例，下面的数字取决于你的系统

    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

    ?>

### 参见

- memory_get_peak_usage() - 返回分配给 PHP 内存的峰值
- memory_limit

# memory_reset_peak_usage

(PHP 8 >= 8.2.0)

memory_reset_peak_usage — Reset the peak memory usage

### 说明

function memory_reset_peak_usage(): void

Resets the peak memory usage returned by the memory_get_peak_usage() function.

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 示例

示例 #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());

    ?>

以上示例的输出类似于：

    int(422440)
    int(2508672)
    int(399208)

### 参见

- memory_get_peak_usage() - 返回分配给 PHP 内存的峰值

# php_ini_loaded_file

(PHP 5 >= 5.2.4, PHP 7, PHP 8)

php_ini_loaded_file — 取得已加载的 php.ini 文件的路径

### 说明

function php_ini_loaded_file(): string|false

检查是否有加载的 php.ini 文件，并取回它的路径。

### 参数

此函数没有参数。

### 返回值

已加载的 php.ini 路径，或在没有时返回 `false`。

### 示例

示例 #1 php_ini_loaded_file() 示例

    <?php
    $inipath = php_ini_loaded_file();

    if ($inipath) {
        echo 'Loaded php.ini: ' . $inipath;
    } else {
        echo 'A php.ini file is not loaded';
    }
    ?>

以上示例的输出类似于：

    Loaded php.ini: /usr/local/php/php.ini

### 参见

- php_ini_scanned_files() - 返回从额外 ini 目录里解析的 .ini 文件列表
- phpinfo() - 输出关于 PHP 配置的信息
- 配置文件

# php_ini_scanned_files

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

php_ini_scanned_files — 返回从额外 ini 目录里解析的 .ini 文件列表

### 说明

function php_ini_scanned_files(): string|false

php_ini_scanned_files() 在 php.ini 之后解析的配置文件的逗号分割列表。搜索的目录由编译时选项设置，也可以在运行时由环境变量设置：更多信息可以从安装指南中找到。

返回的配置文件包含完整路径。

### 参数

此函数没有参数。

### 返回值

成功时返回逗号分隔的 .ini 文件字符串。每个逗号后紧跟新的一行。如果未设置配置指令 --with-config-file-scan-dir 并且没有设置环境变量 PHP_INI_SCAN_DIR 将会返回 `false`。如果它设置了，并且目录是空的，将会返回一个空字符串。如果有未识别的文件，此文件也会进入返回的字符串，但是会导致一个 PHP 错误。此 PHP 错误即会在编译时出现也会在使用 php_ini_scanned_files() 函数时出现。

### 示例

示例 #1 列出返回的 ini 文件的简单示例

    <?php
    if ($filelist = php_ini_scanned_files()) {
        if (strlen($filelist) > 0) {
            $files = explode(',', $filelist);

            foreach ($files as $file) {
                echo "<li>" . trim($file) . "</li>\n";
            }
        }
    }
    ?>

### 参见

- ini_set() - 为一个配置选项设置值
- phpinfo() - 输出关于 PHP 配置的信息
- php_ini_loaded_file() - 取得已加载的 php.ini 文件的路径

# php_sapi_name

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

php_sapi_name — 返回 web 服务器和 PHP 之间的接口类型

### 说明

function php_sapi_name(): string|false

返回描述 PHP 所使用的接口类型（the Server API, SAPI）的小写字符串。 例如，CLI 的 PHP 下这个字符串会是 "cli"，Apache 下可能会有几个不同的值，取决于具体使用的 SAPI。 以下列出了可能的值。

### 参数

此函数没有参数。

### 返回值

返回接口类型的小写字符串， 或者在失败时返回 `false`。

尽管不够全面，可能返回的值包括了 `apache`、`apache2handler`、`cgi`（直到 PHP 5.3）、`cgi-fcgi`、`cli`、`cli-server`、`embed`、`fpm-fcgi`、`litespeed`、`phpdbg`。

### 示例

示例 #1 php_sapi_name() 示例

以下示例检测了子字符串 `cgi`，因为它也有可能会是 `cgi-fcgi`。

    <?php
    $sapi_type = php_sapi_name();
    if (substr($sapi_type, 0, 3) == 'cgi') {
        echo "You are using CGI PHP\n";
    } else {
        echo "You are not using CGI PHP\n";
    }
    ?>

### 注释

> 注意: 另一种方法

> PHP 常量 `PHP_SAPI` 具有和 php_sapi_name() 相同的值。

小技巧

# 一个潜在的疑难问题

定义的 SAPI 可能不够明显，比如它可能定义为 `apache2handler`，而不是 `apache`。

### 参见

- PHP_SAPI

# php_uname

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

php_uname — 返回运行 PHP 的系统的有关信息

### 说明

function php_uname(string `$mode` = "a"): string

php_uname() 返回了运行 PHP 的操作系统的描述。 这和 phpinfo() 最顶端上输出的是同一个字符串。 如果仅仅要获取操作系统的名称。可以考虑使用常量 `PHP_OS`，不过要注意该常量会包含 PHP 构建（built）时的操作系统名。

在一些旧的 UNIX 平台，它有可能无法检测到当前系统的信息，然后会还原显示成构建 PHP 时的系统信息。 这仅仅在你的 uname() 函数库不存在或无法运行时发生。

### 参数

`mode`

  `mode` 是单个字符，用于定义要返回什么信息：

  - `'a'`：此为默认。返回与空格分隔的单独模式 `'s'`, `'n'`, `'r'`, `'v'`, `'m'` 相同的信息。

  - `'s'`：操作系统名称。例如： `FreeBSD`。
  - `'n'`：主机名。例如： `localhost.example.com`。
  - `'r'`：版本名称，例如： `5.1.2-RELEASE`。
  - `'v'`：版本信息。操作系统之间有很大的不同。
  - `'m'`：机器类型。例如：`i386`。

### 返回值

返回描述字符串。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 当指定的 `mode` 无效时，抛出 ValueError。

### 示例

示例 #1 一些 php_uname() 示例

    <?php
    echo php_uname();
    echo PHP_OS;

    /* 比如有些会输出：
    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!';
    }

    ?>

同样可以方便地使用一些相关的 PHP 预定义常量，例如：

示例 #2 一些系统相关常量的示例

    <?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;      // ;
    ?>

### 参见

- phpversion() - 获取当前的PHP版本
- php_sapi_name() - 返回 web 服务器和 PHP 之间的接口类型
- phpinfo() - 输出关于 PHP 配置的信息

# phpcredits

(PHP 4, PHP 5, PHP 7, PHP 8)

phpcredits — 打印 PHP 贡献者名单

### 说明

function phpcredits(int `$flags` = `CREDITS_ALL`): true

这个函数打印出了 PHP 开发者、模块等贡献者名单。 它生成了合适、可嵌入信息到页面中的 HTML 代码。

### 参数

`flags`

  生成自定义的贡献者页面，你也许想要使用 `flags` 参数。

  预定义的 phpcredits() flags
  名称 | 描述
  --- | ---
  CREDITS_ALL | 所有贡献者，等同于使用： `CREDITS_DOCS` + `CREDITS_GENERAL` + `CREDITS_GROUP` + `CREDITS_MODULES` + `CREDITS_FULLPAGE`。 它以适当的标签产生了完整独立的 HTML 页面。
  CREDITS_DOCS | 文档组贡献名单
  CREDITS_FULLPAGE | 常用于和其他标志进行组合。 表示需要打印包含其他标志表示信息的独立 HTML 页面。
  CREDITS_GENERAL | 普遍名单：语言设计与理念、PHP作者以及 SAPI 模块。
  CREDITS_GROUP | 核心开发者名单
  CREDITS_MODULES | PHP 扩展模块以及它们的作者的清单
  CREDITS_SAPI | PHP 的服务器 API 模块以及他们的作者的清单

### 返回值

总是返回 `true`。

### 示例

示例 #1 打印普遍名单

    <?php
    phpcredits(CREDITS_GENERAL);
    ?>

示例 #2 打印核心开发者和文档组

    <?php
    phpcredits(CREDITS_GROUP | CREDITS_DOCS | CREDITS_FULLPAGE);
    ?>

示例 #3 打印所有贡献者

    <html>
     <head>
      <title>My credits page</title>
     </head>
     <body>
    <?php
    // 一些你自己的代码
    phpcredits(CREDITS_ALL - CREDITS_FULLPAGE);
    // 一些其他的代码
    ?>
     </body>
    </html>

### 注释

> 注意:

> 在 CLI 模式下 phpcredits() 输出明文而不是 HTML。

### 参见

- phpversion() - 获取当前的PHP版本
- phpinfo() - 输出关于 PHP 配置的信息

# phpinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

phpinfo — 输出关于 PHP 配置的信息

### 说明

function phpinfo(int `$flags` = `INFO_ALL`): true

输出 PHP 当前状态的大量信息，包含了 PHP 编译选项、启用的扩展、PHP 版本、服务器信息和环境变量（如果编译为一个模块的话）、PHP 环境变量、操作系统版本信息、path 变量、配置选项的本地值和主值、HTTP 头和PHP授权信息（License）。

因为每个系统安装得有所不同，phpinfo() 常用于在系统上检查配置设置和预定义变量。

phpinfo() 同时是个很有价值的、包含所有 EGPCS(Environment、GET、POST、Cookie、Server) 数据的调试工具。

### 参数

`flags`

  可以用以下的一个或多个 constants 用位运算传递给可选的 `flags` 参数来定制输出的信息。 该参数可以把常量相加或者用按位或操作符按位运算。

  phpinfo() 选项
  Name (constant) | Value | Description
  --- | --- | ---
  INFO_GENERAL | 1 | 配置的命令行、php.ini 的文件位置、建立的时间、Web 服务器、系统及更多其他信息。
  INFO_CREDITS | 2 | PHP 贡献者名单。参见 phpcredits()。
  INFO_CONFIGURATION | 4 | 当前PHP指令的本地值和主值。参见 ini_get()。
  INFO_MODULES | 8 | 已加载的模块和模块相应的设置。参见 get_loaded_extensions()。
  INFO_ENVIRONMENT | 16 | 环境变量信息也可以用 $_ENV 获取。
  INFO_VARIABLES | 32 | 显示所有来自 EGPCS (Environment, GET, POST, Cookie, Server) 的 预定义变量。
  INFO_LICENSE | 64 | PHP许可证信息。参见 » license FAQ。
  INFO_ALL | -1 | 显示以上所有信息。

### 返回值

总是返回 `true`。

### 示例

示例 #1 phpinfo() 示例

    <?php

    // 显示所有信息，默认显示 INFO_ALL
    phpinfo();

    // Show just the module information. 仅仅显示PHP模块信息，
    // phpinfo(8) 返回同样的结果。
    phpinfo(INFO_MODULES);

    ?>

### 注释

> 注意:

> 在 PHP 5.5 之前版本，当 expose_php 设置为 `off` 可以禁用一部分信息。 这包括了 PHP 和 Zend 的 logo，以及贡献者名单。

> 注意:

> 在命令行（CLI）模式下 phpinfo() 仅会输出纯文本，而不是HTML。

### 参见

- phpversion() - 获取当前的PHP版本
- phpcredits() - 打印 PHP 贡献者名单
- ini_get() - 获取一个配置选项的值
- ini_set() - 为一个配置选项设置值
- get_loaded_extensions() - 返回所有编译并加载模块名的 array
- 预定义变量

# phpversion

(PHP 4, PHP 5, PHP 7, PHP 8)

phpversion — 获取当前的PHP版本

### 说明

function phpversion(?string `$extension` = `null`): string|false

返回了包含当前运行 PHP 解释器或扩展版本信息的 string。

### 参数

`extension`

  可选的扩展名。

### 返回值

以 string 形式返回当前 PHP 版本。如果为 `extension` 提供了 string 类型的参数，phpversion() 会返回该扩展的版本。如果没有对应的版本信息，或者该扩展未启用，则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `extension` 现在可为 null。

### 示例

示例 #1 phpversion() 示例

    <?php
    // 打印 'Current PHP version: 8.3.12'
    echo 'Current PHP version: ' . phpversion();

    // 打印 '2.0'，如果扩展未启用则不输出
    echo phpversion('tidy');
    ?>

示例 #2 `PHP_VERSION_ID` 示例和用法

    <?php

    /**
     * PHP_VERSION_ID 定义为一个数字，PHP 版本越高，数字越大。
     * 使用下列表达式定义
     *
     * $version_id = $major_version * 10000 + $minor_version * 100 + $release_version;
     *
     * 现在可以通过 PHP_VERSION_ID 来检查 PHP 版本，
     * 而不用每次都必须用 version_compare() 来检查 PHP 是否支持某个功能。
     *
     * 比如，可以在此定义一系列 PHP_*_VERSION 常量，
     * 而在 5.2.7 之前的版本并没有定义。
     */

    if (PHP_VERSION_ID < 50207) {
        define('PHP_MAJOR_VERSION',   $version[0]);
        define('PHP_MINOR_VERSION',   $version[1]);
        define('PHP_RELEASE_VERSION', $version[2]);

        // 等等， ...
    }

    ?>

### 注释

> 注意:

> 这些信息也存在于预定义常量 `PHP_VERSION` 里。更多版本的信息可以使用常量 `PHP_*_VERSION`。

> 注意:

> 许多扩展可能会定义它们自己的版本号。然而，大多数捆绑版本将会使用 PHP 版本作为他们的版本号。

> 注意:

> 一些扩展可能会定义他们自己的版本号。 然而，大多数内置的扩展会使用 PHP 版本作为它们的版本号。

### 参见

- 常量 PHP_VERSION
- version_compare() - 对比两个「PHP 规范化」的版本数字字符串
- phpinfo() - 输出关于 PHP 配置的信息
- phpcredits() - 打印 PHP 贡献者名单
- zend_version() - 获取当前 Zend 引擎的版本

# putenv

(PHP 4, PHP 5, PHP 7, PHP 8)

putenv — 设置环境变量的值

### 说明

function putenv(string `$assignment`): bool

添加 `assignment` 到服务器环境变量。 环境变量仅存活于当前请求期间。 在请求结束时环境会恢复到初始状态。

### 参数

`assignment`

  设置，例如 `"FOO=BAR"`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 设置一个环境变量

    <?php
    putenv("UNIQID=$uniqid");
    ?>

### 参见

- getenv() - 获取单个或者全部环境变量
- apache_setenv() - 设置 Apache 子进程环境变量

# restore_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7)

restore_include_path — 还原 include_path 配置选项的值

警告

本函数已自 PHP 7.4.0 起弃用，自 PHP 8.0.0 起移除。强烈建议不要依赖本函数。

### 说明

function restore_include_path(): void

还原到 php.ini 中设置的 include_path 主值。

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 此函数已移除。
7.4.0 | 此函数已废弃。

### 示例

示例 #1 restore_include_path() 示例

    <?php

    echo get_include_path();  // .:/usr/local/lib/php

    set_include_path('/inc');

    echo get_include_path();  // /inc

    restore_include_path();

    // 或使用 ini_restore
    ini_restore('include_path');

    echo get_include_path();  // .:/usr/local/lib/php

    ?>

### 参见

- ini_restore() - 恢复配置选项的值
- get_include_path() - 获取当前的 include_path 配置选项
- set_include_path() - 设置 include_path 配置选项
- include - include

# set_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

set_include_path — 设置 include_path 配置选项

### 说明

function set_include_path(string `$include_path`): string|false

为当前脚本设置 include_path 运行时的配置选项。

### 参数

`include_path`

  include_path 新的值。

### 返回值

成功时返回旧的 include_path 或者在失败时返回 `false`。

### 示例

示例 #1 set_include_path() 示例

    <?php
    set_include_path('/usr/lib/pear');

    // 或使用 ini_set
    ini_set('include_path', '/usr/lib/pear');
    ?>

示例 #2 添加到include path

利用常量 `PATH_SEPARATOR` 可跨平台扩展 include path。

这个示例中我们把 /usr/lib/pear 添加到了 现有的 `include_path` 的尾部。

    <?php
    $path = '/usr/lib/pear';
    set_include_path(get_include_path() . PATH_SEPARATOR . $path);
    ?>

### 参见

- ini_set() - 为一个配置选项设置值
- get_include_path() - 获取当前的 include_path 配置选项
- restore_include_path() - 还原 include_path 配置选项的值
- include - include

# set_time_limit

(PHP 4, PHP 5, PHP 7, PHP 8)

set_time_limit — 设置脚本最大执行时间

### 说明

function set_time_limit(int `$seconds`): bool

设置允许脚本运行的时间，单位为秒。如果超过了此设置，脚本返回一个致命的错误。默认值为30秒，或者是在php.ini的`max_execution_time`被定义的值，如果此值存在。

当此函数被调用时，set_time_limit()会从零开始重新启动超时计数器。换句话说，如果超时默认是30秒，在脚本运行了25秒时调用 `set_time_limit(20)`，那么，脚本在超时之前可运行总时间为45秒。

### 参数

`seconds`

  最大的执行时间，单位为秒。如果设置为0（零），没有时间方面的限制。

### 返回值

成功时返回 `true`，失败时返回 `false` 。

### 注释

> 注意:

> set_time_limit()函数和配置指令max_execution_time只影响脚本本身执行的时间。任何发生在诸如使用system()的系统调用，流操作，数据库操作等的脚本执行的最大时间不包括其中，当该脚本已运行。在测量时间是实值的Windows中，情况就不是如此了。

### 参见

- max_execution_time
- max_input_time

# sys_get_temp_dir

(PHP 5 >= 5.2.1, PHP 7, PHP 8)

sys_get_temp_dir — 返回用于临时文件的目录

### 说明

function sys_get_temp_dir(): string

返回 PHP 储存临时文件的默认目录的路径。

### 参数

此函数没有参数。

### 返回值

返回临时目录的路径。

### 示例

示例 #1 sys_get_temp_dir() 示例

    <?php
    // 使用 sys_get_temp_dir() 在目录里创建临时文件
    $temp_file = tempnam(sys_get_temp_dir(), 'Tux');

    echo $temp_file;
    ?>

以上示例的输出类似于：

    C:\Windows\Temp\TuxA318.tmp

### 参见

- tmpfile() - 建立一个临时文件
- tempnam() - 建立一个具有唯一文件名的文件

# version_compare

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

version_compare — 对比两个「PHP 规范化」的版本数字字符串

### 说明

function version_compare(string `$version1`, string `$version2`, ?string `$operator` = `null`): int|bool

version_compare() 用于对比两个「PHP 规范化」的版本数字字符串。

此函数首先在版本字符串里用一个点 `.` 替换 `_`、`-` 和 `+`，也会在任意非数字前后插入一个点 `.`，这样，类似 '4.3.2RC1' 将会变成 '4.3.2.RC.1'。 接下来它会分割结果， 然后它会从左往右对比各个部分。 如果某部分包含了特定的版本字符串，将会用以下顺序处理： `列表中未找到的任意字符串` < `dev` < `alpha` = `a` < `beta` = `b` < `RC` = `rc` < `#` < `pl` = `p`。 这种方式不仅能够对比类似 '4.1' 和 '4.1.2' 那种不同的版本级别，同时也可以指定对比任何包含 PHP 开发状态的版本。

### 参数

`version1`

  第一个版本数。

`version2`

  第二个版本数。

`operator`

  可选运算符。可能运算符有：`<`、`lt`、`<=`、`le`、 `>`、`gt`、`>=`、`ge`、`==`、 `=`、`eq`、`!=`、`<>`、`ne`。

  此参数区分大小写，它的值应该是小写的。

### 返回值

默认情况下，在第一个版本低于第二个时，version_compare() 返回 `-1`；如果两者相等，返回 `0`；第二个版本更低时则返回 `1`。

当使用了可选参数 `operator` 时，如果关系是操作符所指定的那个，函数将返回 `true`，否则返回 `false`。

### 示例

下例使用了 `PHP_VERSION` 常量，因为它执行的代码包含了 PHP 版本的值。

示例 #1 version_compare() examples

    <?php
    if (version_compare(PHP_VERSION, '7.0.0') >= 0) {
        echo 'I am at least PHP version 7.0.0, my version: ' . PHP_VERSION . "\n";
    }

    if (version_compare(PHP_VERSION, '5.3.0') >= 0) {
        echo 'I am at least PHP version 5.3.0, my version: ' . PHP_VERSION . "\n";
    }

    if (version_compare(PHP_VERSION, '5.0.0', '>=')) {
        echo 'I am at least PHP version 5.0.0, my version: ' . PHP_VERSION . "\n";
    }

    if (version_compare(PHP_VERSION, '5.0.0', '<')) {
        echo 'I am still PHP 4, my version: ' . PHP_VERSION . "\n";
    }
    ?>

### 注释

> 注意:

> `PHP_VERSION` 常量包含了当前 PHP 的版本。

> 注意:

> 注意，类似 5.3.0-dev 的预发行版本，被认为是低于它们的最终发行版本（就像 5.3.0）。

> 注意:

> 指定类似 `alpha`、`beta` 的版本字符串是大小写敏感的。 版本字符串的来源若不遵循 PHP 标准，可能需要在调用 version_compare() 之前先用 strtolower() 转成小写。

### 参见

- phpversion() - 获取当前的PHP版本
- php_uname() - 返回运行 PHP 的系统的有关信息
- function_exists() - 如果给定的函数已经被定义就返回 true

# zend_thread_id

(PHP 5, PHP 7, PHP 8)

zend_thread_id — 返回当前线程的唯一识别符

### 说明

function zend_thread_id(): int

该函数返回当前线程的唯一识别符。

### 参数

此函数没有参数。

### 返回值

以整型（integer）返回线程的 ID。

### 示例

示例 #1 zend_thread_id() 示例

    <?php
    $thread_id = zend_thread_id();

    echo 'Current thread id is: ' . $thread_id;
    ?>

以上示例的输出类似于：

    Current thread id is: 7864

### 注释

> 注意:

> 该函数仅在以下情况有效：PHP 内置 ZTS（Zend 线程安全）的支持， 并开启调试模式（`--enable-debug`）时。

# zend_version

(PHP 4, PHP 5, PHP 7, PHP 8)

zend_version — 获取当前 Zend 引擎的版本

### 说明

function zend_version(): string

获取当前运行的 Zend 引擎的版本字符串。

### 参数

此函数没有参数。

### 返回值

获取 Zend 引擎的版本数字的字符串。

### 示例

示例 #1 zend_version() 示例

    <?php
    echo "Zend engine version: " . zend_version();
    ?>

以上示例的输出类似于：

    Zend engine version: 2.2.0

### 参见

- phpinfo() - 输出关于 PHP 配置的信息
- phpcredits() - 打印 PHP 贡献者名单
- phpversion() - 获取当前的PHP版本

## 目录

- assert — 断言检测
- assert_options — 设置/获取各种断言 flag
- cli_get_process_title — Returns the current process title
- cli_set_process_title — Sets the process title
- dl — 运行时载入一个 PHP 扩展
- extension_loaded — 检查一个扩展是否已经加载
- gc_collect_cycles — 强制收集所有现存的垃圾循环周期
- gc_disable — 停用循环引用收集器
- gc_enable — 激活循环引用收集器
- gc_enabled — 返回循环引用计数器的状态
- gc_mem_caches — Reclaims memory used by the Zend Engine memory manager
- gc_status — 获取有关垃圾回收的信息
- get_cfg_var — 获取 PHP 配置选项的值
- get_current_user — 获取当前 PHP 脚本所有者名称
- get_defined_constants — 返回所有常量的关联数组，键是常量名，值是常量值
- get_extension_funcs — 返回模块函数名称的数组
- get_include_path — 获取当前的 include_path 配置选项
- get_included_files — 返回被 include 和 require 文件名的 array
- get_loaded_extensions — 返回所有编译并加载模块名的 array
- get_magic_quotes_gpc — 获取当前 magic_quotes_gpc 的配置选项设置
- get_magic_quotes_runtime — 获取当前 magic_quotes_runtime 配置选项的激活状态
- get_required_files — 别名 get_included_files
- get_resources — Returns active resources
- getenv — 获取单个或者全部环境变量
- getlastmod — 获取页面最后修改的时间
- getmygid — 获取当前 PHP 脚本拥有者的 GID
- getmyinode — 获取当前脚本的索引节点（inode）
- getmypid — 获取 PHP 进程的 ID
- getmyuid — 获取 PHP 脚本所有者的 UID
- getopt — 从命令行参数列表中获取选项
- getrusage — 获取当前资源使用状况
- ini_alter — 别名 ini_set
- ini_get — 获取一个配置选项的值
- ini_get_all — 获取所有配置选项
- ini_parse_quantity — Get interpreted size from ini shorthand syntax
- ini_restore — 恢复配置选项的值
- ini_set — 为一个配置选项设置值
- memory_get_peak_usage — 返回分配给 PHP 内存的峰值
- memory_get_usage — 返回分配给 PHP 的内存量
- memory_reset_peak_usage — Reset the peak memory usage
- php_ini_loaded_file — 取得已加载的 php.ini 文件的路径
- php_ini_scanned_files — 返回从额外 ini 目录里解析的 .ini 文件列表
- php_sapi_name — 返回 web 服务器和 PHP 之间的接口类型
- php_uname — 返回运行 PHP 的系统的有关信息
- phpcredits — 打印 PHP 贡献者名单
- phpinfo — 输出关于 PHP 配置的信息
- phpversion — 获取当前的PHP版本
- putenv — 设置环境变量的值
- restore_include_path — 还原 include_path 配置选项的值
- set_include_path — 设置 include_path 配置选项
- set_time_limit — 设置脚本最大执行时间
- sys_get_temp_dir — 返回用于临时文件的目录
- version_compare — 对比两个「PHP 规范化」的版本数字字符串
- zend_thread_id — 返回当前线程的唯一识别符
- zend_version — 获取当前 Zend 引擎的版本

- 安装/配置
  - 运行时配置
- 预定义常量
- PHP 选项/信息 函数
  - assert — 断言检测
  - assert_options — 设置/获取各种断言 flag
  - cli_get_process_title — Returns the current process title
  - cli_set_process_title — Sets the process title
  - dl — 运行时载入一个 PHP 扩展
  - extension_loaded — 检查一个扩展是否已经加载
  - gc_collect_cycles — 强制收集所有现存的垃圾循环周期
  - gc_disable — 停用循环引用收集器
  - gc_enable — 激活循环引用收集器
  - gc_enabled — 返回循环引用计数器的状态
  - gc_mem_caches — Reclaims memory used by the Zend Engine memory manager
  - gc_status — 获取有关垃圾回收的信息
  - get_cfg_var — 获取 PHP 配置选项的值
  - get_current_user — 获取当前 PHP 脚本所有者名称
  - get_defined_constants — 返回所有常量的关联数组，键是常量名，值是常量值
  - get_extension_funcs — 返回模块函数名称的数组
  - get_include_path — 获取当前的 include_path 配置选项
  - get_included_files — 返回被 include 和 require 文件名的 array
  - get_loaded_extensions — 返回所有编译并加载模块名的 array
  - get_magic_quotes_gpc — 获取当前 magic_quotes_gpc 的配置选项设置
  - get_magic_quotes_runtime — 获取当前 magic_quotes_runtime 配置选项的激活状态
  - get_required_files — 别名 get_included_files
  - get_resources — Returns active resources
  - getenv — 获取单个或者全部环境变量
  - getlastmod — 获取页面最后修改的时间
  - getmygid — 获取当前 PHP 脚本拥有者的 GID
  - getmyinode — 获取当前脚本的索引节点（inode）
  - getmypid — 获取 PHP 进程的 ID
  - getmyuid — 获取 PHP 脚本所有者的 UID
  - getopt — 从命令行参数列表中获取选项
  - getrusage — 获取当前资源使用状况
  - ini_alter — 别名 ini_set
  - ini_get — 获取一个配置选项的值
  - ini_get_all — 获取所有配置选项
  - ini_parse_quantity — Get interpreted size from ini shorthand syntax
  - ini_restore — 恢复配置选项的值
  - ini_set — 为一个配置选项设置值
  - memory_get_peak_usage — 返回分配给 PHP 内存的峰值
  - memory_get_usage — 返回分配给 PHP 的内存量
  - memory_reset_peak_usage — Reset the peak memory usage
  - php_ini_loaded_file — 取得已加载的 php.ini 文件的路径
  - php_ini_scanned_files — 返回从额外 ini 目录里解析的 .ini 文件列表
  - php_sapi_name — 返回 web 服务器和 PHP 之间的接口类型
  - php_uname — 返回运行 PHP 的系统的有关信息
  - phpcredits — 打印 PHP 贡献者名单
  - phpinfo — 输出关于 PHP 配置的信息
  - phpversion — 获取当前的PHP版本
  - putenv — 设置环境变量的值
  - restore_include_path — 还原 include_path 配置选项的值
  - set_include_path — 设置 include_path 配置选项
  - set_time_limit — 设置脚本最大执行时间
  - sys_get_temp_dir — 返回用于临时文件的目录
  - version_compare — 对比两个「PHP 规范化」的版本数字字符串
  - zend_thread_id — 返回当前线程的唯一识别符
  - zend_version — 获取当前 Zend 引擎的版本

# Interactive PHP Debugger

# 简介

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

# 安装/配置

## 目录

- 运行时配置

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

phpdbg 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
phpdbg.eol | 2 | `INI_ALL` | Removed as of PHP 8.1.0
phpdbg.path |  | 6 | Removed as of PHP 8.1.0

这是配置指令的简短说明。

`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

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`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 函数

# phpdbg_break_file

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_file — Inserts a breakpoint at a line in a file

### 说明

function phpdbg_break_file(string `$file`, int `$line`): void

Insert a breakpoint at the given `line` in the given `file`.

### 参数

`file`
  The name of the file.
`line`
  The line number.

### 返回值

没有返回值。

### 参见

- 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

### 说明

function phpdbg_break_function(string `$function`): void

Insert a breakpoint at the entry to the given `function`.

### 参数

`function`
  The name of the function.

### 返回值

没有返回值。

### 参见

- 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

### 说明

function phpdbg_break_method(string `$class`, string `$method`): void

Insert a breakpoint at the entry to the given `method` of the given `class`.

### 参数

`class`
  The name of the class.
`method`
  The name of the method.

### 返回值

没有返回值。

### 参见

- 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

### 说明

function phpdbg_break_next(): void

Insert a breakpoint at the next opcode.

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 参见

- 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

### 说明

function phpdbg_clear(): void

Clear all breakpoints that have been set, either via one of the phpdbg_break_*() functions or interactively in the console.

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 参见

- 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

### 说明

function phpdbg_color(int `$element`, string `$color`): void

Set the `color` of the given `element`.

### 参数

`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`.

### 返回值

没有返回值。

### 参见

- phpdbg_prompt() - Sets the command prompt

# phpdbg_end_oplog

(PHP 7, PHP 8)

phpdbg_end_oplog — Ends an oplog

### 说明

function phpdbg_end_oplog(array `$options` = []): ?array

警告

本函数还未编写文档，仅有参数列表。

### 参数

`options`

### 返回值

# phpdbg_exec

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_exec — Attempts to set the execution context

### 说明

function phpdbg_exec(string `$context`): string|bool

警告

本函数还未编写文档，仅有参数列表。

### 参数

`context`

### 返回值

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

### 说明

function phpdbg_get_executable(array `$options` = []): array

警告

本函数还未编写文档，仅有参数列表。

### 参数

`options`

### 返回值

# phpdbg_prompt

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_prompt — Sets the command prompt

### 说明

function phpdbg_prompt(string `$string`): void

Set the command prompt to the given `string`.

### 参数

`string`
  The string to use as command prompt.

### 返回值

没有返回值。

### 参见

- phpdbg_color() - Sets the color of certain elements

# phpdbg_start_oplog

(PHP 7, PHP 8)

phpdbg_start_oplog — Starts an oplog

### 说明

function phpdbg_start_oplog(): void

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

没有返回值。

## 目录

- 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 — Starts an oplog

- 安装/配置
  - 运行时配置
- 预定义常量
- phpdbg 函数
  - 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 — Starts an oplog

# runkit7

# 简介

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.

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置

## 需求

Modifying Constants, Functions, Classes, and Methods as well as Custom Superglobals works with all releases of PHP 7. No special requirements are necessary.

## 安装

此 » PECL 扩展未与 PHP 捆绑。

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/runkit7.

此扩展在 Windows 平台的二进制扩展 (DLL 文件) PECL 可以在 PECL 官方网站上下载。

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

Runkit Configuration Options
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
runkit.superglobal | "" | `INI_PERDIR` |
runkit.internal_override | "0" | `INI_SYSTEM` |

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`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.

  示例 #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.

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`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 函数

# runkit7_constant_add

(PECL runkit7 >= Unknown)

runkit7_constant_add — Similar to define(), but allows defining in class definitions as well

### 说明

function runkit7_constant_add(string `$constant_name`, mixed `$value`, int `$newVisibility` = ?): bool

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- define() - 定义一个常量
- 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

### 说明

function runkit7_constant_redefine(string `$constant_name`, mixed `$value`, int `$new_visibility` = ?): bool

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function runkit7_constant_remove(string `$constant_name`): bool

### 参数

`constant_name`
  Name of the constant to remove. Either the name of a global constant, or `classname::constname` indicating a class constant.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- define() - 定义一个常量
- 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()

### 说明

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

### 参数

`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`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

以上示例会输出：

    The value of a is 1
    The value of b is 2

### 参见

- create_function() - 通过执行代码字符串创建动态函数
- 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

### 说明

function runkit7_function_copy(string `$source_name`, string `$target_name`): bool

### 参数

`source_name`
  Name of the existing function
`target_name`
  Name of the new function to copy the definition to

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 A runkit7_function_copy() example

    <?php
    function original() {
      echo "In a function\n";
    }
    runkit7_function_copy('original','duplicate');
    original();
    duplicate();
    ?>

以上示例会输出：

    In a function
    In a function

### 参见

- 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

### 说明

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

> 注意: 默认情况下，仅在用户空间可删除，重命名，或者修改函数。为了覆盖内部函数，必须启用 php.ini 中的 `runkit.internal_override` 设置。

### 参数

`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`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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();
    ?>

以上示例会输出：

    Original Testme Implementation
    New Testme Implementation

### 参见

- 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

### 说明

function runkit7_function_remove(string `$function_name`): bool

> 注意: 默认情况下，仅在用户空间可删除，重命名，或者修改函数。为了覆盖内部函数，必须启用 php.ini 中的 `runkit.internal_override` 设置。

### 参数

`function_name`
  Name of the function to be deleted

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function runkit7_function_rename(string `$source_name`, string `$target_name`): bool

> 注意: 默认情况下，仅在用户空间可删除，重命名，或者修改函数。为了覆盖内部函数，必须启用 php.ini 中的 `runkit.internal_override` 设置。

### 参数

`source_name`
  Current function name
`target_name`
  New function name

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

警告

This feature has been removed in PECL runkit7 4.0.0.

### 说明

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.

### 参数

`filename`
  Filename to import function and class definitions from
`flags`
  Bitwise OR of the `RUNKIT7_IMPORT_*` family of constants.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# runkit7_method_add

(PECL runkit7 >= Unknown)

runkit7_method_add — Dynamically adds a new method to a given class

### 说明

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

### 参数

`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`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

以上示例会输出：

    16

### 参见

- 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

### 说明

function runkit7_method_copy(
string `$destination_class`,
string `$destination_method_name`,
string `$source_class`,
string `$source_method_name` = ?
): bool

### 参数

`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.

### 返回值

### 示例

示例 #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();
    ?>

以上示例会输出：

    foo!

### 参见

- 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

### 说明

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

### 参数

`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`.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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();
    ?>

以上示例会输出：

    Before: foo!
    After: bar!

### 参见

- 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

### 说明

function runkit7_method_remove(string `$class_name`, string `$method_name`): bool

> 注意: 此函数不能用来操作当前正常运行（或运行链上）的方法。

### 参数

`class_name`
  The class in which to remove the method
`method_name`
  The name of the method to remove

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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'));

    ?>

以上示例会输出：

    bar

### 参见

- 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

### 说明

function runkit7_method_rename(string `$class_name`, string `$source_method_name`, string `$target_method_name`): bool

> 注意: 此函数不能用来操作当前正常运行（或运行链上）的方法。

### 参数

`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

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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();
    ?>

以上示例会输出：

    foo!

### 参见

- 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

### 说明

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().

### 参数

`obj`
  Any object.

### 返回值

An integer identifier that is unique for each currently existing object and is always the same for each object.

### 注释

> 注意: When an object is destroyed, its id may be reused for other objects.

### 参见

- 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

### 说明

function runkit7_superglobals(): array

### 参数

此函数没有参数。

### 返回值

Returns a numerically indexed array of the currently registered superglobals. i.e. _GET, _POST, _REQUEST, _COOKIE, _SESSION, _SERVER, _ENV, _FILES

### 参见

- Variable Scope

# runkit7_zval_inspect

(PECL runkit7 >= Unknown)

runkit7_zval_inspect — Returns information about the passed in value with data types, reference counts, etc

### 说明

function runkit7_zval_inspect(string `$value`): array

### 参数

`value`
  The value to return the representation of

### 返回值

The array returned by this function contains the following elements:

- `address`
- `refcount` (optional)
- `is_ref` (optional)
- `type`

### 示例

示例 #1 runkit7_zval_inspect() example

    <?php

    $var = new DateTime();
    var_dump(runkit7_zval_inspect($var));

    $var = 1;
    var_dump(runkit7_zval_inspect($var));
    ?>

以上示例会输出：

    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)
    }

### 参见

- References Explained
- » References Explained (by Derick Rethans)

## 目录

- 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

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
- 预定义常量
- runkit7 函数
  - 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

# 简介

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

> 注意:

> All of the activities supported are compatible with opcache

警告

PECL uopz 6.1.1 is not compatible with Xdebug >= 2.9.4. Later uopz versions are not compatible with Xdebug < 2.9.4.

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置

## 需求

As of uopz 5.0 PHP 7.0 is required. As of uopz 5.1, PHP 7.1+ is required.

## 安装

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.

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

uopz 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
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.

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`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().

> 注意: When running with OPcache enabled, it may be necessary to disable all OPcache optimizations (`opcache.optimization_level=0`).

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

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 函数

# uopz_add_function

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_add_function — Adds non-existent function or method

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

uopz_add_function() throws a RuntimeException if the function or method to add already exists.

### 示例

示例 #1 Basic uopz_add_function() Usage

    <?php
    uopz_add_function('foo', function () {echo 'bar';});
    foo();
    ?>

以上示例会输出：

    bar

### 参见

- 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

### 说明

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.

### 参数

`allow`

  Whether to allow the execution of exit opcodes or not.

### 返回值

没有返回值。

### 示例

示例 #1 uopz_allow_exit() example

    <?php
    exit(1);
    echo 1;
    uopz_allow_exit(true);
    exit(2);
    echo 2;
    ?>

以上示例会输出：

    1

### 注释

警告

OPcache optimizes away dead code after unconditional exit.

### 参见

- 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

警告

This function has been REMOVED in PECL uopz 5.0.0.

### 说明

function uopz_backup(string `$function`): void
function uopz_backup(string `$class`, string `$function`): void

Backup a function at runtime, to be restored on shutdown

### 参数

`class`

  The name of the class containing the function to backup

`function`

  The name of the function

### 返回值

### 示例

示例 #1 uopz_backup() example

    <?php
    uopz_backup("fgets");
    uopz_function("fgets", function(){
        return true;
    });
    var_dump(fgets());
    ?>

以上示例会输出：

    bool(true)

# uopz_compose

(PECL uopz 1, PECL uopz 2)

uopz_compose — Compose a class

警告

This function has been REMOVED in PECL uopz 5.0.0.

### 说明

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

### 参数

`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

### 返回值

### 示例

示例 #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));
    ?>

以上示例会输出：

    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

警告

This function has been REMOVED in PECL uopz 5.0.0.

### 说明

function uopz_copy(string `$function`): Closure
function uopz_copy(string `$class`, string `$function`): Closure

Copy a function by name

### 参数

`class`

  The name of the class containing the function to copy

`function`

  The name of the function

### 返回值

A Closure for the specified function

### 示例

示例 #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'));
    ?>

以上示例会输出：

    string(5) "dummy"

# uopz_del_function

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_del_function — Deletes previously added function or method

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

uopz_del_function() throws a RuntimeException if the function or method to delete has not been added by uopz_add_function().

### 示例

示例 #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'));
    ?>

以上示例会输出：

    bool(true)
    bool(false)

### 参见

- 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

警告

This function has been REMOVED in PECL uopz 5.0.0.

### 说明

function uopz_delete(string `$function`): void
function uopz_delete(string `$class`, string `$function`): void

Deletes a function or method

### 参数

`class`

`function`

### 返回值

### 示例

示例 #1 uopz_delete() example

    <?php
    uopz_delete("strlen");

    echo strlen("Hello World");
    ?>

以上示例的输出类似于：

    PHP Fatal error: Call to undefined function strlen() in /path/to/script.php on line 4

示例 #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");
    ?>

以上示例的输出类似于：

    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

### 说明

function uopz_extend(string `$class`, string `$parent`): bool

Makes `class` extend `parent`

### 参数

`class`

  The name of the class to extend

`parent`

  The name of the class to inherit

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 示例

示例 #1 uopz_extend() example

    <?php
    class A {}
    class B {}

    uopz_extend(A::class, B::class);

    var_dump(class_parents(A::class));
    ?>

以上示例会输出：

    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

### 说明

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

### 参数

`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.

### 返回值

If setting, returns old flags, else returns flags

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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));
    ?>

以上示例会输出：

    bool(false)
    bool(false)
    int(1234567890)
    bool(true)
    bool(true)

示例 #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());
    ?>

以上示例会输出：

    bool(false)

# uopz_function

(PECL uopz 1, PECL uopz 2)

uopz_function — Creates a function at runtime

警告

This function has been REMOVED in PECL uopz 5.0.0.

### 说明

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

### 参数

`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

### 返回值

### 示例

示例 #1 uopz_function() example

    <?php
    uopz_function("my_strlen", function($arg) {
        return strlen($arg);
    });
    echo my_strlen("Hello World");
    ?>

以上示例会输出：

    11

示例 #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");
    ?>

以上示例会输出：

    11

# uopz_get_exit_status

(PECL uopz 5, PECL uopz , PECL uopz 7)

uopz_get_exit_status — Retrieve the last set exit status

### 说明

function uopz_get_exit_status(): mixed

Retrieves the last set exit status, i.e. the value passed to exit().

### 参数

此函数没有参数。

### 返回值

This function returns the last exit status, or `null` if exit() has not been called.

### 示例

示例 #1 uopz_get_exit_status() example

    <?php
    exit(123);
    echo uopz_get_exit_status();?>

以上示例会输出：

    123

### 注释

警告

OPcache optimizes away dead code after unconditional exit.

### 参见

- 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

### 说明

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.

### 参数

`class`

  The name of the class.

`function`

  The name of the function or method.

### 返回值

Returns the previously set hook on a function or method, or `null` if no hook has been set.

### 示例

示例 #1 Basic uopz_get_hook() Usage

    <?php
    function foo() {
        echo 'foo';
    }
    uopz_set_hook('foo', function () {echo 'bar';});
    var_dump(uopz_get_hook('foo'));
    ?>

以上示例的输出类似于：

    object(Closure)#2 (0) {
    }

### 参见

- 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

### 说明

function uopz_get_mock(string `$class`): mixed

Returns the current mock for `class`.

### 参数

`class`

  The name of the mocked class.

### 返回值

Either a string containing the name of the mock, or an object, or `null` if no mock has been set.

### 示例

示例 #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);
    ?>

以上示例会输出：

    mockA

### 参见

- 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

### 说明

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.

### 参数

`class`

  The name of the class.

`instance`

  The object instance.

`property`

  The name of the property.

### 返回值

Returns the value of the class or instance property, or `null` if the property is not defined.

### 示例

示例 #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'));
    ?>

以上示例的输出类似于：

    int(10)
    int(100)

### 参见

- 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

### 说明

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().

### 参数

`class`

  The name of the class containing the function

`function`

  The name of the function

### 返回值

The return value or Closure previously set.

### 示例

示例 #1 uopz_get_return() example

    <?php
    uopz_set_return("strlen", 42);
    echo uopz_get_return("strlen");
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`class`

  The name of the class.

`function`

  The name of the function or method.

### 返回值

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.

### 示例

示例 #1 Basic uopz_get_static() Usage

    <?php
    function foo() {
        static $bar = 'baz';
    }
    var_dump(uopz_get_static('foo'));
    ?>

以上示例会输出：

    array(1) {
      ["bar"]=>
      string(3) "baz"
    }

### 参见

- ReflectionFunctionAbstract::getStaticVariables() - 获取静态变量
- 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

### 说明

function uopz_implement(string `$class`, string `$interface`): bool

Makes `class` implement `interface`

### 参数

`class`

`interface`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

As of PHP 7.4.0, uopz_implement() throws a RuntimeException, if OPcache is enabled, and the class entry of `class` is immutable.

### 示例

示例 #1 uopz_implement() example

    <?php
    interface myInterface {}

    class myClass {}

    uopz_implement(myClass::class, myInterface::class);

    var_dump(class_implements(myClass::class));
    ?>

以上示例会输出：

    array(1) {
      ["myInterface"]=>
      string(11) "myInterface"
    }

# uopz_overload

(PECL uopz 1, PECL uopz 2)

uopz_overload — Overload a VM opcode

警告

This function has been REMOVED in PECL uopz 5.0.0.

### 说明

function uopz_overload(int `$opcode`, Callable `$callable`): void

Overloads the specified `opcode` with the user defined function

### 参数

`opcode`

  A valid opcode, see constants for details of supported codes

`callable`

### 返回值

### 示例

示例 #1 uopz_overload() example

    <?php
    uopz_overload(ZEND_EXIT, function(){});

    exit();
    echo "Hello World";
    ?>

以上示例会输出：

    Hello World

# uopz_redefine

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_redefine — Redefine a constant

### 说明

function uopz_redefine(string `$constant`, mixed `$value`): bool
function uopz_redefine(string `$class`, string `$constant`, mixed `$value`): bool

Redefines the given `constant` as `value`

### 参数

`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

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 uopz_redefine() example

    <?php
    define("MY", 100);

    uopz_redefine("MY", 1000);

    echo MY;
    ?>

以上示例会输出：

    1000

# uopz_rename

(PECL uopz 1, PECL uopz 2)

uopz_rename — Rename a function at runtime

警告

This function has been REMOVED in PECL uopz 5.0.0.

### 说明

function uopz_rename(string `$function`, string `$rename`): void
function uopz_rename(string `$class`, string `$function`, string `$rename`): void

Renames `function` to `rename`

> 注意:

> If both functions exist, this effectively swaps their names

### 参数

`class`

  The name of the class containing the function

`function`

  The name of an existing function

`rename`

  The new name for the function

### 返回值

### 示例

示例 #1 uopz_rename() example

    <?php
    uopz_rename("strlen", "original_strlen");

    echo original_strlen("Hello World");
    ?>

以上示例会输出：

    11

示例 #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");
    ?>

以上示例会输出：

    11

# uopz_restore

(PECL uopz 1 >= 1.0.3, PECL uopz 2)

uopz_restore — Restore a previously backed up function

警告

This function has been REMOVED in PECL uopz 5.0.0.

### 说明

function uopz_restore(string `$function`): void
function uopz_restore(string `$class`, string `$function`): void

Restore a previously backed up function

### 参数

`class`

  The name of the class containing the function to restore

`function`

  The name of the function

### 返回值

### 示例

示例 #1 uopz_restore() example

    <?php
    uopz_backup("fgets");
    uopz_function("fgets", function(){
        return true;
    });
    var_dump(fgets());
    uopz_restore('fgets');
    fgets();
    ?>

以上示例的输出类似于：

    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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Basic uopz_set_hook() Usage

    <?php
    function foo() {
        echo 'foo';
    }
    uopz_set_hook('foo', function () {echo 'bar';});
    foo();
    ?>

以上示例会输出：

    barfoo

### 参见

- 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

### 说明

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.

> 注意:

> Only dynamic access to properties and methods will use the `mock` object. Static access still uses the original `class`. See example below.

### 参数

`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.

### 返回值

没有返回值。

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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();
    ?>

以上示例会输出：

    mockA

示例 #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();
    ?>

以上示例会输出：

    mockA

示例 #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();
    ?>

以上示例会输出：

    A
    A

Output of the above example in uopz 5:

    mockA
    mockA

### 参见

- 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

### 说明

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.

### 参数

`class`

  The name of the class.

`instance`

  The object instance.

`property`

  The name of the property.

`value`

  The value to assign to the property.

### 返回值

没有返回值。

### 示例

示例 #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());
    ?>

以上示例会输出：

    int(10)

### 参见

- 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

### 说明

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.

> 注意:

> This function replaces uopz_rename().

### 参数

`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.

### 返回值

True if succeeded, false otherwise.

### 示例

示例 #1 uopz_set_return() example

    <?php
    uopz_set_return("strlen", 42);
    echo strlen("Banana");
    ?>

以上示例会输出：

    42

示例 #2 uopz_set_return() example

    <?php
    uopz_set_return("strlen", function($str) { return strlen($str) * 2; }, true );
    echo strlen("Banana");
    ?>

以上示例会输出：

    12

示例 #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");
    ?>

以上示例会输出：

    12

# uopz_set_static

(PECL uopz 5, PECL uopz , PECL uopz 7)

uopz_set_static — Sets the static variables in function or method scope

### 说明

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.

### 参数

`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.

### 返回值

没有返回值。

### 示例

示例 #1 Basic uopz_set_static() Usage

    <?php
    function foo() {
        static $bar = 'baz';
        var_dump($bar);
    }
    uopz_set_static('foo', ['bar' => 'qux']);
    foo();
    ?>

以上示例会输出：

    string(3) "qux"

### 参见

- 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

### 说明

function uopz_undefine(string `$constant`): bool
function uopz_undefine(string `$class`, string `$constant`): bool

Removes the constant at runtime

### 参数

`class`

  The name of the class containing `constant`

`constant`

  The name of an existing constant

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 uopz_undefine() example

    <?php
    define("MY", true);

    uopz_undefine("MY");

    var_dump(defined("MY"));
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`class`

  The name of the class.

`function`

  The name of the function or method.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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();
    ?>

以上示例会输出：

    barfoo
    foo

### 参见

- 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

### 说明

function uopz_unset_mock(string `$class`): void

Unsets the previously set mock for `class`.

### 参数

`class`

  The name of the mocked class.

### 返回值

没有返回值。

### 错误／异常

A RuntimeException is thrown, if no mock was previously set for `class`.

### 示例

示例 #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();
    ?>

以上示例会输出：

    A

### 参见

- 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

### 说明

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().

### 参数

`class`

  The name of the class containing the function

`function`

  The name of the function

### 返回值

True on success

### 示例

示例 #1 uopz_unset_return() example

    <?php
    uopz_set_return("strlen", 42);
    $len = strlen("Banana");
    uopz_unset_return("strlen");
    echo $len + strlen("Banana");
    ?>

以上示例会输出：

    48

## 目录

- 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

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
- 预定义常量
- Uopz 函数
  - 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

# 简介

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.

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置
- WinCache Statistics Script
- WinCache Session Handler
- WinCache Functions Reroutes

## 需求

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

> 注意: The WinCache Extension can only be used when IIS is configured to run PHP via FastCGI.

## 安装

此 » PECL 扩展未与 PHP 捆绑。

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » 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.

> 注意: Do not forget to remove phpinfo.php file from the web site's root folder after verifying that extension has been enabled.

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

The following table lists and explains the configuration settings provided by the WinCache extension:

WinCache configuration options
名字 | 默认 | Minimum | Maximum | 可修改范围 | 更新日志
--- | --- | --- | --- | --- | ---
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

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`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
  警告

  This option has been REMOVED as of 2.0.0.0

  Enables or disables the opcode cache functionality
`wincache.ocenabledfilter` string
  警告

  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
  警告

  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 - "|".

  示例 #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
  警告

  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
  警告

  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:

示例 #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 ========================== */
    ?>

> 注意: 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.

示例 #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.

示例 #1 Enabling WinCache functions reroutes

    wincache.rerouteini = C:\PHP\reroute.ini

> 注意: 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.

示例 #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 函数

# wincache_fcache_fileinfo

(PECL wincache >= 1.0.0)

wincache_fcache_fileinfo — Retrieves information about files cached in the file cache

### 说明

function wincache_fcache_fileinfo(bool `$summaryonly` = `false`): array|false

Retrieves information about file cache content and its usage.

### 参数

`summaryonly`

  Controls whether the returned array will contain information about individual cache entries along with the file cache summary.

### 返回值

Array of meta data about file cache 或者在失败时返回 `false`

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

### 示例

示例 #1 A wincache_fcache_fileinfo() example

    <pre>
    <?php
    print_r(wincache_fcache_fileinfo());
    ?>
    </pre>

以上示例会输出：

    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)
            )
    )

### 参见

- 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

### 说明

function wincache_fcache_meminfo(): array|false

Retrieves information about memory usage by file cache.

### 参数

此函数没有参数。

### 返回值

Array of meta data about file cache memory usage 或者在失败时返回 `false`

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

### 示例

示例 #1 A wincache_fcache_meminfo() example

    <pre>
    <?php
    print_r(wincache_fcache_meminfo());
    ?>
    </pre>

以上示例会输出：

    Array
    (
        [memory_total] => 134217728
        [memory_free] => 131339120
        [num_used_blks] => 361
        [num_free_blks] => 3
        [memory_overhead] => 5856
    )

### 参见

- 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

### 说明

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().

警告

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

### 参见

- 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

### 说明

function wincache_ocache_fileinfo(bool `$summaryonly` = `false`): array|false

Retrieves information about opcode cache content and its usage.

警告

该函数已在 PHP 7.0.0 中 移除。

### 参数

`summaryonly`

  Controls whether the returned array will contain information about individual cache entries along with the opcode cache summary.

### 返回值

Array of meta data about opcode cache 或者在失败时返回 `false`

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

### 示例

示例 #1 A wincache_ocache_fileinfo() example

    <pre>
    <?php
    print_r(wincache_ocache_fileinfo());
    ?>
    </pre>

以上示例会输出：

    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)
            )
    )

### 参见

- 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

### 说明

function wincache_ocache_meminfo(): array|false

Retrieves information about memory usage by opcode cache.

### 参数

此函数没有参数。

### 返回值

Array of meta data about opcode cache memory usage 或者在失败时返回 `false`

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

警告

该函数已在 PHP 7.0.0 中 移除。

### 示例

示例 #1 A wincache_ocache_meminfo() example

    <pre>
    <?php
    print_r(wincache_ocache_meminfo());
    ?>
    </pre>

以上示例会输出：

    Array
    (
        [memory_total] => 134217728
        [memory_free] => 112106972
        [num_used_blks] => 15469
        [num_free_blks] => 4
        [memory_overhead] => 247600
    )

### 参见

- 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

### 说明

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.

### 参数

`files`

  An array of file names for files that need to be refreshed. An absolute or relative file paths can be used.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

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.

示例 #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));
    ?>

### 参见

- 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

### 说明

function wincache_rplist_fileinfo(bool `$summaryonly` = `false`): array|false

Retrieves information about cached mappings between relative file paths and corresponding absolute file paths.

### 参数

`summaryonly`

### 返回值

Array of meta data about the resolve file path cache 或者在失败时返回 `false`

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

### 示例

示例 #1 A wincache_rplist_fileinfo() example

    <pre>
    <?php
    print_r(wincache_rplist_fileinfo());
    ?>
    </pre>

以上示例会输出：

    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)
            )
    )

### 参见

- 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

### 说明

function wincache_rplist_meminfo(): array|false

Retrieves information about memory usage by resolve file path cache.

### 参数

此函数没有参数。

### 返回值

Array of meta data that describes memory usage by resolve file path cache. 或者在失败时返回 `false`

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

### 示例

示例 #1 A wincache_rplist_meminfo() example

    <pre>
    <?php
    print_r(wincache_rplist_meminfo());
    ?>
    </pre>

以上示例会输出：

    Array
    (
        [memory_total] => 9437184
        [memory_free] => 9416744
        [num_used_blks] => 23
        [num_free_blks] => 1
        [memory_overhead] => 416
    )

### 参见

- 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

### 说明

function wincache_scache_info(bool `$summaryonly` = `false`): array|false

Retrieves information about session cache content and its usage.

### 参数

`summaryonly`

  Controls whether the returned array will contain information about individual cache entries along with the session cache summary.

### 返回值

Array of meta data about session cache 或者在失败时返回 `false`

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

### 示例

示例 #1 A wincache_scache_info() example

    <pre>
    <?php
    print_r(wincache_scache_info());
    ?>
    </pre>

以上示例会输出：

    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)
            )
    )

### 参见

- 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

### 说明

function wincache_scache_meminfo(): array|false

Retrieves information about memory usage by session cache.

### 参数

此函数没有参数。

### 返回值

Array of meta data about session cache memory usage 或者在失败时返回 `false`

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

### 示例

示例 #1 A wincache_scache_meminfo() example

    <pre>
    <?php
    print_r(wincache_scache_meminfo());
    ?>
    </pre>

以上示例会输出：

    Array
    (
        [memory_total] => 5242880
        [memory_free] => 5215056
        [num_used_blks] => 6
        [num_free_blks] => 3
        [memory_overhead] => 176
    )

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 示例

示例 #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'));
    ?>

以上示例会输出：

    bool(true)
    bool(false)
    string(3) "BAR"

示例 #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'));
    ?>

以上示例会输出：

    array(0) { }
    array(4) {
      ["green"]=> int(-1)
      ["Blue"]=> int(-1)
      ["yellow"]=> int(-1)
      ["cyan"]=> int(-1)
    }
    string(1) "6"

### 参见

- 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

### 说明

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.

### 参数

`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`.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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'));
    ?>

以上示例会输出：

    bool(true)
    int(1)

### 参见

- 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

### 说明

function wincache_ucache_clear(): bool

Clears/deletes all the values stored in the user cache.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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));
    ?>

以上示例会输出：

    array(5) { ["green"]=> int(1)
               ["red"]=> int(2)
               ["orange"]=> int(4)
               ["blue"]=> int(8)
               ["cyan"]=> int(16) }
    bool(true)
    bool(false)

### 参见

- 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

### 说明

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`.

### 参数

`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.

### 返回值

Returns the decremented value on success and `false` on failure.

### 示例

示例 #1 Using wincache_ucache_dec()

    <?php
    wincache_ucache_set('counter', 1);
    var_dump(wincache_ucache_dec('counter', 2923, $success));
    var_dump($success);
    ?>

以上示例会输出：

    int(2922)
    bool(true)

### 参见

- 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

### 说明

function wincache_ucache_delete(mixed `$key`): bool

Deletes the elements in the user cache pointed by `key`.

### 参数

`key`

  The `key` that was used to store the variable in the cache. `key` is case sensitive. `key` can be an array of keys.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

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.

### 示例

示例 #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'));
    ?>

以上示例会输出：

    bool(true)
    bool(false)

示例 #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));
    ?>

以上示例会输出：

    array(4) { [0]=> string(5) "green"
               [1]=> string(4) "blue"
               [2]=> string(6) "yellow"
               [3]=> string(4) "cyan" }

示例 #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));
    ?>

以上示例会输出：

    array(2) { [0]=> string(6) "yellow"
               [1]=> string(4) "cyan" }

### 参见

- 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

### 说明

function wincache_ucache_exists(string `$key`): bool

Checks if a variable with the `key` exists in the user cache or not.

### 参数

`key`

  The `key` that was used to store the variable in the cache. `key` is case sensitive.

### 返回值

Returns `true` if variable with the `key` exitsts, otherwise returns `false`.

### 示例

示例 #1 Using wincache_ucache_exists()

    <?php
    if (!wincache_ucache_exists('green'))
        wincache_ucache_set('green', 1);
    var_dump(wincache_ucache_exists('green'));
    ?>

以上示例会输出：

    bool(true)

### 参见

- 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

### 说明

function wincache_ucache_get(mixed `$key`, bool `&$success` = ?): mixed

Gets a variable stored in the user cache.

### 参数

`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.

### 返回值

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.

### 示例

示例 #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);
    ?>

以上示例会输出：

    string(4) "blue"
    bool(true)

示例 #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);
    ?>

以上示例会输出：

    array(4) { ["green"]=> string(1) "5"
               ["Blue"]=> string(1) "6"
               ["yellow"]=> string(1) "7"
               ["cyan"]=> string(1) "8" }
    bool(true)

### 参见

- 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

### 说明

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`.

### 参数

`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.

### 返回值

Returns the incremented value on success and `false` on failure.

### 示例

示例 #1 Using wincache_ucache_inc()

    <?php
    wincache_ucache_set('counter', 1);
    var_dump(wincache_ucache_inc('counter', 2921, $success));
    var_dump($success);
    ?>

以上示例会输出：

    int(2922)
    bool(true)

### 参见

- 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

### 说明

function wincache_ucache_info(bool `$summaryonly` = `false`, string `$key` = NULL): array|false

Retrieves information about data stored in the user cache.

### 参数

`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.

### 返回值

Array of meta data about user cache 或者在失败时返回 `false`

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

### 示例

示例 #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());
    ?>

以上示例会输出：

    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)
           )
        )
    )

### 参见

- 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

### 说明

function wincache_ucache_meminfo(): array|false

Retrieves information about memory usage by user cache.

### 参数

此函数没有参数。

### 返回值

Array of meta data about user cache memory usage 或者在失败时返回 `false`

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

### 示例

示例 #1 A wincache_ucache_meminfo() example

    <pre>
    <?php
    print_r(wincache_ucache_meminfo());
    ?>
    </pre>

以上示例会输出：

    Array
    (
        [memory_total] => 5242880
        [memory_free] => 5215056
        [num_used_blks] => 6
        [num_free_blks] => 3
        [memory_overhead] => 176
    )

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 示例

示例 #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'));
    ?>

以上示例会输出：

    bool(true)
    string(3) "BAR"
    bool(true)
    string(3) "BAR1"

示例 #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'));
    ?>

以上示例会输出：

    array(0) {}
    array(0) {}
    string(1) "6"

### 参见

- 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

### 说明

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.

警告

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.

### 参数

`key`

  Name of the key in the cache to release the lock on.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

### 参见

- 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

## 目录

- 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

## 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.

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
  - WinCache Statistics Script
  - WinCache Session Handler
  - WinCache Functions Reroutes
- WinCache 函数
  - 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

# 层次式性能分析器

# 简介

XHProf 是一个轻量级的分层性能测量分析器。 在数据收集阶段，它跟踪调用次数与测量数据，展示程序动态调用的弧线图。 它在报告、后期处理阶段计算了独占的性能度量，例如运行经过的时间、CPU 计算时间和内存开销。 函数性能报告可以由调用者和被调用者终止。 在数据搜集阶段 XHProf 通过调用图的循环来检测递归函数，通过赋予唯一的深度名称来避免递归调用的循环。

XHProf 包含了一个基于 HTML 的简单用户界面(由 PHP 写成)。 基于浏览器的用户界面使得浏览、分享性能数据结果更加简单方便。 同时也支持查看调用图。

XHProf 的报告对理解代码执行结构常常很有帮助。 比如此分层报告可用于确定在哪个调用链里调用了某个函数。

XHProf 对两次运行进行比较（又名 "diff" 报告），或者多次运行数据的合计。 对比、合并报告，很像针对单次运行的“平式视图”性能报告，就像“分层式视图”的性能报告。

更多额外文档可以在 » facebook xhprof 上找到。

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置

## 需求

虽然不是必需的，xhprof 包含了一个用 PHP 写的用户界面。 它是一个用来保存分析后的数据、并用浏览器显示的实用办法。 因此一个启用了 PHP 的 web 服务器将使人更能体验到 xhprof 的用处。

在 » http://github.com/preinheimer/xhprof 也有一个 GUI 的分支。

## 安装

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/xhprof

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

Xhprof 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
xhprof.output_dir | "" | `INI_ALL` |

这是配置指令的简短说明。

`xhprof.output_dir` string

  储存 XHProf 运行数据的默认目录，用于接口 iXHProfRuns(即 XHProfRuns_Default 类)。

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`XHPROF_FLAGS_NO_BUILTINS` (int)
  使得跳过所有内置（内部）函数。
`XHPROF_FLAGS_CPU` (int)
  使输出的性能数据中添加 CPU 数据。
`XHPROF_FLAGS_MEMORY` (int)
  使输出的性能数据中添加内存数据。

# 示例

示例 #1 Xhprof 范例，可选使用图形界面

本示例启动并结束性能分析器，然后使用捆绑的用户界面来保存和解析结果。 换言之，扩展的代码在调用 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";

    ?>

以上示例的输出类似于：

    http://localhost/xhprof/xhprof_html/index.php?run=t11_4bdf44d21121f&source=xhprof_testing

# Xhprof 函数

# xhprof_disable

(PECL xhprof >= 0.9.0)

xhprof_disable — 停止 xhprof 分析器

### 说明

function xhprof_disable(): ?array

停止性能分析，并返回此次运行的 xhprof 数据。

### 参数

此函数没有参数。

### 返回值

本次运行的 array 类型的 xhprof 数据。如果未启用分析，则返回 `null`。

### 示例

示例 #1 xhprof_disable() 示例

    <?php
    xhprof_enable();

    $foo = strlen("foo bar");

    $xhprof_data = xhprof_disable();

    print_r($xhprof_data);
    ?>

以上示例的输出类似于：

    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 — 启动 xhprof 性能分析器

### 说明

function xhprof_enable(int `$flags` = 0, array `$options` = ?): void

启动 xhprof 进行性能分析。

### 参数

`flags`

  分析添加额外信息的可选标记。 关于此标记的更多信息参见 XHprof 常量，例如， `XHPROF_FLAGS_MEMORY` 可以开启内存的分析。

`options`

  array 的可选选项，就是通过传递 'ignored_functions' 选项来忽略性能分析中的某些函数。

### 返回值

`null`

### 更新日志

版本 | 说明
--- | ---
PECL xhprof 0.9.2 | 添加可选的 `options` 参数。

### 示例

示例 #1 xhprof_enable() 示例

    <?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')));
    ?>

### 参见

- xhprof_disable() - 停止 xhprof 分析器
- xhprof_sample_enable() - 以采样模式启动 XHProf 性能分析
- memory_get_usage() - 返回分配给 PHP 的内存量
- getrusage() - 获取当前资源使用状况

# xhprof_sample_disable

(PECL xhprof >= 0.9.0)

xhprof_sample_disable — 停止 xhprof 性能采样分析器

### 说明

function xhprof_sample_disable(): ?array

停止采样模式的 xhprof 分析器，并返回分析信息。

### 参数

此函数没有参数。

### 返回值

本次运行的xhprof采样数据，array 类型。如果未启用分析，则返回 `null`。

### 示例

示例 #1 xhprof_sample_disable() 示例

    <?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);
    ?>

以上示例的输出类似于：

    Array
    (
        [1272935300.800000] => main()
        [1272935300.900000] => main()
    )

# xhprof_sample_enable

(PECL xhprof >= 0.9.0)

xhprof_sample_enable — 以采样模式启动 XHProf 性能分析

### 说明

function xhprof_sample_enable(): void

xhprof_enable() 的更轻量的版本，以采样模式开始性能分析。 抽样的间隔为 0.1 秒，样本记录了完整的函数调用堆栈。 主要使用的情况是以较低的性能开销来进行性能监控和诊断。

### 参数

此函数没有参数。

### 返回值

`null`

### 参见

- xhprof_sample_disable() - 停止 xhprof 性能采样分析器
- xhprof_enable() - 启动 xhprof 性能分析器
- memory_get_usage() - 返回分配给 PHP 的内存量
- getrusage() - 获取当前资源使用状况

## 目录

- xhprof_disable — 停止 xhprof 分析器
- xhprof_enable — 启动 xhprof 性能分析器
- xhprof_sample_disable — 停止 xhprof 性能采样分析器
- xhprof_sample_enable — 以采样模式启动 XHProf 性能分析

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
- 预定义常量
- 示例
- Xhprof 函数
  - xhprof_disable — 停止 xhprof 分析器
  - xhprof_enable — 启动 xhprof 性能分析器
  - xhprof_sample_disable — 停止 xhprof 性能采样分析器
  - xhprof_sample_enable — 以采样模式启动 XHProf 性能分析

# Yac

# 简介

Yac (Yet Another cache), is a lock-free, shared memory user data cache, could be used to replace APC, local memcache.

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置
- 资源类型

## 需求

## 安装

此 » PECL 扩展未与 PHP 捆绑。

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/yac.

此扩展在 Windows 平台的二进制扩展 (DLL 文件) PECL 可以在 PECL 官方网站上下载。

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

Yac 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
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` |

这是配置指令的简短说明。

`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

## 资源类型

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`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)

## 简介

## 类摘要

class Yac {
/* 属性 */
protected $_prefix;
/* 方法 */
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
}

## 属性

_prefix

# Yac::add

(PECL yac >= 1.0.0)

Yac::add — Store into cache

### 说明

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.

### 参数

`keys`

  string key

`value`

  mixed value, All php value type could be stored except resource

`ttl`

  expire time

### 返回值

bool, `true` on success, `false` on failure

> 注意:

> 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:

> 示例 #1 Make sure the item is stored

>     while(!$yac->set("key", "value"));

# Yac::__construct

(PECL yac >= 1.0.0)

Yac::__construct — Constructor

### 说明

public function Yac::__construct(string `$prefix` = "")

prefix is used to prepended to keys, this could be used to avoiding conflicts between apps.

### 参数

`prefix`

  string prefix

### 错误／异常

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

### 说明

public function Yac::delete(string|array `$keys`, int `$ttl` = ?): bool

remove items from cache

### 参数

`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.

### 返回值

# Yac::dump

(PECL yac >= 1.0.0)

Yac::dump — Dump cache

### 说明

public function Yac::dump(int `$$num`): mixed

Dump values stored in cache

### 参数

`num`

  Maximum number of items should be returned

### 返回值

mixed

# Yac::flush

(PECL yac >= 1.0.0)

Yac::flush — Flush the cache

### 说明

public function Yac::flush(): bool

Remove all cached values

### 参数

此函数没有参数。

### 返回值

bool, always true

# Yac::get

(PECL yac >= 1.0.0)

Yac::get — Retrieve values from cache

### 说明

public function Yac::get(string|array `$key`, int `&$cas` = `null`): mixed

Retrieve values from cache

### 参数

`key`

  string keys, or array of multiple keys.

`cas`

  if not `null`, it will be set to the retrieved item's cas.

### 返回值

mixed on success, false on failure

# Yac::__get

(PECL yac >= 1.0.0)

Yac::__get — Getter

### 说明

public function Yac::__get(string `$key`): mixed

Retrieve values from cache

### 参数

`key`

  string key

### 返回值

mixed on success, `null` on failure

# Yac::info

(PECL yac >= 1.0.0)

Yac::info — Status of cache

### 说明

public function Yac::info(): array

Get status of cache system

### 参数

此函数没有参数。

### 返回值

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

### 说明

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.

### 参数

`keys`

  string key

`value`

  mixed value, All php value type could be stored except resource

`ttl`

  expire time

### 返回值

the value self

# Yac::__set

(PECL yac >= 1.0.0)

Yac::__set — Setter

### 说明

public function Yac::__set(string `$keys`, mixed `$value`): mixed

store a item into cache

### 参数

`keys`

  string key

`value`

  mixed value, All php value type could be stored except resource

### 返回值

Always return the value self

## 目录

- 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

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
  - 资源类型
- 预定义常量
- 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 用户缓存
  - 安装/配置
  - 预定义常量
  - APCu 函数
  - APCUIterator — APCUIterator 类
- Componere
  - 安装/配置
  - 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 函数
- 错误处理 — 错误处理和日志记录
  - 安装/配置
  - 预定义常量
  - 示例
  - 错误处理 函数
- FFI — 外部函数接口
  - 安装/配置
  - 示例
  - FFI — C 代码和数据的主接口
  - FFI\CData — C Data Handles
  - FFI\CType — C Type Handles
  - FFI\Exception — FFI Exceptions
  - FFI\ParserException — FFI Parser Exceptions
- OPcache
  - 安装/配置
  - 预加载
  - OPcache 函数
- 输出控制 — 输出缓冲控制
  - 安装/配置
  - 预定义常量
  - 输出缓冲
  - 冲刷系统缓冲区
  - 用户级输出缓冲区
  - 示例
  - 输出控制 函数
- PHP 选项/信息 — PHP 选项和信息
  - 安装/配置
  - 预定义常量
  - PHP 选项/信息 函数
- phpdbg — Interactive PHP Debugger
  - 安装/配置
  - 预定义常量
  - phpdbg 函数
- runkit7
  - 安装/配置
  - 预定义常量
  - runkit7 函数
- uopz — User Operations for Zend
  - 安装/配置
  - 预定义常量
  - Uopz 函数
- WinCache — Windows Cache for PHP
  - 安装/配置
  - WinCache 函数
  - Building for Windows
- Xhprof — 层次式性能分析器
  - 安装/配置
  - 预定义常量
  - 示例
  - Xhprof 函数
- Yac
  - 安装/配置
  - 预定义常量
  - Yac — The Yac class

# 音频格式操作

# OpenAL Audio Bindings

# 简介

Platform independent audio bindings. Requires the » OpenAL library.

# 安装/配置

## 目录

- 安装
- 资源类型

## 安装

此 » PECL 扩展未与 PHP 捆绑。

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/openal.

PECL 扩展的 DLL 当前不可用。参见 在 Windows 上构建章节。

## 资源类型

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().

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`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 函数

# openal_buffer_create

(PECL openal >= 0.1.0)

openal_buffer_create — Generate OpenAL buffer

### 说明

function openal_buffer_create(): resource

### 参数

此函数没有参数。

### 返回值

Returns an Open AL(Buffer) resource on success or `false` on failure.

### 参见

- 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

### 说明

function openal_buffer_data(
resource `$buffer`,
int `$format`,
string `$data`,
int `$freq`
): bool

### 参数

`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`和 `AL_FORMAT_STEREO16`
`data`
  Block of binary audio data in the `format` and `freq` specified.
`freq`
  Frequency of `data` given in Hz.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function openal_buffer_destroy(resource `$buffer`): bool

### 参数

`buffer`
  An Open AL(Buffer) resource (previously created by openal_buffer_create()).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- openal_buffer_create() - Generate OpenAL buffer

# openal_buffer_get

(PECL openal >= 0.1.0)

openal_buffer_get — Retrieve an OpenAL buffer property

### 说明

function openal_buffer_get(resource `$buffer`, int `$property`): int|false

### 参数

`buffer`
  An Open AL(Buffer) resource (previously created by openal_buffer_create()).
`property`
  Specific property, one of: `AL_FREQUENCY`, `AL_BITS`, `AL_CHANNELS`和 `AL_SIZE`.

### 返回值

Returns an integer value appropriate to the `property` requested 或者在失败时返回 `false`.

### 参见

- openal_buffer_create() - Generate OpenAL buffer

# openal_buffer_loadwav

(PECL openal >= 0.1.0)

openal_buffer_loadwav — Load a .wav file into a buffer

### 说明

function openal_buffer_loadwav(resource `$buffer`, string `$wavfile`): bool

### 参数

`buffer`
  An Open AL(Buffer) resource (previously created by openal_buffer_create()).
`wavfile`
  Path to .wav file on local file system.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function openal_context_create(resource `$device`): resource

### 参数

`device`
  An Open AL(Device) resource (previously created by openal_device_open()).

### 返回值

Returns an Open AL(Context) resource on success or `false` on failure.

### 参见

- 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

### 说明

function openal_context_current(resource `$context`): bool

### 参数

`context`
  An Open AL(Context) resource (previously created by openal_context_create()).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- openal_context_create() - Create an audio processing context

# openal_context_destroy

(PECL openal >= 0.1.0)

openal_context_destroy — Destroys a context

### 说明

function openal_context_destroy(resource `$context`): bool

### 参数

`context`
  An Open AL(Context) resource (previously created by openal_context_create()).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- openal_context_create() - Create an audio processing context

# openal_context_process

(PECL openal >= 0.1.0)

openal_context_process — Process the specified context

### 说明

function openal_context_process(resource `$context`): bool

### 参数

`context`
  An Open AL(Context) resource (previously created by openal_context_create()).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function openal_context_suspend(resource `$context`): bool

### 参数

`context`
  An Open AL(Context) resource (previously created by openal_context_create()).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function openal_device_close(resource `$device`): bool

### 参数

`device`
  An Open AL(Device) resource (previously created by openal_device_open()) to be closed.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- openal_device_open() - Initialize the OpenAL audio layer

# openal_device_open

(PECL openal >= 0.1.0)

openal_device_open — Initialize the OpenAL audio layer

### 说明

function openal_device_open(string `$device_desc` = ?): resource

### 参数

`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.

### 返回值

Returns an Open AL(Device) resource on success or `false` on failure.

### 参见

- 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

### 说明

function openal_listener_get(int `$property`): mixed

### 参数

`property`
  Property to retrieve, one of: `AL_GAIN` (float), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float))和 `AL_ORIENTATION` (array(float,float,float)).

### 返回值

Returns a float or array of floats (as appropriate) 或者在失败时返回 `false`.

### 参见

- openal_listener_set() - Set a listener property

# openal_listener_set

(PECL openal >= 0.1.0)

openal_listener_set — Set a listener property

### 说明

function openal_listener_set(int `$property`, mixed `$setting`): bool

### 参数

`property`
  Property to set, one of: `AL_GAIN` (float), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float))和 `AL_ORIENTATION` (array(float,float,float)).
`setting`
  Value to set, either float, or an array of floats as appropriate.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- openal_listener_get() - Retrieve a listener property

# openal_source_create

(PECL openal >= 0.1.0)

openal_source_create — Generate a source resource

### 说明

function openal_source_create(): resource

### 参数

此函数没有参数。

### 返回值

Returns an Open AL(Source) resource on success or `false` on failure.

### 参见

- 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

### 说明

function openal_source_destroy(resource `$source`): bool

### 参数

`source`
  An Open AL(Source) resource (previously created by openal_source_create()).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- openal_source_create() - Generate a source resource

# openal_source_get

(PECL openal >= 0.1.0)

openal_source_get — Retrieve an OpenAL source property

### 说明

function openal_source_get(resource `$source`, int `$property`): mixed

### 参数

`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)).

### 返回值

Returns the type associated with the property being retrieved 或者在失败时返回 `false`.

### 参见

- 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

### 说明

function openal_source_pause(resource `$source`): bool

### 参数

`source`
  An Open AL(Source) resource (previously created by openal_source_create()).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function openal_source_play(resource `$source`): bool

### 参数

`source`
  An Open AL(Source) resource (previously created by openal_source_create()).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function openal_source_rewind(resource `$source`): bool

### 参数

`source`
  An Open AL(Source) resource (previously created by openal_source_create()).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function openal_source_set(resource `$source`, int `$property`, mixed `$setting`): bool

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function openal_source_stop(resource `$source`): bool

### 参数

`source`
  An Open AL(Source) resource (previously created by openal_source_create()).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function openal_stream(resource `$source`, int `$format`, int `$rate`): resource|false

### 参数

`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`和 `AL_FORMAT_STEREO16`
`rate`
  Frequency of data to stream given in Hz.

### 返回值

Returns a stream resource on success 或者在失败时返回 `false`.

### 参见

- openal_source_create() - Generate a source resource
- fwrite() - 写入文件（可安全用于二进制文件）

## 目录

- 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_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
  - 安装/配置
  - 预定义常量
  - OpenAL 函数

# 身份认证服务

# Radius

# 简介

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.

> 注意: An exact description for libradius can be found » here. A detailed description of the configuration file can be found » here.

# 安装/配置

## 目录

- 安装

## 安装

此 » PECL 扩展未与 PHP 捆绑。

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/radius.

# 预定义常量

## 目录

- RADIUS Options
- RADIUS Packet Types
- RADIUS Attribute Types
- RADIUS Vendor Specific Attribute Types

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`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.

  示例 #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`

# 示例

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 函数

# radius_acct_open

(PECL radius >= 1.1.0)

radius_acct_open — Creates a Radius handle for accounting

### 说明

function radius_acct_open(): resource

### 参数

此函数没有参数。

### 返回值

Returns a handle on success, `false` on error. This function only fails if insufficient memory is available.

### 示例

示例 #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

### 说明

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.

### 参数

`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`.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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;
    }
    ?>

### 参见

- 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

### 说明

function radius_auth_open(): resource

### 参数

此函数没有参数。

### 返回值

Returns a handle on success, `false` on error. This function only fails if insufficient memory is available.

### 示例

示例 #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 — Frees all ressources

### 说明

function radius_close(resource `$radius_handle`): bool

It is not needed to call this function because php frees all resources at the end of each request.

### 参数

`radius_handle`
  The RADIUS resource.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# radius_config

(PECL radius >= 1.1.0)

radius_config — Causes the library to read the given configuration file

### 说明

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.

### 参数

`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().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- radius_add_server() - Adds a server

# radius_create_request

(PECL radius >= 1.1.0)

radius_create_request — Create accounting or authentication request

### 说明

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().

> 注意: Attention: You must call this function, before you can put any attribute!

### 参数

`radius_handle`
`type`
  Type is `RADIUS_ACCESS_REQUEST` or `RADIUS_ACCOUNTING_REQUEST`.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 radius_create_request() example

    <?php
    if (!radius_create_request($res, RADIUS_ACCESS_REQUEST)) {
        echo 'RadiusError:' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### 参见

- 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

### 说明

function radius_cvt_addr(string `$data`): string

Converts raw data to IP-Address

### 参数

`data`
  Input data

### 返回值

Returns the IP-Address.

### 示例

示例 #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;
        }
    }
    ?>

### 参见

- 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

### 说明

function radius_cvt_int(string `$data`): int

Converts raw data to integer

### 参数

`data`
  Input data

### 返回值

Returns the integer, retrieved from data.

### 示例

示例 #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;
        }
    }
    ?>

### 参见

- 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

### 说明

function radius_cvt_string(string `$data`): string

Converts raw data to string

### 参数

`data`
  Input data

### 返回值

Returns the string, retrieved from data.

### 示例

示例 #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;
        }
    }
    ?>

### 参见

- 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

### 说明

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.

### 参数

`radius_handle`
  The RADIUS resource.
`mangled`
  The mangled data to demangle

### 返回值

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

### 说明

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.

### 参数

`radius_handle`
  The RADIUS resource.
`mangled`
  The mangled data to demangle

### 返回值

Returns the demangled string, or `false` on error.

# radius_get_attr

(PECL radius >= 1.1.0)

radius_get_attr — Extracts an attribute

### 说明

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.

### 参数

`radius_handle`
  The RADIUS resource.

### 返回值

Returns an associative array containing the attribute-type and the data, or error number <= 0.

### 示例

示例 #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));
    }
    ?>

### 参见

- 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

### 说明

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.

### 参数

`data`
  The tagged attribute to be decoded.

### 返回值

Returns the data from the tagged attribute 或者在失败时返回 `false`.

### 示例

示例 #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);
    }
    ?>

### 参见

- 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

### 说明

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.

### 参数

`data`
  The tagged attribute to be decoded.

### 返回值

Returns the tag from the tagged attribute 或者在失败时返回 `false`.

### 示例

示例 #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);
    }
    ?>

### 参见

- 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

### 说明

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.

### 参数

`data`
  Input data

### 返回值

Returns an associative array containing the attribute-type, vendor and the data, or `false` on error.

### 示例

示例 #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));
            }

        }
    }
    ?>

### 参见

- 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

### 说明

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.

> 注意: A request must be created via radius_create_request() before this function can be called.

### 参数

`radius_handle`
  The RADIUS resource.
`type`
  The attribute type.
`addr`
  An IPv4 address in string form, such as `10.0.0.1`.
`options`
  A bitmask of the attribute options. The available options include `RADIUS_OPTION_TAGGED` and `RADIUS_OPTION_SALT`.
`tag`
  The attribute tag. This parameter is ignored unless the `RADIUS_OPTION_TAGGED` option is set.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
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

### 说明

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.

> 注意: A request must be created via radius_create_request() before this function can be called.

### 参数

`radius_handle`
  The RADIUS resource.
`type`
  The attribute type.
`value`
  The attribute value, which will be treated as a raw binary string.
`options`
  A bitmask of the attribute options. The available options include `RADIUS_OPTION_TAGGED` and `RADIUS_OPTION_SALT`.
`tag`
  The attribute tag. This parameter is ignored unless the `RADIUS_OPTION_TAGGED` option is set.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
PECL radius 1.3.0 | The `options` and `tag` parameters were added.

### 示例

示例 #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;
    }
    ?>

### 参见

- 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

### 说明

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.

> 注意: A request must be created via radius_create_request() before this function can be called.

### 参数

`radius_handle`
  The RADIUS resource.
`type`
  The attribute type.
`value`
  The attribute value.
`options`
  A bitmask of the attribute options. The available options include `RADIUS_OPTION_TAGGED` and `RADIUS_OPTION_SALT`.
`tag`
  The attribute tag. This parameter is ignored unless the `RADIUS_OPTION_TAGGED` option is set.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
PECL radius 1.3.0 | The `options` and `tag` parameters were added.

### 示例

示例 #1 radius_put_int() example

    <?php
    if (!radius_put_int($res, RAD_FRAMED_PROTOCOL, RAD_PPP)) {
       echo 'RadiusError:' . radius_strerror($res). "\n<br />";
       exit;
    }
    ?>

### 参见

- 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

### 说明

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.

> 注意: A request must be created via radius_create_request() before this function can be called.

### 参数

`radius_handle`
  The RADIUS resource.
`type`
  The attribute type.
`value`
  The attribute value. This value is expected by the underlying library to be null terminated, therefore this parameter is not binary safe.
`options`
  A bitmask of the attribute options. The available options include `RADIUS_OPTION_TAGGED` and `RADIUS_OPTION_SALT`.
`tag`
  The attribute tag. This parameter is ignored unless the `RADIUS_OPTION_TAGGED` option is set.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
PECL radius 1.3.0 | The `options` and `tag` parameters were added.

### 示例

示例 #1 radius_put_string() example

    <?php
    if (!radius_put_string($res, RADIUS_USER_NAME, 'billy')) {
        echo 'RadiusError:' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### 参见

- 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

### 说明

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.

> 注意: A request must be created via radius_create_request() before this function can be called.

### 参数

`radius_handle`
  The RADIUS resource.
`vendor`
  The vendor ID.
`type`
  The attribute type.
`addr`
  An IPv4 address in string form, such as `10.0.0.1`.
`options`
  A bitmask of the attribute options. The available options include `RADIUS_OPTION_TAGGED` and `RADIUS_OPTION_SALT`.
`tag`
  The attribute tag. This parameter is ignored unless the `RADIUS_OPTION_TAGGED` option is set.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
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

### 说明

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.

> 注意: A request must be created via radius_create_request() before this function can be called.

### 参数

`radius_handle`
  The RADIUS resource.
`vendor`
  The vendor ID.
`type`
  The attribute type.
`value`
  The attribute value, which will be treated as a raw binary string.
`options`
  A bitmask of the attribute options. The available options include `RADIUS_OPTION_TAGGED` and `RADIUS_OPTION_SALT`.
`tag`
  The attribute tag. This parameter is ignored unless the `RADIUS_OPTION_TAGGED` option is set.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
PECL radius 1.3.0 | The `options` and `tag` parameters were added.

### 示例

示例 #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;
    }
    ?>

### 参见

- 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

### 说明

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.

> 注意: A request must be created via radius_create_request() before this function can be called.

### 参数

`radius_handle`
  The RADIUS resource.
`vendor`
  The vendor ID.
`type`
  The attribute type.
`value`
  The attribute value.
`options`
  A bitmask of the attribute options. The available options include `RADIUS_OPTION_TAGGED` and `RADIUS_OPTION_SALT`.
`tag`
  The attribute tag. This parameter is ignored unless the `RADIUS_OPTION_TAGGED` option is set.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
PECL radius 1.3.0 | The `options` and `tag` parameters were added.

### 参见

- 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

### 说明

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.

> 注意: A request must be created via radius_create_request() before this function can be called.

### 参数

`radius_handle`
  The RADIUS resource.
`vendor`
  The vendor ID.
`type`
  The attribute type.
`value`
  The attribute value. This value is expected by the underlying library to be null terminated, therefore this parameter is not binary safe.
`options`
  A bitmask of the attribute options. The available options include `RADIUS_OPTION_TAGGED` and `RADIUS_OPTION_SALT`.
`tag`
  The attribute tag. This parameter is ignored unless the `RADIUS_OPTION_TAGGED` option is set.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
PECL radius 1.3.0 | The `options` and `tag` parameters were added.

### 参见

- 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

### 说明

function radius_request_authenticator(resource `$radius_handle`): string

The request authenticator is needed for demangling mangled data like passwords and encryption-keys.

### 参数

`radius_handle`
  The RADIUS resource.

### 返回值

Returns the request authenticator as string, or `false` on error.

### 参见

- radius_demangle() - Demangles data

# radius_salt_encrypt_attr

(PECL radius >= 1.3.0)

radius_salt_encrypt_attr — Salt-encrypts a value

### 说明

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.

### 参数

`data`
  The data to be salt-encrypted.

### 返回值

Returns the salt-encrypted data 或者在失败时返回 `false`.

### 参见

- 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

### 说明

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.

### 参数

`radius_handle`
  The RADIUS resource.

### 返回值

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`.

### 参见

- radius_create_request() - Create accounting or authentication request

# radius_server_secret

(PECL radius >= 1.1.0)

radius_server_secret — Returns the shared secret

### 说明

function radius_server_secret(resource `$radius_handle`): string

The shared secret is needed as salt for demangling mangled data like passwords and encryption-keys.

### 参数

`radius_handle`
  The RADIUS resource.

### 返回值

Returns the server's shared secret as string, or `false` on error.

# radius_strerror

(PECL radius >= 1.1.0)

radius_strerror — Returns an error message

### 说明

function radius_strerror(resource `$radius_handle`): string

If Radius-functions fail then they record an error message. This error message can be retrieved with this function.

### 参数

`radius_handle`
  The RADIUS resource.

### 返回值

Returns error messages as string from failed radius functions.

## 目录

- 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 — Frees all ressources
- 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 — Returns an error message

- 安装/配置
  - 安装
- 预定义常量
  - RADIUS Options
  - RADIUS Packet Types
  - RADIUS Attribute Types
  - RADIUS Vendor Specific Attribute Types
- 示例
- Radius 函数
  - 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 — Frees all ressources
  - 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 — Returns an error message

- Radius
  - 安装/配置
  - 预定义常量
  - 示例
  - Radius 函数

# 针对命令行的扩展

# GNU Readline

# 简介

readline 扩展函数实现了访问 GNU Readline 库的接口。这些函数提供了可编辑的命令行。一个例子是在 Bash 中允许使用箭头按键来插入字符或者翻看历史命令。因为这个库的交互特性，对编写 Web 应用程序没多大用处，但当编写从命令行使用的脚本时非常有用.

从 PHP 7.1.0 开始，该扩展支持 Windows。

警告

readline 扩展并非线程安全！因此，强烈建议不要在任何真正线程安全的 SAPI（例如 Apache 的 mod_winnt）中使用这个扩展！

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置

## 需求

如果要使用 readline 函数，必须安装 libreadline。可以在 GNU readline 项目主页找到 libreadline，在 » https://tiswww.case.edu/php/chet/readline/rltop.html。由 Chet Ramey 维护，他也是 Bash 的作者。

也能使用非 GPL 的 libedit 库来替代 readline 库，libedit 库是使用 BSD 证书，可以从 » http://www.thrysoee.dk/editline/ 下载。

## 安装

要使用这些函数，必须编译支持 readline 的 PHP 的 CGI 或者 CLI 版本。需要配置 PHP --with-readline[=DIR]。如果想使用 libedit 代替 readline，配置 PHP --with-libedit[=DIR]。

在 Windows 上，此扩展自 PHP 7.1.0 起默认可用。

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

Readline 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
cli.pager | "" | `INI_ALL` |
cli.prompt | "\\b \\> " | `INI_ALL` |

这是配置指令的简短说明。

`cli.pager` string
  命令行显示输出的外部工具。
`cli.prompt` string
  命令行提示。

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`READLINE_LIB` (string)
  The library which is used for readline support; currently either `readline` or `libedit`.

# Readline 函数

# readline

(PHP 4, PHP 5, PHP 7, PHP 8)

readline — 读取一行

### 说明

function readline(?string `$prompt` = `null`): string|false

从用户端读取一行。必须使用 readline_add_history() 将这一行添加到历史记录中。

### 参数

`prompt`
  可以指定字符串来作为用户的提示信息。

### 返回值

从用户端返回单个字符串。返回的行将会移除行尾换行符。 如果没有更多数据可读，则返回 `false`。

### 示例

示例 #1 readline() 示例

    <?php
    //get 3 commands from user
    for ($i=0; $i < 3; $i++) {
            $line = readline("Command: ");
            readline_add_history($line);
    }

    //dump history
    print_r(readline_list_history());

    //dump variables
    print_r(readline_info());
    ?>

# readline_add_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_add_history — 添加一行到历史

### 说明

function readline_add_history(string `$prompt`): true

此函数添加一行到命令行历史。

### 参数

`prompt`
  添加到历史中的行。

### 返回值

总是返回 `true`。

# readline_callback_handler_install

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_handler_install — 初始化 readline 回调接口和终端，然后打印提示并立即返回

### 说明

function readline_callback_handler_install(string `$prompt`, callable `$callback`): true

设置 readline 回调接口然后打印 `prompt` 并立即返回。在不移除旧的回调接口的情况下再次调用此函数，将自动覆盖旧接口。

与 stream_select() 结合使用时，回调功能很有用，因为允许 IO 和用户输入交互，这与 readline() 不同。

### 参数

`prompt`
  提示信息。
`callback`
  `callback` 函数接受一个参数；返回用户输入。

### 返回值

总是返回 `true`。

### 示例

示例 #1 Readline 回调接口示例

    <?php
    function rl_callback($ret)
    {
        global $c, $prompting;

        echo "You entered: $ret\n";
        $c++;

        if ($c > 10) {
            $prompting = false;
            readline_callback_handler_remove();
        } else {
            readline_callback_handler_install("[$c] Enter something: ", 'rl_callback');
        }
    }

    $c = 1;
    $prompting = true;

    readline_callback_handler_install("[$c] Enter something: ", 'rl_callback');

    while ($prompting) {
        $w = NULL;
        $e = NULL;
        $n = stream_select($r = array(STDIN), $w, $e, null);
        if ($n && in_array(STDIN, $r)) {
            // read a character, will call the callback when a newline is entered
            readline_callback_read_char();
        }
    }

    echo "Prompting disabled. All done.\n";
    ?>

### 参见

- readline_callback_handler_remove() - 移除之前已安装的回调函数句柄并且恢复终端设置
- readline_callback_read_char() - 当一个行被接收时读取一个字符并且通知 readline 回调接口
- 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 — 移除之前已安装的回调函数句柄并且恢复终端设置

### 说明

function readline_callback_handler_remove(): bool

移除之前已安装的回调句柄并且恢复终端设置。

### 参数

此函数没有参数。

### 返回值

如果移除了之前已安装的回调句柄，返回 `true` 或者如果没有找到的话返回 `false`。

### 示例

有关如何使用 readline 回调接口的示例，参见 readline_callback_handler_install()。

### 参见

- readline_callback_handler_install() - 初始化 readline 回调接口和终端，然后打印提示并立即返回
- readline_callback_read_char() - 当一个行被接收时读取一个字符并且通知 readline 回调接口

# readline_callback_read_char

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_read_char — 当一个行被接收时读取一个字符并且通知 readline 回调接口

### 说明

function readline_callback_read_char(): void

读取用户输入中的一个字符。当一行被接收时，这个函数将通知使用 readline_callback_handler_install() 安装的 readline 回调接口，并且 这一个行已经准备输入。

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 示例

有关如何使用 readline 回调接口的示例，参见 readline_callback_handler_install()。

### 参见

- readline_callback_handler_install() - 初始化 readline 回调接口和终端，然后打印提示并立即返回
- readline_callback_handler_remove() - 移除之前已安装的回调函数句柄并且恢复终端设置

# readline_clear_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_clear_history — 清除历史

### 说明

function readline_clear_history(): true

这个函数清除全部的命令行历史。

### 参数

此函数没有参数。

### 返回值

总是返回 `true`。

# readline_completion_function

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_completion_function — 注册完成函数

### 说明

function readline_completion_function(callable `$callback`): bool

这个函数注册完成函数。这与在使用 Bash 时按下 Tab 键将获得的功能相同。

### 参数

`callback`
  必须提供现有的函数名，该函数接受部分命令行并返回可能的匹配项数组。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# readline_info

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_info — 获取/设置各种 readline 内部变量

### 说明

function readline_info(?string `$var_name` = `null`, int|string|bool|null `$value` = `null`): mixed

获取/设置各种 readline 内部变量。

### 参数

`var_name`
  变量名。
`value`
  如果提供，将是设置的新值。

### 返回值

如果调用时没有参数，此函数将返回 readline 使用的所有设置的值组成的数组。元素将按照以下值进行索引 `done`、`end`、`erase_empty_line`、`library_version`、`line_buffer`、`mark`、`pending_input`、`point`、`prompt`、`readline_name`、和 `terminal_name`。 array 仅包含库用于编译 readline 扩展支持的元素。

如果使用一个或两个参数调用，则返回原来的值。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `var_name` 和 `value` 现在可为 null。

# readline_list_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_list_history — 获取历史

### 说明

function readline_list_history(): array

获取完整命令行历史。

### 参数

此函数没有参数。

### 返回值

返回完整命令行历史的数组。元素的索引为整数，从零开始。

# readline_on_new_line

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_on_new_line — 通知 readline 将光标移动到新行

### 说明

function readline_on_new_line(): void

告诉 readline 将光标移动到新行。

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 注释

> 注意: 此函数仅在底层 readline 库支持时可用。不支持 Windows。

# readline_read_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_read_history — 读取历史

### 说明

function readline_read_history(?string `$filename` = `null`): bool

这个函数从文件中读取命令历史。

### 参数

`filename`
  包含命令行历史的文件路径。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `filename` 现在可为 null。

# readline_redisplay

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_redisplay — 重绘显示区

### 说明

function readline_redisplay(): void

readline 重绘用于重绘显示区。

### 参数

此函数没有参数。

### 返回值

没有返回值。

# readline_write_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_write_history — 写入历史记录

### 说明

function readline_write_history(?string `$filename` = `null`): bool

这个函数将命令历史写入到文件。

### 参数

`filename`
  保存文件的路径.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `filename` 现在可为 null。

## 目录

- readline — 读取一行
- readline_add_history — 添加一行到历史
- readline_callback_handler_install — 初始化 readline 回调接口和终端，然后打印提示并立即返回
- readline_callback_handler_remove — 移除之前已安装的回调函数句柄并且恢复终端设置
- readline_callback_read_char — 当一个行被接收时读取一个字符并且通知 readline 回调接口
- readline_clear_history — 清除历史
- readline_completion_function — 注册完成函数
- readline_info — 获取/设置各种 readline 内部变量
- readline_list_history — 获取历史
- readline_on_new_line — 通知 readline 将光标移动到新行
- readline_read_history — 读取历史
- readline_redisplay — 重绘显示区
- readline_write_history — 写入历史记录

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
- 预定义常量
- Readline 函数
  - readline — 读取一行
  - readline_add_history — 添加一行到历史
  - readline_callback_handler_install — 初始化 readline 回调接口和终端，然后打印提示并立即返回
  - readline_callback_handler_remove — 移除之前已安装的回调函数句柄并且恢复终端设置
  - readline_callback_read_char — 当一个行被接收时读取一个字符并且通知 readline 回调接口
  - readline_clear_history — 清除历史
  - readline_completion_function — 注册完成函数
  - readline_info — 获取/设置各种 readline 内部变量
  - readline_list_history — 获取历史
  - readline_on_new_line — 通知 readline 将光标移动到新行
  - readline_read_history — 读取历史
  - readline_redisplay — 重绘显示区
  - readline_write_history — 写入历史记录

- Readline — GNU Readline
  - 安装/配置
  - 预定义常量
  - Readline 函数

# 压缩与归档扩展

# Bzip2

# 简介

bzip2 函数用于透明地读写 bzip2（.bz2）压缩文件。

# 安装/配置

## 目录

- 需求
- 安装
- 资源类型

## 需求

本模块使用了 Julian Seward 的 » bzip2 库中的函数。本模块需要 bzip2/libbzip2 版本 >= 1.0.x。

## 安装

PHP 的 Bzip2 支持默认未打开。编译 PHP 时需要 --with-bz2[=DIR] 配置选项来激活 bzip2 支持。

## 资源类型

本扩展定义了一种资源类型：用于识别和操作 bz2 文件的指针。

# 示例

该范例打开一个临时文件并写入了一个测试字符串，然后输出该文件里的内容。

示例 #1 bzip2 小例子

    <?php

    $filename = "/tmp/testfile.bz2";
    $str = "This is a test string.\n";

    // 打开一个文件用于写入
    $bz = bzopen($filename, "w");

    // 写入字符串到文件
    bzwrite($bz, $str);

    // 关闭文件
    bzclose($bz);

    // 打开文件用于读取
    $bz = bzopen($filename, "r");

    // 读取 10 个字符
    echo bzread($bz, 10);

    // 输出直到文件末尾（或者后面的 1024 个字符），并关闭。
    echo bzread($bz);

    bzclose($bz);

    ?>

# Bzip2 函数

# bzclose

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzclose — 关闭一个 bzip2 文件

### 说明

function bzclose(resource `$bz`): bool

关闭给出的 bzip2 文件指针。

### 参数

`bz`
  文件指针。它必须是有效的并且指向 bzopen() 成功打开的文件。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- bzopen() - 打开 bzip2 压缩文件

# bzcompress

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzcompress — 把一个字符串压缩成 bzip2 编码数据

### 说明

function bzcompress(string `$data`, int `$block_size` = 4, int `$work_factor` = 0): string|int

bzcompress() 压缩了指定的字符串并以 bzip2 编码返回数据。

### 参数

`data`
  待压缩的字符串。
`block_size`
  指定压缩时使用的块大小，应该是一个 1-9 的数字。9 可以有最高的压缩比，但会使用更多的资源。
`work_factor`
  控制压缩阶段出现最坏的重复性高的情况下输入数据时的行为。 该值可以是在 0 至 250 之间，0是一个特殊的情况。 无论 `work_factor`是什么，产生的输出都是一致的。

### 返回值

压缩后的字符串，或者在出现错误时返回错误号。

### 示例

示例 #1 压缩数据

    <?php
    $str = "sample data";
    $bzstr = bzcompress($str, 9);
    echo $bzstr;
    ?>

### 参见

- bzdecompress() - 解压经 bzip2 编码过的数据

# bzdecompress

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzdecompress — 解压经 bzip2 编码过的数据

### 说明

function bzdecompress(string `$data`, bool `$use_less_memory` = `false`): string|int|false

bzdecompress() 解压了包含 bzip2 压缩数据的指定字符串。

### 参数

`data`
  要解压的字符串。
`use_less_memory`
  如果为 `true`，将会使用一种内存开销更小的替代算法（最大内存需求降低至大约 2300K）但速度会降低约一半。 寻找该功能的更多信息可参见 » bzip2 文档。

### 返回值

返回解压后的字符串或者 `false`，如果发生了一个错误则返回一个错误码。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `use_less_memory` 的类型从 int 变为 bool。 之前默认值为 `0`。

### 示例

示例 #1 解压一个字符串

    <?php
    $start_str = "This is not an honest face?";
    $bzstr = bzcompress($start_str);

    echo "Compressed String: ";
    echo $bzstr;
    echo "\n<br />\n";

    $str = bzdecompress($bzstr);
    echo "Decompressed String: ";
    echo $str;
    echo "\n<br />\n";
    ?>

### 参见

- bzcompress() - 把一个字符串压缩成 bzip2 编码数据

# bzerrno

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrno — 返回一个 bzip2 错误码

### 说明

function bzerrno(resource `$bz`): int

返回指定文件指针任意返回的 bzip2 错误的错误码。

### 参数

`bz`
  文件指针。它必须是有效的并且指向 bzopen() 成功打开的文件。

### 返回值

返回 integer 的错误码。

### 参见

- bzerror() - 返回包含 bzip2 错误号和错误字符串的一个 array
- bzerrstr() - 返回一个 bzip2 的错误字符串

# bzerror

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerror — 返回包含 bzip2 错误号和错误字符串的一个 array

### 说明

function bzerror(resource `$bz`): array

返回文件指针中返回的 bzip2 错误的错误号和错误字符串。

### 参数

`bz`
  文件指针。它必须是有效的并且指向 bzopen() 成功打开的文件。

### 返回值

返回一个关联数组，包含错误码于 `errno` 条目， 以及错误信息于 `errstr` 条目。

### 示例

示例 #1 bzerror() 范例

    <?php
    $error = bzerror($bz);

    echo $error["errno"];
    echo $error["errstr"];
    ?>

### 参见

- bzerrno() - 返回一个 bzip2 错误码
- bzerrstr() - 返回一个 bzip2 的错误字符串

# bzerrstr

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrstr — 返回一个 bzip2 的错误字符串

### 说明

function bzerrstr(resource `$bz`): string

获取指定文件指针中返回 bzip2 任何错误的错误字符串。

### 参数

`bz`
  文件指针。它必须是有效的并且指向 bzopen() 成功打开的文件。

### 返回值

返回包含错误信息的 string。

### 参见

- bzerrno() - 返回一个 bzip2 错误码
- bzerror() - 返回包含 bzip2 错误号和错误字符串的一个 array

# bzflush

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzflush — 什么都不做

### 说明

function bzflush(resource `$bz`): bool

该函数应该强制写入 bzip2 文件指针 `bz` 的所有写缓冲数据。但在 libbz2 中实现为空函数，因此什么都不做。

### 参数

`bz`
  文件指针。它必须是有效的并且指向 bzopen() 成功打开的文件。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- bzread() - bzip2 文件二进制安全地读取
- bzwrite() - 二进制安全地写入 bzip2 文件

# bzopen

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzopen — 打开 bzip2 压缩文件

### 说明

function bzopen(string|resource `$file`, string `$mode`): resource|false

bzopen() 打开一个 bzip2（.bz2）文件用于读或写。

### 参数

`file`
  待打开的文件的文件名，或者已经存在的资源流。
`mode`
  支持 `'r'`（读）和 `'w'`（写）模式。 其他任何模式都会导致 bzopen() 返回 `false`。

### 返回值

如果打开失败，bzopen() 会返回 `false`，否则返回一个指向最新打开文件的指针。

### 示例

示例 #1 bzopen() 范例

    <?php

    $file = "/tmp/foo.bz2";
    $bz = bzopen($file, "r") or die("Couldn't open $file for reading");

    bzclose($bz);

    ?>

### 参见

- bzclose() - 关闭一个 bzip2 文件

# bzread

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzread — bzip2 文件二进制安全地读取

### 说明

function bzread(resource `$bz`, int `$length` = 1024): string|false

bzread() 从指定的 bzip2 文件指针中读取数据。

读取到 `length`（未经压缩的长度）个字节，或者到文件尾，取决于先到哪个。

### 参数

`bz`
  文件指针。它必须是有效的并且指向 bzopen() 成功打开的文件。
`length`
  如果没有提供， bzread() 一次会读入 1024 个字节（未经压缩的长度）。 一次最大可读入 8192 个未压缩的字节。

### 返回值

返回解压的数据，在错误时返回 `false`。

### 示例

示例 #1 bzread() 范例

    <?php

    $file = "/tmp/foo.bz2";
    $bz = bzopen($file, "r") or die("Couldn't open $file");

    $decompressed_file = '';
    while (!feof($bz)) {
      $decompressed_file .= bzread($bz, 4096);
    }
    bzclose($bz);

    echo "The contents of $file are: <br />\n";
    echo $decompressed_file;

    ?>

### 参见

- bzwrite() - 二进制安全地写入 bzip2 文件
- feof() - 测试文件指针是否到了文件结束的位置
- bzopen() - 打开 bzip2 压缩文件

# bzwrite

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzwrite — 二进制安全地写入 bzip2 文件

### 说明

function bzwrite(resource `$bz`, string `$data`, ?int `$length` = `null`): int|false

bzwrite() 把字符串（string）写入了指定的 bzip2 文件流。

### 参数

`bz`
  文件指针。它必须是有效的并且指向 bzopen() 成功打开的文件。
`data`
  要写入的数据。
`length`
  如果提供了这个参数，将仅仅写入 `length`（未压缩）个字节，若 `data` 小于该指定的长度则写入全部数据。

### 返回值

返回写入的数据字节数，错误时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `length` 现在可为空（nullable）。

### 示例

示例 #1 bzwrite() 范例

    <?php
    $str = "uncompressed data";
    $bz = bzopen("/tmp/foo.bz2", "w");
    bzwrite($bz, $str, strlen($str));
    bzclose($bz);
    ?>

### 参见

- bzread() - bzip2 文件二进制安全地读取
- bzopen() - 打开 bzip2 压缩文件

## 目录

- bzclose — 关闭一个 bzip2 文件
- bzcompress — 把一个字符串压缩成 bzip2 编码数据
- bzdecompress — 解压经 bzip2 编码过的数据
- bzerrno — 返回一个 bzip2 错误码
- bzerror — 返回包含 bzip2 错误号和错误字符串的一个 array
- bzerrstr — 返回一个 bzip2 的错误字符串
- bzflush — 什么都不做
- bzopen — 打开 bzip2 压缩文件
- bzread — bzip2 文件二进制安全地读取
- bzwrite — 二进制安全地写入 bzip2 文件

- 安装/配置
  - 需求
  - 安装
  - 资源类型
- 示例
- Bzip2 函数
  - bzclose — 关闭一个 bzip2 文件
  - bzcompress — 把一个字符串压缩成 bzip2 编码数据
  - bzdecompress — 解压经 bzip2 编码过的数据
  - bzerrno — 返回一个 bzip2 错误码
  - bzerror — 返回包含 bzip2 错误号和错误字符串的一个 array
  - bzerrstr — 返回一个 bzip2 的错误字符串
  - bzflush — 什么都不做
  - bzopen — 打开 bzip2 压缩文件
  - bzread — bzip2 文件二进制安全地读取
  - bzwrite — 二进制安全地写入 bzip2 文件

# LZF

# 简介

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.

# 安装/配置

## 目录

- 安装

## 安装

此 » PECL 扩展未与 PHP 捆绑。 安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » 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 函数

# lzf_compress

(PECL lzf >= 0.1.0)

lzf_compress — LZF compression

### 说明

function lzf_compress(string `$data`): string

lzf_compress() compresses the given `data` string using LZF encoding.

### 参数

`data`
  The string to compress.

### 返回值

Returns the compressed data or `false` if an error occurred.

### 参见

- lzf_decompress() - LZF decompression

# lzf_decompress

(PECL lzf >= 0.1.0)

lzf_decompress — LZF decompression

### 说明

function lzf_decompress(string `$data`): string

lzf_compress() decompresses the given `data` string containing lzf encoded data.

### 参数

`data`
  The compressed string.

### 返回值

Returns the decompressed data or `false` if an error occurred.

### 参见

- lzf_compress() - LZF compression

# lzf_optimized_for

(PECL lzf >= 1.0.0)

lzf_optimized_for — Determines what LZF extension was optimized for

### 说明

function lzf_optimized_for(): int

Determines what was LZF extension optimized for during compilation.

### 参数

此函数没有参数。

### 返回值

Returns 1 if LZF was optimized for speed, 0 for compression.

## 目录

- lzf_compress — LZF compression
- lzf_decompress — LZF decompression
- lzf_optimized_for — Determines what LZF extension was optimized for

- 安装/配置
  - 安装
- LZF 函数
  - lzf_compress — LZF compression
  - lzf_decompress — LZF decompression
  - lzf_optimized_for — Determines what LZF extension was optimized for

# Phar

# 简介

phar 扩展提供了一种将整个 PHP 应用程序放入单个叫做“phar”（PHP 归档）文件的方法，以便于分发和安装。 除了提供此服务外，phar 扩展还提供了一种文件格式抽象方法，用于通过 PharData 类创建和操作 tar 和 zip 文件，就像 PDO 提供访问不同数据库的统一接口一样。与不能在不同数据库之间转换的 PDO 不同，phar 还可以使用一行代码在 tar、zip 和 phar 文件格式之间进行转换。参见 Phar::convertToExecutable() 中的示例。

什么是 phar？phar 归档的最佳特征是可以将多个文件组合成一个文件。 因此，phar 归档提供了在单个文件中分发完整的 PHP 应用程序并无需将其解压缩到磁盘而直接运行文件的方法。此外，phar 归档可以像任何其他文件一样由 PHP 在命令行和 Web 服务器上执行。phar 有点像 PHP 应用程序的移动存储器。

phar 通过 stream 封装协议实现这个功能。通常，要在 PHP 脚本中使用外部文件，将使用 include：

示例 #1 使用外部文件

    <?php
     include '/path/to/external/file.php';
     ?>

PHP 实际上将 `/path/to/external/file.php` 转换为 stream 封装协议`file:///path/to/external/file.php`，在底层，实际上使用普通文件 stream 封装协议 stream 函数访问所有的本地文件。

要使用 phar 归档 `/path/to/myphar.phar` 中名为 `file.php` 的文件，语法跟上面的 `file://` 语法非常相似。

示例 #2 使用 phar 归档内部文件

    <?php
     include 'phar:///path/to/myphar.phar/file.php';
     ?>

实际上可以将 phar 归档完全视为外部磁盘，可以使用任何 fopen() 相关函数，opendir() 和 mkdir() 相关函数在 phar 归档内读取、更改、创建新文件或目录。这将允许完整 PHP 应用程序分布在单个文件中，并直接从该文件中运行。

phar 归档最常见的用法是在单个文件中分发完整的应用程序。例如，PEAR 安装程序与 PHP 版本捆绑作为 phar 归档分发。要使用以这种方式分发 phar 归档，可以在命令行或通过 Web 服务器执行归档操作。

phar 归档可以作为 `tar` 归档、`zip` 归档或专门为 phar 扩展设计的自定义 `phar` 文件格式分发。每种文件格式都有优点和缺点。tar 和 zip 文件格式可以由任何可以读取格式的第三方工具读取或提取，但需要 PHP 和 phar 扩展才能运行。phar 文件格式是针对 phar 扩展定制和独有的，只能由 phar 扩展或 PEAR 包 » PHP_Archive 创建，优点是以这种格式创建的应用程序即使未启用 phar 扩展也能运行。

换句话说，即使禁用了 phar 扩展，也可以执行或包含基于 phar 的归档。只有使用 phar 扩展才能访问 phar 归档中的单个文件，除非 phar 归档是由 PHP_Archive 创建的。

phar 扩展还能够在单个命令中将 phar 归档从 tar 转换为 zip 或 phar 文件格式：

示例 #3 将 phar 归档从 phar 转换为 tar 文件格式

    <?php
     $phar = new Phar('myphar.phar');
     $pgz = $phar->convertToExecutable(Phar::TAR, Phar::GZ); // makes myphar.phar.tar.gz
     ?>

phar 可以使用 gzip 或 bzip2 来压缩单个文件或整个归档，并且可以通过使用 MD5、SHA-1、SHA-256 或 SHA-512 签名自动验证归档完整性。

最后，phar 扩展有安全意识，默认禁用对可执行 phar 归档的写访问，并且需要系统级禁用 `phar.readonly` php.ini 设置才能创建或修改 phar 归档。没有可执行存根（executable stub）的普通 tar 和 zip 归档始终可以使用 PharData 类创建或修改。

如果正在创建用于分发的应用程序，需要阅读如何创建 phar 归档。如果想了解关于 phar 支持的三种文件格式之间差异的更多信息，应该阅读 Phar、Tar 和 Zip。

如果使用的是 phar 应用程序，那么在如何使用 phar 归档中有一些有用的提示。

`phar` 是 `PHP` 和 `Archive` 的合成词，大致上基于 Java 开发人员熟悉的 `jar`（Java 归档）。

phar 归档的实现基于 PEAR 包 » PHP_Archive，尽管实现细节相似，但是 phar 扩展功能更强大。此外，phar 扩展允许大多数 PHP 应用程序不加修改地运行，而基于 PHP_Archive 的 phar 归档通常需要大量修改才能工作。

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置
- 资源类型

## 需求

想要利用压缩 phar，需要启用 zlib 和 bzip2 扩展。 此外，想要利用 OpenSSL 签名，需要开启 OpenSSL 扩展才能使用。

若要启用 zend.multibyte，必须同时启用 zend.detect_unicode。

## 安装

Phar 扩展与 PHP 捆绑且默认启用。禁用 Phar 支持，使用 --disable-phar。

在之前的 PHP 版本，可以通过 PECL 扩展安装 Phar，» Phar PECL 页面包含了历史以及更多信息。

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

文件系统和 stream 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
phar.readonly | "1" | `INI_ALL` |
phar.require_hash | "1" | `INI_ALL` |
phar.cache_list | "" | `INI_SYSTEM` |

这是配置指令的简短说明。

`phar.readonly` bool

  在使用 `phar` 流或 Phar 对象的写入操作时， 本选项可以禁止创建、修改 Phar 归档。 在生产环境中推荐始终启用本设置，否则伴随其他常见安全漏洞， phar 扩展支持写入时也能创建基于 PHP 的病毒。

  > 注意:

  > 出于安全考虑，只能在 php.ini 中取消此设置。 若在 php.ini 中禁用 `phar.readonly`，可以在代码中启用 `phar.readonly` 或其后禁用它。 若在 php.ini 中启用 `phar.readonly`，在代码中只能 "重复启用" INI 变量，不能禁用。

`phar.require_hash` bool

  此选项要求调用的所有 Phar 归档必须包含签名（目前支持的签名类型有 MD5、SHA1、SHA256、SHA512、OpenSSL）， 而且会拒绝处理不含签名的 Phar 归档。

  > 注意:

  > 只能在 php.ini 中取消此设置。 若在 php.ini 中禁用 `phar.require_hash`，可以在代码中启用 `phar.require_hash` 或其后禁用它。 若在 php.ini 中启用 `phar.require_hash`，在代码中可以 "重复启用" INI 变量，但不能禁用它。

  > 此选项不影响 PharData 类读取普通 tar 文件。

  警告

  `phar.require_hash` 本身不提供任何安全保障，它只能阻止运行因意外而损坏的 Phar 归档， 因为任何人都可以篡改 Phar 归档后轻松修改成对应的签名。

`phar.cache_list` string

  允许 web 服务启动时预先解析映射 phar 归档，提供性能上的优化， 使得从 phar 归档中运行文件的速度几乎接近从传统的基于磁盘安装运行这些文件的速度。

  示例 #1 phar.cache_list 用法示例

      在 php.ini 中（windows）：
      phar.cache_list =C:\path\to\phar1.phar;C:\path\to\phar2.phar
      在 php.ini 中（unix）：
      phar.cache_list =/path/to/phar1.phar:/path/to/phar2.phar

## 资源类型

Phar 扩展提供了 `phar` 流，能够透明访问 phar 中的文件。 另请参阅 Phar 文件格式说明。

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

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

## 目录

- 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

## 目录

- 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?

## 目录

- 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

小技巧

[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.

小技巧

[2] All write access requires `phar.readonly` to be disabled in php.ini or on the command-line directly.

小技巧

[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.

# The Phar class

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

## 简介

The Phar class provides a high-level interface to accessing and creating phar archives.

## 类摘要

class Phar extends RecursiveDirectoryIterator implements Countable, ArrayAccess {
/* 继承的常量 */
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;
/* 常量 */
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;
/* 方法 */
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()
/* 继承的方法 */
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
}

## 更新日志

版本 | 说明
--- | ---
8.4.0 | Added support for the Unix timestamp extension for Zip-based archives.
8.0.0 | Meta-data is no longer deserialized upon opening the archive, but is deferred until Phar::getMetadata() is called.

## 注释

警告

Prior to PHP 8.0.0, the meta-data was deserialized upon opening the archive. This could lead to security vulnerabilities. Starting with PHP 8.0.0, meta-data is only deserialized when calling Phar::getMetadata(), which has options to restrict deserialization for security reasons.

# Phar::addEmptyDir

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addEmptyDir — 添加一个空目录到 phar 档案

### 说明

public function Phar::addEmptyDir(string `$directory`): void

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

通过这个方法，可以创建一个以 `dirname` 为路径名的空目录。 这个方法和 ZipArchive::addEmptyDir() 类似。

### 参数

`directory`

  需要在 phar 档案中创建的空目录名称

### 返回值

没有返回值, 失败时抛出异常（exception）。

### 示例

示例 #1 一个 Phar::addEmptyDir() 示例

    <?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
    }
    ?>

### 参见

- PharData::addEmptyDir() - Add an empty directory to the tar/zip archive
- Phar::addFile() - 将一个文件从文件系统添加到 phar 档案中
- Phar::addFromString() - 以字符串的形式添加一个文件到 phar 档案

# Phar::addFile

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addFile — 将一个文件从文件系统添加到 phar 档案中

### 说明

public function Phar::addFile(string `$filename`, ?string `$localName` = `null`): void

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

通过这个方法，任何文件或者 URL 可以被添加到 phar 档案中。如果第二个可选参数 `localName` 被设定， 那么文件则会以该参数为名称保存到档案中，此外，`file` 参数会被作为路径保存在档案中。 URLs 必须提交 localname 参数，否则会抛出异常。 这个方法与 ZipArchive::addFile() 类似。

### 参数

`filename`

  需要添加到 phar 档案的文件在磁盘上的完全（绝对）或者相对路径。

`localName`

  文件保存到档案时的路径。

### 返回值

没有返回值，失败时会抛出异常。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `localName` 现在可以为空。

### 示例

示例 #1 一个 Phar::addFile() 示例

    <?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
    }
    ?>

### 注释

> 注意: Phar::addFile(), Phar::addFromString() and Phar::offsetSet() save a new phar archive each time they are called. If performance is a concern, Phar::buildFromDirectory() or Phar::buildFromIterator() should be used instead.

### 参见

- 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() - 以字符串的形式添加一个文件到 phar 档案
- Phar::addEmptyDir() - 添加一个空目录到 phar 档案

# Phar::addFromString

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addFromString — 以字符串的形式添加一个文件到 phar 档案

### 说明

public function Phar::addFromString(string `$localName`, string `$contents`): void

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

通过这个方法，任何字符串都可以被添加到 phar 档案中。 文件将会以 `localname` 为路径保存到档案中。 这个方法与 ZipArchive::addFromString() 类似。

### 参数

`localName`

  文件保存到档案时的路径。

`contents`

  要保存的文件内容。

### 返回值

没有返回值，失败时会抛出异常。

### 示例

示例 #1 一个 Phar::addFromString() 示例

    <?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
    }
    ?>

### 注释

> 注意: Phar::addFile(), Phar::addFromString() and Phar::offsetSet() save a new phar archive each time they are called. If performance is a concern, Phar::buildFromDirectory() or Phar::buildFromIterator() should be used instead.

### 参见

- 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() - 将一个文件从文件系统添加到 phar 档案中
- Phar::addEmptyDir() - 添加一个空目录到 phar 档案

# Phar::apiVersion

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::apiVersion — Returns the api version

### 说明

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.

### 参数

### 返回值

The API version string as in `"1.0.0"`.

### 示例

示例 #1 A Phar::apiVersion() example

    <?php
    echo Phar::apiVersion();
    ?>

以上示例会输出：

    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

### 说明

public function Phar::buildFromDirectory(string `$directory`, string `$pattern` = ""): array

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

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().

### 参数

`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.

### 返回值

Phar::buildFromDirectory() returns an associative array mapping internal path of file to the full path of the file on the filesystem.

### 错误／异常

This method throws BadMethodCallException when unable to instantiate the internal directory iterators, or a PharException if there were errors saving the phar archive.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | Phar::buildFromDirectory() no longer returns `false`.

### 示例

示例 #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'));
    ?>

### 参见

- 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

### 说明

public function Phar::buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

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.

### 参数

`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

### 返回值

Phar::buildFromIterator() returns an associative array mapping internal path of file to the full path of the file on the filesystem.

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | Phar::buildFromIterator() no longer returns `false`.
8.0.0 | `baseDirectory` is now nullable.

### 示例

示例 #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'));
    ?>

示例 #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'));
    ?>

### 参见

- 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

### 说明

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.

### 参数

`compression`

  Either `Phar::GZ` or `Phar::BZ2` can be used to test whether compression is possible with a specific compression algorithm (zlib or bzip2).

### 返回值

`true` if compression/decompression is available, `false` if not.

### 示例

示例 #1 A Phar::canCompress() example

    <?php
    if (Phar::canCompress()) {
        echo file_get_contents('phar://compressedphar.phar/internal/file.txt');
    } else {
        echo 'no compression available';
    }
    ?>

### 参见

- 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

### 说明

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.

### 参数

### 返回值

`true` if write access is enabled, `false` if it is disabled.

### 示例

示例 #1 A Phar::canWrite() example

    <?php
    if (Phar::canWrite()) {
        file_put_contents('phar://myphar.phar/file.txt', 'hi there');
    }
    ?>

### 参见

- 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

### 说明

public function Phar::compress(int `$compression`, ?string `$extension` = `null`): ?Phar

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

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.

### 参数

`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`.

### 返回值

Returns a Phar object, or `null` on failure.

### 错误／异常

Throws BadMethodCallException if the phar.readonly INI variable is on, the zlib extension is not available, or the bzip2 extension is not enabled.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `extension` is now nullable.

### 示例

示例 #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
    ?>

### 参见

- 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

### 说明

public function Phar::compressFiles(int `$compression`): void

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

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.

### 参数

`compression`

  Compression must be one of `Phar::GZ`, `Phar::BZ2` to add compression, or `Phar::NONE` to remove compression.

### 返回值

没有返回值。

### 错误／异常

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.

### 示例

示例 #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));
    }
    ?>

以上示例会输出：

    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)

### 参见

- 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

### 说明

public function Phar::__construct(string `$filename`, int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS, ?string `$alias` = `null`)

### 参数

`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.

### 错误／异常

Throws BadMethodCallException if called twice, UnexpectedValueException if the phar archive can't be opened.

### 示例

示例 #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

### 说明

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.

### 参数

`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`.

### 返回值

The method returns a PharData object on success, or `null` on failure.

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `format`, `compression`, and `extension` are now nullable.

### 示例

示例 #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
    }
    ?>

### 参见

- 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

### 说明

public function Phar::convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

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.

### 参数

`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`.

### 返回值

The method returns a Phar object on success, or `null` on failure.

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `format`, `compression`, and `extension` are now nullable.

### 示例

示例 #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
    }
    ?>

### 参见

- 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

### 说明

public function Phar::copy(string `$from`, string `$to`): true

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

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.

### 参数

`from`

`to`

### 返回值

总是返回 `true`。

### 错误／异常

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.

### 示例

示例 #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

### 说明

public function Phar::count(int `$mode` = `COUNT_NORMAL`): int

### 参数

`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.

### 返回值

The number of files contained within this phar, or `0` (the number zero) if none.

### 示例

示例 #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";
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`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

### 返回值

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.

### 错误／异常

Throws UnexpectedValueException if either parameter is longer than 400 bytes.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `index` and `webIndex` are now nullable.

### 示例

示例 #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
    }
    ?>

### 参见

- 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

### 说明

public function Phar::decompress(?string `$extension` = `null`): ?Phar

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

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.

### 参数

`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.

### 返回值

A Phar object is returned on success, and `null` on failure.

### 错误／异常

Throws BadMethodCallException if the phar.readonly INI variable is on, the zlib extension is not available, or the bzip2 extension is not enabled.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `extension` is now nullable.

### 示例

示例 #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
    ?>

### 参见

- 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

### 说明

public function Phar::decompressFiles(): true

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

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.

### 参数

此函数没有参数。

### 返回值

总是返回 `true`。

### 错误／异常

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.

### 示例

示例 #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));
    }
    ?>

以上示例会输出：

    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)

### 参见

- 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

### 说明

public function Phar::delMetadata(): true

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

Deletes the global metadata of the phar

### 参数

### 返回值

总是返回 `true`。

### 错误／异常

Throws PharException if errors occur while flushing changes to disk.

### 示例

示例 #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
    }
    ?>

以上示例会输出：

    NULL
    string(8) "hi there"
    NULL

### 参见

- 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 — 删除 phar 档案中的一个文件

### 说明

public function Phar::delete(string `$localName`): true

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

删除档案中的一个文件。这个方法与下面示例中调用 unlink() 处理数据流包装器的方式等价。

### 参数

`localName`

  需要删除的文件在档案中的路径。

### 返回值

总是返回 `true`。

### 错误／异常

如果将修改保存到磁盘时发生了错误，会抛出 PharException 异常。

### 示例

示例 #1 Phar::delete() 示例

    <?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
    }
    ?>

### 参见

- 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

### 说明

public function Phar::__destruct()

### 参数

此函数没有参数。

# 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

### 说明

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().

### 参数

`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

### 返回值

returns `true` on success, but it is better to check for thrown exception, and assume success if none is thrown.

### 错误／异常

Throws PharException if errors occur while flushing changes to disk.

### 示例

示例 #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
    }
    ?>

### 注释

> 注意: Windows NTFS file systems do not support some characters in filenames, namely `<|>*?":`. Filenames with a trailing dot are not supported either. Contrary to some extraction tools, this method does not replace these characters with an underscore, but instead fails to extract such files.

### 参见

- 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

### 说明

public function Phar::getAlias(): ?string

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function Phar::getMetadata(array `$unserializeOptions` = []): mixed

Retrieve archive meta-data. Meta-data can be any PHP variable that can be serialized.

警告

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.

### 参数

No parameters.

### 返回值

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.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | The parameter `unserializeOptions` has been added.

### 示例

示例 #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;
    }
    ?>

以上示例会输出：

    array(1) {
      ["bootstrap"]=>
      string(8) "file.php"
    }

### 参见

- 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

### 说明

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.

### 参数

No parameters.

### 返回值

`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

### 说明

public function Phar::getPath(): string

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# 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

### 说明

public function Phar::getSignature(): array|false

Returns the verification signature of a phar archive in a hexadecimal string.

### 参数

### 返回值

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

### 说明

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

### 参数

此函数没有参数。

### 返回值

Returns a string containing the contents of the bootstrap loader (stub) of the current Phar archive.

### 错误／异常

Throws RuntimeException if it is not possible to read the stub from the Phar archive.

### 示例

示例 #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();
    ?>

以上示例会输出：

    <?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(); ?>

### 参见

- 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

### 说明

final public static function Phar::getSupportedCompression(): array

### 参数

No parameters.

### 返回值

Returns an array containing any of `Phar::GZ` or `Phar::BZ2`, depending on the availability of the zlib extension or the bz2 extension.

### 参见

- 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

### 说明

final public static function Phar::getSupportedSignatures(): array

Return array of supported signature types

### 参数

No parameters.

### 返回值

Returns an array containing any of `MD5`, `SHA-1`, `SHA-256`, `SHA-512`, or `OpenSSL`.

### 参见

- 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

### 说明

public function Phar::getVersion(): string

Returns the API version of an opened Phar archive.

### 参数

### 返回值

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.

### 参见

- 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

### 说明

public function Phar::hasMetadata(): bool

Returns whether phar has global meta-data set.

### 参数

No parameters.

### 返回值

Returns `true` if meta-data has been set, and `false` if not.

### 示例

示例 #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
    }
    ?>

以上示例会输出：

    bool(false)
    bool(true)
    bool(false)

### 参见

- 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

### 说明

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.

### 参数

No parameters.

### 返回值

### 示例

示例 #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:

示例 #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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns `true` if the write operations are being buffer, `false` otherwise.

### 示例

示例 #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());
    ?>

以上示例会输出：

    bool(false)
    bool(false)
    =2=
    bool(true)
    bool(false)
    =3=
    bool(false)
    bool(false)

### 参见

- 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)

### 说明

public function Phar::isCompressed(): int|false

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

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.

### 参数

No parameters.

### 返回值

`Phar::GZ`, `Phar::BZ2` or `false`.

### 示例

示例 #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) {
    }
    ?>

以上示例会输出：

    bool(false)
    bool(false)
    bool(true)

### 参见

- 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

### 说明

public function Phar::isFileFormat(int `$format`): bool

### 参数

`format`

  Either `Phar::PHAR`, `Phar::TAR`, or `Phar::ZIP` to test for the format of the archive.

### 返回值

Returns `true` if the phar archive matches the file format requested by the parameter

### 错误／异常

PharException is thrown if the parameter is an unknown file format specifier.

### 参见

- 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

### 说明

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.

### 参数

`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

### 返回值

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

### 说明

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.

### 参数

No parameters.

### 返回值

Returns `true` if the phar archive can be modified

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

PharException is thrown if an alias is passed in and the phar archive already has an explicit alias

### 示例

示例 #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;
    }
    ?>

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 示例

示例 #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();

### 参见

- 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

### 说明

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.

### 参数

`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

### 返回值

No return. PharException is thrown on failure.

### 错误／异常

Throws PharException if any problems occur mounting the path.

### 示例

示例 #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

### 说明

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`.

### 参数

`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.

### 返回值

No return.

### 错误／异常

Throws UnexpectedValueException if any problems are found with the passed in data.

### 示例

示例 #1 A Phar::mungServer() example

    <?php
    // example stub
    Phar::mungServer(array('REQUEST_URI'));
    Phar::webPhar();
    __HALT_COMPILER();
    ?>

### 参见

- 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

### 说明

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.

### 参数

`localName`

  The filename (relative path) to look for in a Phar.

### 返回值

Returns `true` if the file exists within the phar, or `false` if not.

### 示例

示例 #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']));
    ?>

以上示例会输出：

    bool(true)
    bool(false)

### 参见

- 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

### 说明

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.

### 参数

`localName`

  The filename (relative path) to look for in a Phar.

### 返回值

A PharFileInfo object is returned that can be used to iterate over a file's contents or to retrieve information about the current file.

### 错误／异常

This method throws BadMethodCallException if the file does not exist in the Phar archive.

### 示例

示例 #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;
    }
    ?>

以上示例会输出：

    file exists
    Entry doesnotexist.txt does not exist

### 参见

- 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

### 说明

public function Phar::offsetSet(string `$localName`, resource|string `$value`): void

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

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.

### 参数

`localName`

  The filename (relative path) to modify in a Phar.

`value`

  Content of the file.

### 返回值

No return values.

### 错误／异常

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.

### 示例

示例 #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;
    }
    ?>

### 注释

> 注意: Phar::addFile(), Phar::addFromString() and Phar::offsetSet() save a new phar archive each time they are called. If performance is a concern, Phar::buildFromDirectory() or Phar::buildFromIterator() should be used instead.

### 参见

- 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

### 说明

public function Phar::offsetUnset(string `$localName`): void

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

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.

### 参数

`localName`

  The filename (relative path) to modify in a Phar.

### 返回值

没有返回值。

### 错误／异常

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.

### 示例

示例 #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;
    }
    ?>

### 参见

- 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() - 删除 phar 档案中的一个文件

# 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

### 说明

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.

### 参数

`returnPhar`

  If `false`, the full path on disk to the phar archive is returned. If `true`, a full phar URL is returned.

### 返回值

Returns the filename if valid, empty string otherwise.

### 示例

示例 #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

### 说明

public function Phar::setAlias(string `$alias`): true

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

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.

### 参数

`alias`

  A shorthand string that this archive can be referred to in `phar` stream wrapper access.

### 返回值

总是返回 `true`。

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | Phar::setAlias() now has a tentative return of true.

### 示例

示例 #1 A Phar::setAlias() example

    <?php
    try {
        $phar = new Phar('myphar.phar');
        $phar->setAlias('myp.phar');
    } catch (Exception $e) {
        // handle error
    }
    ?>

### 参见

- 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

### 说明

public function Phar::setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): true

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

This method is a convenience method that combines the functionality of Phar::createDefaultStub() and Phar::setStub().

### 参数

`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

### 返回值

总是返回 `true`。

### 错误／异常

UnexpectedValueException is thrown if phar.readonly is enabled in php.ini. PharException is thrown if any problems are encountered flushing changes to disk.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | Phar::setDefaultStub() now has a tentative return of true.
8.0.0 | `webIndex` is nullable now.

### 示例

示例 #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
    }
    ?>

### 参见

- 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

### 说明

public function Phar::setMetadata(mixed `$metadata`): void

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

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.

### 参数

`metadata`

  Any PHP variable containing information to store that describes the phar archive

### 返回值

没有返回值。

### 示例

示例 #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;
    }
    ?>

以上示例会输出：

    array(1) {
      ["bootstrap"]=>
      string(8) "file.php"
    }

### 参见

- 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

### 说明

public function Phar::setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

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().

### 参数

`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.

### 返回值

没有返回值。

### 错误／异常

Throws UnexpectedValueException for many errors, and a PharException if any problems occur flushing changes to disk.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `privateKey` is now nullable.

### 参见

- 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

### 说明

public function Phar::setStub(resource|string `$stub`, int `$length` = -1): true

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

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';
    ?>

### 参数

`stub`

  A string or an open stream handle to use as the executable stub for this phar archive.

`length`
  Length of `stub` in bytes.
  警告

  Passing the `length` argument with a resource in the first argument is DEPRECATED as of PHP 8.3.0. Use `$phar->setStub(stream_get_contents($resource))` instead.

### 返回值

总是返回 `true`。

### 错误／异常

UnexpectedValueException is thrown if phar.readonly is enabled in php.ini. PharException is thrown if any problems are encountered flushing changes to disk.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | The return type is `true` now; previously, it was 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));`

### 示例

示例 #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;
    }
    ?>

以上示例会输出：

    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(); ?>"

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 示例

示例 #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();
    ?>

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 错误／异常

PharException is thrown if any problems are encountered flushing changes to disk.

### 示例

示例 #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());
    ?>

以上示例会输出：

    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();"

### 参见

- 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

### 说明

final public static function Phar::unlinkArchive(string `$filename`): true

Removes a phar archive from disk and memory.

### 参数

`filename`

  The path on disk to the phar archive.

### 返回值

总是返回 `true`。

### 错误／异常

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.

### 示例

示例 #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');
    ?>

### 参见

- Phar::delete() - 删除 phar 档案中的一个文件
- 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

### 说明

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).

### 参数

`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.

### 返回值

没有返回值。

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `fileNotFoundScript` and `rewrite` are nullable now.

### 示例

示例 #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
    }
    ?>

### 参见

- 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

## 目录

- Phar::addEmptyDir — 添加一个空目录到 phar 档案
- Phar::addFile — 将一个文件从文件系统添加到 phar 档案中
- Phar::addFromString — 以字符串的形式添加一个文件到 phar 档案
- 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 — 删除 phar 档案中的一个文件
- 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)

## 简介

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`.

## 类摘要

class PharData extends RecursiveDirectoryIterator implements Countable, ArrayAccess {
/* 继承的常量 */
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;
/* 方法 */
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()
/* 继承的方法 */
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

### 说明

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().

### 参数

`directory`

  The name of the empty directory to create in the phar archive

### 返回值

no return value, exception is thrown on failure.

### 示例

示例 #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
    }
    ?>

### 参见

- Phar::addEmptyDir() - 添加一个空目录到 phar 档案
- 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

### 说明

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().

### 参数

`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.

### 返回值

no return value, exception is thrown on failure.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `localName` is now nullable.

### 示例

示例 #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
    }
    ?>

### 注释

> 注意: PharData::addFile(), PharData::addFromString() and PharData::offsetSet() save a new phar archive each time they are called. If performance is a concern, PharData::buildFromDirectory() or PharData::buildFromIterator() should be used instead.

### 参见

- PharData::offsetSet() - Set the contents of a file within the tar/zip to those of an external file or string
- Phar::addFile() - 将一个文件从文件系统添加到 phar 档案中
- 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

### 说明

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().

### 参数

`localName`

  Path that the file will be stored in the archive.

`contents`

  The file contents to store

### 返回值

no return value, exception is thrown on failure.

### 示例

示例 #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
    }
    ?>

### 注释

> 注意: PharData::addFile(), PharData::addFromString() and PharData::offsetSet() save a new phar archive each time they are called. If performance is a concern, PharData::buildFromDirectory() or PharData::buildFromIterator() should be used instead.

### 参见

- PharData::offsetSet() - Set the contents of a file within the tar/zip to those of an external file or string
- Phar::addFromString() - 以字符串的形式添加一个文件到 phar 档案
- 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

### 说明

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().

### 参数

`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.

### 返回值

Phar::buildFromDirectory() returns an associative array mapping internal path of file to the full path of the file on the filesystem, 或者在失败时返回 `false`.

### 错误／异常

This method throws BadMethodCallException when unable to instantiate the internal directory iterators, or a PharException if there were errors saving the phar archive.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | PharData::buildFromDirectory() no longer returns `false`.

### 示例

示例 #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$/');
    ?>

### 参见

- 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

### 说明

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.

### 参数

`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

### 返回值

PharData::buildFromIterator() returns an associative array mapping internal path of file to the full path of the file on the filesystem.

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | PharData::buildFromIterator() no longer returns `false`.
8.0.0 | `baseDirectory` is now nullable.

### 示例

示例 #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'));
    ?>

示例 #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'),
         )));
    ?>

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

A PharData object is returned on success, or `null` on failure.

### 错误／异常

Throws BadMethodCallException if the zlib extension is not available, or the bzip2 extension is not enabled.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `extension` is now nullable.

### 示例

示例 #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
    ?>

### 参见

- 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

### 说明

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.

### 参数

`compression`

  Compression must be one of `Phar::GZ`, `Phar::BZ2` to add compression, or `Phar::NONE` to remove compression.

### 返回值

没有返回值。

### 错误／异常

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.

### 示例

示例 #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));
    }
    ?>

以上示例会输出：

    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)

### 参见

- 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

### 说明

public function PharData::__construct(
string `$filename`,
int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS,
?string `$alias` = `null`,
int `$format` = 0
)

### 参数

`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.

### 错误／异常

Throws BadMethodCallException if called twice; UnexpectedValueException if the Phar archive can't be opened.

### 示例

示例 #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

### 说明

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.

### 参数

`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`.

### 返回值

The method returns a PharData object on success, or `null` on failure.

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `format`, `compression`, and `extension` are now nullable.

### 示例

示例 #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
    }
    ?>

### 参见

- 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

### 说明

public function PharData::convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

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.

### 参数

`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`.

### 返回值

The method returns a Phar object on success, or `null` on failure.

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `format`, `compression`, and `localName` are now nullable.

### 示例

示例 #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
    }
    ?>

### 参见

- 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

### 说明

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.

### 参数

`from`

`to`

### 返回值

总是返回 `true`。

### 错误／异常

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.

### 示例

示例 #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

### 说明

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.

### 参数

`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.

### 返回值

A PharData object is returned on success, or `null` on failure.

### 错误／异常

Throws BadMethodCallException if the zlib extension is not available, or the bzip2 extension is not enabled.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `extension` is now nullable.

### 示例

示例 #1 A PharData::decompress() example

    <?php
    $p = new PharData('/path/to/my.tar.gz');
    $p->decompress(); // creates /path/to/my.tar
    ?>

### 参见

- 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

### 说明

public function PharData::decompressFiles(): true

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

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.

### 参数

此函数没有参数。

### 返回值

总是返回 `true`。

### 错误／异常

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.

### 示例

示例 #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));
    }
    ?>

以上示例会输出：

    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)

### 参见

- 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

### 说明

public function PharData::delMetadata(): true

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

Deletes the global metadata of the zip archive

### 参数

### 返回值

总是返回 `true`。

### 错误／异常

Throws PharException if errors occur while flushing changes to disk.

### 示例

示例 #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
    }
    ?>

以上示例会输出：

    NULL
    string(8) "hi there"
    NULL

### 参见

- 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

### 说明

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.

### 参数

`localName`

  Path within an archive to the file to delete.

### 返回值

总是返回 `true`。

### 错误／异常

Throws PharException if errors occur while flushing changes to disk.

### 示例

示例 #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
    }
    ?>

### 参见

- Phar::delete() - 删除 phar 档案中的一个文件

# 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

### 说明

public function PharData::__destruct()

### 参数

此函数没有参数。

# 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

### 说明

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().

### 参数

`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

### 返回值

returns `true` on success, but it is better to check for thrown exception, and assume success if none is thrown.

### 错误／异常

Throws PharException if errors occur while flushing changes to disk.

### 示例

示例 #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
    }
    ?>

### 注释

> 注意: Windows NTFS file systems do not support some characters in filenames, namely `<|>*?":`. Filenames with a trailing dot are not supported either. Contrary to some extraction tools, this method does not replace these characters with an underscore, but instead fails to extract such files.

### 参见

- 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

### 说明

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`.

### 参数

No parameters.

### 返回值

Returns `true` if the tar/zip archive can be modified

### 参见

- 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

### 说明

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.

### 参数

`localName`

  The filename (relative path) to modify in a tar or zip archive.

`value`

  Content of the file.

### 返回值

No return values.

### 错误／异常

Throws PharException if there are any problems flushing changes made to the tar/zip archive to disk.

### 示例

示例 #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;
    }
    ?>

### 注释

> 注意: PharData::addFile(), PharData::addFromString() and PharData::offsetSet() save a new phar archive each time they are called. If performance is a concern, PharData::buildFromDirectory() or PharData::buildFromIterator() should be used instead.

### 参见

- 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

### 说明

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.

### 参数

`localName`

  The filename (relative path) to modify in the tar/zip archive.

### 返回值

没有返回值。

### 错误／异常

Throws PharException if there are any problems flushing changes made to the tar/zip archive to disk.

### 示例

示例 #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;
    }
    ?>

### 参见

- 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)

### 说明

public function PharData::setAlias(string `$alias`): bool

Non-executable tar/zip archives cannot have an alias, so this method simply throws an exception.

### 参数

`alias`

  A shorthand string that this archive can be referred to in `phar` stream wrapper access. This parameter is ignored.

### 返回值

### 错误／异常

Throws PharException on all method calls

### 参见

- 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)

### 说明

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.

### 参数

`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

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

Throws PharException on all method calls

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `webIndex` is nullable now.

### 参见

- 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

### 说明

public function PharData::setMetadata(mixed `$metadata`): void

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

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.

### 参数

`metadata`

  Any PHP variable containing information to store that describes the phar archive

### 返回值

没有返回值。

### 示例

示例 #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;
    }
    ?>

以上示例会输出：

    array(1) {
      ["bootstrap"]=>
      string(8) "file.php"
    }

### 参见

- 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

### 说明

public function PharData::setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void

> 注意: 此方法需要 将 php.ini 中的 `phar.readonly` 设为 `0` 以适合 Phar 对象. 否则, 将抛出PharException.

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`.

### 参数

`algo`

  One of `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512`, or `Phar::OPENSSL`

### 返回值

没有返回值。

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `privateKey` is now nullable.

### 参见

- 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)

### 说明

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.

### 参数

`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.

### 返回值

总是返回 `true`。

### 错误／异常

Throws PharException on all method calls

### 更新日志

版本 | 说明
--- | ---
8.4.0 | The return type is `true` now; previously, it was bool.

### 参见

- Phar::setStub() - Used to set the PHP loader or bootstrap stub of a Phar archive

## 目录

- 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)

## 简介

The PharFileInfo class provides a high-level interface to the contents and attributes of a single file within a phar archive.

## 类摘要

class PharFileInfo extends SplFileInfo {
/* 方法 */
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()
/* 继承的方法 */
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

### 说明

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.

### 参数

`perms`

  permissions (see chmod())

### 返回值

没有返回值。

### 示例

示例 #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;
    }
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`compression`

  Compression must be `Phar::GZ` or `Phar::BZ2`.

### 返回值

总是返回 `true`。

### 错误／异常

Throws BadMethodCallException if the phar.readonly INI variable is on, or if the bzip2/zlib extension is not available.

### 示例

示例 #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;
    }
    ?>

以上示例会输出：

    bool(false)
    bool(true)

### 参见

- 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

### 说明

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.

### 参数

`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`.

### 错误／异常

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.

### 示例

示例 #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;
    }
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

总是返回 `true`。

### 错误／异常

Throws BadMethodCallException if the phar.readonly INI variable is on, or if the bzip2/zlib extension is not available.

### 示例

示例 #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;
    }
    ?>

以上示例会输出：

    int(4096)
    bool(false)

### 参见

- 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

### 说明

public function PharFileInfo::delMetadata(): true

Deletes the metadata of the entry, if any.

### 参数

No parameters.

### 返回值

总是返回 `true`。 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.

### 错误／异常

Throws PharException if errors occurred while flushing changes to disk, and BadMethodCallException if write access is disabled.

### 示例

示例 #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
    }
    ?>

以上示例会输出：

    bool(false)
    bool(true)
    bool(false)

### 参见

- 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

### 说明

public function PharFileInfo::__destruct()

### 参数

此函数没有参数。

# 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

### 说明

public function PharFileInfo::getCRC32(): int

This returns the crc32() checksum of the file within the Phar archive.

### 参数

此函数没有参数。

### 返回值

The crc32() checksum of the file within the Phar archive.

### 错误／异常

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.

### 示例

示例 #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;
    }
    ?>

以上示例会输出：

    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

### 说明

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()

### 参数

此函数没有参数。

### 返回值

The size in bytes of the file within the Phar archive on disk.

### 示例

示例 #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;
    }
    ?>

以上示例会输出：

    2

### 参见

- 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

### 说明

public function PharFileInfo::getContent(): string

This function behaves like file_get_contents() but for Phar.

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function PharFileInfo::getMetadata(array `$unserializeOptions` = []): mixed

Return meta-data that was saved in the Phar archive's manifest for this file.

### 参数

### 返回值

any PHP variable that can be serialized and is stored as meta-data for the file, or `null` if no meta-data is stored.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | The parameter `unserializeOptions` has been added.

### 示例

示例 #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;
    }
    ?>

以上示例会输出：

    array(2) {
      ["user"]=>
      string(4) "bill"
      ["mime-type"]=>
      string(10) "text/plain"
    }

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

The Phar flags (always `0` in the current implementation)

### 示例

示例 #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;
    }
    ?>

以上示例会输出：

    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

### 说明

public function PharFileInfo::hasMetadata(): bool

Returns the metadata of a file within a phar archive.

### 参数

No parameters.

### 返回值

Returns `false` if no metadata is set or is `null`, `true` if metadata is not `null`

### 参见

- 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

### 说明

public function PharFileInfo::isCRCChecked(): bool

This returns whether a file within a Phar archive has had its CRC verified.

### 参数

此函数没有参数。

### 返回值

`true` if the file has had its CRC verified, `false` if not.

### 示例

示例 #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;
    }
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`compression`

  One of `Phar::GZ` or `Phar::BZ2`, defaults to any compression.

### 返回值

`true` if the file is compressed within the Phar archive, `false` if not.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `compression` is now nullable.

### 示例

示例 #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;
    }
    ?>

以上示例会输出：

    bool(false)
    bool(true)

### 参见

- 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

### 说明

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.

### 参数

`metadata`

  Any PHP variable containing information to store alongside a file

### 返回值

没有返回值。

### 示例

示例 #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;
    }
    ?>

以上示例会输出：

    array(2) {
      ["user"]=>
      string(4) "bill"
      ["mime-type"]=>
      string(10) "text/plain"
    }

### 参见

- 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

## 目录

- 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)

## 简介

The PharException class provides a phar-specific exception class for try/catch blocks.

## 类摘要

class PharException extends Exception {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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
}

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
  - 资源类型
- 预定义常量
- 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 — The Phar class
  - Phar::addEmptyDir — 添加一个空目录到 phar 档案
  - Phar::addFile — 将一个文件从文件系统添加到 phar 档案中
  - Phar::addFromString — 以字符串的形式添加一个文件到 phar 档案
  - 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 — 删除 phar 档案中的一个文件
  - 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

# 简介

Rar is a powerful and effective archiver created by Eugene Roshal. This extension gives you possibility to read Rar archives but doesn't support writing Rar archives, because this is not supported by the UnRar library and is directly prohibited by its license.

More information about Rar and UnRar can be found at » http://www.rarlabs.com/.

# 安装/配置

## 目录

- 安装
- 资源类型

## 安装

Rar is currently available through PECL » https://pecl.php.net/package/rar.

Also you can use the PECL installer to install the Rar extension, using the following command: pecl -v install rar.

You can always download the tar.gz package and install Rar by hand:

示例 #1 Rar installation

    gunzip rar-xxx.tgz
    tar -xvf rar-xxx.tar
    cd rar-xxx
    phpize
    ./configure && make && make install

Windows users will enable php_rar.dll inside of php.ini in order to use these functions.

## 资源类型

This extension registers three internal classes: the archive representations returned by rar_open() – RarArchive, the entry representations returned by rar_list() and rar_entry_get() – RarEntry and the exception type RarException.

This extension also register a stream resource, called "rar" and a URL wrapper called "rar wrapper" and registered under the prefix "rar".

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`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.

# 示例

See also the examples under `rar://` wrapper.

示例 #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.

示例 #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 函数

# rar_wrapper_cache_stats

(PECL rar >= 3.0.0)

rar_wrapper_cache_stats — Cache hits and misses for the URL wrapper

### 说明

function rar_wrapper_cache_stats(): string

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

## 目录

- rar_wrapper_cache_stats — Cache hits and misses for the URL wrapper

# The RarArchive class

(PECL rar >= 2.0.0)

## 简介

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().

## 类摘要

final class RarArchive implements Traversable {
/* 方法 */
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

### 说明

面向对象风格 (method):

public function RarArchive::close(): bool

过程化风格:

function rar_close(RarArchive `$rarfile`): bool

Close RAR archive and free all allocated resources.

### 参数

`rarfile`
  A RarArchive object, opened with rar_open().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #1 面向对象风格

    <?php
    $rar_arch = RarArchive::open('latest_winrar.rar');
    echo $rar_arch."\n";
    $rar_arch->close();
    echo $rar_arch."\n";
    ?>

以上示例的输出类似于：

    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar"
    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)

示例 #2 过程化风格

    <?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

### 说明

面向对象风格 (method):

public function RarArchive::getComment(): string

过程化风格:

function rar_comment_get(RarArchive `$rarfile`): string

Get the (global) comment stored in the RAR archive. It may be up to 64 KiB long.

> 注意: This extension does not support comments at the entry level.

### 参数

`rarfile`
  A RarArchive object, opened with rar_open().

### 返回值

Returns the comment or `null` if there is none.

> 注意: 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.

### 示例

示例 #1 面向对象风格

    <?php
    $rar_arch = RarArchive::open('commented.rar');
    echo $rar_arch->getComment();
    ?>

以上示例的输出类似于：

    This is the comment of the file commented.rar.

示例 #2 过程化风格

    <?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

### 说明

面向对象风格 (method):

public function RarArchive::getEntries(): array|false

过程化风格:

function rar_list(RarArchive `$rarfile`): array|false

Get entries list (files and directories) from the RAR archive.

> 注意: 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).

### 参数

`rarfile`
  A RarArchive object, opened with rar_open().

### 返回值

rar_list() returns array of RarEntry objects 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
PECL rar 3.0.0 | Support for RAR archives with repeated entry names is no longer defective.

### 示例

示例 #1 面向对象风格

    <?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();
    ?>

以上示例的输出类似于：

    Found 2 entries.
    RarEntry for file "tese.txt" (23b93a7a)
    RarEntry for file "unrardll.txt" (2ed64b6e)

示例 #2 过程化风格

    <?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);
    ?>

### 参见

- 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

### 说明

面向对象风格 (method):

public function RarArchive::getEntry(string `$entryname`): RarEntry|false

过程化风格:

function rar_entry_get(RarArchive `$rarfile`, string `$entryname`): RarEntry|false

Get entry object (file or directory) from the RAR archive.

> 注意: 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.

### 参数

`rarfile`
  A RarArchive object, opened with rar_open().
`entryname`
  Path to the entry within the RAR archive.

  > 注意: The path must be the same returned by RarEntry::getName().

### 返回值

Returns the matching RarEntry object 或者在失败时返回 `false`.

### 示例

示例 #1 面向对象风格

    <?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();
    ?>

以上示例的输出类似于：

    RarEntry
    RarEntry for file "tese.txt" (23b93a7a)

示例 #2 过程化风格

    <?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);
    ?>

### 参见

- 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)

### 说明

面向对象风格 (method):

public function RarArchive::isBroken(): bool

过程化风格:

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.

### 参数

`rarfile`
  A RarArchive object, opened with rar_open().

### 返回值

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.

### 示例

示例 #1 面向对象风格

    <?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());
    ?>

以上示例的输出类似于：

    bool(true)

示例 #2 过程化风格

    <?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));
    ?>

### 参见

- 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

### 说明

面向对象风格 (method):

public function RarArchive::isSolid(): bool

过程化风格:

function rar_solid_is(RarArchive `$rarfile`): bool

Check whether the RAR archive is solid. Individual file extraction is slower on solid archives.

### 参数

`rarfile`
  A RarArchive object, opened with rar_open().

### 返回值

Returns `true` if the archive is solid, `false` otherwise.

### 示例

示例 #1 面向对象风格

    <?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";
    ?>

以上示例的输出类似于：

    RAR Archive "C:\php_rar\trunk\tests\store_method.rar": no
    RAR Archive "C:\php_rar\trunk\tests\solid.rar": yes

示例 #2 过程化风格

    <?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

### 说明

面向对象风格 (method):

public static function RarArchive::open(string `$filename`, string `$password` = NULL, callable `$volume_callback` = NULL): RarArchive|false

过程化风格:

function rar_open(string `$filename`, string `$password` = NULL, callable `$volume_callback` = NULL): RarArchive|false

Open specified RAR archive and return RarArchive instance representing it.

> 注意: 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.

### 参数

`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.

警告

Prior to version 2.0.0, this function would not handle relative paths correctly. Use realpath() as a workaround.

### 返回值

Returns the requested RarArchive instance 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
PECL rar 3.0.0 | `volume_callback` was added.

### 示例

示例 #1 面向对象风格

    <?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);
    ?>

以上示例的输出类似于：

    Found 2 files.
    Content of first one follows:
    Encrypted file 1 contents.

示例 #2 过程化风格

    <?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);
    ?>

示例 #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");
    ?>

### 参见

- `rar://` wrapper

# RarArchive::setAllowBroken

(PECL rar >= 3.0.0)

RarArchive::setAllowBroken — Whether opening broken archives is allowed

### 说明

面向对象风格 (method):

public function RarArchive::setAllowBroken(bool `$allow_broken`): bool

过程化风格:

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.

### 参数

`rarfile`
  A RarArchive object, opened with rar_open().
`allow_broken`
  Whether to allow reading broken files (`true`) or not (`false`).

### 返回值

Returns `true` 或者在失败时返回 `false`. It will only fail if the file has already been closed.

### 示例

示例 #1 面向对象风格

    <?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));
    ?>

以上示例的输出类似于：

    RarEntry for file "file1.txt" (52b28202)
    int(1)

示例 #2 过程化风格

    <?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));
    ?>

### 参见

- RarArchive::isBroken() - Test whether an archive is broken (incomplete)

# RarArchive::__toString

(PECL rar >= 2.0.0)

RarArchive::__toString — Get text representation

### 说明

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.

### 参数

此函数没有参数。

### 返回值

A textual representation of this RarArchive object. The content of this representation is unspecified.

### 示例

示例 #1 RarArchive::__toString() example

    <?php
    $rar_arch = RarArchive::open('latest_winrar.rar');
    echo $rar_arch."\n";
    $rar_arch->close();
    echo $rar_arch."\n";
    ?>

以上示例的输出类似于：

    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar"
    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)

## 目录

- 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)

## 简介

A RAR entry, representing a directory or a compressed file inside a RAR archive.

## 类摘要

final class RarEntry {
/* 常量 */
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;
/* 方法 */
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
}

## 预定义常量

`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

### 说明

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.

### 参数

`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.

警告

Prior to version 2.0.0, this function would not handle relative paths correctly. Use realpath() as a workaround.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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

    ?>

示例 #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);

    ?>

### 参见

- RarEntry::getStream() - Get file handler for entry
- `rar://` wrapper

# RarEntry::getAttr

(PECL rar >= 0.1)

RarEntry::getAttr — Get attributes of the entry

### 说明

public function RarEntry::getAttr(): int

Returns the OS-dependent attributes of the archive entry.

### 参数

此函数没有参数。

### 返回值

Returns the attributes or `false` on error.

### 示例

示例 #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);

    ?>

### 参见

- RarEntry::getHostOs() - Get entry host OS
- The constants in RarEntry

# RarEntry::getCrc

(PECL rar >= 0.1)

RarEntry::getCrc — Get CRC of the entry

### 说明

public function RarEntry::getCrc(): string

Returns an hexadecimal string representation of the CRC of the archive entry.

### 参数

此函数没有参数。

### 返回值

Returns the CRC of the archive entry or `false` on error.

### 更新日志

版本 | 说明
--- | ---
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

### 说明

public function RarEntry::getFileTime(): string

Gets entry last modification time.

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function RarEntry::getHostOs(): int

Returns the code of the host OS of the archive entry.

### 参数

此函数没有参数。

### 返回值

Returns the code of the host OS, or `false` on error.

### 示例

示例 #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;
    }

    ?>

示例 #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;
    }

    ?>

### 参见

- RarEntry::extract() - Extract entry from the archive

# RarEntry::getMethod

(PECL rar >= 0.1)

RarEntry::getMethod — Get pack method of the entry

### 说明

public function RarEntry::getMethod(): int

RarEntry::getMethod() returns number of the method used when adding current archive entry.

### 参数

此函数没有参数。

### 返回值

Returns the method number or `false` on error.

### 示例

示例 #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

### 说明

public function RarEntry::getName(): string

Returns the name (with path) of the archive entry.

### 参数

此函数没有参数。

### 返回值

Returns the entry name as a string, or `false` on error.

### 更新日志

版本 | 说明
--- | ---
PECL rar 2.0.0 | As of version 2.0.0, the returned string is encoded in Unicode/UTF-8.

### 示例

示例 #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

### 说明

public function RarEntry::getPackedSize(): int

Get packed size of the archive entry.

> 注意: 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`.

### 参数

此函数没有参数。

### 返回值

Returns the packed size, or `false` on error.

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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

### 说明

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().

警告

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.

### 参数

`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().

### 返回值

The file handler 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
PECL rar 3.0.0 | Support for RAR archives with repeated entry names is no longer defective.

### 示例

示例 #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);

    ?>

### 参见

- RarEntry::extract() - Extract entry from the archive
- `rar://` wrapper

# RarEntry::getUnpackedSize

(PECL rar >= 0.1)

RarEntry::getUnpackedSize — Get unpacked size of the entry

### 说明

public function RarEntry::getUnpackedSize(): int

Get unpacked size of the archive entry.

> 注意: 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`.

### 参数

此函数没有参数。

### 返回值

Returns the unpacked size, or `false` on error.

### 更新日志

版本 | 说明
--- | ---
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.

### 返回值

示例 #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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the version or `false` on error.

### 示例

示例 #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

### 说明

public function RarEntry::isDirectory(): bool

Tests whether the current entry is a directory.

### 参数

此函数没有参数。

### 返回值

Returns `true` if this entry is a directory and `false` otherwise.

### 注释

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

### 说明

public function RarEntry::isEncrypted(): bool

Tests whether the current entry contents are encrypted.

> 注意: The password used may differ between files inside the same RAR archive.

### 参数

此函数没有参数。

### 返回值

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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

A textual representation for the entry.

## 目录

- 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)

## 简介

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

## 类摘要

final class RarException extends Exception {
/* 方法 */
public static function isUsingExceptions(): bool
public static function setUsingExceptions(bool `$using_exceptions`): void
/* 继承的方法 */
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

### 说明

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).

### 参数

此函数没有参数。

### 返回值

Returns `true` if exceptions are being used, `false` otherwise.

### 示例

示例 #1 RarException::isUsingExceptions() example

    <?php
    //The default is not to use exceptions
    var_dump(RarException::isUsingExceptions());
    ?>

以上示例的输出类似于：

    bool(false)

### 参见

- 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

### 说明

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().

### 参数

`using_exceptions`
  Should be `true` to activate exception throwing, `false` to deactivate (the default).

### 返回值

没有返回值。

### 示例

示例 #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
    ?>

以上示例的输出类似于：

    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

### 参见

- RarException::isUsingExceptions() - Check whether error handling with exceptions is in use

## 目录

- RarException::isUsingExceptions — Check whether error handling with exceptions is in use
- RarException::setUsingExceptions — Activate and deactivate error handling with exceptions

- 安装/配置
  - 安装
  - 资源类型
- 预定义常量
- 示例
- Rar 函数
  - rar_wrapper_cache_stats — Cache hits and misses for the 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

# 简介

此扩展能够透明地读取或写入 ZIP 压缩档案及其中的文件。

# 安装/配置

## 目录

- 需求
- 安装
- 资源类型

## 需求

此扩展需要 » libzip。在 7.3 及其以前的版本，1.1.2 版本都捆绑在 PHP 中。

最低支持版本为 0.11，但强烈建议使用更高版本。

- 加密支持需要版本 1.2，参阅 ZipArchive::setEncryptionIndex()
- 进度支持需要版本 1.3，参阅 ZipArchive::registerProgressCallback()
- 取消支持（cancel support）需要版本 1.6 版，参阅 ZipArchive::registerCancelCallback()

## 安装

## Linux 系统

必须在编译 PHP 时用 --with-zip 配置选项来提供 zip 支持来使用这些方法。

PHP 7.4.0 之前，PHP 捆绑了 libzip，编译扩展需要使用 --enable-zip 配置项。从 PHP 7.3.0 开始, 不鼓励使用捆绑的 libzip 进行构建，但仍然可以使用 --without-libzip 配置项。

新增 --with-libzip=DIR 配置选项以使用系统 libzip 安装。需要 libzip 版本 0.11，推荐使用 0.11.2 或更高版本。

## Windows

从 PHP 8.2.0 开始，必须在 php.ini 中启用 php_zip.dll DLL。以前内置此扩展。

## 通过 PECL 安装

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/zip.

## 资源类型

在 Zip 模块里用到两种资源类型。第一种是 Zip 文档的 Zip 目录，第二种是文档条目的 Zip 条目。

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

ZipArchive 使用类常量。有各种类型的常量，主要有：Flag（以 `FL_` 为前缀）、全局 Flag（以 `AFL_` 为前缀）、错误（以 `ER_` 为前缀）以及模式（没有前缀）。

归档打开模式
`ZIPARCHIVE::CREATE` (int)
  如果不存在则创建归档。
`ZIPARCHIVE::OVERWRITE` (int)
  如果归档存在，则忽略其当前内容。换句话说，处理方式与空归档相同。
`ZIPARCHIVE::EXCL` (int)
  如果归档已经存在，则出错。
`ZipArchive::RDONLY` (int)
  只读模式打开归档。 在 PHP 7.4.3 和 PECL zip 1.17.1 中可用，前提是编译时使用的 libzip 版本大于等于 1.0.0。
`ZIPARCHIVE::CHECKCONS` (int)
  对归档执行额外的一致性检查，如果失败则显示错误。

归档全局 flag
`ZipArchive::AFL_RDONLY` (int)
  归档只读，无法清除。如果构建时使用的是 libzip ≥ 1.10.0，分别在 PHP 8.3.0 和 PECL zip 1.22.0 中可用。
`ZipArchive::AFL_IS_TORRENTZIP` (int)
  当前归档是 torrentzipped（使用 BitTorrent 压缩）。如果构建时使用的是 libzip ≥ 1.10.0，分别在 PHP 8.3.0 和 PECL zip 1.22.0 中可用。
`ZipArchive::AFL_WANT_TORRENTZIP` (int)
  使用 torrentzip 格式写入归档。如果构建时使用的是 libzip ≥ 1.10.0，分别在 PHP 8.3.0 和 PECL zip 1.22.0 中可用。
`ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE` (int)
  归档为空时不要删除文件。如果构建时使用的是 libzip ≥ 1.10.0，分别在 PHP 8.3.0 和 PECL zip 1.22.0 中可用。

归档 flag
`ZIPARCHIVE::FL_NOCASE` (int)
  名称查找时忽略大小写。
`ZIPARCHIVE::FL_NODIR` (int)
  忽略目录部分
`ZIPARCHIVE::FL_COMPRESSED` (int)
  读取压缩数据
`ZIPARCHIVE::FL_UNCHANGED` (int)
  使用原始数据，忽略更改。
`ZipArchive::FL_RECOMPRESS` (int)
  强制重新压缩数据。 PHP 8.0.0 和 PECL zip 1.18.0 起可以使用。 从 PHP 8.3.0 和 PECL zip 1.22.1 起已被弃用， 将在 libzip 的未来版本中被删除。
`ZipArchive::FL_ENCRYPTED` (int)
  读取加密数据（意味着 FL_COMPRESSED）。 PHP 8.0.0 和 PECL zip 1.18.0 起可以使用。
`ZipArchive::FL_OVERWRITE` (int)
  如果文件名称存在，重写（覆盖）它。 PHP 8.0.0 和 PECL zip 1.18.0 起可以使用。
`ZipArchive::FL_LOCAL` (int)
  在本地 header 中。 PHP 8.0.0 和 PECL zip 1.18.0 起可以使用。
`ZipArchive::FL_CENTRAL` (int)
  In central directory. PHP 8.0.0 和 PECL zip 1.18.0 起可以使用。
`ZipArchive::FL_ENC_GUESS` (int)
  猜测字符串编码（默认情况）。从 PHP 7.0.8 起可用。
`ZipArchive::FL_ENC_RAW` (int)
  获取未修改的字符串。从 PHP 7.0.8 起可用。
`ZipArchive::FL_ENC_STRICT` (int)
  严格遵循规范要求。从 PHP 7.0.8 起可用。
`ZipArchive::FL_ENC_UTF_8` (int)
  字符串是 UTF-8 编码。从 PHP 7.0.8 起可用。
`ZipArchive::FL_ENC_CP437` (int)
  字符串是 CP437 编码。从 PHP 7.0.8 起可用。
`ZipArchive::FL_OPEN_FILE_NOW` (int)
  在添加文件，而不是等待归档关闭时打开文件。需要注意文件描述符消耗的情况。 从 PHP 8.3.0 和 PECL zip 1.22.1 起可用。

压缩模式
`ZIPARCHIVE::CM_DEFAULT` (int)
  更好的压缩或存储。
`ZIPARCHIVE::CM_STORE` (int)
  存储（不压缩）。
`ZIPARCHIVE::CM_SHRINK` (int)
  收缩
`ZIPARCHIVE::CM_REDUCE_1` (int)
  用因子 1 换算
`ZIPARCHIVE::CM_REDUCE_2` (int)
  用因子 2 换算
`ZIPARCHIVE::CM_REDUCE_3` (int)
  用因子 3 换算
`ZIPARCHIVE::CM_REDUCE_4` (int)
  用因子 4 换算
`ZIPARCHIVE::CM_IMPLODE` (int)
  聚爆
`ZIPARCHIVE::CM_DEFLATE` (int)
  deflated
`ZIPARCHIVE::CM_DEFLATE64` (int)
  deflate64
`ZIPARCHIVE::CM_PKWARE_IMPLODE` (int)
  PKWARE imploding
`ZIPARCHIVE::CM_BZIP2` (int)
  BZIP2 算法
`ZipArchive::CM_LZMA` (int)
  LZMA 算法
`ZipArchive::CM_LZMA2` (int)
  LZMA2 algorithm. Available as of PHP 7.4.3 and PECL zip 1.16.0, respectively, if built against libzip ≥ 1.6.0.
`ZipArchive::CM_ZSTD` (int)
  Zstandard（zstd）压缩算法。如果针对 libzip ≥ 1.8.0 编译，则分别从 PHP 8.0.0 和 PECL zip 1.19.1 开始可用。
`ZipArchive::CM_XZ` (int)
  XZ 算法。 在 PHP 7.4.3 和 PECL zip 1.16.1 中可用，前提是编译时使用的 libzip 版本大于等于 1.6.0。
`ZipArchive::CM_TERSE` (int)
`ZipArchive::CM_LZ77` (int)
`ZipArchive::CM_WAVPACK` (int)
`ZipArchive::CM_PPMD` (int)

错误
`ZIPARCHIVE::ER_OK` (int)
  没有错误。
`ZIPARCHIVE::ER_MULTIDISK` (int)
  不支持多磁盘 zip 归档。
`ZIPARCHIVE::ER_RENAME` (int)
  重命名临时文件失败。
`ZIPARCHIVE::ER_CLOSE` (int)
  关闭 zip 归档失败
`ZIPARCHIVE::ER_SEEK` (int)
  寻址错误
`ZIPARCHIVE::ER_READ` (int)
  读取错误
`ZIPARCHIVE::ER_WRITE` (int)
  写入错误
`ZIPARCHIVE::ER_CRC` (int)
  CRC校验失败
`ZIPARCHIVE::ER_ZIPCLOSED` (int)
  zip 归档已关闭
`ZIPARCHIVE::ER_NOENT` (int)
  没有文件
`ZIPARCHIVE::ER_EXISTS` (int)
  文件已经存在
`ZIPARCHIVE::ER_OPEN` (int)
  不能打开文件
`ZIPARCHIVE::ER_TMPOPEN` (int)
  创建临时文件失败
`ZIPARCHIVE::ER_ZLIB` (int)
  Zlib错误
`ZIPARCHIVE::ER_MEMORY` (int)
  内存分配失败
`ZIPARCHIVE::ER_CHANGED` (int)
  条目已被改变
`ZIPARCHIVE::ER_COMPNOTSUPP` (int)
  不支持的压缩方式
`ZIPARCHIVE::ER_EOF` (int)
  过早的EOF
`ZIPARCHIVE::ER_INVAL` (int)
  无效的参数
`ZIPARCHIVE::ER_NOZIP` (int)
  不是 zip 归档
`ZIPARCHIVE::ER_INTERNAL` (int)
  内部错误
`ZIPARCHIVE::ER_INCONS` (int)
  Zip 归档不一致
`ZIPARCHIVE::ER_REMOVE` (int)
  不能移除文件
`ZIPARCHIVE::ER_DELETED` (int)
  条目已删除
`ZipArchive::ER_ENCRNOTSUPP` (int)
  不支持的压缩方式。 PHP 7.4.3 和 PECL zip 1.16.1 起可用。
`ZipArchive::ER_RDONLY` (int)
  归档只读。 分别于 PHP 7.4.3 和 PECL zip 1.16.1 起可用。
`ZipArchive::ER_NOPASSWD` (int)
  没有提供密码。 分别于 PHP 7.4.3 和 PECL zip 1.16.1 起可用。
`ZipArchive::ER_WRONGPASSWD` (int)
  提供的密码错误。 分别于 PHP 7.4.3 和 PECL zip 1.16.1 起可用。
`ZipArchive::ER_OPNOTSUPP` (int)
  操作不支持。 在 PHP 7.4.3 和 PECL zip 1.16.1 中可用，前提是编译时使用的 libzip 版本大于等于 1.0.0。
`ZipArchive::ER_INUSE` (int)
  资源仍在使用。 在 PHP 7.4.3 和 PECL zip 1.16.1 中可用，前提是编译时使用的 libzip 版本大于等于 1.0.0。
`ZipArchive::ER_TELL` (int)
  Tell error. 在 PHP 7.4.3 和 PECL zip 1.16.1 中可用，前提是编译时使用的 libzip 版本大于等于 1.0.0。
`ZipArchive::ER_COMPRESSED_DATA` (int)
  压缩数据无效。 在 PHP 7.4.3 和 PECL zip 1.16.1 中可用，前提是编译时使用的 libzip 版本大于等于 1.6.0。
`ZipArchive::ER_CANCELLED` (int)
  操作已取消。 在 PHP 7.4.3 和 PECL zip 1.16.1 中可用，前提是编译时使用的 libzip 版本大于等于 1.6.0。
`ZipArchive::ER_DATA_LENGTH` (int)
  数据长度异常。如果构建时使用的是 libzip ≥ 1.10.0，分别在 PHP 8.3.0 和 PECL zip 1.22.0 中可用。
`ZipArchive::ER_NOT_ALLOWED` (int)
  在 torrentzip 中不允许。如果构建时使用的是 libzip ≥ 1.10.0，分别在 PHP 8.3.0 和 PECL zip 1.22.0 中可用。
`ZipArchive::ER_TRUNCATED_ZIP` (int)
  可能截断或损坏的 zip 归档。 如果构建时使用的是 libzip ≥ 1.11.1， 分别在 PHP 8.4.0 和 PECL zip 1.22.4 中可用。

加密模式
`ZipArchive::EM_NONE` (int)
  没有加密。分别从 PHP 7.2.0 和 PECL zip 1.14.0 开始可用。
`ZipArchive::EM_TRAD_PKWARE` (int)
  传统 PKWARE 加密。分别从 PHP 8.0.0 和 PECL zip 1.19.0 开始可用。
`ZipArchive::EM_AES_128` (int)
  AES 128 encryption, since PHP 7.2.0, PECL zip 1.14.0
`ZipArchive::EM_AES_192` (int)
  AES 1192 encryption, since PHP 7.2.0, PECL zip 1.14.0
`ZipArchive::EM_AES_256` (int)
  AES 256 encryption, since PHP 7.2.0, PECL zip 1.14.0
`ZipArchive::EM_UNKNOWN` (int)
  未知的加密算法。分别从 PHP 8.0.0 和 PECL zip 1.19.0 开始可用。

length 参数常量
`ZipArchive::LENGTH_TO_END` (int)
  使用的文件大小，如果文件增大，将会忽略附加数据，如果文件变小，则会引发错误（`ZipArchive::ER_DATA_LENGTH`）。 自 PHP 8.3.0 和 PECL zip 1.22.2 起可用。
`ZipArchive::LENGTH_UNCHECKED` (int)
  使用所有可用的数据。如果针对 libzip ≥ 1.10.1 编译，自 PHP 8.3.0 和 PECL zip 1.22.2 起可用。

其它常量
`ZipArchive::LIBZIP_VERSION` (string)
  Zip 库版本。从 PHP 7.4.3 和 PECL zip 1.16.0 开始起可用。

外部属性的操作系统常量
`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)
  自 PECL zip 1.12.4 起可用

# 示例

示例 #1 创建 Zip 归档

    <?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();
    ?>

示例 #2 输出文档细节和列表

    <?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";
    ?>

示例 #3 Zip 流封装，读取 OpenOffice 文件的元信息

    <?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);
    ?>

此例使用了旧的 API（PHP 4），它打开了 ZIP 文件归档，读取归档里的每个文件，并输出文件内容。此例用到的 test2.zip 文档是 ZZIPlib 源分布里测试文档中的一个。

示例 #4 Zip 使用范例

    <?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);

    }
    ?>

# ZipArchive 类

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

## 简介

用 Zip 压缩的文件归档。

## 类摘要

class ZipArchive implements Countable {
/* 常量 */
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;
/* 属性 */
public readonly int $lastId;
public readonly int $status;
public readonly int $statusSys;
public readonly int $numFiles;
public readonly string $filename;
public readonly string $comment;
/* 方法 */
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
}

## 属性

lastId
  最后新增的条目（文件或目录）索引值。 从 PHP 8.0.0 和 PECL zip 1.18.0 开始可用。
status
  Zip 归档的状态。从 PHP 8.0.0 和 PECL zip 1.18.0 开始，可用于关闭归档。
statusSys
  Zip 归档的系统状态。从 PHP 8.0.0 和 PECL zip 1.18.0 开始，可用于关闭归档。
numFiles
  归档里的文件数
filename
  在文件系统里的文件名
comment
  归档里的注释

# ZipArchive::addEmptyDir

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.8.0)

ZipArchive::addEmptyDir — Add a new directory

### 说明

public function ZipArchive::addEmptyDir(string `$dirname`, int `$flags` = 0): bool

Adds an empty directory in the archive.

### 参数

`dirname`
  The directory to add.
`flags`
  Bitmask consisting of `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`. The behaviour of these constants is described on the ZIP constants page.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL zip 1.18.0 | `flags` was added.

### 示例

示例 #1 Create a new directory in an archive

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        if($zip->addEmptyDir('newDirectory')) {
            echo 'Created a new root directory';
        } else {
            echo 'Could not create the directory';
        }
        $zip->close();
    } else {
        echo 'failed';
    }
    ?>

# ZipArchive::addFile

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::addFile — Adds a file to a ZIP archive from the given path

### 说明

public function ZipArchive::addFile(
string `$filepath`,
string `$entryname` = "",
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = `ZipArchive::FL_OVERWRITE`
): bool

Adds a file to a ZIP archive from a given path.

> 注意: 为了最大限度地提高代码可移植性，建议在 ZIP 文件名中使用斜线 (`/`) 做为目录分隔符。

### 参数

`filepath`
  The path to the file to add.
`entryname`
  If supplied and not empty, this is the local name inside the ZIP archive that will override the `filepath`.
`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_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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL zip 1.18.0 | `flags` was added.
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.

### 示例

This example opens a ZIP file archive test.zip and add the file /path/to/index.txt. as newname.txt.

示例 #1 Open and add

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->addFile('/path/to/index.txt', 'newname.txt');
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

### 注释

> 注意: When a file is set to be added to the archive, PHP will lock the file. The lock is only released once the ZipArchive object has been closed, either via ZipArchive::close() or the ZipArchive object being destroyed. This may prevent you from being able to delete the file being added until after the lock has been released.

### 参见

- 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 — Add a file to a ZIP archive using its contents

### 说明

public function ZipArchive::addFromString(string `$name`, string `$content`, int `$flags` = `ZipArchive::FL_OVERWRITE`): bool

Add a file to a ZIP archive using its contents.

> 注意: 为了最大限度地提高代码可移植性，建议在 ZIP 文件名中使用斜线 (`/`) 做为目录分隔符。

### 参数

`name`
  The name of the entry to create.
`content`
  The contents to use to create the entry. It is used in a binary safe mode.
`flags`
  Bitmask consisting of `ZipArchive::FL_OVERWRITE`, `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`. The behaviour of these constants is described on the ZIP constants page.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL zip 1.18.0 | `flags` was added.

### 示例

示例 #1 Add an entry to a new archive

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('test.txt', 'file content goes here');
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

示例 #2 Add file to a directory inside an archive

    <?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 'failed';
    }
    ?>

# 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

### 说明

public function ZipArchive::addGlob(string `$pattern`, int `$flags` = 0, array `$options` = []): array|false

Add files from a directory which match the glob `pattern`.

> 注意: 为了最大限度地提高代码可移植性，建议在 ZIP 文件名中使用斜线 (`/`) 做为目录分隔符。

### 参数

`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.

### 返回值

An array of added files on success 或者在失败时返回 `false`

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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();
    }
    ?>

### 参见

- ZipArchive::addFile() - Adds a file to a ZIP archive from the given path
- 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

### 说明

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.

### 参数

`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().

### 返回值

An array of added files on success 或者在失败时返回 `false`

### 示例

示例 #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();
    }
    ?>

### 参见

- ZipArchive::addFile() - Adds a file to a ZIP archive from the given path
- ZipArchive::addGlob() - Add files from a directory by glob pattern

# ZipArchive::clearError

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::clearError — 清除状态错误消息、系统和/或 zip 消息

### 说明

public function ZipArchive::clearError(): void

清除状态错误消息、系统和/或 zip 消息。

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 参见

- ZipArchive::getStatusString() - Returns the status error message, system and/or zip messages

# ZipArchive::close

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::close — Close the active archive (opened or newly created)

### 说明

public function ZipArchive::close(): bool

Close opened or created archive and save changes. This method is automatically called at the end of the script.

If the archive contains no files, the file is completely removed by default (no empty archive is written) according to the value of the `ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE` global flag.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ZipArchive::setArchiveFlag() - 设置 ZIP 归档的全局 flag

# ZipArchive::count

(PHP 7 >= 7.2.0, PHP 8, PECL zip >= 1.15.0)

ZipArchive::count — Counts the number of files in the archive

### 说明

public function ZipArchive::count(): int

### 参数

此函数没有参数。

### 返回值

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 — Delete an entry in the archive using its index

### 说明

public function ZipArchive::deleteIndex(int `$index`): bool

Delete an entry in the archive using its index.

### 参数

`index`
  Index of the entry to delete.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Delete file from archive using its index

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->deleteIndex(2);
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

# ZipArchive::deleteName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::deleteName — Delete an entry in the archive using its name

### 说明

public function ZipArchive::deleteName(string `$name`): bool

Delete an entry in the archive using its name.

### 参数

`name`
  Name of the entry to delete.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Deleting a file and directory from an archive, using names

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test1.zip') === TRUE) {
        $zip->deleteName('testfromfile.php');
        $zip->deleteName('testDir/');
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

# ZipArchive::extractTo

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::extractTo — 解压缩文件

### 说明

public function ZipArchive::extractTo(string `$pathto`, array|string|null `$files` = `null`): bool

将完整归档或指定文件提取到指定的目录。

警告

提取的文件和目录的默认权限提供尽可能广泛的访问权限。这可以通过设置当前 umask 来限制，可以使用 umask() 更改。

出于安全原因，不会恢复原始权限。有关如何还原的示例，请参阅 ZipArchive::getExternalAttributesIndex() 页面上的代码示例。

### 参数

`pathto`
  解压缩的本地目标路径
`files`
  要提取的条目。接受单个条目名称或名称数组。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 提取所有条目

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->extractTo('/my/destination/dir/');
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

示例 #2 提取两个条目

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test_im.zip');
    if ($res === TRUE) {
        $zip->extractTo('/my/destination/dir/', array('pear_item.gif', 'testfromfile.php'));
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

### 注释

> 注意: Windows NTFS file systems do not support some characters in filenames, namely `<|>*?":`. Filenames with a trailing dot are not supported either. Contrary to some extraction tools, this method does not replace these characters with an underscore, but instead fails to extract such files.

# ZipArchive::getArchiveComment

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getArchiveComment — Returns the Zip archive comment

### 说明

public function ZipArchive::getArchiveComment(int `$flags` = 0): string|false

Returns the Zip archive comment.

### 参数

`flags`
  If flags is set to `ZipArchive::FL_UNCHANGED`, the original unchanged comment is returned.

### 返回值

Returns the Zip archive comment 或者在失败时返回 `false`.

### 示例

示例 #1 Dump an archive comment

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test_with_comment.zip');
    if ($res === TRUE) {
        var_dump($zip->getArchiveComment());
        /* Or using the archive property */
        var_dump($zip->comment);
    } else {
        echo 'failed, code:' . $res;
    }
    ?>

# ZipArchive::getArchiveFlag

(PHP >= 8.3.0, PECL zip >= 1.22.0)

ZipArchive::getArchiveFlag — 返回 Zip 归档全局 flag 的值

### 说明

public function ZipArchive::getArchiveFlag(int `$flag`, int `$flags` = 0): int

返回 Zip 归档全局 flag 的值。

### 参数

`flag`

  检索的全局 flag，包含 `AFL_*` 常量：

  - `ZipArchive::AFL_RDONLY`
  - `ZipArchive::AFL_IS_TORRENTZIP`
  - `ZipArchive::AFL_WANT_TORRENTZIP`
  - `ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE`
`flags`
  如果将 `flags` 设置为 `ZipArchive::FL_UNCHANGED`，则返回原始未更改的 flag。

### 返回值

如果 flag 在归档中设置了，返回 1，没有返回 0，发生错误，返回 -1。

### 示例

示例 #1 测试归档是否是 torrentzip 格式

    <?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;
    }

    ?>

### 参见

- ZipArchive::setArchiveFlag() - 设置 ZIP 归档的全局 flag

# ZipArchive::getCommentIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::getCommentIndex — Returns the comment of an entry using the entry index

### 说明

public function ZipArchive::getCommentIndex(int `$index`, int `$flags` = 0): string|false

Returns the comment of an entry using the entry index.

### 参数

`index`
  Index of the entry
`flags`
  If flags is set to `ZipArchive::FL_UNCHANGED`, the original unchanged comment is returned.

### 返回值

Returns the comment on success 或者在失败时返回 `false`.

### 示例

示例 #1 Dump an entry comment

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test1.zip');
    if ($res === TRUE) {
        var_dump($zip->getCommentIndex(1));
    } else {
        echo 'failed, code:' . $res;
    }
    ?>

# ZipArchive::getCommentName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::getCommentName — Returns the comment of an entry using the entry name

### 说明

public function ZipArchive::getCommentName(string `$name`, int `$flags` = 0): string|false

Returns the comment of an entry using the entry name.

### 参数

`name`
  Name of the entry
`flags`
  If flags is set to `ZipArchive::FL_UNCHANGED`, the original unchanged comment is returned.

### 返回值

Returns the comment on success 或者在失败时返回 `false`.

### 示例

示例 #1 Dump an entry comment

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test1.zip');
    if ($res === TRUE) {
        var_dump($zip->getCommentName('test/entry1.txt'));
    } else {
        echo 'failed, 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

This example extract all the entries of a ZIP archive test.zip and set the Unix rights from external attributes.

示例 #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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# ZipArchive::getFromIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getFromIndex — Returns the entry contents using its index

### 说明

public function ZipArchive::getFromIndex(int `$index`, int `$len` = 0, int `$flags` = 0): string|false

Returns the entry contents using its index.

### 参数

`index`
  Index of the entry
`len`
  The length to be read from the entry. If `0`, then the entire entry is read.
`flags`

  The flags to use to open the archive. the following values may be ORed to it.

  - `ZipArchive::FL_UNCHANGED`
  - `ZipArchive::FL_COMPRESSED`

### 返回值

Returns the contents of the entry on success 或者在失败时返回 `false`.

### 示例

示例 #1 Get the file contents

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        echo $zip->getFromIndex(2);
        $zip->close();
    } else {
        echo 'failed';
    }
    ?>

### 参见

- ZipArchive::getFromName() - Returns the entry contents using its name

# ZipArchive::getFromName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getFromName — Returns the entry contents using its name

### 说明

public function ZipArchive::getFromName(string `$name`, int `$len` = 0, int `$flags` = 0): string|false

Returns the entry contents using its name.

### 参数

`name`
  Name of the entry
`len`
  The length to be read from the entry. If `0`, then the entire entry is read.
`flags`

  The flags to use to find the entry. The following values may be ORed.

  - `ZipArchive::FL_UNCHANGED`
  - `ZipArchive::FL_COMPRESSED`
  - `ZipArchive::FL_NOCASE`

### 返回值

Returns the contents of the entry on success 或者在失败时返回 `false`.

### 示例

示例 #1 Get the file contents

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test1.zip') === TRUE) {
        echo $zip->getFromName('testfromfile.php');
        $zip->close();
    } else {
        echo 'failed';
    }
    ?>

示例 #2 Convert an image from a zip entry

    <?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');
    }
    ?>

### 参见

- ZipArchive::getFromIndex() - Returns the entry contents using its index

# ZipArchive::getNameIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::getNameIndex — Returns the name of an entry using its index

### 说明

public function ZipArchive::getNameIndex(int `$index`, int `$flags` = 0): string|false

Returns the name of an entry using its index.

### 参数

`index`
  Index of the entry.
`flags`
  If flags is set to `ZipArchive::FL_UNCHANGED`, the original unchanged name is returned.

### 返回值

Returns the name on success 或者在失败时返回 `false`.

### 示例

示例 #1 ZipArchive::getNameIndex() example

    <?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 — Returns the status error message, system and/or zip messages

### 说明

public function ZipArchive::getStatusString(): string

Returns the status error message, system and/or zip messages.

### 参数

此函数没有参数。

### 返回值

Returns a string with the status message.

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL zip 1.18.0 | This method can be called on closed archive.
8.0.0, PECL zip 1.18.0 | This method no longer returns `false` on failure.

# ZipArchive::getStream

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getStream — Get a file handler to the entry defined by its name (read only)

### 说明

public function ZipArchive::getStream(string `$name`): resource|false

Get a file handler to the entry defined by its name. For now, it only supports read operations.

### 参数

`name`
  The name of the entry to use.

### 返回值

Returns a file pointer (resource) on success 或者在失败时返回 `false`.

### 示例

示例 #1 Get the entry contents with fread() and store it

    <?php
    $contents = '';
    $z = new ZipArchive();
    if ($z->open('test.zip')) {
        $fp = $z->getStream('test');
        if(!$fp) exit("failed\n");

        while (!feof($fp)) {
            $contents .= fread($fp, 2);
        }

        fclose($fp);
        file_put_contents('t',$contents);
        echo "done.\n";
    }
    ?>

示例 #2 Same as the previous example but with fopen() and the zip stream wrapper

    <?php
    $contents = '';
    $fp = fopen('zip://' . dirname(__FILE__) . '/test.zip#test', 'r');
    if (!$fp) {
        exit("cannot open\n");
    }
    while (!feof($fp)) {
        $contents .= fread($fp, 2);
    }
    echo "$contents\n";
    fclose($fp);
    echo "done.\n";
    ?>

示例 #3 Stream wrapper and image, can be used with the xml function as well

    <?php
    $im = imagecreatefromgif('zip://' . dirname(__FILE__) . '/test_im.zip#pear_item.gif');
    imagepng($im, 'a.png');
    ?>

### 参见

- 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)
- Compression Streams

# 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)

### 说明

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.

### 参数

`index`
  Index of the entry
`flags`
  If flags is set to `ZipArchive::FL_UNCHANGED`, the original unchanged stream is returned.

### 返回值

Returns a file pointer (resource) on success 或者在失败时返回 `false`.

### 示例

示例 #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);
    }
    ?>

### 参见

- 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)

### 说明

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.

### 参数

`name`
  The name of the entry to use.
`flags`
  If flags is set to `ZipArchive::FL_UNCHANGED`, the original unchanged stream is returned.

### 返回值

Returns a file pointer (resource) on success 或者在失败时返回 `false`.

### 示例

示例 #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);
    }
    ?>

### 参见

- 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

### 说明

public static function ZipArchive::isCompressionMethodSupported(int `$method`, bool `$enc` = `true`): bool

Check if a compression method is supported by libzip.

### 参数

`method`
  The compression method, one of the `ZipArchive::CM_*` constants.
`enc`
  If `true` check for compression, else check for decompression.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 注释

> 注意: This function is only available if built against libzip ≥ 1.7.0.

### 参见

- 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

### 说明

public static function ZipArchive::isEncryptionMethodSupported(int `$method`, bool `$enc` = `true`): bool

Check if a compression method is supported by libzip.

### 参数

`method`
  The encryption method, one of the `ZipArchive::EM_*` constants.
`enc`
  If `true` check for encryption, else check for decryption.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 注释

> 注意: This function is only available if built against libzip ≥ 1.7.0.

### 参见

- 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 — Returns the index of the entry in the archive

### 说明

public function ZipArchive::locateName(string `$name`, int `$flags` = 0): int|false

Locates an entry using its name.

### 参数

`name`
  The name of the entry to look up
`flags`

  The flags are specified by ORing the following values, or 0 for none of them.

  - `ZipArchive::FL_NOCASE`
  - `ZipArchive::FL_NODIR`

### 返回值

Returns the index of the entry on success 或者在失败时返回 `false`.

### 示例

示例 #1 Create an archive and then use it with ZipArchive::locateName()

    <?php
    $file = 'testlocate.zip';

    $zip = new ZipArchive;
    if ($zip->open($file, ZipArchive::CREATE) !== TRUE) {
        exit('failed');
    }

    $zip->addFromString('entry1.txt', 'entry #1');
    $zip->addFromString('entry2.txt', 'entry #2');
    $zip->addFromString('dir/entry2d.txt', 'entry #2');

    if ($zip->status !== ZipArchive::ER_OK) {
        echo "failed to write zip\n";
    }
    $zip->close();

    if ($zip->open($file) !== TRUE) {
        exit('failed');
    }

    echo $zip->locateName('entry1.txt') . "\n";
    echo $zip->locateName('eNtry2.txt') . "\n";
    echo $zip->locateName('eNtry2.txt', ZipArchive::FL_NOCASE) . "\n";
    echo $zip->locateName('enTRy2d.txt', ZipArchive::FL_NOCASE|ZipArchive::FL_NODIR) . "\n";
    $zip->close();

    ?>

以上示例会输出：

    0

    1
    2

# ZipArchive::open

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::open — Open a ZIP file archive

### 说明

public function ZipArchive::open(string `$filename`, int `$flags` = 0): bool|int

Opens a new or existing zip archive for reading, writing or modifying.

Since libzip 1.6.0, an empty file is not a valid archive any longer.

### 参数

`filename`
  The file name of the ZIP archive to open.
`flags`

  The mode to use to open the archive.

  - `ZipArchive::OVERWRITE`
  - `ZipArchive::CREATE`
  - `ZipArchive::RDONLY`
  - `ZipArchive::EXCL`
  - `ZipArchive::CHECKCONS`

### 返回值

Returns `true` on success, `false` or one of the following error codes on error:

`ZipArchive::ER_EXISTS`
  File already exists.
`ZipArchive::ER_INCONS`
  Zip archive inconsistent.
`ZipArchive::ER_INVAL`
  Invalid argument.
`ZipArchive::ER_MEMORY`
  Malloc failure.
`ZipArchive::ER_NOENT`
  No such file.
`ZipArchive::ER_NOZIP`
  Not a zip archive.
`ZipArchive::ER_OPEN`
  Can't open file.
`ZipArchive::ER_READ`
  Read error.
`ZipArchive::ER_SEEK`
  Seek error.

### 示例

示例 #1 Open and extract

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        echo 'ok';
        $zip->extractTo('test');
        $zip->close();
    } else {
        echo 'failed, code:' . $res;
    }
    ?>

示例 #2 Create an archive

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('test.txt', 'file content goes here');
        $zip->addFile('data.txt', 'entryname.txt');
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

示例 #3 Create an temporary archive

    <?php
    $name = tempnam(sys_get_temp_dir(), "FOO");
    $zip = new ZipArchive;
    $res = $zip->open($name, ZipArchive::OVERWRITE); /* truncate as empty file is not valid */
    if ($res === TRUE) {
        $zip->addFile('data.txt', 'entryname.txt');
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

# ZipArchive::registerCancelCallback

(PHP >= 8.0.0, PECL zip >= 1.17.0)

ZipArchive::registerCancelCallback — Register a callback to allow cancellation during archive close.

### 说明

public function ZipArchive::registerCancelCallback(callable `$callback`): bool

Register a `callback` function to allow cancellation during archive close.

### 参数

`callback`
  If this function return 0 operation will continue, other value it will be cancelled.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

This example creates a ZIP file archive php.zip and cancel operation on some run condition.

示例 #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();
    }

### 注释

> 注意: This function is only available if built against libzip ≥ 1.6.0.

### 参见

- 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.

### 说明

public function ZipArchive::registerProgressCallback(float `$rate`, callable `$callback`): bool

Register a `callback` function to provide updates during archive close.

### 参数

`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).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

This example creates a ZIP file archive php.zip and show progression.

示例 #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();
    }

### 注释

> 注意: This function is only available if built against libzip ≥ 1.3.0.

### 参见

- 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 — Renames an entry defined by its index

### 说明

public function ZipArchive::renameIndex(int `$index`, string `$new_name`): bool

Renames an entry defined by its index.

### 参数

`index`
  Index of the entry to rename.
`new_name`
  New name.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Rename one entry

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->renameIndex(2,'newname.txt');
        $zip->close();
    } else {
        echo 'failed, code:' . $res;
    }
    ?>

# ZipArchive::renameName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::renameName — Renames an entry defined by its name

### 说明

public function ZipArchive::renameName(string `$name`, string `$new_name`): bool

Renames an entry defined by its name.

### 参数

`name`
  Name of the entry to rename.
`new_name`
  New name.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Rename one entry

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->renameName('currentname.txt','newname.txt');
        $zip->close();
    } else {
        echo 'failed, code:' . $res;
    }
    ?>

# ZipArchive::replaceFile

(PHP >= 8.0.0, PECL zip >= 1.18.0)

ZipArchive::replaceFile — Replace file in ZIP archive with a given path

### 说明

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.

> 注意: 为了最大限度地提高代码可移植性，建议在 ZIP 文件名中使用斜线 (`/`) 做为目录分隔符。

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

This example opens a ZIP file archive test.zip and replaces index 1 entry with /path/to/index.txt.

示例 #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';
    }
    ?>

### 参见

- ZipArchive::addFile() - Adds a file to a ZIP archive from the given path

# ZipArchive::setArchiveComment

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setArchiveComment — Set the comment of a ZIP archive

### 说明

public function ZipArchive::setArchiveComment(string `$comment`): bool

Set the comment of a ZIP archive.

### 参数

`comment`
  The contents of the comment.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Create an archive and set a comment

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('test.txt', 'file content goes here');
        $zip->setArchiveComment('new archive comment');
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

# ZipArchive::setArchiveFlag

(PHP >= 8.3.0, PECL zip >= 1.22.0)

ZipArchive::setArchiveFlag — 设置 ZIP 归档的全局 flag

### 说明

public function ZipArchive::setArchiveFlag(int `$flag`, int `$value`): bool

设置 ZIP 归档的全局 flag。

### 参数

`flag`

  要改变的全局 flag，包含 `AFL_*` 常量。

  - `ZipArchive::AFL_WANT_TORRENTZIP`
  - `ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE`
`value`
  flag 的新值。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 创建 torrentzip 归档

    <?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';
    }
    ?>

### 参见

- ZipArchive::getArchiveFlag() - 返回 Zip 归档全局 flag 的值

# ZipArchive::setCommentIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setCommentIndex — Set the comment of an entry defined by its index

### 说明

public function ZipArchive::setCommentIndex(int `$index`, string `$comment`): bool

Set the comment of an entry defined by its index.

### 参数

`index`
  Index of the entry.
`comment`
  The contents of the comment.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Open an archive and set a comment for an entry

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->setCommentIndex(2, 'new entry comment');
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

# ZipArchive::setCommentName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setCommentName — Set the comment of an entry defined by its name

### 说明

public function ZipArchive::setCommentName(string `$name`, string `$comment`): bool

Set the comment of an entry defined by its name.

### 参数

`name`
  Name of the entry.
`comment`
  The contents of the comment.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Open an archive and set a comment for an entry

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->setCommentName('entry1.txt', 'new entry comment');
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

# ZipArchive::setCompressionIndex

(PHP 7, PHP 8, PECL zip >= 1.13.0)

ZipArchive::setCompressionIndex — Set the compression method of an entry defined by its index

### 说明

public function ZipArchive::setCompressionIndex(int `$index`, int `$method`, int `$compflags` = 0): bool

Set the compression method of an entry defined by its index.

### 参数

`index`
  Index of the entry.
`method`
  The compression method, one of the `ZipArchive::CM_*` constants.
`compflags`
  Compression level.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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

### 说明

public function ZipArchive::setCompressionName(string `$name`, int `$method`, int `$compflags` = 0): bool

Set the compression method of an entry defined by its name.

### 参数

`name`
  Name of the entry.
`method`
  The compression method, one of the `ZipArchive::CM_*` constants.
`compflags`
  Compression level.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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';
    }
    ?>

示例 #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

### 说明

public function ZipArchive::setEncryptionIndex(int `$index`, int `$method`, #[\SensitiveParameter] ?string `$password` = `null`): bool

Set the encryption method of an entry defined by its index.

### 参数

`index`
  Index of the entry.
`method`
  The encryption method defined by one of the ZipArchive::EM_ constants.
`password`
  Optional password, default used when missing.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `password` is now nullable.

### 注释

> 注意: This function is only available if built against libzip ≥ 1.2.0.

### 参见

- 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

### 说明

public function ZipArchive::setEncryptionName(string `$name`, int `$method`, #[\SensitiveParameter] ?string `$password` = `null`): bool

Set the encryption method of an entry defined by its name.

### 参数

`name`
  Name of the entry.
`method`
  The encryption method defined by one of the ZipArchive::EM_ constants.
`password`
  Optional password, default used when missing.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `password` is now nullable.

### 示例

This example creates a ZIP file archive test.zip and add the file test.txt encrypted using the AES 256 method.

示例 #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";
    }
    ?>

### 注释

> 注意: This function is only available if built against libzip ≥ 1.2.0.

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

This example opens a ZIP file archive test.zip and add the file test.txt with its Unix rights as external attributes.

示例 #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

### 说明

public function ZipArchive::setMtimeIndex(int `$index`, int `$timestamp`, int `$flags` = 0): bool

Set the modification time of an entry defined by its index.

### 参数

`index`
  Index of the entry.
`timestamp`
  The modification time (unix timestamp) of the file.
`flags`
  Optional flags, unused for now.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

This example creates a ZIP file archive test.zip and add the file test.txt with its modification date.

示例 #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";
    }
    ?>

### 注释

> 注意: This function is only available if built against libzip ≥ 1.0.0.

### 参见

- 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

### 说明

public function ZipArchive::setMtimeName(string `$name`, int `$timestamp`, int `$flags` = 0): bool

Set the modification time of an entry defined by its name.

### 参数

`name`
  Name of the entry.
`timestamp`
  The modification time (unix timestamp) of the file.
`flags`
  Optional flags, unused for now.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

This example creates a ZIP file archive test.zip and add the file test.txt with its modification date.

示例 #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";
    }
    ?>

### 注释

> 注意: This function is only available if built against libzip ≥ 1.0.0.

### 参见

- 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

### 说明

public function ZipArchive::setPassword(#[\SensitiveParameter] string `$password`): bool

Sets the password for the active archive.

### 参数

`password`
  The password to be used for the archive.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 注释

> 注意: 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.

### 参见

- 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 — Get the details of an entry defined by its index

### 说明

public function ZipArchive::statIndex(int `$index`, int `$flags` = 0): array|false

The function obtains information about the entry defined by its index.

### 参数

`index`
  Index of the entry
`flags`
  `ZipArchive::FL_UNCHANGED` may be ORed to it to request information about the original file in the archive, ignoring any changes made.

### 返回值

Returns an array containing the entry details 或者在失败时返回 `false`.

### 示例

示例 #1 Dump the stat info of an entry

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        print_r($zip->statIndex(3));
        $zip->close();
    } else {
        echo 'failed, code:' . $res;
    }
    ?>

以上示例的输出类似于：

    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 — Get the details of an entry defined by its name

### 说明

public function ZipArchive::statName(string `$name`, int `$flags` = 0): array|false

The function obtains information about the entry defined by its name.

### 参数

`name`
  Name of the entry
`flags`

  The flags argument specifies how the name lookup should be done. Also, `ZipArchive::FL_UNCHANGED` may be ORed to it to request information about the original file in the archive, ignoring any changes made.

  - `ZipArchive::FL_NOCASE`
  - `ZipArchive::FL_NODIR`
  - `ZipArchive::FL_UNCHANGED`

### 返回值

Returns an array containing the entry details 或者在失败时返回 `false`.

### 示例

示例 #1 Dump the stat info of an entry

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        print_r($zip->statName('foobar/baz'));
        $zip->close();
    } else {
        echo 'failed, code:' . $res;
    }
    ?>

以上示例的输出类似于：

    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 — Undo all changes done in the archive

### 说明

public function ZipArchive::unchangeAll(): bool

Undo all changes done in the archive.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# ZipArchive::unchangeArchive

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeArchive — Revert all global changes done in the archive

### 说明

public function ZipArchive::unchangeArchive(): bool

Revert all global changes to the archive. For now, this only reverts archive comment changes.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# ZipArchive::unchangeIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeIndex — Revert all changes done to an entry at the given index

### 说明

public function ZipArchive::unchangeIndex(int `$index`): bool

Revert all changes done to an entry at the given index.

### 参数

`index`
  Index of the entry.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# ZipArchive::unchangeName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::unchangeName — Revert all changes done to an entry with the given name

### 说明

public function ZipArchive::unchangeName(string `$name`): bool

Revert all changes done to an entry.

### 参数

`name`
  Name of the entry.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

## 目录

- ZipArchive::addEmptyDir — Add a new directory
- ZipArchive::addFile — Adds a file to a ZIP archive from the given path
- ZipArchive::addFromString — Add a file to a ZIP archive using its contents
- ZipArchive::addGlob — Add files from a directory by glob pattern
- ZipArchive::addPattern — Add files from a directory by PCRE pattern
- ZipArchive::clearError — 清除状态错误消息、系统和/或 zip 消息
- ZipArchive::close — Close the active archive (opened or newly created)
- ZipArchive::count — Counts the number of files in the archive
- ZipArchive::deleteIndex — Delete an entry in the archive using its index
- ZipArchive::deleteName — Delete an entry in the archive using its name
- ZipArchive::extractTo — 解压缩文件
- ZipArchive::getArchiveComment — Returns the Zip archive comment
- ZipArchive::getArchiveFlag — 返回 Zip 归档全局 flag 的值
- ZipArchive::getCommentIndex — Returns the comment of an entry using the entry index
- ZipArchive::getCommentName — Returns the comment of an entry using the entry name
- 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 — Returns the entry contents using its index
- ZipArchive::getFromName — Returns the entry contents using its name
- ZipArchive::getNameIndex — Returns the name of an entry using its index
- ZipArchive::getStatusString — Returns the status error message, system and/or zip messages
- ZipArchive::getStream — Get a file handler to the entry defined by its name (read only)
- 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 — Returns the index of the entry in the archive
- ZipArchive::open — Open a ZIP file archive
- ZipArchive::registerCancelCallback — Register a callback to allow cancellation during archive close.
- ZipArchive::registerProgressCallback — Register a callback to provide updates during archive close.
- ZipArchive::renameIndex — Renames an entry defined by its index
- ZipArchive::renameName — Renames an entry defined by its name
- ZipArchive::replaceFile — Replace file in ZIP archive with a given path
- ZipArchive::setArchiveComment — Set the comment of a ZIP archive
- ZipArchive::setArchiveFlag — 设置 ZIP 归档的全局 flag
- ZipArchive::setCommentIndex — Set the comment of an entry defined by its index
- ZipArchive::setCommentName — Set the comment of an entry defined by its name
- 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 — Get the details of an entry defined by its index
- ZipArchive::statName — Get the details of an entry defined by its name
- ZipArchive::unchangeAll — Undo all changes done in the archive
- ZipArchive::unchangeArchive — Revert all global changes done in the archive
- ZipArchive::unchangeIndex — Revert all changes done to an entry at the given index
- ZipArchive::unchangeName — Revert all changes done to an entry with the given name

# Zip 函数

警告

从 PHP 8.0.0 开始，弃用过程式 API。应该改用 ZipArchive。

# zip_close

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_close — 关闭一个ZIP档案文件

警告

本函数已自 PHP 8.0.0 起被废弃。强烈建议不要依赖本函数。

### 说明

#[\Deprecated]
function zip_close(resource `$zip`): void

关闭一个指定的ZIP档案文件。

### 参数

`zip`
  一个由zip_open()打开的ZIP文件资源。

### 返回值

没有返回值。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 弃用此函数，取而代之的是对象 API，请参阅 ZipArchive::close()。

### 参见

- zip_open() - 打开 ZIP 文件归档
- zip_read() - 读取 ZIP 文件归档中下一项

# 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 — 关闭目录项

警告

本函数已自 PHP 8.0.0 起被废弃。强烈建议不要依赖本函数。

### 说明

#[\Deprecated]
function zip_entry_close(resource `$zip_entry`): bool

关闭指定的目录项。

### 参数

`zip_entry`
  一个由zip_entry_open()打开的项目。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 弃用此函数，取而代之的是对象 API。

### 参见

- zip_entry_open() - 打开用于读取的目录实体
- zip_entry_read() - 读取一个打开了的压缩目录实体

# 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 — 检索目录项压缩过后的大小

警告

本函数已自 PHP 8.0.0 起被废弃。强烈建议不要依赖本函数。

### 说明

#[\Deprecated]
function zip_entry_compressedsize(resource `$zip_entry`): int|false

返回指定目录项压缩过后的大小。

### 参数

`zip_entry`
  由函数zip_read() 返回的目录项。

### 返回值

压缩后的大小， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 弃用此函数，取而代之的是对象 API，请参阅 ZipArchive::statIndex()。

### 参见

- zip_open() - 打开 ZIP 文件归档
- zip_read() - 读取 ZIP 文件归档中下一项

# 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 — 检索目录实体的压缩方法

警告

本函数已自 PHP 8.0.0 起被废弃。强烈建议不要依赖本函数。

### 说明

#[\Deprecated]
function zip_entry_compressionmethod(resource `$zip_entry`): string|false

返回由函数`zip_entry`确定的目录实体的压缩方法。

### 参数

`zip_entry`
  由函数zip_read() 返回的目录实体。

### 返回值

压缩方法， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 弃用此函数，取而代之的是对象 API，请参阅 ZipArchive::statIndex()。

### 参见

- zip_open() - 打开 ZIP 文件归档
- zip_read() - 读取 ZIP 文件归档中下一项

# 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 — 检索目录实体的实际大小

警告

本函数已自 PHP 8.0.0 起被废弃。强烈建议不要依赖本函数。

### 说明

#[\Deprecated]
function zip_entry_filesize(resource `$zip_entry`): int|false

返回指定目录实体的实际大小。

### 参数

`zip_entry`
  由函数zip_read() 返回的目录实体。

### 返回值

返回该目录实体的大小， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 弃用此函数，取而代之的是对象 API，请参阅 ZipArchive::statIndex()。

### 参见

- zip_open() - 打开 ZIP 文件归档
- zip_read() - 读取 ZIP 文件归档中下一项

# 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 — 检索目录项的名称

警告

本函数已自 PHP 8.0.0 起被废弃。强烈建议不要依赖本函数。

### 说明

#[\Deprecated]
function zip_entry_name(resource `$zip_entry`): string|false

返回指定目录项的名称。

### 参数

`zip_entry`
  由函数zip_read() 返回的目录项。

### 返回值

目录项的名称， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 弃用此函数，取而代之的是对象 API，请参阅 ZipArchive::statIndex()。

### 参见

- zip_open() - 打开 ZIP 文件归档
- zip_read() - 读取 ZIP 文件归档中下一项

# 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 — 打开用于读取的目录实体

警告

本函数已自 PHP 8.0.0 起被废弃。强烈建议不要依赖本函数。

### 说明

#[\Deprecated]
function zip_entry_open(resource `$zip_dp`, resource `$zip_entry`, string `$mode` = "rb"): bool

打开ZIP文件中的目录实体以便后续读取。

### 参数

`zip_dp`
  由函数zip_open()返回的有效的资源句柄。
`zip_entry`
  由函数zip_read()返回的目录实体。
`mode`
  任何在fopen()处理文档中指定的模式。

  > 注意: 由于ZIP在PHP中只支持读取模式，所以`mode` 实际上总是被设置为`"rb"`(其他模式会被忽略)。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

> 注意: 与fopen()和其他类似的方法不同，zip_entry_open() 的返回值只用于标示该操作结果，不需要读取或关闭该目录实体。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 弃用此函数，取而代之的是对象 API。

### 参见

- zip_entry_close() - 关闭目录项
- zip_entry_read() - 读取一个打开了的压缩目录实体

# 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 — 读取一个打开了的压缩目录实体

警告

本函数已自 PHP 8.0.0 起被废弃。强烈建议不要依赖本函数。

### 说明

#[\Deprecated]
function zip_entry_read(resource `$zip_entry`, int `$len` = 1024): string|false

读取一个打开了的压缩目录实体。

### 参数

`zip_entry`
  由函数zip_read() 返回的目录实体。
`len`
  需要返回的字节数。

  > 注意: 这字节数应该是你所要读取的未压缩的字节数。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 弃用此函数，取而代之的是对象 API，请参阅 ZipArchive::getFromIndex()。

### 返回值

成功的时候返回读取到的数据；到达文件末尾的时候返回一个空的字符串； 读取出错的时候则会返回`false`

### 参见

- zip_entry_open() - 打开用于读取的目录实体
- zip_entry_close() - 关闭目录项
- zip_entry_filesize() - 检索目录实体的实际大小

# zip_open

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_open — 打开 ZIP 文件归档

警告

本函数已自 PHP 8.0.0 起被废弃。强烈建议不要依赖本函数。

### 说明

#[\Deprecated]
function zip_open(string `$filename`): resource|int|false

打开一个新的ZIP归档文件进行读取。

### 参数

`filename`
  待打开ZIP归档的文件名。

### 返回值

成功的时候返回资源句柄供 zip_read() 和 zip_close() 后续使用；如果 `filename` 文件不存在或者出现其他错误，则会返回 `false` 或相应的错误码。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 弃用此函数，取而代之的是对象 API，请参阅 ZipArchive::open()。

### 参见

- zip_read() - 读取 ZIP 文件归档中下一项
- zip_close() - 关闭一个ZIP档案文件

# zip_read

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_read — 读取 ZIP 文件归档中下一项

警告

本函数已自 PHP 8.0.0 起被废弃。强烈建议不要依赖本函数。

### 说明

#[\Deprecated]
function zip_read(resource `$zip`): resource|false

读取 ZIP 文件归档中下一项。

### 参数

`zip`
  一个ZIP压缩文件,该ZIP归档文件之前应由函数 zip_open() 打开。

### 返回值

成功的时候返回该当前实体资源供`zip_entry_...` 系列函数后续使用; 如果没有更多的读取项，则会返回 `false` 如果遇到错误则会返回相应的错误码。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 弃用此函数，取而代之的是对象 API，请参阅 ZipArchive::statIndex()。

### 参见

- zip_open() - 打开 ZIP 文件归档
- zip_close() - 关闭一个ZIP档案文件
- zip_entry_open() - 打开用于读取的目录实体
- zip_entry_read() - 读取一个打开了的压缩目录实体

## 目录

- zip_close — 关闭一个ZIP档案文件
- zip_entry_close — 关闭目录项
- zip_entry_compressedsize — 检索目录项压缩过后的大小
- zip_entry_compressionmethod — 检索目录实体的压缩方法
- zip_entry_filesize — 检索目录实体的实际大小
- zip_entry_name — 检索目录项的名称
- zip_entry_open — 打开用于读取的目录实体
- zip_entry_read — 读取一个打开了的压缩目录实体
- zip_open — 打开 ZIP 文件归档
- zip_read — 读取 ZIP 文件归档中下一项

- 安装/配置
  - 需求
  - 安装
  - 资源类型
- 预定义常量
- 示例
- ZipArchive — ZipArchive 类
  - ZipArchive::addEmptyDir — Add a new directory
  - ZipArchive::addFile — Adds a file to a ZIP archive from the given path
  - ZipArchive::addFromString — Add a file to a ZIP archive using its contents
  - ZipArchive::addGlob — Add files from a directory by glob pattern
  - ZipArchive::addPattern — Add files from a directory by PCRE pattern
  - ZipArchive::clearError — 清除状态错误消息、系统和/或 zip 消息
  - ZipArchive::close — Close the active archive (opened or newly created)
  - ZipArchive::count — Counts the number of files in the archive
  - ZipArchive::deleteIndex — Delete an entry in the archive using its index
  - ZipArchive::deleteName — Delete an entry in the archive using its name
  - ZipArchive::extractTo — 解压缩文件
  - ZipArchive::getArchiveComment — Returns the Zip archive comment
  - ZipArchive::getArchiveFlag — 返回 Zip 归档全局 flag 的值
  - ZipArchive::getCommentIndex — Returns the comment of an entry using the entry index
  - ZipArchive::getCommentName — Returns the comment of an entry using the entry name
  - 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 — Returns the entry contents using its index
  - ZipArchive::getFromName — Returns the entry contents using its name
  - ZipArchive::getNameIndex — Returns the name of an entry using its index
  - ZipArchive::getStatusString — Returns the status error message, system and/or zip messages
  - ZipArchive::getStream — Get a file handler to the entry defined by its name (read only)
  - 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 — Returns the index of the entry in the archive
  - ZipArchive::open — Open a ZIP file archive
  - ZipArchive::registerCancelCallback — Register a callback to allow cancellation during archive close.
  - ZipArchive::registerProgressCallback — Register a callback to provide updates during archive close.
  - ZipArchive::renameIndex — Renames an entry defined by its index
  - ZipArchive::renameName — Renames an entry defined by its name
  - ZipArchive::replaceFile — Replace file in ZIP archive with a given path
  - ZipArchive::setArchiveComment — Set the comment of a ZIP archive
  - ZipArchive::setArchiveFlag — 设置 ZIP 归档的全局 flag
  - ZipArchive::setCommentIndex — Set the comment of an entry defined by its index
  - ZipArchive::setCommentName — Set the comment of an entry defined by its name
  - 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 — Get the details of an entry defined by its index
  - ZipArchive::statName — Get the details of an entry defined by its name
  - ZipArchive::unchangeAll — Undo all changes done in the archive
  - ZipArchive::unchangeArchive — Revert all global changes done in the archive
  - ZipArchive::unchangeIndex — Revert all changes done to an entry at the given index
  - ZipArchive::unchangeName — Revert all changes done to an entry with the given name
- Zip 函数
  - zip_close — 关闭一个ZIP档案文件
  - zip_entry_close — 关闭目录项
  - zip_entry_compressedsize — 检索目录项压缩过后的大小
  - zip_entry_compressionmethod — 检索目录实体的压缩方法
  - zip_entry_filesize — 检索目录实体的实际大小
  - zip_entry_name — 检索目录项的名称
  - zip_entry_open — 打开用于读取的目录实体
  - zip_entry_read — 读取一个打开了的压缩目录实体
  - zip_open — 打开 ZIP 文件归档
  - zip_read — 读取 ZIP 文件归档中下一项

# Zlib 压缩

# 简介

该模块能够无障碍地读写 gzip 压缩过的文件，使用大多数 filesystem 函数的版本，与 gzip 压缩文件（以及未压缩的文件，但不能与 socket 一起使用）一起使用。

> 注意:

> PHP 还有用于 .gz 文件的 fopen 封装协议。有关 zlib:// 的部分提供了更多信息。

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置
- 资源类型

## 需求

该模块依赖于 » zlib 的函数， 由 Jean-loup Gailly 和 Mark Adler 开发。 从 PHP 8.4.0 开始，所需的最低 zlib 版本为 1.2.11。 在 PHP 8.4.0 之前，所需的最低 zlib 版本为 1.2.0.4。

## 安装

PHP 中的 Zlib 支持默认未启用。需要配置 PHP --with-zlib[=DIR]

PHP 的 Windows 版本已内建对此扩展的支持。不需要载入额外的扩展来使用这些函数。

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

The zlib extension offers the option to transparently compress your pages on-the-fly, if the requesting browser supports this. Therefore there are three options in the configuration file php.ini.

Zlib Configuration Options
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
zlib.output_compression | "0" | `INI_ALL` |
zlib.output_compression_level | "-1" | `INI_ALL` |
zlib.output_handler | "" | `INI_ALL` |

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`zlib.output_compression` bool/int

  Whether to transparently compress pages. If this option is set to "On" in php.ini or the Apache configuration, pages are compressed if the browser sends an "Accept-Encoding: gzip" or "deflate" header. "Content-Encoding: gzip" (respectively "deflate") and "Vary: Accept-Encoding" headers are added to the output. In runtime, it can be set only before sending any output.

  This option also accepts integer values instead of boolean "On"/"Off", using this you can set the output buffer size (default is 4KB).

  > 注意:

  > output_handler must be empty if this is set 'On' ! Instead you must use `zlib.output_handler`.

`zlib.output_compression_level` int

  Compression level used for transparent output compression. Specify a value between 0 (no compression) to 9 (most compression). The default value, -1, lets the server decide which level to use.

`zlib.output_handler` string

  You cannot specify additional output handlers if zlib.output_compression is activated here. This setting does the same as output_handler but in a different order.

## 资源类型

该扩展定义了 gzopen() 返回的文件指针资源。在 PHP 8.0.0 之前，还定义了 `zlib.deflate` 和 `zlib.inflate` 资源。

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`FORCE_GZIP` (int)
`FORCE_DEFLATE` (int)
`ZLIB_ENCODING_RAW` (int)
  DEFLATE 压缩算法，按照 RFC 1951 标准。
`ZLIB_ENCODING_DEFLATE` (int)
  ZLIB 压缩算法，按照 RFC 1950 标准。
`ZLIB_ENCODING_GZIP` (int)
  GZIP algorithm as per 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)
  string 类型的 `zlib` 版本号。
`ZLIB_VERNUM` (int)
  int 类型的 `zlib` 版本号。
`ZLIB_OK` (int)
  没有错误或其他状态信息。
`ZLIB_STREAM_END` (int)
  流已成功结束。
`ZLIB_NEED_DICT` (int)
  需要预设词典。
`ZLIB_ERRNO` (int)
  文件操作错误。
`ZLIB_STREAM_ERROR` (int)
  流状态不一致或参数无效。
`ZLIB_DATA_ERROR` (int)
  输入数据已损坏。
`ZLIB_MEM_ERROR` (int)
  内存不足。
`ZLIB_BUF_ERROR` (int)
  由于缓冲区空间不足或输入流意外结束，因此没有处理。
`ZLIB_VERSION_ERROR` (int)
  `zlib` 库版本与调用者假设的版本不兼容。

# 示例

This example opens a temporary file and writes a test string to it, then it prints out the content of this file twice.

示例 #1 Small Zlib Example

    <?php

    $filename = tempnam('/tmp', 'zlibtest') . '.gz';
    echo "<html>\n<head></head>\n<body>\n<pre>\n";
    $s = "Only a test, test, test, test, test, test, test, test!\n";

    // open file for writing with maximum compression
    $zp = gzopen($filename, "w9");

    // write string to file
    gzwrite($zp, $s);

    // close file
    gzclose($zp);

    // open file for reading
    $zp = gzopen($filename, "r");

    // read 3 char
    echo gzread($zp, 3);

    // output until end of the file and close it.
    gzpassthru($zp);
    gzclose($zp);

    echo "\n";

    // open file and print content (the 2nd time).
    if (readgzfile($filename) != strlen($s)) {
            echo "Error with zlib functions!";
    }
    unlink($filename);
    echo "</pre>\n</body>\n</html>\n";

    ?>

示例 #2 Working with the incremental compression and decompression API

    <?php
    // Perform GZIP compression:
    $deflateContext = deflate_init(ZLIB_ENCODING_GZIP);
    $compressed = deflate_add($deflateContext, "Data to compress", ZLIB_NO_FLUSH);
    $compressed .= deflate_add($deflateContext, ", more data", ZLIB_NO_FLUSH);
    $compressed .= deflate_add($deflateContext, ", and even more data!", ZLIB_FINISH);

    // Perform GZIP decompression:
    $inflateContext = inflate_init(ZLIB_ENCODING_GZIP);
    $uncompressed = inflate_add($inflateContext, $compressed, ZLIB_NO_FLUSH);
    $uncompressed .= inflate_add($inflateContext, NULL, ZLIB_FINISH);
    echo $uncompressed;
    ?>

以上示例会输出：

    Data to compress, more data, and even more data!

# Zlib 函数

# deflate_add

(PHP 7, PHP 8)

deflate_add — Incrementally deflate data

### 说明

function deflate_add(DeflateContext `$context`, string `$data`, int `$flush_mode` = `ZLIB_SYNC_FLUSH`): string|false

Incrementally deflates data in the specified context.

### 参数

`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.

### 返回值

Returns a chunk of compressed data, 或者在失败时返回 `false`.

### 错误／异常

If invalid arguments are given, an error of level `E_WARNING` is generated.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `context` expects a DeflateContext instance now; previously, a resource was expected.

### 参见

- deflate_init() - Initialize an incremental deflate context

# deflate_init

(PHP 7, PHP 8)

deflate_init — Initialize an incremental deflate context

### 说明

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.)

### 参数

`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).

### 返回值

Returns a deflate context resource (`zlib.deflate`) on success, 或者在失败时返回 `false`.

### 错误／异常

If an invalid option is passed to `options` or the context couldn't be created, an error of level `E_WARNING` is generated.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | On success, this function returns a DeflateContext instance now; previously, a resource was returned.

### 参见

- deflate_add() - Incrementally deflate data
- inflate_init() - Initialize an incremental inflate context

# gzclose

(PHP 4, PHP 5, PHP 7, PHP 8)

gzclose — Close an open gz-file pointer

### 说明

function gzclose(resource `$stream`): bool

Closes the given gz-file pointer.

### 参数

`stream`

  The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 gzclose() example

    <?php
    $gz = gzopen('somefile.gz','w9');
    gzputs ($gz, 'I was added to somefile.gz');
    gzclose($gz);
    ?>

### 参见

- gzopen() - Open gz-file

# gzcompress

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

gzcompress — Compress a string

### 说明

function gzcompress(string `$data`, int `$level` = -1, int `$encoding` = `ZLIB_ENCODING_DEFLATE`): string|false

This function compresses the given string using the `ZLIB` data format.

For details on the ZLIB compression algorithm see the document "» ZLIB Compressed Data Format Specification version 3.3" (RFC 1950).

> 注意:

> This is not the same as gzip compression, which includes some header data. See gzencode() for gzip compression.

### 参数

`data`

  The data to compress.

`level`

  The level of compression. Can be given as 0 for no compression up to 9 for maximum compression.

  If -1 is used, the default compression of the zlib library is used which is 6.

`encoding`

  One of `ZLIB_ENCODING_*` constants.

### 返回值

The compressed string or `false` if an error occurred.

### 示例

示例 #1 gzcompress() example

    <?php
    $compressed = gzcompress('Compress me', 9);
    echo $compressed;
    ?>

### 参见

- gzdeflate() - Deflate a string
- gzinflate() - Inflate a deflated string
- gzuncompress() - Uncompress a compressed string
- gzencode() - Create a gzip compressed string

# gzdecode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

gzdecode — Decodes a gzip compressed string

### 说明

function gzdecode(string `$data`, int `$max_length` = 0): string|false

This function returns a decoded version of the input `data`.

### 参数

`data`

  The data to decode, encoded by gzencode().

`max_length`

  The maximum length of data to decode.

### 返回值

The decoded string, or 或者在失败时返回 `false`.

### 错误／异常

In case of failure, an `E_WARNING` level error is issued.

### 参见

- gzencode() - Create a gzip compressed string

# gzdeflate

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzdeflate — Deflate a string

### 说明

function gzdeflate(string `$data`, int `$level` = -1, int `$encoding` = `ZLIB_ENCODING_RAW`): string|false

This function compresses the given string using the `DEFLATE` data format.

For details on the DEFLATE compression algorithm see the document "» DEFLATE Compressed Data Format Specification version 1.3" (RFC 1951).

### 参数

`data`

  The data to deflate.

`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`

  One of `ZLIB_ENCODING_*` constants.

### 返回值

The deflated string or `false` if an error occurred.

### 示例

示例 #1 gzdeflate() example

    <?php
    $compressed = gzdeflate('Compress me', 9);
    echo $compressed;
    ?>

### 参见

- gzinflate() - Inflate a deflated string
- gzcompress() - Compress a string
- gzuncompress() - Uncompress a compressed 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

### 说明

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).

### 参数

`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.

### 返回值

The encoded string, or `false` if an error occurred.

### 示例

The resulting data contains the appropriate headers and data structure to make a standard .gz file, e.g.:

示例 #1 Creating a gzip file

    <?php
    $data = file_get_contents("bigfile.txt");
    $gzdata = gzencode($data, 9);
    file_put_contents("bigfile.txt.gz", $gzdata);
    ?>

### 参见

- gzdecode() - Decodes a gzip compressed string
- gzdeflate() - Deflate a string
- gzinflate() - Inflate a deflated string
- gzuncompress() - Uncompress a compressed string
- gzcompress() - Compress a string
- » ZLIB Compressed Data Format Specification (RFC 1950)

# gzeof

(PHP 4, PHP 5, PHP 7, PHP 8)

gzeof — Test for EOF on a gz-file pointer

### 说明

function gzeof(resource `$stream`): bool

Tests the given GZ file pointer for EOF.

### 参数

`stream`

  The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().

### 返回值

Returns `true` if the gz-file pointer is at EOF or an error occurs; otherwise returns `false`.

### 示例

示例 #1 gzeof() example

    <?php
    $gz = gzopen('somefile.gz', 'r');
    while (!gzeof($gz)) {
      echo gzgetc($gz);
    }
    gzclose($gz);
    ?>

# gzfile

(PHP 4, PHP 5, PHP 7, PHP 8)

gzfile — Read entire gz-file into an array

### 说明

function gzfile(string `$filename`, bool `$use_include_path` = `false`): array|false

This function is identical to readgzfile(), except that it returns the file in an array.

### 参数

`filename`

  The file name.

`use_include_path`
  If set to `true`, files in the include_path are searched for too.

### 返回值

An array containing the file, one line per cell, empty lines included, and with newlines still attached, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.5.0 | `use_include_path` is now of type bool. Previously, it was of type int.

### 示例

示例 #1 gzfile() example

    <?php
    $lines = gzfile('somefile.gz');
    foreach ($lines as $line) {
        echo $line;
    }
    ?>

### 参见

- readgzfile() - Output a gz-file
- gzopen() - Open gz-file

# gzgetc

(PHP 4, PHP 5, PHP 7, PHP 8)

gzgetc — Get character from gz-file pointer

### 说明

function gzgetc(resource `$stream`): string|false

Returns a string containing a single (uncompressed) character read from the given gz-file pointer.

### 参数

`stream`

  The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().

### 返回值

The uncompressed character or `false` on EOF (unlike gzeof()).

### 示例

示例 #1 gzgetc() example

    <?php
    $gz = gzopen('somefile.gz', 'r');
    while (!gzeof($gz)) {
      echo gzgetc($gz);
    }
    gzclose($gz);
    ?>

### 参见

- gzopen() - Open gz-file
- gzgets() - Get line from file pointer

# gzgets

(PHP 4, PHP 5, PHP 7, PHP 8)

gzgets — Get line from file pointer

### 说明

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).

### 参数

`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.

### 返回值

The uncompressed string, or `false` on error.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `length` is nullable now; previously, the default was `1024`.

### 示例

示例 #1 gzgets() example

    <?php
    $handle = gzopen('somefile.gz', 'r');
    while (!gzeof($handle)) {
       $buffer = gzgets($handle, 4096);
       echo $buffer;
    }
    gzclose($handle);
    ?>

### 参见

- gzopen() - Open gz-file
- gzgetc() - Get character from gz-file pointer
- gzwrite() - Binary-safe gz-file write

# gzgetss

(PHP 4, PHP 5, PHP 7)

gzgetss — Get line from gz-file pointer and strip HTML tags

警告

本函数已自 PHP 7.3.0 起弃用，自 PHP 8.0.0 起移除。强烈建议不要依赖本函数。

### 说明

function gzgetss(resource `$zp`, int `$length`, string `$allowable_tags` = ?): string

Identical to gzgets(), except that gzgetss() attempts to strip any HTML and PHP tags from the text it reads.

### 参数

`zp`

  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.

`allowable_tags`

  You can use this optional parameter to specify tags which should not be stripped.

### 返回值

The uncompressed and stripped string, or `false` on error.

### 示例

示例 #1 gzgetss() example

    <?php
    $handle = gzopen('somefile.gz', 'r');
    while (!gzeof($handle)) {
       $buffer = gzgetss($handle, 4096);
       echo $buffer;
    }
    gzclose($handle);
    ?>

### 参见

- gzopen() - Open gz-file
- gzgets() - Get line from file pointer
- strip_tags() - 从字符串中去除 HTML 和 PHP 标签

# gzinflate

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzinflate — Inflate a deflated string

### 说明

function gzinflate(string `$data`, int `$max_length` = 0): string|false

This function inflates a deflated string.

### 参数

`data`

  The data compressed by gzdeflate().

`max_length`

  The maximum length of decoded data.

### 返回值

The original uncompressed data or `false` on error.

The function will return an error if the uncompressed data is more than 32768 times the length of the compressed input `data` or, unless `max_length` is `0`, more than the optional parameter `max_length`.

### 示例

示例 #1 gzinflate() example

    <?php
    $compressed   = gzdeflate('Compress me', 9);
    $uncompressed = gzinflate($compressed);
    echo $uncompressed;
    ?>

### 参见

- gzdeflate() - Deflate a string
- gzcompress() - Compress a string
- gzuncompress() - Uncompress a compressed string
- gzencode() - Create a gzip compressed string

# gzopen

(PHP 4, PHP 5, PHP 7, PHP 8)

gzopen — Open gz-file

### 说明

function gzopen(string `$filename`, string `$mode`, bool `$use_include_path` = `false`): resource|false

Opens a gzip (.gz) file for reading or writing.

gzopen() can be used to read a file which is not in gzip format; in this case gzread() will directly read from the file without decompression.

### 参数

`filename`

  The file name.

`mode`

  As in fopen() (`rb` or `wb`) but can also include a compression level (`wb9`) or a strategy: `f` for filtered data as in `wb6f`, `h` for `Huffman only compression` as in `wb1h`. (See the description of `deflateInit2` in zlib.h for more information about the strategy parameter.)

`use_include_path`
  If set to `true`, files in the include_path are searched for too.

### 返回值

Returns a file pointer to the file opened, after that, everything you read from this file descriptor will be transparently decompressed and what you write gets compressed.

If the open fails, the function returns `false`.

### 更新日志

版本 | 说明
--- | ---
8.5.0 | `use_include_path` is now of type bool. Previously, it was of type int.

### 示例

示例 #1 gzopen() Example

    <?php
    $fp = gzopen("/tmp/file.gz", "r");
    ?>

### 参见

- gzclose() - Close an open gz-file pointer

# gzpassthru

(PHP 4, PHP 5, PHP 7, PHP 8)

gzpassthru — Output all remaining data on a gz-file pointer

### 说明

function gzpassthru(resource `$stream`): int

Reads to EOF on the given gz-file pointer from the current position and writes the (uncompressed) results to standard output.

> 注意:

> You may need to call gzrewind() to reset the file pointer to the beginning of the file if you have already written data to it.

小技巧

If you just want to dump the contents of a file to the output buffer, without first modifying it or seeking to a particular offset, you may want to use the readgzfile() function, which saves you the gzopen() call.

### 参数

`stream`

  The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().

### 返回值

The number of uncompressed characters read from `gz` and passed through to the input.

### 示例

示例 #1 gzpassthru() example

    <?php
    $fp = gzopen('file.gz', 'r');
    gzpassthru($fp);
    gzclose($fp);
    ?>

# gzputs

(PHP 4, PHP 5, PHP 7, PHP 8)

gzputs — 别名 gzwrite()

### 说明

此函数是该函数的别名： gzwrite().

# gzread

(PHP 4, PHP 5, PHP 7, PHP 8)

gzread — Binary-safe gz-file read

### 说明

function gzread(resource `$stream`, int `$length`): string|false

gzread() reads up to `length` bytes from the given gz-file pointer. Reading stops when `length` (uncompressed) bytes have been read or EOF is reached, whichever comes first.

### 参数

`stream`

  The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().

`length`

  The number of bytes to read.

### 返回值

The data that have been read, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
7.4.0 | This functions returns `false` on failure now; previously `0` was returned.

### 示例

示例 #1 gzread() example

    <?php
    // get contents of a gz-file into a string
    $filename = "/usr/local/something.txt.gz";
    $zd = gzopen($filename, "r");
    $contents = gzread($zd, 10000);
    gzclose($zd);
    ?>

### 参见

- gzwrite() - Binary-safe gz-file write
- gzopen() - Open gz-file
- gzgets() - Get line from file pointer
- gzgetss() - Get line from gz-file pointer and strip HTML tags
- gzfile() - Read entire gz-file into an array
- gzpassthru() - Output all remaining data on a gz-file pointer

# gzrewind

(PHP 4, PHP 5, PHP 7, PHP 8)

gzrewind — Rewind the position of a gz-file pointer

### 说明

function gzrewind(resource `$stream`): bool

Sets the file position indicator of the given gz-file pointer to the beginning of the file stream.

### 参数

`stream`

  The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- gzseek() - Seek on a gz-file pointer
- gztell() - Tell gz-file pointer read/write position

# gzseek

(PHP 4, PHP 5, PHP 7, PHP 8)

gzseek — Seek on a gz-file pointer

### 说明

function gzseek(resource `$stream`, int `$offset`, int `$whence` = `SEEK_SET`): int

Sets the file position indicator for the given file pointer to the given offset byte into the file stream. Equivalent to calling (in C) `gzseek(zp, offset, SEEK_SET)`.

If the file is opened for reading, this function is emulated but can be extremely slow. If the file is opened for writing, only forward seeks are supported; gzseek() then compresses a sequence of zeroes up to the new starting position.

### 参数

`stream`

  The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().

`offset`

  The seeked offset.

`whence`

  `whence` values are:

  - `SEEK_SET` - Set position equal to `offset` bytes.
  - `SEEK_CUR` - Set position to current location plus `offset`.

  If `whence` is not specified, it is assumed to be `SEEK_SET`.

### 返回值

Upon success, returns 0; otherwise, returns -1. Note that seeking past EOF is not considered an error.

### 示例

示例 #1 gzseek() example

    <?php
    $gz = gzopen('somefile.gz', 'r');
    gzseek($gz,2);
    echo gzgetc($gz);
    gzclose($gz);
    ?>

### 参见

- gztell() - Tell gz-file pointer read/write position
- gzrewind() - Rewind the position of a gz-file pointer

# gztell

(PHP 4, PHP 5, PHP 7, PHP 8)

gztell — Tell gz-file pointer read/write position

### 说明

function gztell(resource `$stream`): int|false

Gets the position of the given file pointer; i.e., its offset into the uncompressed file stream.

### 参数

`stream`

  The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().

### 返回值

The position of the file pointer or `false` if an error occurs.

### 参见

- gzopen() - Open gz-file
- gzseek() - Seek on a gz-file pointer
- gzrewind() - Rewind the position of a gz-file pointer

# gzuncompress

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

gzuncompress — Uncompress a compressed string

### 说明

function gzuncompress(string `$data`, int `$max_length` = 0): string|false

This function uncompress a compressed string.

### 参数

`data`

  The data compressed by gzcompress().

`max_length`

  The maximum length of data to decode.

### 返回值

The original uncompressed data or `false` on error.

The function will return an error if the uncompressed data is more than 32768 times the length of the compressed input `data` or more than the optional parameter `max_length`.

### 示例

示例 #1 gzuncompress() example

    <?php
    $compressed   = gzcompress('Compress me', 9);
    $uncompressed = gzuncompress($compressed);
    echo $uncompressed;
    ?>

### 参见

- gzcompress() - Compress a string
- gzinflate() - Inflate a deflated string
- gzdeflate() - Deflate a string
- gzencode() - Create a gzip compressed string

# gzwrite

(PHP 4, PHP 5, PHP 7, PHP 8)

gzwrite — Binary-safe gz-file write

### 说明

function gzwrite(resource `$stream`, string `$data`, ?int `$length` = `null`): int|false

gzwrite() writes the contents of `data` to the given gz-file.

### 参数

`stream`

  The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().

`data`

  The string to write.

`length`

  The number of uncompressed bytes to write. If supplied, writing will stop after `length` (uncompressed) bytes have been written or the end of `data` is reached, whichever comes first.

### 返回值

Returns the number of (uncompressed) bytes written to the given gz-file stream, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `length` is nullable now; previously, the default was `0`.
7.4.0 | This functions returns `false` on failure now; previously `0` was returned.

### 示例

示例 #1 gzwrite() example

    <?php
    $string = 'Some information to compress';
    $gz = gzopen('somefile.gz','w9');
    gzwrite($gz, $string);
    gzclose($gz);
    ?>

### 参见

- gzread() - Binary-safe gz-file read
- gzopen() - Open gz-file

# inflate_add

(PHP 7, PHP 8)

inflate_add — Incrementally inflate encoded data

### 说明

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.

### 参数

`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.

### 返回值

Returns a chunk of uncompressed data, 或者在失败时返回 `false`.

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `context` expects an InflateContext instance now; previously, a resource was expected.

### 参见

- 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

### 说明

function inflate_get_read_len(InflateContext `$context`): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

`context`

### 返回值

Returns number of bytes read so far 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
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

### 说明

function inflate_get_status(InflateContext `$context`): int

Usually returns either `ZLIB_OK` or `ZLIB_STREAM_END`.

### 参数

`context`

### 返回值

Returns decompression status.

### 更新日志

版本 | 说明
--- | ---
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

### 说明

function inflate_init(int `$encoding`, array|object `$options` = []): InflateContext|false

Initialize an incremental inflate context with the specified `encoding`.

### 参数

`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).

### 返回值

Returns an inflate context resource (`zlib.inflate`) on success, 或者在失败时返回 `false`.

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | On success, this function returns an InflateContext instance now; previously, a resource was returned.

### 注释

警告

Unlike gzinflate(), incremental inflate contexts do not constrain the length of the decoded data, so provide no automatic protection against Zip bombs.

### 参见

- 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 回调函数压缩输出缓冲区

### 说明

function ob_gzhandler(string `$data`, int `$flags`): string|false

ob_gzhandler() 目的用作 ob_start() 的回调函数，以便将 gz 编码的数据发送到支持网页压缩的 Web 浏览器。在 ob_gzhandler() 实际发送压缩数据之前，该函数会确定浏览器接受哪种类型的内容编码（"gzip"、"deflate" 或都不接受），然后相应的返回输出。支持所有发送正确头消息以表明接受压缩网页的浏览器。如果浏览器不支持压缩页面，则函数返回 `false`。

### 参数

`data`

`flags`

### 返回值

### 示例

示例 #1 ob_gzhandler() 示例

    <?php

    ob_start("ob_gzhandler");

    ?>
    <html>
    <body>
    <p>This should be a compressed page.</p>
    </body>
    </html>

### 注释

> 注意:

> ob_gzhandler() 需要 zlib 扩展。

> 注意:

> 不能同时使用 ob_gzhandler() 和 zlib.output_compression。也要注意使用 zlib.output_compression 要优于 ob_gzhandler()。

### 参见

- ob_start() - 打开输出控制缓冲
- ob_end_flush() - 冲刷（发送）活动输出处理程序的返回值，并关闭活动输出缓冲区

# readgzfile

(PHP 4, PHP 5, PHP 7, PHP 8)

readgzfile — Output a gz-file

### 说明

function readgzfile(string `$filename`, bool `$use_include_path` = `false`): int|false

Reads a file, decompresses it and writes it to standard output.

readgzfile() can be used to read a file which is not in gzip format; in this case readgzfile() will directly read from the file without decompression.

### 参数

`filename`

  The file name. This file will be opened from the filesystem and its contents written to standard output.

`use_include_path`
  When set to `true` the include_path will be used to determine which file to open.

### 返回值

Returns the number of (uncompressed) bytes read from the file on success, 或者在失败时返回 `false`

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 更新日志

版本 | 说明
--- | ---
8.5.0 | `use_include_path` is now of type bool. Previously, it was of type int.

### 参见

- gzpassthru() - Output all remaining data on a gz-file pointer
- gzfile() - Read entire gz-file into an array
- gzopen() - Open gz-file

# zlib_decode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

zlib_decode — Uncompress any raw/gzip/zlib encoded data

### 说明

function zlib_decode(string `$data`, int `$max_length` = 0): string|false

Uncompress any raw/gzip/zlib encoded data.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`data`

`max_length`

### 返回值

Returns the uncompressed data, 或者在失败时返回 `false`.

### 参见

- zlib_encode() - Compress data with the specified encoding

# zlib_encode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

zlib_encode — Compress data with the specified encoding

### 说明

function zlib_encode(string `$data`, int `$encoding`, int `$level` = -1): string|false

Compress data with the specified encoding.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`data`

  The data to compress.

`encoding`

  The compression algorithm. Either `ZLIB_ENCODING_RAW`, `ZLIB_ENCODING_DEFLATE` or `ZLIB_ENCODING_GZIP`.

`level`

### 返回值

### 示例

示例 #1 zlib_encode() example

    <?php
    $str = 'hello world';
    $enc = zlib_encode($str, ZLIB_ENCODING_DEFLATE);
    echo bin2hex($enc);
    ?>

以上示例会输出：

    789ccb48cdc9c95728cf2fca4901001a0b045d

### 参见

- zlib_decode() - Uncompress any raw/gzip/zlib encoded data

# zlib_get_coding_type

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

zlib_get_coding_type — Returns the coding type used for output compression

### 说明

function zlib_get_coding_type(): string|false

Returns the coding type used for output compression.

### 参数

此函数没有参数。

### 返回值

Possible return values are `gzip`, `deflate`, or `false`.

### 参见

- The zlib.output_compression directive

## 目录

- deflate_add — Incrementally deflate data
- deflate_init — Initialize an incremental deflate context
- gzclose — Close an open gz-file pointer
- gzcompress — Compress a string
- gzdecode — Decodes a gzip compressed string
- gzdeflate — Deflate a string
- gzencode — Create a gzip compressed string
- gzeof — Test for EOF on a gz-file pointer
- gzfile — Read entire gz-file into an array
- gzgetc — Get character from gz-file pointer
- gzgets — Get line from file pointer
- gzgetss — Get line from gz-file pointer and strip HTML tags
- gzinflate — Inflate a deflated string
- gzopen — Open gz-file
- gzpassthru — Output all remaining data on a gz-file pointer
- gzputs — 别名 gzwrite
- gzread — Binary-safe gz-file read
- gzrewind — Rewind the position of a gz-file pointer
- gzseek — Seek on a gz-file pointer
- gztell — Tell gz-file pointer read/write position
- gzuncompress — Uncompress a compressed string
- gzwrite — Binary-safe gz-file write
- 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 回调函数压缩输出缓冲区
- readgzfile — Output a gz-file
- zlib_decode — Uncompress any raw/gzip/zlib encoded data
- zlib_encode — Compress data with the specified encoding
- zlib_get_coding_type — Returns the coding type used for output compression

# The DeflateContext class

(PHP 8)

## 简介

A fully opaque class which replaces `zlib.deflate` resources as of PHP 8.0.0.

## 类摘要

final class DeflateContext {
}

# The InflateContext class

(PHP 8)

## 简介

A fully opaque class which replaces `zlib.inflate` resources as of PHP 8.0.0.

## 类摘要

final class InflateContext {
}

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
  - 资源类型
- 预定义常量
- 示例
- Zlib 函数
  - deflate_add — Incrementally deflate data
  - deflate_init — Initialize an incremental deflate context
  - gzclose — Close an open gz-file pointer
  - gzcompress — Compress a string
  - gzdecode — Decodes a gzip compressed string
  - gzdeflate — Deflate a string
  - gzencode — Create a gzip compressed string
  - gzeof — Test for EOF on a gz-file pointer
  - gzfile — Read entire gz-file into an array
  - gzgetc — Get character from gz-file pointer
  - gzgets — Get line from file pointer
  - gzgetss — Get line from gz-file pointer and strip HTML tags
  - gzinflate — Inflate a deflated string
  - gzopen — Open gz-file
  - gzpassthru — Output all remaining data on a gz-file pointer
  - gzputs — 别名 gzwrite
  - gzread — Binary-safe gz-file read
  - gzrewind — Rewind the position of a gz-file pointer
  - gzseek — Seek on a gz-file pointer
  - gztell — Tell gz-file pointer read/write position
  - gzuncompress — Uncompress a compressed string
  - gzwrite — Binary-safe gz-file write
  - 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 回调函数压缩输出缓冲区
  - readgzfile — Output a gz-file
  - zlib_decode — Uncompress any raw/gzip/zlib encoded data
  - zlib_encode — Compress data with the specified encoding
  - zlib_get_coding_type — Returns the coding type used for output compression
- DeflateContext — The DeflateContext class
- InflateContext — The InflateContext class

- Bzip2
  - 安装/配置
  - 示例
  - Bzip2 函数
- LZF
  - 安装/配置
  - LZF 函数
- Phar
  - 安装/配置
  - 预定义常量
  - Using Phar Archives
  - Creating Phar Archives
  - What makes a phar a phar and not a tar or a zip?
  - Phar — The Phar class
  - PharData — The PharData class
  - PharFileInfo — The PharFileInfo class
  - PharException — The PharException class
- Rar — Rar Archiving
  - 安装/配置
  - 预定义常量
  - 示例
  - Rar 函数
  - RarArchive — The RarArchive class
  - RarEntry — The RarEntry class
  - RarException — The RarException class
- Zip
  - 安装/配置
  - 预定义常量
  - 示例
  - ZipArchive — ZipArchive 类
  - Zip 函数
- Zlib — Zlib 压缩
  - 安装/配置
  - 预定义常量
  - 示例
  - Zlib 函数
  - DeflateContext — The DeflateContext class
  - InflateContext — The InflateContext class

# 加密扩展

# 散列消息摘要框架

# 简介

该扩展提供了一些函数，可用于使用多种散列算法对任意长度的消息进行直接或增量处理，包括生成 HMAC 值以及包括 HKDF 和 PBKDF2 在内的密钥派生。

散列算法大致分为三类，完整算法列表可在 hash_algos() 的文档中找到。

- 校验和算法（例如 `"crc32b"` 或 `"adler32"`）：用于计算校验和，适用于检测传输错误等场景。这类算法通常速度非常快。但其生成的值往往容易被“猜测”或操纵以制造冲突，因此完全不适合用于加密用途。
- 非加密算法（例如 xxHash 系列）：这些算法通常用于计算散列表的散列值，因为它们旨在为任意字符串输入提供良好的分布性。这些算法通常速度较快，但同样不适合用于加密用途。
- 加密算法（例如 SHA-2 系列）：这些算法旨在生成能够反映输入特征但不可猜测且不易发生冲突的散列值。性能通常是次要考虑因素，但现代硬件通常对这些算法提供专门支持，在可用时 PHP 会尝试利用这些支持。 NIST（美国国家标准与技术研究院）的计算机安全资源中心提供了» 关于美国联邦信息处理标准当前批准算法的说明。
  警告

  一些早期的加密算法，例如 `"md4"`、`"md5"` 和 `"sha1"`，已证明容易受到碰撞攻击，通常建议不再将其用于加密应用。

另请参阅关于安全密码散列的常见问题解答，以获取在处理密码时使用散列函数的最佳实践信息。

# 安装/配置

## 目录

- 安装
- 资源类型

## 安装

Hash 扩展是 PHP 的核心扩展，所以始终启用。

PHP 7.4 之前，Hash 扩展默认在 PHP 中捆绑并编译，但可以通过 --disable-hash 手动禁用。

在 5.1.2 之前，Hash 扩展作为 » PECL 模块 安装。

## 资源类型

本扩展中定义了哈希上下文资源类型， 该类型资源由 hash_init() 函数返回。

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`HASH_HMAC` (int)
  hash_init() 中的可选标志。表示 HMAC digest-keying 算法应被用于当前散列上下文环境。

# HashContext 类

(PHP 7 >= 7.2.0, PHP 8)

## 简介

## 类摘要

final class HashContext {
/* 方法 */
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 function HashContext::__construct()

### 参数

此函数没有参数。

# HashContext::__debugInfo

(PHP 8 >= 8.4.0)

HashContext::__debugInfo — Returns debugging information about the hashing context

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns an associative array of debugging information. It contains an `algo` key holding the name of the hashing algorithm in use by the context.

### 示例

示例 #1 HashContext::__debugInfo() example

    <?php
    $ctx = hash_init('sha256');
    var_dump($ctx);
    ?>

以上示例会输出：

    object(HashContext)#1 (1) {
      ["algo"]=>
      string(6) "sha256"
    }

### 参见

- hash_init() - 初始化增量散列运算上下文
- var_dump() - 打印变量的相关信息

# HashContext::__serialize

(PHP 8)

HashContext::__serialize — 序列化 HashContext 对象

### 说明

public function HashContext::__serialize(): array

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

没有返回值。

# HashContext::__unserialize

(PHP 8)

HashContext::__unserialize — 反序列化 `data` 参数为 HashContext 对象

### 说明

public function HashContext::__unserialize(array `$data`): void

警告

本函数还未编写文档，仅有参数列表。

### 参数

`data`

  要发序列化的值。

### 返回值

没有返回值。

## 目录

- HashContext::__construct — 私有构造方法以禁止直接实例化
- HashContext::__debugInfo — Returns debugging information about the hashing context
- HashContext::__serialize — 序列化 HashContext 对象
- HashContext::__unserialize — 反序列化 data 参数为 HashContext 对象

# Hash 函数

# hash

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash — 生成散列值（消息摘要）

### 说明

function hash(
string `$algo`,
string `$data`,
bool `$binary` = `false`,
array `$options` = []
): string

### 参数

`algo`

  要使用的散列算法的名称（例如：`“sha256”`）。 可以在 hash_algos() 中查看当前支持的算法。

`data`

  要进行散列运算的消息。

`binary`

  设置为 `true` 输出原始二进制数据， 设置为 `false` 输出小写 16 进制字符串。

`options`

  各种散列算法的一系列选项数组。 目前 MurmurHash 算法仅支持 `“seed”` 参数。

### 返回值

如果 `binary` 设置为 `true`， 则返回原始二进制数据表示的信息摘要， 否则返回 16 进制小写字符串格式表示的信息摘要。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 新增 `options` 参数。
8.0.0 | 如果 `algo` 未知，现在 hash() 将抛出 ValueError 异常，之前返回 `false`。

### 示例

示例 #1 hash() 示例

    <?php
    echo hash('sha256', 'The quick brown fox jumped over the lazy dog.');
    ?>

以上示例会输出：

    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

### 参见

- hash_init() - 初始化增量散列运算上下文
- hash_file() - 给指定文件的内容生成散列值
- hash_hmac() - 使用 HMAC 方法生成带有密钥的散列值

# hash_algos

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_algos — 返回已注册的散列算法列表

### 说明

function hash_algos(): array

### 参数

此函数没有参数。

### 返回值

返回一个数值索引的数组， 包含了受支持的散列算法名称。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 新增对 MurmurHash3 和 xxHash 算法的支持。
7.4.0 | 支持 crc32c。
7.1.0 | 加入 sha512/224，sha512/256，sha3-224，sha3-256，sha3-384 以及 sha3-512 算法的支持。

### 示例

示例 #1 hash_algos() 示例

在 PHP 8.1.0 中，hash_algos() 会返回下表所示的算法清单：

    <?php
    print_r(hash_algos());
    ?>

以上示例的输出类似于：

    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
    )

### 参见

- hash() - 生成散列值（消息摘要）
- hash_hmac_algos() - 返回适用于 hash_hmac 的已注册散列算法列表

# hash_copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

hash_copy — 拷贝哈希运算上下文

### 说明

function hash_copy(HashContext `$context`): HashContext

### 参数

`context`

  由 hash_init() 函数返回的哈希运算上下文。

### 返回值

返回哈希运算上下文的一个复本。

### 更新日志

版本 | 说明
--- | ---
7.2.0 | 接受的参数以及返回值从资源类型修改为 HashContext 对象类型。

### 示例

示例 #1 hash_copy() 示例

    <?php
    $context = hash_init("sha256");
    hash_update($context, "The quick brown fox ");

    /* 拷贝上下文资源以便继续使用 */
    $copy_context = hash_copy($context);

    echo hash_final($context), "\n";

    hash_update($copy_context, "jumped over the lazy dog.");
    echo hash_final($copy_context), "\n";
    ?>

以上示例会输出：

    b29d66e56ed90cce9b0165c43fedec612b60a071974d8be4513e18580d55b5bd
    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

# hash_equals

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

hash_equals — 可防止时序攻击的字符串比较

### 说明

function hash_equals(#[\SensitiveParameter] string `$known_string`, #[\SensitiveParameter] string `$user_string`): bool

检查两个字符串是否相等，而不会通过执行时泄露有关 `known_string` 内容的任何信息。

此函数可用于缓解计时攻击。使用 `===` 进行常规比较所需的时间的长短取决于两个值是否不同以及可以找到第一个不同的位置，从而泄露有关 `known_string` 内容的秘密信息。

警告

非常重要的一点是，用户提供的字符串必须是第二个参数。

### 参数

`known_string`

  必须保密的已知 string。

`user_string`

  与已知字符串进行比较的用户提供的 string。

### 返回值

当两个字符串相等时返回 `true`，否则返回 `false`。

### 示例

示例 #1 hash_equals() 示例

    <?php
    $secretKey = '8uRhAeH89naXfFXKGOEj';

    // 值和签名是由用户提供的，例如在 URL 中，使用 $_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;
    }
    ?>

以上示例会输出：

    The value is correctly signed.

### 注释

> 注意:

> 要想成功进行比较，那么所提供的 2 个参数必须是相同长度的字符串。 如果所提供的字符串长度不同，那么本函数会立即返回 `false`， 在时序攻击的场景下，已知字符串的长度可能会被泄露。

### 参见

- hash_hmac() - 使用 HMAC 方法生成带有密钥的散列值

# hash_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_file — 给指定文件的内容生成散列值

### 说明

function hash_file(
string `$algo`,
string `$filename`,
bool `$binary` = `false`,
array `$options` = []
): string|false

### 参数

`algo`

  要使用的散列算法的名称（例如：`“sha256”`）。 可以在 hash_algos() 中查看当前支持的算法。

`filename`

  要进行散列运算的文件位置的 URL；支持 fopen() 封装协议。

`binary`

  设置为 `true` 时，输出原始二进制数据。 设置为 `false` 时，输出小写的十六进制字符串。

`options`

  各种散列算法的一系列选项数组。 目前 MurmurHash 算法仅支持 `“seed”` 参数。

### 返回值

返回的字符串包含计算出的消息摘要，默认为小写十六进制字符串， 如果 `binary` 设置为 true，则返回原始二进制表示， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 新增 `options` 参数。

### 示例

示例 #1 hash_file() 示例

    <?php
    /* Create a file to calculate hash of */
    file_put_contents('example.txt', 'The quick brown fox jumped over the lazy dog.');

    echo hash_file('sha256', 'example.txt');
    ?>

以上示例会输出：

    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

### 参见

- hash_init() - 初始化增量散列运算上下文
- hash_hmac_file() - 使用 HMAC 方法和给定文件的内容生成带密钥的散列值

# hash_final

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_final — 结束增量散列且返回摘要结果

### 说明

function hash_final(HashContext `$context`, bool `$binary` = `false`): string

### 参数

`context`

  hash_init() 返回的散列上下文资源。

`binary`

  设置为 `true`，输出格式为原始的二进制数据。 设置为 `false`，输出小写的 16 进制字符串。

### 返回值

如果 `binary` 设置为 `true`， 则返回原始二进制数据表示的信息摘要， 否则返回 16 进制小写字符串格式表示的信息摘要。

### 更新日志

版本 | 说明
--- | ---
7.2.0 | 接收参数从资源类型修改为 HashContext 对象类型。

### 参见

- hash_init() - 初始化增量散列运算上下文
- hash_update() - 向活跃的哈希运算上下文中填充数据
- hash_update_stream() - 从打开的流向活跃的散列运算上下文中填充数据
- hash_update_file() - 从文件向活跃的散列运算上下文中填充数据

# hash_hkdf

(PHP 7 >= 7.1.2, PHP 8)

hash_hkdf — Generate a HKDF key derivation of a supplied key input

### 说明

function hash_hkdf(
string `$algo`,
#[\SensitiveParameter] string `$key`,
int `$length` = 0,
string `$info` = "",
string `$salt` = ""
): string

### 参数

`algo`

  Name of selected hashing algorithm (e.g. `"sha256"`). For a list of supported algorithms see hash_hmac_algos().

  > 注意:

  > 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.

### 返回值

Returns a string containing a raw binary representation of the derived key (also known as output keying material - OKM).

### 错误／异常

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).

### 更新日志

版本 | 说明
--- | ---
8.0.0 | Now throws a ValueError exception on error. Previously, `false` was returned and an `E_WARNING` message was emitted.

### 示例

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.

示例 #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)
    ?>

### 参见

- hash_pbkdf2() - 生成所提供密码的 PBKDF2 密钥导出
- » RFC 5869
- » userland implementation

# hash_hmac

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_hmac — 使用 HMAC 方法生成带有密钥的散列值

### 说明

function hash_hmac(
string `$algo`,
string `$data`,
#[\SensitiveParameter] string `$key`,
bool `$binary` = `false`
): string

### 参数

`algo`

  要使用的散列算法的名称（例如：`“sha256”`）。 可以在 hash_hmac_algos() 中查看当前支持的算法。

  > 注意:

  > 不允许使用非加密哈希函数。

`data`

  要进行散列运算的消息。

`key`

  使用 HMAC 生成信息摘要时所使用的密钥。

`binary`

  设置为 `true` 输出原始二进制数据，设置为 `false` 输出小写 16 进制字符串。

### 返回值

如果 `binary` 设置为 `true`，则返回原始二进制数据表示的信息摘要，否则返回 16 进制小写字符串格式表示的信息摘要。

### 错误／异常

如果 `algo` 未知或非加密散列函数，则抛出 ValueError 异常。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 如果 `algo` 未知或者非加密散列函数，现在将抛出 ValueError 异常；以前返回 `false`。
7.2.0 | 不再支持非加密的散列函数（adler32、crc32、crc32b、fnv132、fnv1a32、fnv164、fnv1a64、joaat）。

### 示例

示例 #1 hash_hmac() 示例

    <?php
    echo hash_hmac('sha256', 'The quick brown fox jumped over the lazy dog.', 'secret');
    ?>

以上示例会输出：

    9c5c42422b03f0ee32949920649445e417b2c634050833c5165704b825c2a53b

### 参见

- hash_hmac_algos() - 返回适用于 hash_hmac 的已注册散列算法列表
- hash_hmac_file() - 使用 HMAC 方法和给定文件的内容生成带密钥的散列值
- hash_equals() - 可防止时序攻击的字符串比较

# hash_hmac_algos

(PHP 7 >= 7.2.0, PHP 8)

hash_hmac_algos — 返回适用于 hash_hmac 的已注册散列算法列表

### 说明

function hash_hmac_algos(): array

### 参数

此函数没有参数。

### 返回值

返回数字索引数组，包含适用于 hash_hmac() 支持的散列算法列表。

### 示例

示例 #1 hash_hmac_algos() 示例

    <?php
    print_r(hash_hmac_algos());

以上示例的输出类似于：

    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
    )

### 注释

> 注意:

> 在 PHP 7.2.0 之前，获取支持的散列算法列表的唯一方法是调用 hash_algos()，该方法也会返回不适合 hash_hmac() 的散列算法。

### 参见

- hash_hmac() - 使用 HMAC 方法生成带有密钥的散列值
- hash_algos() - 返回已注册的散列算法列表

# hash_hmac_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_hmac_file — 使用 HMAC 方法和给定文件的内容生成带密钥的散列值

### 说明

function hash_hmac_file(
string `$algo`,
string `$filename`,
#[\SensitiveParameter] string `$key`,
bool `$binary` = `false`
): string|false

### 参数

`algo`

  要使用的散列算法的名称（例如：`“sha256”`）。 可以在 hash_hmac_algos() 中查看当前支持的算法。

  > 注意:

  > 不允许使用非加密哈希函数。

`filename`

  要进行散列运算的文件路径，支持 fopen 封装器。

`key`

  使用 HMAC 生成信息摘要时所使用的密钥。

`binary`

  设置为 `true` 输出原始二进制数据， 设置为 `false` 输出小写 16 进制字符串。

### 返回值

如果 `binary` 设置为 `true`， 则返回原始二进制数据表示的信息摘要，否则返回 16 进制小写字符串格式表示的信息摘要。如果无法读取文件 `filename`，则返回 `false`。

### 错误／异常

如果 `algo` 未知或非加密散列函数，则抛出 ValueError 异常。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 如果 `algo` 未知或非加密散列函数，现在抛出 ValueError 异常，之前返回 `false`。
7.2.0 | 禁用非加密散列函数（adler32、crc32、crc32b、fnv132、fnv1a32、fnv164、fnv1a64、joaat）。

### 示例

示例 #1 hash_hmac_file() 示例

    <?php
    /* 创建一个要计算散列值的文件 */
    file_put_contents('example.txt', 'The quick brown fox jumped over the lazy dog.');

    echo hash_hmac_file('sha256', 'example.txt', 'secret');
    ?>

以上示例会输出：

    9c5c42422b03f0ee32949920649445e417b2c634050833c5165704b825c2a53b

### 参见

- hash_hmac() - 使用 HMAC 方法生成带有密钥的散列值
- hash_hmac_algos() - 返回适用于 hash_hmac 的已注册散列算法列表
- hash_init() - 初始化增量散列运算上下文
- hash_equals() - 可防止时序攻击的字符串比较

# hash_init

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_init — 初始化增量散列运算上下文

### 说明

function hash_init(
string `$algo`,
int `$flags` = 0,
#[\SensitiveParameter] string `$key` = "",
array `$options` = []
): HashContext

### 参数

`algo`

  要使用的散列算法的名称（例如：`“sha256”`）。 可以在 hash_algos() 中查看当前支持的算法。

  > 注意:

  > 如果指定 `HASH_HMAC` 标志，则不允许使用非加密哈希函数。

`flags`

  进行散列运算的可选设置，目前仅支持一个选项：`HASH_HMAC`。当指定此选项的时候，必须指定 `key` 参数。

`key`

  当 `flags` 参数为 `HASH_HMAC` 时，使用此参数传入进行 HMAC 散列运算时的共享密钥。

`options`

  各种散列算法的一系列选项数组。 目前 MurmurHash 算法仅支持 `“seed”` 参数。

### 返回值

返回散列运算上下文对象，以供 hash_update()、hash_update_stream()、hash_update_file() 和 hash_final() 函数使用。

### 错误／异常

- 如果 `algo` 未知或非加密散列函数，或者 `key` 为空时，抛出 ValueError 异常。
- 在 `options` 中传递错误类型的配置选项时，现在会发出 `E_DEPRECATED` 错误，因为会解读错误。在未来，这将成为 ValueError。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 现在已弃用传递错误类型的选项。
8.1.0 | 新增 `options` 参数。
8.0.0 | 如果 `algo` 未知或非加密散列函数，或者 `key` 为空时，现在抛出 ValueError 异常。之前返回 `false` 并发出 `E_WARNING` 消息。
7.2.0 | 当使用 `HASH_HMAC` 选项的时候，不再支持非加密的散列函数（adler32，crc32，crc32b，fnv132，fnv1a32，fnv164，fnv1a64，joaat）。
7.2.0 | 返回 HashContext 对象，不再返回资源类型。

### 示例

示例 #1 增量散列运算示例

    <?php
    $hash = hash('sha256', 'The quick brown fox jumped over the lazy dog.');

    $ctx = hash_init('sha256');
    hash_update($ctx, 'The quick brown fox ');
    hash_update($ctx, 'jumped over the lazy dog.');
    $incremental_hash = hash_final($ctx);

    echo $incremental_hash, PHP_EOL;
    var_dump($hash === $incremental_hash);
    ?>

以上示例会输出：

    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483
    bool(true)

### 参见

- hash_algos() - 返回已注册的散列算法列表
- hash_update() - 向活跃的哈希运算上下文中填充数据
- hash_update_file() - 从文件向活跃的散列运算上下文中填充数据
- hash_update_stream() - 从打开的流向活跃的散列运算上下文中填充数据
- hash_final() - 结束增量散列且返回摘要结果

# hash_pbkdf2

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

hash_pbkdf2 — 生成所提供密码的 PBKDF2 密钥导出

### 说明

function hash_pbkdf2(
string `$algo`,
#[\SensitiveParameter] string `$password`,
string `$salt`,
int `$iterations`,
int `$length` = 0,
bool `$binary` = `false`,
array `$options` = []
): string

### 参数

`algo`

  要使用的散列算法的名称（例如：`“sha256”`）。 可以在 hash_hmac_algos() 中查看当前支持的算法。

  > 注意:

  > 不允许使用非加密哈希函数。

`password`

  要进行导出的密码。

`salt`

  进行导出时所使用的“盐”，这个值应该是随机生成的。

`iterations`

  进行导出时的迭代次数。

`length`

  密钥导出数据的长度。如果 `binary` 为 `true`， 此参数为密钥导出数据的字节长度。如果 `binary` 为 `false`， 此参数为密钥导出数据的字节长度的 2 倍，因为 1 个字节数据对应的 2 个 16 进制的字符。

  如果传入 `0`，则使用所选算法的完整输出大小。

`binary`

  设置为 `true` 输出原始二进制数据， 设置为 `false` 输出小写 16 进制字符串。

`options`

  各种散列算法的一系列选项数组。 目前 MurmurHash 算法仅支持 `“seed”` 参数。

### 返回值

如果 `binary` 设置为 `true`， 则返回原始二进制数据表示的信息摘要， 否则返回 16 进制小写字符串格式表示的信息摘要。

### 错误／异常

在以下情况下会抛出 ValueError 异常：算法未知，`iterations` 小于等于 `0`，`length` 小于等于 `0` 或者 `salt` 过长（大于 `INT_MAX``- 4`）。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在错误时将抛出 ValueError 异常。之前返回 `false` 并发出 `E_WARNING` 消息。
7.2.0 | 不再支持非加密的散列函数（adler32、crc32、crc32b、fnv132、fnv1a32、fnv164、fnv1a64、joaat）。

### 示例

示例 #1 hash_pbkdf2() 示例，基础用法

    <?php
    $password = "password";
    $iterations = 600000;

    // 使用 random_bytes() 生成一个加密安全的随机盐。
    $salt = random_bytes(16);

    $hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 20);
    var_dump($hash);

    // 对于原始二进制，$length 需要减半以获得相同的结果
    $hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 10, true);
    var_dump(bin2hex($hash));?>
    ?>

以上示例的输出类似于：

    string(20) "120fb6cffcf8b32c43e7"
    string(20) "120fb6cffcf8b32c43e7"

### 注释

警告

为了安全起见，可以使用 PBKDF2 方法对密码明文进行散列运算后再存储。但是更好的方案是使用 password_hash() 函数或者使用 `CRYPT_BLOWFISH` 算法调用 crypt() 函数。

### 参见

- password_hash() - 创建密码的散列（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 — 向活跃的哈希运算上下文中填充数据

### 说明

function hash_update(HashContext `$context`, string `$data`): true

### 参数

`context`

  由 hash_init() 函数返回的哈希运算上下文。

`data`

  要向哈希摘要中追加的数据。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 现在返回类型为 true，而不是 bool。
7.2.0 | 接收参数从资源类型修改为 HashContext 对象类型。

### 参见

- hash_init() - 初始化增量散列运算上下文
- hash_update_file() - 从文件向活跃的散列运算上下文中填充数据
- hash_update_stream() - 从打开的流向活跃的散列运算上下文中填充数据
- hash_final() - 结束增量散列且返回摘要结果

# hash_update_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update_file — 从文件向活跃的散列运算上下文中填充数据

### 说明

function hash_update_file(HashContext `$context`, string `$filename`, ?resource `$stream_context` = `null`): bool

### 参数

`context`

  由 hash_init() 函数返回的散列运算上下文。

`filename`

  要进行散列运算的文件位置的 URL；支持 fopen() 封装器。

`stream_context`

  由 stream_context_create() 函数返回的流上下文。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `stream_context` 现在可以为 null。
7.2.0 | 接收参数从资源类型修改为 HashContext 对象类型。

### 参见

- hash_init() - 初始化增量散列运算上下文
- hash_update() - 向活跃的哈希运算上下文中填充数据
- hash_update_stream() - 从打开的流向活跃的散列运算上下文中填充数据
- hash_final() - 结束增量散列且返回摘要结果
- hash_file() - 给指定文件的内容生成散列值

# hash_update_stream

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update_stream — 从打开的流向活跃的散列运算上下文中填充数据

### 说明

function hash_update_stream(HashContext `$context`, resource `$stream`, int `$length` = -1): int

### 参数

`context`

  由 hash_init() 函数返回的散列运算上下文。

`stream`

  创建流的函数返回的打开的文件句柄。

`length`

  要从 `stream` 向活跃的散列运算上下文中拷贝的最大字符数。

### 返回值

从 `stream` 向散列运算上下文中实际填充的字节数量。

### 更新日志

版本 | 说明
--- | ---
7.2.0 | 接收参数从资源类型修改为 HashContext 对象类型。

### 示例

示例 #1 hash_update_stream() 示例

    <?php
    $fp = tmpfile();
    fwrite($fp, 'jumped over the lazy dog.');
    rewind($fp);

    $ctx = hash_init('sha256');
    hash_update($ctx, 'The quick brown fox ');
    hash_update_stream($ctx, $fp);
    echo hash_final($ctx);
    ?>

以上示例会输出：

    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

### 参见

- hash_init() - 初始化增量散列运算上下文
- hash_update() - 向活跃的哈希运算上下文中填充数据
- hash_final() - 结束增量散列且返回摘要结果

## 目录

- hash — 生成散列值（消息摘要）
- hash_algos — 返回已注册的散列算法列表
- hash_copy — 拷贝哈希运算上下文
- hash_equals — 可防止时序攻击的字符串比较
- hash_file — 给指定文件的内容生成散列值
- hash_final — 结束增量散列且返回摘要结果
- hash_hkdf — Generate a HKDF key derivation of a supplied key input
- hash_hmac — 使用 HMAC 方法生成带有密钥的散列值
- hash_hmac_algos — 返回适用于 hash_hmac 的已注册散列算法列表
- hash_hmac_file — 使用 HMAC 方法和给定文件的内容生成带密钥的散列值
- hash_init — 初始化增量散列运算上下文
- hash_pbkdf2 — 生成所提供密码的 PBKDF2 密钥导出
- hash_update — 向活跃的哈希运算上下文中填充数据
- hash_update_file — 从文件向活跃的散列运算上下文中填充数据
- hash_update_stream — 从打开的流向活跃的散列运算上下文中填充数据

- 安装/配置
  - 安装
  - 资源类型
- 预定义常量
- HashContext — HashContext 类
  - HashContext::__construct — 私有构造方法以禁止直接实例化
  - HashContext::__debugInfo — Returns debugging information about the hashing context
  - HashContext::__serialize — 序列化 HashContext 对象
  - HashContext::__unserialize — 反序列化 data 参数为 HashContext 对象
- Hash 函数
  - hash — 生成散列值（消息摘要）
  - hash_algos — 返回已注册的散列算法列表
  - hash_copy — 拷贝哈希运算上下文
  - hash_equals — 可防止时序攻击的字符串比较
  - hash_file — 给指定文件的内容生成散列值
  - hash_final — 结束增量散列且返回摘要结果
  - hash_hkdf — Generate a HKDF key derivation of a supplied key input
  - hash_hmac — 使用 HMAC 方法生成带有密钥的散列值
  - hash_hmac_algos — 返回适用于 hash_hmac 的已注册散列算法列表
  - hash_hmac_file — 使用 HMAC 方法和给定文件的内容生成带密钥的散列值
  - hash_init — 初始化增量散列运算上下文
  - hash_pbkdf2 — 生成所提供密码的 PBKDF2 密钥导出
  - hash_update — 向活跃的哈希运算上下文中填充数据
  - hash_update_file — 从文件向活跃的散列运算上下文中填充数据
  - hash_update_stream — 从打开的流向活跃的散列运算上下文中填充数据

# Mcrypt

# 简介

警告

此功能自 PHP 7.1.0 起弃用，并在 PHP 7.2.0 中移除。

此功能可以使用如下替代：

- Sodium （自 PHP 7.2.0 起可用）
- OpenSSL

> 注意: 此扩展已被移至 » PECL 资源库；不再与 PHP 捆绑，从 PHP 7.2.0.

本扩展是 mcrypt 库的接口，mcrypt 库提供了对多种块算法的支持，包括：DES、TripleDES、Blowfish（默认）、3-WAY、SAFER-SK64、SAFER-SK128、TWOFISH、TEA、RC2 以及 GOST，并且支持 CBC、OFB、CFB 和 ECB 密码模式。此外，还支持诸如 RC6 和 IDEA 这两种“非免费”的算法。默认情况下，CFB/OFB 是 8bit。

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置
- 资源类型

## 需求

这些函数需要使用 » mcrypt 库。 请从 » http://mcrypt.sourceforge.net/ 下载 libmcrypt-x.x.tar.gz， 并按以下指导完成安装。

你需要使用 libmcrypt 2.5.6 或更高版本。

PHP 5.2 的 Windows 二进制发行版中已经包含了本库。 PHP 5.3 的 Windows 二进制发行版中开始使用 MCrypt 静态库， 所以不再需要 DLL。

如果使用 libmcrypt 2.4.x 或更高版本链接编译 PHP，支持以下附加的分组加密算法： CAST，LOKI97，RIJNDAEL，SAFERPLUS，SERPENT， 以及以下流密码：ENIGMA（加密）， PANAMA，RC4 和 WAKE。 如果使用 libmcrypt 2.4.x 或更高版本，那么还支持 nOFB 密码模式。

## 安装

此扩展已被移至 » PECL 资源库；不再与 PHP 捆绑，从 PHP 7.2.0

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/mcrypt.

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

Mcrypt 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
mcrypt.algorithms_dir | `null` | `INI_ALL` |
mcrypt.modes_dir | `null` | `INI_ALL` |

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`mcrypt.algorithms_dir` string
  包含算法的目录。 默认情况向是 libmcrypt 的编译目录， 通常是 /usr/local/lib/libmcrypt。 更多信息请参见 mcrypt_list_algorithms()。
`mcrypt.modes_dir` string
  包含模式的目录。 默认情况向是 libmcrypt 的编译目录， 通常是 /usr/local/lib/libmcrypt。 更多信息请参见 mcrypt_list_modes()。

## 资源类型

mcrypt_module_open() 返回加密描述符。

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

Mcrypt 支持以下四种分组密码模式：`CBC`， `OFB`，`CFB` 和 `ECB`。 如果使用 libmcrypt-2.4.x 或更高版本链接， 还可以支持 `nOFB` 分组模式 和 `STREAM` 模式。 下列是所支持的加密模式以及其对应的预定义常量。 完整的参考见：Applied Cryptography by Schneier (ISBN 0-471-11709-9)。

- `MCRYPT_MODE_ECB` (`electronic codebook`) 是一种分组加密模式，但是它无法适用于大部分场景， 所以不建议使用这种模式进行分组加密。
- `MCRYPT_MODE_CBC` (`cipher block chaining`) 也是一种分组加密方式， 相对 `ECB` 模式，它更加安全。
- `MCRYPT_MODE_CFB` (`8 比特模式的 cipher feedback`) 是一种流式加密模式。 相对于 `CFB` 而言， 推荐使用 `NCFB` 模式。
- `MCRYPT_MODE_OFB` (`output feedback, in 8bit`) 和 `CFB` 类似， 也是一种流式加密模式，它可以用在无法容忍加密错误传播的应用中。 推荐使用 `NOFB` 模式，而不是 `OFB` 模式。
- `MCRYPT_MODE_NOFB` (`output feedback, in nbit`) 和 `OFB` 类似，但是更加安全， 因为它可以按照算法指定的分组大小来对数据进行加密。
- `MCRYPT_MODE_STREAM` 是一种扩展模式， 它包含了诸如 `"WAKE"` 或 `"RC4"` 的流加密算法。

Mcrypt 还支持一些尚未预定义常量的加密模式。 可以通过传入一个字符串来使用使用未预定义常量的加密模式。

- `"ctr"` (`counter mode`) 是一种流式加密模式。
- `"ncfb"` (`cipher feedback, in n-bit mode`)，类似于 `CFB` 模式， 但是它会对于算法设定的整块数据进行操作。

其他模式以及随机设备常量：

`MCRYPT_ENCRYPT` (int)
`MCRYPT_DECRYPT` (int)
`MCRYPT_DEV_RANDOM` (int)
`MCRYPT_DEV_URANDOM` (int)
`MCRYPT_RAND` (int)

# Mcrypt 密码

下表是 mcrypt 扩展所支持的密码。 所支持的密码的完整列表请参见 mcrypt.h 文件。 在 PHP 中使用 mcrypt-2.2.x 的一个通用规则是你可以使用 MCRYPT_ciphername 来访问密码。 在 libmcrypt-2.4.x 和 libmcrypt-2.5.x 的 API 中，这些常量依然可用， 但是你也可以把密码模式以字符串的形式传入 mcrypt_module_open() 函数 来进行访问。

- MCRYPT_3DES
- MCRYPT_ARCFOUR_IV ( 仅 libmcrypt > 2.4.x 可用 )
- MCRYPT_ARCFOUR ( 仅 libmcrypt > 2.4.x 可用 )
- MCRYPT_BLOWFISH
- MCRYPT_CAST_128
- MCRYPT_CAST_256
- MCRYPT_CRYPT
- MCRYPT_DES
- MCRYPT_DES_COMPAT ( 仅 libmcrypt 2.2.x 可用 )
- MCRYPT_ENIGMA ( 仅 libmcrypt > 2.4.x 可用，MCRYPT_CRYPT 的别名)
- MCRYPT_GOST
- MCRYPT_IDEA (非免费算法)
- MCRYPT_LOKI97 ( 仅 libmcrypt > 2.4.x 可用 )
- MCRYPT_MARS ( 仅 libmcrypt > 2.4.x 可用，非免费算法)
- MCRYPT_PANAMA ( 仅 libmcrypt > 2.4.x 可用 )
- MCRYPT_RIJNDAEL_128 ( 仅 libmcrypt > 2.4.x 可用 )
- MCRYPT_RIJNDAEL_192 ( 仅 libmcrypt > 2.4.x 可用 )
- MCRYPT_RIJNDAEL_256 ( 仅 libmcrypt > 2.4.x 可用 )
- MCRYPT_RC2
- MCRYPT_RC4 ( 仅 libmcrypt 2.2.x 可用 )
- MCRYPT_RC6 ( 仅 libmcrypt > 2.4.x 可用 )
- MCRYPT_RC6_128 ( 仅 libmcrypt 2.2.x 可用 )
- MCRYPT_RC6_192 ( 仅 libmcrypt 2.2.x 可用 )
- MCRYPT_RC6_256 ( 仅 libmcrypt 2.2.x 可用 )
- MCRYPT_SAFER64
- MCRYPT_SAFER128
- MCRYPT_SAFERPLUS ( 仅 libmcrypt > 2.4.x 可用 )
- MCRYPT_SERPENT( 仅 libmcrypt > 2.4.x 可用 )
- MCRYPT_SERPENT_128 ( 仅 libmcrypt 2.2.x 可用 )
- MCRYPT_SERPENT_192 ( 仅 libmcrypt 2.2.x 可用 )
- MCRYPT_SERPENT_256 ( 仅 libmcrypt 2.2.x 可用 )
- MCRYPT_SKIPJACK ( 仅 libmcrypt > 2.4.x 可用 )
- MCRYPT_TEAN ( 仅 libmcrypt 2.2.x 可用 )
- MCRYPT_THREEWAY
- MCRYPT_TRIPLEDES ( 仅 libmcrypt > 2.4.x 可用 )
- MCRYPT_TWOFISH ( mcrypt 2.x 之前的版本，或者 2.4.x 之后版本可用 )
- MCRYPT_TWOFISH128 (TWOFISHxxx 在新的 2.x 版本可用，但在 2.4.x 版本不可用)
- MCRYPT_TWOFISH192
- MCRYPT_TWOFISH256
- MCRYPT_WAKE ( 仅 libmcrypt > 2.4.x 可用 )
- MCRYPT_XTEA ( 仅 libmcrypt > 2.4.x 可用 )

如果使用 `CFB` 和 `OFB` 模式， 必须提供初始向量（IV）， 如果使用 `CBC` 模式， 可以提供一个初始向量。 初始向量必须是唯一的，并且在加密和解密过程中要保持一致。 你可以将初始向量和加密后数据一起存储， 其存储位置可以由一个函数的输出来指定， 例如文件名的 MD5 散列值， 这样你就可以把初始向量和加密后的数据一起传输 （关于本话题的更多信息，请参见 Applied Cryptography by Schneier (ISBN 0-471-11709-9) 9.3 一节）。

# Mcrypt 函数

# mcrypt_create_iv

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_create_iv — 从随机源创建初始向量

警告

此函数自 PHP 7.1.0 起弃用，并在 PHP 7.2.0 中移除。

此函数可以使用如下替代：

- random_bytes()

### 说明

function mcrypt_create_iv(int `$size`, int `$source` = MCRYPT_DEV_URANDOM): string

从随机源创建初始向量。

初始向量只是为了给加密算法提供一个可用的种子， 所以它不需要安全保护， 你甚至可以随同密文一起发布初始向量也不会对安全性带来影响。

### 参数

`size`
  初始向量大小。
`source`
  初始向量数据来源。可选值有： `MCRYPT_RAND` （系统随机数生成器）, `MCRYPT_DEV_RANDOM` （从 /dev/random 文件读取数据） 和 `MCRYPT_DEV_URANDOM` （从 /dev/urandom 文件读取数据）。 在 Windows 平台，PHP 5.3.0 之前的版本中，仅支持 `MCRYPT_RAND`。 请注意，在 PHP 5.6.0 之前的版本中， 此参数的默认值为 `MCRYPT_DEV_RANDOM`。

  > 注意: 需要注意的是，如果没有更多可用的用来产生随机数据的信息，那么 `MCRYPT_DEV_RANDOM` 可能进入阻塞状态。

### 返回值

返回初始向量。如果发生错误，则返回 `false`。

### 示例

示例 #1 mcrypt_create_iv() 示例

    <?php
        $size = mcrypt_get_iv_size(MCRYPT_CAST_256, MCRYPT_MODE_CFB);
        $iv = mcrypt_create_iv($size, MCRYPT_DEV_RANDOM);
    ?>

### 参见

- » http://www.ciphersbyritter.com/GLOSSARY.HTM#IV
- » http://www.quadibloc.com/crypto/co0409.htm
- Applied Cryptography by Schneier (ISBN 0-471-11709-9) 9.3 节。
- 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 — 使用给定参数解密密文

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_decrypt(
string `$cipher`,
string `$key`,
string `$data`,
string `$mode`,
string `$iv` = ?
): string|false

解密 `data` 并返回明文。

### 参数

`cipher`
  `MCRYPT_ciphername` 常量中的一个，或者是字符串值的算法名称。
`key`
  数据加密密钥。 如果密钥长度不是加解密算法能够支持的有效长度， 那么会产生警告并且返回 `false`
`data`
  要使用给定的 `cipher` 和 `mode` 解密的数据。 如果数据大小不是 n * 分组大小，则在其后追加 '`\0`' 来补齐。
`mode`
  `MCRYPT_MODE_modename` 常量中的一个，或以下字符串中的一个："ecb"，"cbc"，"cfb"，"ofb"，"nofb" 和 "stream"。
`iv`
  Used for the initialization in CBC, CFB, OFB modes, and in some algorithms in STREAM mode. If the provided IV size is not supported by the chaining mode or no IV was provided, but the chaining mode requires one, the function will emit a warning and return `false`.

### 返回值

以字符串格式返回解密后的数据， 或者在失败时返回 `false`。

### 参见

- mcrypt_encrypt() - 使用给定参数加密明文

# 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 — 返回打开的算法名称

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_enc_get_algorithms_name(resource `$td`): string

本函数返回算法名称。

### 参数

`td`
  加密描述符。

### 返回值

以字符串格式返回打开的加密算法名称。

### 示例

示例 #1 mcrypt_enc_get_algorithms_name() 示例

    <?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";
    ?>

以上示例会输出：

    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 — 返回打开的算法的分组大小

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_enc_get_block_size(resource `$td`): int

获取打开的算法的分组大小。

### 参数

`td`
  加密描述符。

### 返回值

返回指定算法的分组大小，以字节为单位。

# 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 — 返回打开的算法的初始向量大小

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_enc_get_iv_size(resource `$td`): int

本函数返回由加密描述符指定的算法所使用的初始向量大小， 以字节为单位。 在 cbc，cfb 和 ofb 模式以及某些流模式算法中会用到初始向量。

### 参数

`td`
  加密描述符。

### 返回值

返回初始向量大小。如果算法忽略初始向量，则返回 0。

# 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 — 返回打开的模式所能支持的最长密钥

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_enc_get_key_size(resource `$td`): int

返回打开的模式所能支持的最长密钥，以字节为单位。

### 参数

`td`
  加密描述符。

### 返回值

返回打开的模式所能支持的最长密钥，以字节为单位。

# 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 — 返回打开的模式的名称

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_enc_get_modes_name(resource `$td`): string

返回模式名称。

### 参数

`td`
  加密描述符。

### 返回值

以字符串格式返回模式名称。

### 示例

示例 #1 mcrypt_enc_get_modes_name() 示例

    <?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";
    ?>

以上示例会输出：

    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 — 以数组方式返回打开的算法所支持的密钥长度

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_enc_get_supported_key_sizes(resource `$td`): array

获取打开的算法所支持的密钥长度。

### 参数

`td`
  加密描述符。

### 返回值

返回由加密描述符指定的算法所能够支持的密钥长度。 如果该算法支持从 1 到 mcrypt_enc_get_key_size() 之间任意长度的密钥，则返回空数组。

### 示例

示例 #1 mcrypt_enc_get_supported_key_sizes() 示例

    <?php
        $td = mcrypt_module_open('rijndael-256', '', 'ecb', '');
        var_dump(mcrypt_enc_get_supported_key_sizes($td));
    ?>

以上示例会输出：

    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 — 检测打开模式的算法是否为分组算法

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_enc_is_block_algorithm(resource `$td`): bool

打开模式的算法是否为分组算法。

### 参数

`td`
  加密描述符。

### 返回值

如果是分组算法，返回 `true`， 如果是流模式，返回 `false`。

# 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 — 检测打开的模式是否支持分组加密

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_enc_is_block_algorithm_mode(resource `$td`): bool

打开的模式的算法是否支持分组加密 （例如： 如果是流模式，则返回 `false`， cbc，cfb，ofb 模式则返回 `true`）。

### 参数

`td`
  加密描述符。

### 返回值

如果算法支持分组模式，返回 `true`， 反之返回 `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 — 检测打开的模式是否以分组方式输出

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_enc_is_block_mode(resource `$td`): bool

打开的模式是否以分组方式输出 （例如，对于 cbc 和 ecb 模式而言返回 `true`，对于 cfb 和流模式而言，返回 `false`）。

### 参数

`td`
  加密描述符。

### 返回值

如果模式以字节分组（字节块）方式输出，返回 `true`， 如果是以字节方式输出，返回 `false`。

# 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 — 在打开的模块上进行自检

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_enc_self_test(resource `$td`): int

在 `td` 指定的算法 上进行自检操作。

### 参数

`td`
  加密描述符。

### 返回值

自检成功返回 `0`，失败则返回一个小于零的int。

# mcrypt_encrypt

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_encrypt — 使用给定参数加密明文

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_encrypt(
string `$cipher`,
string `$key`,
string `$data`,
string `$mode`,
string `$iv` = ?
): string|false

加密数据并返回密文。

### 参数

`cipher`
  `MCRYPT_ciphername` 常量中的一个，或者是字符串值的算法名称。
`key`
  加密密钥。 如果密钥长度不是该算法所能够支持的有效长度，则函数将会发出警告并返回 `false`
`data`
  使用给定的 `cipher` 和 `mode` 加密的数据。 如果数据长度不是 n*分组大小，则在其后使用 '`\0`' 补齐。 返回的密文长度可能比 `data` 更大。
`mode`
  `MCRYPT_MODE_modename` 常量中的一个，或以下字符串中的一个："ecb"，"cbc"，"cfb"，"ofb"，"nofb" 和 "stream"。
`iv`
  Used for the initialization in CBC, CFB, OFB modes, and in some algorithms in STREAM mode. If the provided IV size is not supported by the chaining mode or no IV was provided, but the chaining mode requires one, the function will emit a warning and return `false`.

### 返回值

以字符串方式返回密文， 或者在失败时返回 `false`。

### 示例

示例 #1 mcrypt_encrypt() 示例

    <?php
        # --- 加密 ---

        # 密钥应该是随机的二进制数据，
        # 开始使用 scrypt, bcrypt 或 PBKDF2 将一个字符串转换成一个密钥
        # 密钥是 16 进制字符串格式
        $key = pack('H*', "bcb04b7e103a0cd8b54763051cef08bc55abe029fdebae5e1d417e2ffb2a00a3");

        # 显示 AES-128, 192, 256 对应的密钥长度：
        #16，24，32 字节。
        $key_size =  strlen($key);
        echo "Key size: " . $key_size . "\n";

        $plaintext = "This string was AES-256 / CBC / ZeroBytePadding encrypted.";

        # 为 CBC 模式创建随机的初始向量
        $iv_size = mcrypt_get_iv_size(MCRYPT_RIJNDAEL_128, MCRYPT_MODE_CBC);
        $iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);

        # 创建和 AES 兼容的密文（Rijndael 分组大小 = 128）
        # 仅适用于编码后的输入不是以 00h 结尾的
        # （因为默认是使用 0 来补齐数据）
        $ciphertext = mcrypt_encrypt(MCRYPT_RIJNDAEL_128, $key,
                                     $plaintext, MCRYPT_MODE_CBC, $iv);

        # 将初始向量附加在密文之后，以供解密时使用
        $ciphertext = $iv . $ciphertext;

        # 对密文进行 base64 编码
        $ciphertext_base64 = base64_encode($ciphertext);

        echo  $ciphertext_base64 . "\n";

        # === 警告 ===

        # 密文并未进行完整性和可信度保护，
        # 所以可能遭受 Padding Oracle 攻击。

        # --- 解密 ---

        $ciphertext_dec = base64_decode($ciphertext_base64);

        # 初始向量大小，可以通过 mcrypt_get_iv_size() 来获得
        $iv_dec = substr($ciphertext_dec, 0, $iv_size);

        # 获取除初始向量外的密文
        $ciphertext_dec = substr($ciphertext_dec, $iv_size);

        # 可能需要从明文末尾移除 0
        $plaintext_dec = mcrypt_decrypt(MCRYPT_RIJNDAEL_128, $key,
                                        $ciphertext_dec, MCRYPT_MODE_CBC, $iv_dec);

        echo  $plaintext_dec . "\n";
    ?>

以上示例会输出：

    Key size: 32
    ENJW8mS2KaJoNB5E5CoSAAu0xARgsR1bdzFWpEn+poYw45q+73az5kYi4j+0haevext1dGrcW8Qi59txfCBV8BBj3bzRP3dFCp3CPQSJ8eU=
    This string was AES-256 / CBC / ZeroBytePadding encrypted.

### 参见

- mcrypt_decrypt() - 使用给定参数解密密文
- mcrypt_module_open() - 打开算法和模式对应的模块

# mcrypt_generic

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic — 加密数据

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_generic(resource `$td`, string `$data`): string

本函数用来加密数据。 传入数据长度必须是 n * 分组大小，否则需要后补 "`\0`"。 本函数返回加密后的数据。 注意，根据数据补齐不同， 返回的数据可能比输入的数据长度有所增加。

如果你需要把加密后的数据保存到数据库， 请确保保存 mcrypt_generic 返回的完整的字符串， 否则将无法正确解密。 如果原始数据有 10 个字符，分组大小为 8 （使用 mcrypt_enc_get_block_size() 获取分组大小）， 则数据库中至少需要 16 个字符来保存数据。 请注意 mdecrypt_generic() 函数返回的数据也会是 16 个字符。 使用 rtrim($str, "\0") 移除字符串末尾的 0 。

如果你在例如 MySQL 这样的数据库中存储数据， 请注意 varchar 类型的字段会在插入数据时自动移除字符串末尾的“空格”。 由于加密后的数据可能是以空格（ASCII 32）结尾， 这种特性会导致数据损坏。 请使用 tinyblob/tinytext（或 larger）字段来存储加密数据。

### 参数

`td`
  加密描述符。 在调用本函数之前， 请使用 mcrypt_generic_init() 函数初始化加密句柄。 在加密完成之后， 需要调用 mcrypt_generic_deinit() 函数进行必要的清理工作。 请参见 mcrypt_module_open() 。
`data`
  要加密的数据。

### 返回值

返回加密后的数据。

### 参见

- mdecrypt_generic() - 解密数据
- mcrypt_generic_init() - 初始化加密所需的缓冲区
- mcrypt_generic_deinit() - 对加密模块进行清理工作

# mcrypt_generic_deinit

(PHP 4 >= 4.0.7, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic_deinit — 对加密模块进行清理工作

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_generic_deinit(resource `$td`): bool

本函数终止由加密描述符（`td`）指定的加密模块， 它会清理缓冲区，但是并不关闭模块。 要想关闭加密模块， 你需要自行调用 mcrypt_module_close() 函数。 （但是 PHP 会在脚本末尾为你关闭已打开的加密模块）

### 参数

`td`
  加密描述符。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- mcrypt_module_open() - 打开算法和模式对应的模块
- mcrypt_generic_init() - 初始化加密所需的缓冲区

# mcrypt_generic_init

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic_init — 初始化加密所需的缓冲区

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_generic_init(resource `$td`, string `$key`, string `$iv`): int

在每次调用 mcrypt_generic() 或 mdecrypt_generic() 函数之前必须调用本函数。

### 参数

`td`
  加密描述符。
`key`
  调用 mcrypt_enc_get_key_size() 函数获得的密钥最大长度。 小于最大长度的数值都被视为非法参数。
`iv`
  通常情况下，向量大小等于算法的分组大小， 但是你应该通过 mcrypt_enc_get_iv_size() 函数 来获得这个值。在 ECB 模式下，初始向量会被忽略， 在 CFB，CBC，STREAM，nOFB 和 OFB 模式下，必须提供初始向量。 初始向量要求是随机的，并且是唯一的（不需要是安全的）。 加密和解密必须使用相同的初始向量。 如果你不想使用初始向量，请将其设置为全 0 值，但是不建议你这么做。

### 返回值

如果发生错误，将会返回负数： -3 表示密钥长度有误，-4 表示内存分配失败， 其他值表示未知错误， 同时会显示对应的警告信息。 如果传入参数不正确，返回 `false`。

### 参见

- mcrypt_module_open() - 打开算法和模式对应的模块

# mcrypt_get_block_size

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_block_size — 获得加密算法的分组大小

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_get_block_size(int `$cipher`): int|false
function mcrypt_get_block_size(string `$cipher`, string `$mode`): int|false

第一个原型针对 libmcrypt 2.2.x， 第二个原型针对 libmcrypt 2.4.x 或 2.5.x。

mcrypt_get_block_size() 用来获取 `cipher` （其中包括了加密模式） 加密算法分组大小。

mcrypt_enc_get_block_size() 函数更加有用， 因为它可以使用 mcrypt_module_open() 函数所返回的资源。

### 参数

`cipher`
  `MCRYPT_ciphername` 常量中的一个，或者是字符串值的算法名称。
`mode`
  `MCRYPT_MODE_modename` 常量中的一个，或以下字符串中的一个："ecb"，"cbc"，"cfb"，"ofb"，"nofb" 和 "stream"。

### 返回值

返回以字节为单位的此算法的分组数据大小。 或者在失败时返回 `false`。

### 示例

示例 #1 mcrypt_get_block_size() 示例

在 libmcrypt 2.4.x 和 2.5.x 下 如何使用本函数。

    <?php

    echo mcrypt_get_block_size('tripledes', 'ecb'); // 8

    ?>

### 参见

- mcrypt_get_key_size() - 获取指定加密算法的密钥大小
- mcrypt_enc_get_block_size() - 返回打开的算法的分组大小
- mcrypt_encrypt() - 使用给定参数加密明文

# mcrypt_get_cipher_name

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_cipher_name — 获取加密算法名称

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_get_cipher_name(int `$cipher`): string
function mcrypt_get_cipher_name(string `$cipher`): string

mcrypt_get_cipher_name() 用来获取加密算法名称。

libmcrypt 2.2.x 中，mcrypt_get_cipher_name() 接受整数表达的加密算法， libmcrypt 2.4.x 及更高版本中，它接受字符串表达的加密算法名称， 返回的都是字符串表达的名称，如果算法不存在则返回 `false`。

### 参数

`cipher`
  `MCRYPT_ciphername` 常量中的一个，或者是字符串值的算法名称。

### 返回值

本函数返回加密算法名称， 如果算法不存在返回 `false`。

### 示例

示例 #1 mcrypt_get_cipher_name() 示例

    <?php
       $cipher = MCRYPT_TripleDES;

       echo mcrypt_get_cipher_name($cipher);
    ?>

以上示例会输出：

    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 — 返回指定算法/模式组合的初始向量大小

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_get_iv_size(string `$cipher`, string `$mode`): int

获取由 `cipher`/`mode` 参数指定的初始向量大小。

mcrypt_enc_get_iv_size() 更加有用， 因为它使用由 mcrypt_module_open() 返回的资源作为参数。

### 参数

`cipher`
  `MCRYPT_ciphername` 常量中的一个，或者是字符串值的算法名称。
`mode`
  `MCRYPT_MODE_modename` 常量中的一个，或以下字符串中的一个："ecb"，"cbc"，"cfb"，"ofb"，"nofb" 和 "stream"。 由于 ECB 模式不使用初始向量，所以会忽略它。 在加密和解密的过程中， 你需要使用相同的初始向量（想象成：开始点）。

### 返回值

返回初始向量的大小，以字节为单位。 如果发生错误，返回 `false`。 如果指定的算法/模式不需要初始向量，返回 0。

### 示例

示例 #1 mcrypt_get_iv_size() 示例

    <?php
        echo mcrypt_get_iv_size(MCRYPT_CAST_256, MCRYPT_MODE_CFB) . "\n";

        echo mcrypt_get_iv_size('des', 'ecb') . "\n";
    ?>

### 参见

- mcrypt_get_block_size() - 获得加密算法的分组大小
- mcrypt_enc_get_iv_size() - 返回打开的算法的初始向量大小
- mcrypt_create_iv() - 从随机源创建初始向量

# mcrypt_get_key_size

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_key_size — 获取指定加密算法的密钥大小

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_get_key_size(int `$cipher`): int|false
function mcrypt_get_key_size(string `$cipher`, string `$mode`): int|false

第一个原型是针对 libmcrypt 2.2.x 的， 第二个原型是针对 libmcrypt 2.4.x 或 2.5.x 的。

mcrypt_get_key_size() 用来获取 由 `cipher` 所指定的算法和模式所需的密钥长度。

mcrypt_enc_get_key_size() 更加有用， 因为它使用由 mcrypt_module_open() 返回的资源。

### 参数

`cipher`
  `MCRYPT_ciphername` 常量中的一个，或者是字符串值的算法名称。
`mode`
  `MCRYPT_MODE_modename` 常量中的一个，或以下字符串中的一个："ecb"，"cbc"，"cfb"，"ofb"，"nofb" 和 "stream"。

### 返回值

返回算法所支持的最大密钥大小，以字节为单位。 或者在失败时返回 `false`。

### 示例

示例 #1 mcrypt_get_key_size() 示例

    <?php
        echo mcrypt_get_key_size('tripledes', 'ecb');
    ?>

在 libmcrypt 2.4.x 或 2.5.x 版本中， 如果使用本函数。

以上示例会输出：

    24

### 参见

- mcrypt_get_block_size() - 获得加密算法的分组大小
- mcrypt_enc_get_key_size() - 返回打开的模式所能支持的最长密钥
- mcrypt_encrypt() - 使用给定参数加密明文

# mcrypt_list_algorithms

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_list_algorithms — 获取支持的加密算法

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_list_algorithms(string `$lib_dir` = ini_get("mcrypt.algorithms_dir")): array

获取 `lib_dir` 中 包含的受支持的算法。

### 参数

`lib_dir`
  指定算法所在的位置。 如果未指定，将使用 php.ini 中的 `mcrypt.algorithms_dir` 指示所指定的位置。

### 返回值

以数组方式返回所有受支持的算法。

### 示例

示例 #1 mcrypt_list_algorithms() 示例

    <?php
    $algorithms = mcrypt_list_algorithms();
    print_r($algorithms);
    ?>

以上示例的输出类似于：

    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 — 获取所支持的模式

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_list_modes(string `$lib_dir` = ini_get("mcrypt.modes_dir")): array

获取 `lib_dir` 中 包含的受支持的模式。

### 参数

`lib_dir`
  指定模式所在的位置。 如果未指定，将使用 php.ini 中的 `mcrypt.modes_dir` 指示所指定的位置。

### 返回值

以数组形式返回受支持的模式。

### 示例

示例 #1 mcrypt_list_modes() 示例

    <?php
        $modes = mcrypt_list_modes();

        foreach ($modes as $mode) {
            echo "$mode <br />\n";
        }
    ?>

本示例列出在默认目录中 所有受支持的模式。 如果在 php.ini 中未指定 `mcrypt.modes_dir`， 则使用默认的 mcrypt 库 安装目录（/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 — 关闭加密模块

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_module_close(resource `$td`): bool

关闭加密模块。

### 参数

`td`
  加密描述符。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- mcrypt_module_open() - 打开算法和模式对应的模块

# 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 — 返回指定算法的分组大小

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_module_get_algo_block_size(string `$algorithm`, string `$lib_dir` = ?): int

返回指定算法的分组大小。

### 参数

`algorithm`
  算法名称。
`lib_dir`
  可选参数 `lib_dir` ， 表示在操作系统上包含模式模块的路径。

### 返回值

返回指定算法的分组大小，以字节为单位。

# 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 — 获取打开模式所支持的最大密钥大小

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_module_get_algo_key_size(string `$algorithm`, string `$lib_dir` = ?): int

获取打开模式所支持的最大密钥大小。

### 参数

`algorithm`
  算法名称。
`lib_dir`
  可选参数， 表示在操作系统上包含模式模块的路径。

### 返回值

本函数返回算法所支持的最大密钥大小， 以字节为单位。

# 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 — 以数组形式返回打开的算法所支持的密钥大小

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_module_get_supported_key_sizes(string `$algorithm`, string `$lib_dir` = ?): array

以数组形式返回指定算法所支持的密钥大小。 如果从 1 到 mcrypt_module_get_algo_key_size() 的密钥大小都支持，则返回空数组。

### 参数

`algorithm`
  算法名称。
`lib_dir`
  可选参数， 表示在操作系统上包含算法模块的路径。

### 返回值

以数组形式返回指定算法所支持的密钥大小。 如果从 1 到 mcrypt_module_get_algo_key_size() 的密钥大小都支持，则返回空数组。

### 参见

- mcrypt_enc_get_supported_key_sizes() - 以数组方式返回打开的算法所支持的密钥长度

# 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 — 检测指定算法是否为分组加密算法

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_module_is_block_algorithm(string `$algorithm`, string `$lib_dir` = ?): bool

如果指定算法是分组加密算法，返回 `true`， 反之返回 `false`。

### 参数

`algorithm`
  要检测的算法。
`lib_dir`
  可选参数 `lib_dir`， 表示在操作系统上包含算法模块的路径。

### 返回值

如果指定算法是分组加密算法，返回 `true`， 反之返回 `false`。

# 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 — 返回指定模块是否是分组加密模式

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_module_is_block_algorithm_mode(string `$mode`, string `$lib_dir` = ?): bool

对于分组加密模式，返回 `true`， 反之返回 `false`。 （例如，对于 STREAM 模式返回 `false`，对于 cbc，cfb，ofb 返回 `true`）

### 参数

`mode`
  模式。
`lib_dir`
  可选参数， 表示在操作系统上包含算法模块的路径。

### 返回值

对于分组加密模式，返回 `true`， 反之返回 `false`。 （例如，对于 STREAM 模式返回 `false`，对于 cbc，cfb，ofb 返回 `true`）

# 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 — 检测指定模式是否以分组方式输出

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_module_is_block_mode(string `$mode`, string `$lib_dir` = ?): bool

如果模式是以字节块（分组）方式输出，则返回 `true`， 如果只是以字节方式输出，则返回 `false`。 （例如，对于 cbc 和 ecb 模式，返回 `true`，对于 cfb 和 stream 模式，返回 `false`）

### 参数

`mode`
  `MCRYPT_MODE_modename` 常量中的一个，或以下字符串中的一个："ecb"，"cbc"，"cfb"，"ofb"，"nofb" 和 "stream"。
`lib_dir`
  可选参数 `lib_dir` ， 表示在操作系统上包含模式模块的路径。

### 返回值

如果模式是以字节块（分组）方式输出，则返回 `true`， 如果只是以字节方式输出，则返回 `false`。 （例如，对于 cbc 和 ecb 模式，返回 `true`，对于 cfb 和 stream 模式，返回 `false`）

# mcrypt_module_open

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_open — 打开算法和模式对应的模块

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_module_open(
string `$algorithm`,
string `$algorithm_directory`,
string `$mode`,
string `$mode_directory`
): resource

本函数打开指定算法和模式对应的模块。 算法名称可以是字符串，例如 `"twofish"`， 也可以是 `MCRYPT_ciphername` 常量。 调用 mcrypt_module_close() 函数可以关闭模块。

### 参数

`algorithm`
  `MCRYPT_ciphername` 常量中的一个，或者是字符串值的算法名称。
`algorithm_directory`
  `algorithm_directory` 参数指示加密模块的位置。 如果你提供此参数，则使用你指定的值。 如果将此参数设置为空字符串（`""`），将使用 php.ini 中的 `mcrypt.algorithms_dir` 。 如果不指定此参数，则使用 libmcrypt 的编译路径 （通常是 /usr/local/lib/libmcrypt）。
`mode`
  `MCRYPT_MODE_modename` 常量中的一个，或以下字符串中的一个："ecb"，"cbc"，"cfb"，"ofb"，"nofb" 和 "stream"。
`mode_directory`
  `algorithm_directory` 参数指示加密模式的位置。 如果你提供此参数，则使用你指定的值。 如果将此参数设置为空字符串（`""`），将使用 php.ini 中的 `mcrypt.modes_dir` 。 如果不指定此参数，则使用 libmcrypt 的编译路径 （通常是 /usr/local/lib/libmcrypt）。

### 返回值

成功则返回加密描述符，如果发生错误则返回 `false`。

### 示例

示例 #1 mcrypt_module_open() 示例

    <?php
        $td = mcrypt_module_open(MCRYPT_DES, '',
            MCRYPT_MODE_ECB, '/usr/lib/mcrypt-modes');

        $td = mcrypt_module_open('rijndael-256', '', 'ofb', '');
    ?>

示例中的第一行从默认目录打开 `DES` 加密算法， 从 /usr/lib/mcrypt-modes 目录打开 `ECB` 模式。 第二个示例中，使用字符串形式表示算法和模式， 这种形式仅适用于 libmcrypt 2.4.x 或 2.5.x 版本。

示例 #2 在加密中使用 mcrypt_module_open()

    <?php
        /* 打开加密算法和模式 */
        $td = mcrypt_module_open('rijndael-256', '', 'ofb', '');

        /* 创建初始向量，并且检测密钥长度。
         * Windows 平台请使用 MCRYPT_RAND。 */
        $iv = mcrypt_create_iv(mcrypt_enc_get_iv_size($td), MCRYPT_DEV_RANDOM);
        $ks = mcrypt_enc_get_key_size($td);

        /* 创建密钥 (此处仅为示例：MD5 不是一个好的哈希算法) */
        $key = substr(hash('md5', 'very secret key'), 0, $ks);

        /* 初始化加密 */
        mcrypt_generic_init($td, $key, $iv);

        /* 加密数据 */
        $encrypted = mcrypt_generic($td, 'This is very important data');

        /* 结束加密，执行清理工作 */
        mcrypt_generic_deinit($td);

        /* 初始化解密模块 */
        mcrypt_generic_init($td, $key, $iv);

        /* 解密数据 */
        $decrypted = mdecrypt_generic($td, $encrypted);

        /* 结束解密，执行清理工作，并且关闭模块 */
        mcrypt_generic_deinit($td);
        mcrypt_module_close($td);

        /* 显示文本 */
        echo trim($decrypted) . "\n";
    ?>

### 参见

- mcrypt_module_close() - 关闭加密模块
- mcrypt_generic() - 加密数据
- mdecrypt_generic() - 解密数据
- mcrypt_generic_init() - 初始化加密所需的缓冲区
- mcrypt_generic_deinit() - 对加密模块进行清理工作

# 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 — 在指定模块上执行自检

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mcrypt_module_self_test(string `$algorithm`, string `$lib_dir` = ?): bool

在指定模块上执行自检。

### 参数

`algorithm`
  `MCRYPT_ciphername` 常量中的一个，或者是字符串值的算法名称。
`lib_dir`
  可选参数 `lib_dir`， 表示包含加密算法模块的路径。

### 返回值

自检成功返回 `true`， 自检失败返回 `false`。

### 示例

示例 #1 mcrypt_module_self_test() 示例

    <?php
    var_dump(mcrypt_module_self_test(MCRYPT_RIJNDAEL_128)) . "\n";
    var_dump(mcrypt_module_self_test(MCRYPT_BOGUS_CYPHER));
    ?>

以上示例会输出：

    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 — 解密数据

警告

本函数已自 PHP 7.1.0 起废弃并将自 PHP 7.2.0 起移除。强烈建议不要使用本函数。

### 说明

function mdecrypt_generic(resource `$td`, string `$data`): string

解密数据。 请注意，由于存在数据补齐的情况， 返回字符串的长度可能和明文的长度不相等。

### 参数

`td`
  由 mcrypt_module_open() 函数创建的加密描述符。
`data`
  密文。

### 返回值

Returns decrypted string.

### 示例

示例 #1 mdecrypt_generic() 示例

    <?php
        /* 数据 */
        $key = 'this is a very long key, even too long for the cipher';
        $plain_text = 'very important data';

        /* 打开加密模块，并且创建初始向量 */
        $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);

        /* 初始化加密句柄 */
        if (mcrypt_generic_init($td, $key, $iv) != -1) {

            /* 加密数据 */
            $c_t = mcrypt_generic($td, $plain_text);
            mcrypt_generic_deinit($td);

            /* 为解密重新初始化缓冲区 */
            mcrypt_generic_init($td, $key, $iv);
            $p_t = mdecrypt_generic($td, $c_t);

            /* 执行清理工作 */
            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";
        }
    ?>

上例中演示了如何检测 解密后的数据是否和原始明文长度一致。 需要着重提醒的是，在对数据进行机密之前， 必须使用 mcrypt_generic_init() 函数来重新初始化缓冲区。

调用本函数之前， 必须使用密钥和初始向量来调用 mcrypt_generic_init() 函数 对解密句柄进行初始化。 加解密工作完成之后，需要调用 mcrypt_generic_deinit() 来释放加解密缓冲区。 示例请参见 mcrypt_module_open()。

### 参见

- mcrypt_generic() - 加密数据
- mcrypt_generic_init() - 初始化加密所需的缓冲区
- mcrypt_generic_deinit() - 对加密模块进行清理工作

## 目录

- mcrypt_create_iv — 从随机源创建初始向量
- mcrypt_decrypt — 使用给定参数解密密文
- mcrypt_enc_get_algorithms_name — 返回打开的算法名称
- mcrypt_enc_get_block_size — 返回打开的算法的分组大小
- mcrypt_enc_get_iv_size — 返回打开的算法的初始向量大小
- mcrypt_enc_get_key_size — 返回打开的模式所能支持的最长密钥
- mcrypt_enc_get_modes_name — 返回打开的模式的名称
- mcrypt_enc_get_supported_key_sizes — 以数组方式返回打开的算法所支持的密钥长度
- mcrypt_enc_is_block_algorithm — 检测打开模式的算法是否为分组算法
- mcrypt_enc_is_block_algorithm_mode — 检测打开的模式是否支持分组加密
- mcrypt_enc_is_block_mode — 检测打开的模式是否以分组方式输出
- mcrypt_enc_self_test — 在打开的模块上进行自检
- mcrypt_encrypt — 使用给定参数加密明文
- mcrypt_generic — 加密数据
- mcrypt_generic_deinit — 对加密模块进行清理工作
- mcrypt_generic_init — 初始化加密所需的缓冲区
- mcrypt_get_block_size — 获得加密算法的分组大小
- mcrypt_get_cipher_name — 获取加密算法名称
- mcrypt_get_iv_size — 返回指定算法/模式组合的初始向量大小
- mcrypt_get_key_size — 获取指定加密算法的密钥大小
- mcrypt_list_algorithms — 获取支持的加密算法
- mcrypt_list_modes — 获取所支持的模式
- mcrypt_module_close — 关闭加密模块
- mcrypt_module_get_algo_block_size — 返回指定算法的分组大小
- mcrypt_module_get_algo_key_size — 获取打开模式所支持的最大密钥大小
- mcrypt_module_get_supported_key_sizes — 以数组形式返回打开的算法所支持的密钥大小
- mcrypt_module_is_block_algorithm — 检测指定算法是否为分组加密算法
- mcrypt_module_is_block_algorithm_mode — 返回指定模块是否是分组加密模式
- mcrypt_module_is_block_mode — 检测指定模式是否以分组方式输出
- mcrypt_module_open — 打开算法和模式对应的模块
- mcrypt_module_self_test — 在指定模块上执行自检
- mdecrypt_generic — 解密数据

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
  - 资源类型
- 预定义常量
- Mcrypt 密码
- Mcrypt 函数
  - mcrypt_create_iv — 从随机源创建初始向量
  - mcrypt_decrypt — 使用给定参数解密密文
  - mcrypt_enc_get_algorithms_name — 返回打开的算法名称
  - mcrypt_enc_get_block_size — 返回打开的算法的分组大小
  - mcrypt_enc_get_iv_size — 返回打开的算法的初始向量大小
  - mcrypt_enc_get_key_size — 返回打开的模式所能支持的最长密钥
  - mcrypt_enc_get_modes_name — 返回打开的模式的名称
  - mcrypt_enc_get_supported_key_sizes — 以数组方式返回打开的算法所支持的密钥长度
  - mcrypt_enc_is_block_algorithm — 检测打开模式的算法是否为分组算法
  - mcrypt_enc_is_block_algorithm_mode — 检测打开的模式是否支持分组加密
  - mcrypt_enc_is_block_mode — 检测打开的模式是否以分组方式输出
  - mcrypt_enc_self_test — 在打开的模块上进行自检
  - mcrypt_encrypt — 使用给定参数加密明文
  - mcrypt_generic — 加密数据
  - mcrypt_generic_deinit — 对加密模块进行清理工作
  - mcrypt_generic_init — 初始化加密所需的缓冲区
  - mcrypt_get_block_size — 获得加密算法的分组大小
  - mcrypt_get_cipher_name — 获取加密算法名称
  - mcrypt_get_iv_size — 返回指定算法/模式组合的初始向量大小
  - mcrypt_get_key_size — 获取指定加密算法的密钥大小
  - mcrypt_list_algorithms — 获取支持的加密算法
  - mcrypt_list_modes — 获取所支持的模式
  - mcrypt_module_close — 关闭加密模块
  - mcrypt_module_get_algo_block_size — 返回指定算法的分组大小
  - mcrypt_module_get_algo_key_size — 获取打开模式所支持的最大密钥大小
  - mcrypt_module_get_supported_key_sizes — 以数组形式返回打开的算法所支持的密钥大小
  - mcrypt_module_is_block_algorithm — 检测指定算法是否为分组加密算法
  - mcrypt_module_is_block_algorithm_mode — 返回指定模块是否是分组加密模式
  - mcrypt_module_is_block_mode — 检测指定模式是否以分组方式输出
  - mcrypt_module_open — 打开算法和模式对应的模块
  - mcrypt_module_self_test — 在指定模块上执行自检
  - mdecrypt_generic — 解密数据

# Mhash

# 简介

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`.

> 注意:

> This extension is obsoleted by Hash.

> 注意:

> 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.

# 安装/配置

## 目录

- 需求
- 安装

## 需求

To use it, download the mhash distribution from » its web site and follow the included installation instructions.

## 安装

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.

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

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)

# 示例

示例 #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";
    ?>

以上示例会输出：

    The hash is d03cb659cbf9192dcd066272249f8412
    The hmac is 750c783e6ab0b503eaa86e310a5db738

# Mhash 函数

# mhash

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash — Computes hash

警告

此函数自 PHP 8.1.0 起弃用。强烈建议不要应用此函数。

### 说明

#[\Deprecated]
function mhash(int `$algo`, string `$data`, ?string `$key` = `null`): string|false

mhash() applies a hash function specified by `algo` to the `data`.

### 参数

`algo`

  The hash ID. One of the `MHASH_hashname` constants.

`data`

  The user input, as a string.

`key`

  If specified, the function will return the resulting HMAC instead. HMAC is keyed hashing for message authentication, or simply a message digest that depends on the specified key. Not all algorithms supported in mhash can be used in HMAC mode.

### 返回值

Returns the resulting hash (also called digest) or HMAC as a string, or `false` on error.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | This function has been deprecated. Use the `hash_*()` functions instead.
8.0.0 | `key` is now nullable.

# mhash_count

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_count — Gets the highest available hash ID

警告

此函数自 PHP 8.1.0 起弃用。强烈建议不要应用此函数。

### 说明

#[\Deprecated]
function mhash_count(): int

Gets the highest available hash ID.

### 参数

此函数没有参数。

### 返回值

Returns the highest available hash ID. Hashes are numbered from 0 to this hash ID.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | This function has been deprecated. Use the `hash_*()` functions instead.

### 示例

示例 #1 Traversing all hashes

    <?php

    $nr = mhash_count();

    for ($i = 0; $i <= $nr; $i++) {
        echo sprintf("The blocksize of %s is %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 — Gets the block size of the specified hash

警告

此函数自 PHP 8.1.0 起弃用。强烈建议不要应用此函数。

### 说明

#[\Deprecated]
function mhash_get_block_size(int `$algo`): int|false

Gets the size of a block of the specified `algo`.

### 参数

`algo`

  The hash ID. One of the `MHASH_hashname` constants.

### 返回值

Returns the size in bytes or `false`, if the `algo` does not exist.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | This function has been deprecated. Use the `hash_*()` functions instead.

### 示例

示例 #1 mhash_get_block_size() Example

    <?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 — Gets the name of the specified hash

警告

此函数自 PHP 8.1.0 起弃用。强烈建议不要应用此函数。

### 说明

#[\Deprecated]
function mhash_get_hash_name(int `$algo`): string|false

Gets the name of the specified `algo`.

### 参数

`algo`

  The hash ID. One of the `MHASH_hashname` constants.

### 返回值

Returns the name of the hash or `false`, if the hash does not exist.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | This function has been deprecated. Use the `hash_*()` functions instead.

### 示例

示例 #1 mhash_get_hash_name() Example

    <?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

警告

此函数自 PHP 8.1.0 起弃用。强烈建议不要应用此函数。

### 说明

#[\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.

### 参数

`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.

### 返回值

Returns the generated key as a string, or `false` on error.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | This function has been deprecated. Use the `hash_*()` functions instead.

## 目录

- mhash — Computes hash
- mhash_count — Gets the highest available hash ID
- mhash_get_block_size — Gets the block size of the specified hash
- mhash_get_hash_name — Gets the name of the specified hash
- mhash_keygen_s2k — Generates a key

- 安装/配置
  - 需求
  - 安装
- 预定义常量
- 示例
- Mhash 函数
  - mhash — Computes hash
  - mhash_count — Gets the highest available hash ID
  - mhash_get_block_size — Gets the block size of the specified hash
  - mhash_get_hash_name — Gets the name of the specified hash
  - mhash_keygen_s2k — Generates a key

# OpenSSL

# 简介

本扩展使用 » OpenSSL 库来对称/非对称加解密，以及 PBKDF2、 PKCS7、 PKCS12、 X509 和其他加密操作。除此之外还提供了 TLS 流的实现。

OpenSSL 还提供了更多本模块暂不支持的功能，某些功能以后可能会增加。

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置
- 资源类型

## 需求

要使用 Open SSL 函数，你必须安装» OpenSSL 库。 PHP 7.0 需要 OpenSSL >= 0.9.8。PHP 7.1-8.0 需要 OpenSSL >= 1.0.1，< 3.0。PHP >= 8.1 支持 OpenSSL >= 1.0.2, < 4.0。 PHP >= 8.4 支持 OpenSSL >= 1.1.1, < 4.0。

警告

强烈建议使用维护的 OpenSSL 版本，否则 web 服务器很容易受到攻击。

## 安装

要使用 PHP 的 OpenSSL 支持，你应该使用 --with-openssl 参数来编译 PHP。

OpenSSL 库还在运行时对正常操作有额外的要求。最明显的是，OpenSSL 需要访问随机或伪随机数生成器； 在大多数 Unix 和类 Unix 平台上(包括linux)，意味着它必须要访问 `/dev/urandom` 或者 `/dev/random` 设备。

--with-system-ciphers 配置选项可用于设置 PHP 使用系统密码列表，而不是硬编码。

> 注意: Win32 平台的用户请注意

> 为了使此扩展生效， DLL 文件必须能在 Windows 系统的 PATH 指示的路径下找到。如何操作的信息，请参见题为“如何在 Windows 中将 PHP 目录加到 PATH 中”的FAQ。虽然将 DLL 文件从 PHP 文件夹复制到 Windows 系统目录也行，但不建议这样做。 此扩展需要下列文件在 PATH 路径中： libeay32.dll， 或者，自 OpenSSL 1.1 起，为 libcrypto-*.dll

> 此外，如果打算使用密钥生成和证书签名功能，你需要在你的系统上安装一个可用的 openssl.cnf 文件。 在我们的 win32 二进制发行版本中，我们已经包含了一个示例配置文件，在 extras/ssl 文件夹中。

> PHP 将会使用如下逻辑搜索 openssl.cnf 文件:

> - 如果 `OPENSSL_CONF` 环境变量设置了，该变量将会被当作配置文件的路径（含文件名）。
> - 如果 `SSLEAY_CONF` 环境变量设置了，该变量将会被当作配置文件的路径（含文件名）。
> - 假设openssl.cnf 文件将会在 openssl DLL 被编译时配置的默认证书区域被找到。这通常意味着默认的文件名是 C:\Program Files\Common Files\SSL\openssl.cnf(x64) 或者 C:\Program Files (x86)\Common Files\SSL\openssl.cnf (x86)，而 PHP 7.4.0之前，则是 C:\usr\local\ssl\openssl.cnf。
> 在你的安装过程中，你需要决定是否将配置文件安装在默认路径或者使用环境变量(可能是基于每个虚拟主机的基础)来定位配置文件安装到其他地方。注意，可以使用引入配置文件的函数中的 `options` 参数来覆盖脚本中的默认路径。
> 警告

> 确保无权限的用户无法修改 openssl.cnf 文件。

> 自 OpenSSL 3.0.0 起，Windows 上默认使用的 OpenSSL 版本为 PHP 8.2.0，已经将几种算法视为遗留算法。 这些算法通常已经不再使用，被密码学社区视为不安全，或者类似的原因。 这些算法仍然可以通过遗留提供者(extras/ssl/legacy.dll)使用；其使用方法在 OpenSSL 手册的 » 提供者配置部分中有描述。

### 更新日志

版本 | 说明
--- | ---
7.4.0 | --with-openssl[=DIR] 不再接受目录参数，有利于将 pkg-config 变量 PKG_CONFIG_PATH 设置为 OpenSSL 位置，或者通过指定 OPENSSL_LIBS 和 OPENSSL_CFLAGS 变量来指向位置。
7.4.0 | OpenSSL 默认配置文件的路径已经从 C:\usr\local\ssl 分别改至 C:\Program Files\Common Files\SSL 和 C:\Program Files (x86)\Common Files\SSL。

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

openssl 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
openssl.cafile | "" | `INI_PERDIR` |
openssl.capath | "" | `INI_PERDIR` |
openssl.libctx | "custom" | `INI_PERDIR` |

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`openssl.cafile` string

  本地文件系统上证书颁发机构文件的位置， 被用来和对等校验上下文选项一起校验远程对等方的身份。

`openssl.capath` string

  如果没有制定证书颁发机构文件或者证书找不到，将在由capath指向的目录下搜索一个合适的证书。capath 必须是一个正确的已被散列的证书目录。

`openssl.libctx` string
  指定要使用的 OpenSSL 库上下文类型。默认值 `custom` 会为每个工作进程或线程创建独立的库上下文。从而增强与其他使用 OpenSSL 的库之间的隔离性，并在 ZTS 构建中提升线程间的分离程度。也可选择 `default` 值，使 PHP 使用 OpenSSL 的全局默认库上下文。

参见 SSL stream context 选项。

## 资源类型

在 PHP 8.0.0 之前，OpenSSL 模块中定义了 3 种资源类型：

- `OpenSSL key`
- `OpenSSL X.509`
- `OpenSSL X.509 CSR`

# 预定义常量

## 目录

- 目的检查 flag
- 非对称加密的填充标志
- 密钥类型
- PKCS7 flag/常量
- CMS Flag/常量
- 签名算法
- Ciphers
- 版本常量
- Server Name Indication constants
- 其它常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

## 目的检查 flag

`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)

## 非对称加密的填充标志

`OPENSSL_PKCS1_PADDING` (int)
`OPENSSL_SSLV23_PADDING` (int)
`OPENSSL_NO_PADDING` (int)
`OPENSSL_PKCS1_OAEP_PADDING` (int)

## 密钥类型

`OPENSSL_KEYTYPE_RSA` (int)
  RSA 密钥类型。
`OPENSSL_KEYTYPE_DSA` (int)
  DSA 密钥类型。
`OPENSSL_KEYTYPE_DH` (int)
  DH（Diffie-Hellman）密钥类型。
`OPENSSL_KEYTYPE_EC` (int)
  椭圆曲线密钥类型。
`OPENSSL_KEYTYPE_X25519` (int)
  X25519 曲线密钥类型。该常量仅在 PHP 链接 OpenSSL 3.0 或更高版本进行编译时可用。
`OPENSSL_KEYTYPE_ED25519` (int)
  Ed25519 曲线密钥类型。该常量仅在 PHP 链接 OpenSSL 3.0 或更高版本进行编译时可用。
`OPENSSL_KEYTYPE_X448` (int)
  X448 曲线密钥类型。该常量仅在 PHP 链接 OpenSSL 3.0 或更高版本进行编译时可用。
`OPENSSL_KEYTYPE_ED448` (int)
  Ed448 曲线密钥类型。该常量仅在 PHP 链接 OpenSSL 3.0 或更高版本进行编译时可用。

## PKCS7 flag/常量

S/MIME 函数使用通过一个位阈来表示的标志位，该位阈可包含如下一个或多个值：

PKCS7 常量
常量名 | 描述
--- | ---
`PKCS7_TEXT` (int) | 为加密/签名后的消息添加 `text/plain` 内容类型 header。如果解密或者验证时，输出时会除去这些 header。如果解密或验证的消息不是 MIME 类型 `text/plain`，则会发生错误。
`PKCS7_BINARY` (int) | 通常输入消息将被转成以 `CR` 和 `LF` 作行末的 "canonical" 格式(S/MIME规范中的声明)。当该选项出现时，消息将不会被转化。 当处理非 MIME 格式的二进制数据时，这个选项会很有用。
`PKCS7_NOINTERN` (int) | 在验证消息时，在消息中包含的证书(如果有的话)通常会被搜索签名证书。 对于该选项，只有当 openssl_pkcs7_verify() 函数的参数 `untrusted_certificates_filename` 指定了的证书才会被使用。然而提供的证书仍然被当做不受信任的证书使用。
`PKCS7_NOVERIFY` (int) | 不要验证签名消息的签名者证书。
`PKCS7_NOCHAIN` (int) | 不要约束验证签名者证书：不要把签名消息中的证书当做不受信任的证书。
`PKCS7_NOCERTS` (int) | 在签署消息时，签名者的证书通常包括在内，但是有了这个选项后，就不需要包括证书了。这将会缩小被签名消息的大小，但是验证人在本地必须有可用的签名者证书副本(比如由 openssl_pkcs7_verify() 函数中的 `untrusted_certificates_filename` 参数传递) 。
`PKCS7_NOATTR` (int) | 通常当消息被签名了，一些属性的集合将会包含在内，比如签名时间和支持的对称算法。使用该选项用来设置不包含这些属性。
`PKCS7_DETACHED` (int) | 当签名消息时，使用 MIME 类型(`"multipart/signed"`)的明文签名。 如果你为 openssl_pkcs7_sign() 函数没有指定任何 `flags`，这个将会是默认的值。 如果你关闭这个选项，消息将使用不透明的签名来签名, 这将会使消息更能抵抗邮件中继的翻译，但是不支持 S/MIME 的邮件客户端将不能读取该消息。
`PKCS7_NOSIGS` (int) | 不要尝试在消息中验证签名
`PKCS7_NOOLDMIMETYPE` (int) | 自 PHP 8.3.0 起可用。 将 content-type 设置为 `application/pkcs7-mime`，而不是 `application/x-pkcs7-mime` 来加密消息。

## CMS Flag/常量

CMS 函数使用 flag，这些 flag 使用位字段指定，位字段可以包含以下一个或多个值：

CMS CONSTANTS
常量名 | 说明
--- | ---
`OPENSSL_CMS_TEXT` (int) | 将 text/plain 内容类型标头添加到加密/签名消息中。如果解密或验证，将从输出中去除这些标头；如果解密或验证的消息不是 MIME 类型 text/plain，则会发生错误。
`OPENSSL_CMS_BINARY` (int) | 通常，输入消息被转换为有效使用 `CR` 和 `LF` 作为行尾的“canonical”格式：按照 CMS 规范的要求。存在此选项时，不会发生翻译。这在处理可能不是 CMS 格式的二进制数据时很有用。
`OPENSSL_CMS_NOINTERN` (int) | 验证消息时，通常会搜索消息中包含的证书（如果有）以查找签名证书。使用此选项仅使用在 openssl_cms_verify() 的 `untrusted_certificates_filename` 参数中指定的证书。但是，提供的证书仍可用作不受信任的 CA。
`OPENSSL_CMS_NOVERIFY` (int) | 不验证签名消息的签名者证书。
`OPENSSL_CMS_NOCERTS` (int) | When signing a message the signer's certificate is normally included - with this option it is excluded. This will reduce the size of the signed message but the verifier must have a copy of the signers certificate available locally (passed using the `untrusted_certificates_filename` to openssl_cms_verify() for example).
`OPENSSL_CMS_NOATTR` (int) | Normally when a message is signed, a set of attributes are included which include the signing time and the supported symmetric algorithms. With this option they are not included.
`OPENSSL_CMS_DETACHED` (int) | When signing a message, use cleartext signing with the MIME type `"multipart/signed"`. This is the default if you do not specify any `flags` to openssl_cms_sign(). If you turn this option off, the message will be signed using opaque signing, which is more resistant to translation by mail relays but cannot be read by mail agents that do not support S/MIME.
`OPENSSL_CMS_NOSIGS` (int) | 不要尝试验证消息的签名
`OPENSSL_CMS_OLDMIMETYPE` (int) | 自 PHP 8.3.0 起可用。 将 content-type 设置为 `application/x-pkcs7-mime`，而不是 `application/pkcs7-mime` 来加密消息。

## 签名算法

`OPENSSL_ALGO_DSS1` (int)
`OPENSSL_ALGO_SHA1` (int)
  openssl_sign() 和 openssl_verify() 函数使用的默认算法。
`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)
  只有在使用 MD2 支持编译 PHP 时，才可以使用这个常量。当在编译 PHP 时需要验证通过 `-DHAVE_OPENSSL_MD2_H` CFLAGP，当编译 OpenSSL 1.0.0+ 版本时需要启用 `enable-md2` 选项。

## Ciphers

`OPENSSL_DEFAULT_STREAM_CIPHERS` (string)
  默认加密套件列表。
`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)

## 版本常量

`OPENSSL_VERSION_TEXT` (string)
`OPENSSL_VERSION_NUMBER` (int)

## Server Name Indication constants

`OPENSSL_TLSEXT_SERVER_NAME` (int)
  SNI 支持是否可用。

> 注意:

> 这个常量要求 PHP 是由 OpenSSL 0.9.8j 及以上版本构建的。

## 其它常量

`OPENSSL_RAW_DATA` (int)
  如果在 openssl_encrypt() 或 openssl_decrypt() 中设置了 `OPENSSL_RAW_DATA`，将直接返回原始数据。若未指定该选项，则默认返回经过 Base64 编码的数据。
`OPENSSL_DONT_ZERO_PAD_KEY` (int)
  阻止 openssl_encrypt() 对短于默认长度的密钥进行填充。
`OPENSSL_ZERO_PADDING` (int)
  默认情况下，加密操作会使用标准块填充，解密时会自动检查并移除填充。如果在 openssl_encrypt() 或 openssl_decrypt() 的选项中设置了 `OPENSSL_ZERO_PADDING`，则禁用填充机制，此时要求加/解密的数据总长度必须是块大小的整数倍，否则会引发错误。
`OPENSSL_ENCODING_SMIME` (int)
  表明编码是 S/MIME。
`OPENSSL_ENCODING_DER` (int)
  表明编码是 DER。
`OPENSSL_ENCODING_PEM` (int)
  表明编码是 PEM。

# 密钥/证书参数

相当一部分的 openssl 函数需要密钥或者证书参数。可通过以下途径获取这些参数。

- 证书

  1. 从 openssl_x509_read() 返回的 OpenSSLCertificate 实例（在 PHP 8.0.0 之前为类型 `OpenSSL X.509` 的 resource）
  2. 如下格式的字符串 file://path/to/cert.pem；命名文件必须包含一个 PEM 编码的证书
  3. 包含了证书内容的字符串，PEM 编码，应该以 `-----BEGIN CERTIFICATE-----` 开头。

- 证书签名请求 (CSRs)

  1. 从 openssl_csr_new() 返回的 OpenSSLCertificateSigningRequest 实例（在 PHP 8.0.0 之前为类型 `OpenSSL X.509 CSR` 的 resource）
  2. 如下格式的字符串 file://path/to/csr.pem；命名文件必须包含 PEM 编码的 CSR
  3. 包含 CSR 内容的字符串，PEM 编码，应该以 `-----BEGIN CERTIFICATE REQUEST-----` 开头。

- 公钥/私钥 Key

  1. 从 openssl_get_publickey() 或 openssl_get_privatekey() 返回的 OpenSSLAsymmetricKey 实例（在 PHP 8.0.0 之前为类型 `OpenSSL key` 的 resource）
  2. 仅限公钥：OpenSSLCertificate 实例（或在 PHP 8.0.0 之前，`OpenSSL X.509` 类型的 resource）
  3. 如下格式的字符串 file://path/to/file.pem - 命名文件必须包含 PEM 编码的证书/私钥（必须包含二者）
  4. 包含证书/私钥内容的字符串，PEM 编码，应该以 `-----BEGIN PUBLIC KEY-----` 开头。
  5. 对于私钥，应该使用`array($key, $passphrase)` 的语法格式，这里的 $key 代表由file://格式的文件或者文本字符表示的密钥, 而 $passphrase 表示一个包含该私钥的密码的字符串。

# 证书验证

当调用需要验证签名/认证的函数时，`ca_info` 参数是一个包含可信CA文件的文件夹和文件名的数组。如果文件夹指定了，它应该是能够被openssl命令正确使用的哈希目录。

# OpenSSL 函数

# openssl_cipher_iv_length

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

openssl_cipher_iv_length — 获取密码iv长度

### 说明

function openssl_cipher_iv_length(string `$cipher_algo`): int|false

获取密码初始化向量(iv)长度。

### 参数

`cipher_algo`

  密码的方法，更多值查看 openssl_get_cipher_methods() 函数。

### 返回值

成功，返回密码长度, 失败返回 `false` .

### 错误／异常

当密码方法未知时，抛出一个`E_WARNING` 级的错误。

### 示例

示例 #1 openssl_cipher_iv_length() 范例

    <?php
    $method = 'AES-128-CBC';
    $ivlen = openssl_cipher_iv_length($method);

    echo $ivlen;
    ?>

以上示例的输出类似于：

    16

# openssl_cipher_key_length

(PHP 8 >= 8.2.0)

openssl_cipher_key_length — Gets the cipher key length

### 说明

function openssl_cipher_key_length(string `$cipher_algo`): int|false

Gets the cipher key length.

### 参数

`cipher_algo`

  The cipher method, see openssl_get_cipher_methods() for a list of potential values.

### 返回值

Returns the cipher length on success, 或者在失败时返回 `false`.

### 错误／异常

Emits an `E_WARNING` level error when the cipher algorithm is unknown.

### 示例

示例 #1 openssl_cipher_key_length() example

    <?php
    $method = 'AES-128-CBC';

    var_dump(openssl_cipher_key_length($method));
    ?>

以上示例的输出类似于：

    int(16)

# openssl_cms_decrypt

(PHP 8)

openssl_cms_decrypt — Decrypt a CMS message

### 说明

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.

### 参数

`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`.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# openssl_cms_encrypt

(PHP 8)

openssl_cms_encrypt — Encrypt a CMS message

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
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

### 说明

function openssl_cms_read(string `$input_filename`, array `&$certificates`): bool

Performs the exact analog to openssl_pkcs7_read().

警告

本函数还未编写文档，仅有参数列表。

### 参数

`input_filename`

`certificates`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# openssl_cms_sign

(PHP 8)

openssl_cms_sign — Sign a file

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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

### 说明

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.

### 参数

`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`.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# openssl_csr_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_export — 将 CSR 作为字符串导出

### 说明

function openssl_csr_export(OpenSSLCertificateSigningRequest|string `$csr`, string `&$output`, bool `$no_text` = `true`): bool

openssl_csr_export() 获取证书签名请求（`csr`）并通过引用保存其 PEM 格式的字符串（`output`）。

### 参数

`csr`
  See CSR parameters for a list of valid values.
`output`

  在成功时，该字符串将包含 PEM 编码的 CSR。

`no_text`
  可选参数 `notext` 影响输出的冗余度。如果设为 `false`，输出内容将包含附加的人类可读信息。`notext` 的缺省值为 `true`。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `csr` 现在接受 OpenSSLCertificateSigningRequest 实例；之前接受类型 `OpenSSL X.509 CSR` 的 resource。

### 示例

示例 #1 openssl_csr_export() 示例

    <?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;
    ?>

### 参见

- openssl_csr_export_to_file() - 将 CSR 导出到文件
- openssl_csr_new() - 生成一个 CSR
- openssl_csr_sign() - 用另一个证书签署 CSR（或者本身）并且生成一个证书

# openssl_csr_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_export_to_file — 将 CSR 导出到文件

### 说明

function openssl_csr_export_to_file(OpenSSLCertificateSigningRequest|string `$csr`, string `$output_filename`, bool `$no_text` = `true`): bool

openssl_csr_export_to_file() 获取证书签名请求（`csr`）并将之保存在以 `output_filename` 命名的 PEM 格式文件中。

### 参数

`csr`
  See CSR parameters for a list of valid values.
`output_filename`

  输出文件的路径。

`no_text`
  可选参数 `notext` 影响输出的冗余度。如果设为 `false`，输出内容将包含附加的人类可读信息。`notext` 的缺省值为 `true`。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `csr` 现在接受 OpenSSLCertificateSigningRequest 实例；之前接受类型 `OpenSSL X.509 CSR` 的 resource。

### 示例

示例 #1 openssl_csr_export_to_file() 范例

    <?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');
    // Along with the subject, the CSR contains the public key corresponding to the private key
    openssl_csr_export_to_file($csr, 'example-csr.pem');
    ?>

### 参见

- openssl_csr_export() - 将 CSR 作为字符串导出
- openssl_csr_new() - 生成一个 CSR
- openssl_csr_sign() - 用另一个证书签署 CSR（或者本身）并且生成一个证书

# openssl_csr_get_public_key

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_csr_get_public_key — 返回 CSR 的公钥

### 说明

function openssl_csr_get_public_key(OpenSSLCertificateSigningRequest|string `$csr`, bool `$short_names` = `true`): OpenSSLAsymmetricKey|false

openssl_csr_get_public_key() 从 `csr` 中提取公钥供其他功能使用。

### 参数

`csr`
  See CSR parameters for a list of valid values.
`short_names`
  警告

  该参数可以省略。

### 返回值

成功时返回 OpenSSLAsymmetricKey，错误则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 成功时此函数现在返回 OpenSSLAsymmetricKey 实例；之前返回类型 `OpenSSL key` 的 resource。
8.0.0 | `csr` 现在接受 OpenSSLCertificateSigningRequest 实例；之前接受类型 `OpenSSL X.509 CSR` 的 resource。

### 示例

示例 #1 openssl_csr_get_public_key() 示例

    <?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'];
    ?>

### 参见

- openssl_csr_get_subject() - 返回 CSR 的主题
- openssl_csr_new() - 生成一个 CSR
- openssl_pkey_get_details() - 返回包含密钥详情的数组
- openssl_pkey_export_to_file() - 将密钥导出到文件中
- openssl_pkey_export() - 将一个密钥的可输出表示转换为字符串

# openssl_csr_get_subject

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_csr_get_subject — 返回 CSR 的主题

### 说明

function openssl_csr_get_subject(OpenSSLCertificateSigningRequest|string `$csr`, bool `$short_names` = `true`): array|false

openssl_csr_get_subject() 返回 `csr` 中专有名称信息的主题，其中包含了通用名称（CN）、机构名称（O）、国家名（C）等字段。

### 参数

`csr`
  See CSR parameters for a list of valid values.
`short_names`

  `short_names` 控制着数据如何在数组中被索引 - 如果 `short_names` 为 `true` (默认) 将使用简称形式对字段进行索引，否则将使用全称形式 - 比如： CN 就是 commonName 的简称形式。

### 返回值

返回带有主题描述的关联数组， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `csr` 现在接受 OpenSSLCertificateSigningRequest 实例；之前接受类型 `OpenSSL X.509 CSR` 的 resource。

### 示例

示例 #1 openssl_csr_get_subject() 示例

    <?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));
    ?>

以上示例的输出类似于：

    Array
    (
        [C] => CA
        [ST] => Alberta
        [L] => Calgary
        [O] => XYZ Widgets Inc
        [OU] => PHP Documentation Team
        [CN] => Wez Furlong
        [emailAddress] => wez@example.com
    )

### 参见

- openssl_csr_new() - 生成一个 CSR
- openssl_csr_get_public_key() - 返回 CSR 的公钥
- openssl_x509_parse() - 解析 X509 证书并作为一个数组返回信息

# openssl_csr_new

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_new — 生成一个 CSR

### 说明

function openssl_csr_new(
array `$distinguished_names`,
#[\SensitiveParameter] ?OpenSSLAsymmetricKey `&$private_key`,
?array `$options` = `null`,
?array `$extra_attributes` = `null`
): OpenSSLCertificateSigningRequest|bool

openssl_csr_new() 根据 `distinguished_names` 提供的信息生成新的 CSR（证书签名请求）。

> 注意: 必须安装有效的 openssl.cnf 以保证此函数正确运行。参考有关安装的说明以获得更多信息。

### 参数

`distinguished_names`

  在证书中要包含的专有名称或主题字段。`distinguished_names` 是关联数组，其中 key 表示 专有名称的属性名称，value 可以是字符串（对于单个值）或数组（如果需要设置多个值）。

`private_key`

  `private_key` 应设置为由 openssl_pkey_new() 预先生成的私钥（或从其他 openssl_pkey 系列函数获取），或 `null` 变量。如果值为 `null` 变量，则根据提供的 `options` 生成新的私钥并将其分配给提供的变量。密钥的相应公共部分将用于签署 CSR。

`options`

  默认系统 `openssl.conf` 中的信息用于初始化请求；可以通过在 `options` 中设置 `config_section_section` key 来指定配置文件部分。还可以通过将 key `config` 的值设置为要使用的文件路径，来指定备用 OpenSSL 配置文件。如果选项中存在以下 key，它们的行为就像在 `openssl.conf` 中一样，如下表所示。

  配置覆盖
  `options` 键 | 类型 | 等同于 `openssl.conf` | 描述
  --- | --- | --- | ---
  digest_alg | string | default_md | 摘要算法或签名哈希算法，通常是 openssl_get_md_methods() 之一。
  x509_extensions | string | x509_extensions | 选择在创建 x509 证书时应该使用哪些扩展
  req_extensions | string | req_extensions | 创建 CSR 时，选择使用哪个扩展
  private_key_bits | int | default_bits | 指定应该使用多少位来生成私钥
  private_key_type | int | none | 选择在创建 CSR 时应该使用哪些扩展。可选值有 `OPENSSL_KEYTYPE_DSA`、 `OPENSSL_KEYTYPE_DH`、 `OPENSSL_KEYTYPE_RSA` 或 `OPENSSL_KEYTYPE_EC`。 默认值是 `OPENSSL_KEYTYPE_RSA`。
  encrypt_key | bool | encrypt_key | 是否应该对导出的密钥（带有密码短语）进行加密?
  encrypt_key_cipher | int | none | cipher constants 常量之一。
  curve_name | string | none | openssl_get_curve_names() 之一。
  config | string | N/A | 自定义 openssl.conf 文件的路径。

`extra_attributes`

  `extra_attributes` 用于指定 CSR 的附加属性。是关联数组，其中 key 转换为 OID 并应用为 CSR 属性。

### 返回值

成功时返回 CSR，如果 CSR 创建成功但签名失败则返回 `true` 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `distinguished_names` 关联数组现在支持 value 为数组，允许为单个属性指定多个值。
8.4.0 | `extra_attributes` 参数现在可以正确设置 CSR 属性，而不是像以前错误地修改主题的专用名称。
8.0.0 | 成功时，此函数现在返回 OpenSSLCertificateSigningRequest 实例；之前返回类型 `OpenSSL X.509 CSR` 的 resource。
8.0.0 | `private_key` 现在接受 OpenSSLAsymmetricKey 实例；之前接受类型 `OpenSSL key` 的 resource。
7.1.0 | `options` 现在也支持 `curve_name`。

### 示例

示例 #1 创建一个自签名的证书

    <?php
    // for SSL server certificates the commonName is the domain name to be secured
    // for S/MIME email certificates the commonName is the owner of the email address
    // location and identification fields refer to the owner of domain or email subject to be secured
    $dn = array(
        "countryName" => "GB",
        "stateOrProvinceName" => "Somerset",
        "localityName" => "Glastonbury",
        "organizationName" => "The Brain Room Limited",
        "organizationalUnitName" => "PHP Documentation Team",
        "commonName" => "Wez Furlong",
        "emailAddress" => "wez@example.com"
    );

    // Generate a new private (and public) key pair
    $privkey = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));

    // Generate a certificate signing request
    $csr = openssl_csr_new($dn, $privkey, array('digest_alg' => 'sha256'));

    // Generate a self-signed cert, valid for 365 days
    $x509 = openssl_csr_sign($csr, null, $privkey, $days=365, array('digest_alg' => 'sha256'));

    // Save your private key, CSR and self-signed cert for later use
    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);

    // Show any errors that occurred here
    while (($e = openssl_error_string()) !== false) {
        echo $e . "\n";
    }
    ?>

示例 #2 创建一个自签名的 ECC 证书（从 PHP 7.1.0 开始）

    <?php
    $subject = array(
        "commonName" => "docs.php.net",
    );

    // Generate a new private (and public) key pair
    $private_key = openssl_pkey_new(array(
        "private_key_type" => OPENSSL_KEYTYPE_EC,
        "curve_name" => 'prime256v1',
    ));

    // Generate a certificate signing request
    $csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha384'));

    // Generate self-signed EC cert
    $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');
    ?>

### 参见

- openssl_csr_sign() - 用另一个证书签署 CSR（或者本身）并且生成一个证书

# openssl_csr_sign

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_sign — 用另一个证书签署 CSR（或者本身）并且生成一个证书

### 说明

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() 从给定的 CSR 生成 x509 证书。

> 注意: 必须安装有效的 openssl.cnf 以保证此函数正确运行。参考有关安装的说明以获得更多信息。

### 参数

`csr`

  由 openssl_csr_new() 函数生成的 CSR。 也可以是由类似file://path/to/csr格式指定的指向 PEM 编码的 CSR 路径，或者是一个由openssl_csr_export()函数生成的字符串。

`ca_certificate`

  生成的证书将由`ca_certificate`签名。 如果`ca_certificate` 为 `null`, 生成的证书将是自签名证书。

`private_key`

  `private_key` 是 `ca_certificate` 证书对应的私钥。

`days`

  `days` 指定生成的证书在几天内有效的时间长度。

`options`

  可以通过 `options` 确定 CSR 签名。 查看 openssl_csr_new() 方法获取 `options` 的更多相关信息。

`serial`

  可选的已签发证书的序列号。如果未指定，将默认为 0。

`serial_hex`

  可选的十六进制字符串，表示已签发证书的序列号。 如果设置，将优先于 `serial` 参数值。 如果未指定或设置为 `null`，则使用 `serial` 参数值。

### 返回值

成功时返回 OpenSSLCertificate，失败则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 添加了 `serial_hex` 参数。
8.0.0 | 成功时，此函数现在返回 OpenSSLCertificate 实例；之前返回类型 `OpenSSL X.509` 的 resource。
8.0.0 | `csr` 现在接受 OpenSSLCertificateSigningRequest 实例；之前接受类型 `OpenSSL X.509 CSR` 的 resource。
8.0.0 | `ca_certificate` 现在接受 OpenSSLCertificate 实例；之前接受类型 `OpenSSL X.509` 的 resource。
8.0.0 | `private_key` 现在接受 OpenSSLAsymmetricKey 或 OpenSSLCertificate 实例；之前接受类型 `OpenSSL key` 或 `OpenSSL X.509` 的 resource。

### 示例

示例 #1 openssl_csr_sign() 示例——签署 CSR（如何实现自己的 CA）

    <?php
    // Let's assume that this script is set to receive a CSR that has
    // been pasted into a textarea from another page
    $csrdata = $_POST["CSR"];

    // We will sign the request using our own "certificate authority"
    // certificate.  You can use any certificate to sign another, but
    // the process is worthless unless the signing certificate is trusted
    // by the software/users that will deal with the newly signed certificate

    // We need our CA cert and its private key
    $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') );

    // Now display the generated certificate so that the user can
    // copy and paste it into their local configuration (such as a file
    // to hold the certificate for their SSL server)
    openssl_x509_export($usercert, $certout);
    echo $certout;

    // Show any errors that occurred here
    while (($e = openssl_error_string()) !== false) {
        echo $e . "\n";
    }
    ?>

# openssl_decrypt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_decrypt — 解密数据

### 说明

function openssl_decrypt(
string `$data`,
string `$cipher_algo`,
#[\SensitiveParameter] string `$passphrase`,
int `$options` = 0,
string `$iv` = "",
?string `$tag` = `null`,
string `$aad` = ""
): string|false

采用原始或base64编码的字符串，并使用给定的方法和密码短语对其进行解密。

### 参数

`data`

  将被解密的密文。

`cipher_algo`

  加密算法，使用openssl_get_cipher_methods()函数获取可用的加密算法列表。

`passphrase`

  密码短语。若提供的密码短语比期望短，系统会自动用 `NUL` 字符静默填充；若密码短语比期望长，则会静默截断。

  警告

  正如其名称所示，passphrase 没有用于密钥导出函数。唯一的操作是用 `NUL` 字符填充，或者如果长度与预期不同则截断。

`options`

  `options` 可以是以下常量之一： `OPENSSL_RAW_DATA`、 `OPENSSL_ZERO_PADDING` 或 `OPENSSL_DONT_ZERO_PAD_KEY`。

`iv`

  非 `null` 的初始化向量。如果 IV 比预期短，则用 `NUL` 字符填充并发出警告；如果密码短语比预期长，则将其截断并发出警告。

`tag`

  AEAD密码模式中的身份验证标签。 如果是错误的，验证失败，函数返回`false`.

  警告

  函数不检查 `tag` 的长度。调用者有责任确保 tag 的长度与调用 openssl_encrypt() 时检索到的 tag 的长度相匹配。否则，如果给定的 tag 仅匹配正确 tag 的开头，解密可能会成功。

`aad`

  额外的认证数据。

### 返回值

成功时已解密的字符串 或者在失败时返回 `false`。

### 错误／异常

如果通过 `cipher_algo` 参数传递的是未知的加密算法，将会抛出 `E_WARNING` 等级的错误。

如果通过`iv`参数传递的是一个空值，将会抛出一个 `E_WARNING` 等级的错误。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | `tag` 现在可为 null。
7.1.0 | 添加了 `tag` 和 `aad` 参数。

### 参见

- openssl_encrypt() - 加密数据

# openssl_dh_compute_key

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_dh_compute_key — 计算远程 DH 公钥和本地 DH 密钥的共享密钥

### 说明

function openssl_dh_compute_key(string `$public_key`, #[\SensitiveParameter] OpenSSLAsymmetricKey `$private_key`): string|false

openssl_dh_compute_key() 返回的共享密钥通常用作与远端秘密通信的加密密钥。这称为 Diffie-Hellman 密钥交换。

警告

必须确保远程与本地密钥对使用相同的 DH（Diffie-Hellman）参数，否则双方生成的共享密钥将无法匹配。

> 注意: ECDH 仅从 PHP 8.1.0 和 OpenSSL 3.0.0 开始受支持。

### 参数

`public_key`

  远端的 DH 公钥。

`private_key`

  本地 DH 私钥，对应于要与远端共享的公钥。

### 返回值

成功时返回共享密钥， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `private_key` 现在接受 OpenSSLAsymmetricKey；之前接受类型 `OpenSSL key` 的 resource。

### 示例

示例 #1 计算共享秘密

首先在本地生成公私 DH 密钥对，让远端也这样做。需要使用 `openssl` 命令行实用程序。

    # 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

接下来，将公钥发送给远端。使用 `openssl pkey` 命令查看从远端发送的公钥。

    openssl pkey -pubin -in remotepublickey.pem -text -noout

以上示例的输出类似于：

    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...]

使用此公钥作为 openssl_dh_compute_key() 的参数以计算共享密钥。

    <?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";
    ?>

示例 #2 在 php 中生成 DH 公/私钥对

首先，生成 DH 质数

    openssl dhparam -out dhparam.pem 2048
    openssl dh -in dhparam.pem -noout  -text

以上示例的输出类似于：

    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)

质数和生成器值作为 p 和 g 传递给 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";
    ?>

### 参见

- openssl_pkey_new() - 生成新的私钥
- openssl_pkey_get_details() - 返回包含密钥详情的数组
- openssl_pkey_get_private() - 获取私钥
- openssl_pkey_get_public() - 从证书中解析公钥，以供使用

# openssl_digest

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_digest — 计算摘要

### 说明

function openssl_digest(string `$data`, string `$digest_algo`, bool `$binary` = `false`): string|false

使用给定的方法计算给定数据的摘要哈希值，并返回一个原始的或16进制编码的字符串。

### 参数

`data`

  给定的数据。

`digest_algo`

  要使用的摘要方法，比如 "sha256", 查看 openssl_get_md_methods() 函数获取更多可用的摘要方法。

`binary`

  为 `true` 时将会返回原始输出数据，否则返回值将会是16进制。

### 返回值

成功，返回摘要哈希值， 或者在失败时返回 `false`.

### 错误／异常

如果通过 `digest_algo` 参数传递的是未知的摘要算法，将会抛出 `E_WARNING` 级的错误。

### 参见

- openssl_get_md_methods() - 获取可用的摘要算法

# openssl_encrypt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_encrypt — 加密数据

### 说明

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

以指定的方式和密码短语加密数据，返回原始或 base64 编码后的字符串。

### 参数

`data`

  待加密的明文信息数据。

`cipher_algo`

  密码学方式。openssl_get_cipher_methods() 可获取有效密码方式列表。

`passphrase`

  密码短语。若 passphrase 比预期长度短，将静默用 `NUL` 填充； 若比预期长度更长，将静默截断。

  警告

  正如其名称所示，passphrase 没有用于密钥导出函数。唯一的操作是用 `NUL` 字符填充，或者如果长度与预期不同则截断。

`options`

  `options` 是以下标记的按位或： `OPENSSL_RAW_DATA` 和 `OPENSSL_ZERO_PADDING` 或 `OPENSSL_DONT_ZERO_PAD_KEY`。

`iv`

  非 `null` 的初始化向量。如果 IV 比预期短，则用 `NUL` 字符填充并发出警告；如果密码短语比预期长，则将其截断并发出警告。

`tag`

  使用 AEAD 密码模式（GCM 或 CCM）时传引用的验证标签。

`aad`

  附加的验证数据。

`tag_length`

  验证 `tag` 的长度。GCM 模式时，它的范围是 4 到 16。

### 返回值

成功时返回加密后的字符串， 或者在失败时返回 `false`。

### 错误／异常

`cipher_algo` 传入未知算法时，产生 `E_WARNING` 级别的错误。

`iv` 传入空字符串时产生 `E_WARNING` 级别的错误。

### 更新日志

版本 | 说明
--- | ---
7.1.0 | 增加了 `tag`、`aad`、`tag_length` 参数

### 示例

示例 #1 PHP 7.1 之前的 GCM 模式的 AES 认证加密示例

    <?php
    //$key should have been previously generated in a cryptographically safe way, like openssl_random_pseudo_bytes
    $plaintext = "message to be encrypted";
    $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);
        //store $cipher, $iv, and $tag for decryption later
        $original_plaintext = openssl_decrypt($ciphertext, $cipher, $key, $options=0, $iv, $tag);
        echo $original_plaintext."\n";
    }
    ?>

示例 #2 PHP 5.6+ 的 AES 认证加密例子

    <?php
    //$key previously generated safely, ie: openssl_random_pseudo_bytes
    $plaintext = "message to be encrypted";
    $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 );

    //decrypt later....
    $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))// timing attack safe comparison
    {
        echo $original_plaintext."\n";
    }
    ?>

### 参见

- openssl_decrypt() - 解密数据

# openssl_error_string

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_error_string — 返回 openSSL 错误消息

### 说明

function openssl_error_string(): string|false

openssl_error_string() 从openSSL库返回最后一个错误。错误消息已被队列化，因此这个函数可以多次调用用来收集所有的信息。最后一个错误将是最近的一个。

### 参数

此函数没有参数。

### 返回值

成功，返回错误信息字符串，如果没有任何错误信息则返回 `false`。

### 示例

示例 #1 openssl_error_string() example

    <?php
    // lets assume you just called an openssl function that failed
    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 — 释放密钥资源

警告

本函数已自 PHP 8.0.0 起被废弃。强烈建议不要依赖本函数。

### 说明

#[\Deprecated]
function openssl_free_key(OpenSSLAsymmetricKey `$key`): void

openssl_free_key() 从内存中释放和指定的 `key` 相关联的密钥。

### 参数

`key`

### 返回值

没有返回值。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 此函数现已弃用，因为不再有效。
8.0.0 | `key` 现在接受 OpenSSLAsymmetricKey；之前接受类型 `OpenSSL key` 的 resource。

# openssl_get_cert_locations

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_get_cert_locations — 检索可用的证书位置

### 说明

function openssl_get_cert_locations(): array

openssl_get_cert_locations() 返回一个数组，其中包含要搜索SSL证书的可用证书位置的信息。

### 参数

此函数没有参数。

### 返回值

返回一个带有可用证书位置信息的数组。

### 示例

示例 #1 openssl_get_cert_locations() 范例

    <?php
    var_dump(openssl_get_cert_locations());
    ?>

以上示例会输出：

    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 — 获取可用的加密算法

### 说明

function openssl_get_cipher_methods(bool `$aliases` = `false`): array

获取可用的加密算法的列表。

### 参数

`aliases`

  如果密码别名应该包含在返回的array中，则设置为 `true`.

### 返回值

包含可用加密算法的array。 请注意：在 OpenSSL 1.1.1 版本之前，返回加密算法的拼法大小写都有； 从 OpenSSL 1.1.1 开始，统一只返回小写的形式。

### 示例

示例 #1 openssl_get_cipher_methods() example

展示了哪些加密算法能被找到，哪些别名可用。

    <?php
    $ciphers             = openssl_get_cipher_methods();
    $ciphers_and_aliases = openssl_get_cipher_methods(true);
    $cipher_aliases      = array_diff($ciphers_and_aliases, $ciphers);

    //ECB mode should be avoided
    $ciphers = array_filter( $ciphers, function($n) { return stripos($n,"ecb")===FALSE; } );

    //At least as early as Aug 2016, Openssl declared the following weak: RC2, RC4, DES, 3DES, MD5 based
    $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);
    ?>

以上示例的输出类似于：

    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
    )

### 参见

- openssl_get_md_methods() - 获取可用的摘要算法

# openssl_get_curve_names

(PHP 7 >= 7.1.0, PHP 8)

openssl_get_curve_names — 获得ECC的可用曲线名称列表

### 说明

function openssl_get_curve_names(): array|false

获取用于公钥/私钥操作的椭圆曲线密码（ECC）中可用曲线名称的列表。两个最广泛的标准化/支持的曲线是 prime256v1（NIST P-256）和 secp384r1（NIST P-384）。

AES、RSA、DSA 和 ECC 密钥长度近似等值
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 推荐使用的 ECC 曲线最少为 256 位。

### 参数

此函数没有参数。

### 返回值

有效曲线名称的 array， 或者在失败时返回 `false`。

### 示例

示例 #1 openssl_get_curve_names() 示例

    <?php
    $curve_names = openssl_get_curve_names();
    print_r($curve_names);
    ?>

以上示例的输出类似于：

    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 — 获取可用的摘要算法

### 说明

function openssl_get_md_methods(bool `$aliases` = `false`): array

获取可用的摘要算法列表

### 参数

`aliases`

  设置为 `true` 时，返回的array中将会包含摘要的别名.

### 返回值

含有可用摘要算法的数组

### 示例

示例 #1 openssl_get_md_methods() 范例：

显示了可用的摘要，以及哪些别名可能是可用的。

    <?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);

    ?>

以上示例的输出类似于：

    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
    )

### 参见

- openssl_digest() - 计算摘要
- openssl_get_cipher_methods() - 获取可用的加密算法

# openssl_get_privatekey

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_get_privatekey — 别名 openssl_pkey_get_private()

### 说明

此函数是该函数的别名： openssl_pkey_get_private().

# openssl_get_publickey

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_get_publickey — 别名 openssl_pkey_get_public()

### 说明

此函数是该函数的别名： openssl_pkey_get_public().

# openssl_open

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_open — 打开密封的数据

### 说明

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() 使用通过 `private_key` 从 `encrypted_key` 解密得到的信封密钥来打开/解密 `data`。解密过程采用 `cipher_algo` 和 `iv`。仅当加密方法需要时，才需提供 iv。该函数将解密后的数据填充至 `output`。信封密钥通常在使用与私钥对应的公钥密封数据时生成。更多信息请参阅 openssl_seal()。

### 参数

`data`

  密封数据。

`output`

  如果调用成功，则在这个参数中返回打开的数据。

`encrypted_key`

  可使用 `private_key` 解密的对称加密密钥。

`private_key`

  用于解密 `encrypted_key` 的私钥。

`cipher_algo`

  用于解密 `data` 的密码算法。

  警告

  PHP 8.0 之前版本的默认值为（`'RC4'`），该算法存在安全隐患。强烈建议明确指定安全密码方法。

`iv`

  用于解密 `data` 的初始化向量。当密码算法需要 IV 时，必须提供该参数。可通过调用 openssl_cipher_iv_length() 并传入 `cipher_algo` 来确认是否需要 IV。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `private_key` 现在接受 OpenSSLAsymmetricKey 或 OpenSSLCertificate 实例；之前接受类型 `OpenSSL key` 或 `OpenSSL X.509 CSR` 的 resource。
8.0.0 | `cipher_algo` 不再是可选参数。

### 示例

示例 #1 openssl_open() 示例

    <?php

    // $sealed、$env_key 和 $iv 分别假设包含密封数据、信封密钥和初始化向量，这些参数均由数据密封方提供。

    // 从 private_key.pem 文件中获取私钥
    $pkey = openssl_get_privatekey("file://private_key.pem");

    // 解密数据并存储到 $open
    if (openssl_open($sealed, $open, $env_key, $pkey, 'AES256', $iv)) {
        echo "Here is the opened data: ", $open;
    } else {
        echo "Failed to open data";
    }

    ?>

### 参见

- openssl_seal() - 密封 (加密) 数据

# openssl_password_hash

(PHP 8 >= 8.4.0)

openssl_password_hash — Create a password hash using OpenSSL's Argon2 implementation

### 说明

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`).

### 参数

`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

### 返回值

Returns the password hash as a string.

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | Function added.

### 示例

示例 #1 openssl_password_hash() example

    <?php
    $hash = openssl_password_hash('argon2id', 'my-secret-password');
    echo $hash;
    ?>

以上示例的输出类似于：

    $argon2id$v=19$m=65536,t=4,p=1$c29tZXNhbHR2YWx1ZQ$hashvalue...

示例 #2 openssl_password_hash() with custom options

    <?php
    $hash = openssl_password_hash('argon2id', 'my-secret-password', [
        'memory_cost' => 65536,
        'time_cost'   => 4,
        'threads'     => 1,
    ]);
    ?>

### 参见

- openssl_password_verify() - Verify a password against a hash using OpenSSL's Argon2 implementation
- password_hash() - 创建密码的散列（hash）

# openssl_password_verify

(PHP 8 >= 8.4.0)

openssl_password_verify — Verify a password against a hash using OpenSSL's Argon2 implementation

### 说明

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`).

### 参数

`algo`

  The password hashing algorithm. Supported values: `"argon2id"` and `"argon2i"`.

`password`

  The user's password.

`hash`

  A hash created by openssl_password_hash().

### 返回值

Returns `true` if the password and hash match, or `false` otherwise.

### 错误／异常

Throws a ValueError if `algo` is not one of the supported values (`"argon2i"` or `"argon2id"`).

### 更新日志

版本 | 说明
--- | ---
8.4.0 | Function added.

### 示例

示例 #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.';
    }
    ?>

### 参见

- openssl_password_hash() - Create a password hash using OpenSSL's Argon2 implementation
- password_verify() - 验证密码是否和散列值匹配

# openssl_pbkdf2

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

openssl_pbkdf2 — 生成 PKCS5 v2 PBKDF2 字符串

### 说明

function openssl_pbkdf2(
#[\SensitiveParameter] string `$password`,
string `$salt`,
int `$key_length`,
int `$iterations`,
string `$digest_algo` = "sha1"
): string|false

openssl_pbkdf2() 计算 PBKDF2 (Password-Based Key Derivation Function 2)，在 PKCS5 v2 中定义的密钥的推导函数。

### 参数

`password`

  派生密钥所生成的密码。

`salt`

  PBKDF2 推荐不少于 128 位（16 字节）的密码盐值。

`key_length`

  希望输出密钥的长度。

`iterations`

  需要的迭代次数。» NIST 建议至少 10,000 次。自 2023 年起，OWASP 针对 PBKDF2-HMAC-SHA256 推荐 600,000 次迭代，针对 PBKDF2-HMAC-SHA512 推荐 210,000 次。

`digest_algo`

  在 openssl_get_md_methods() 中可选的散列或摘要算法。默认是 SHA-1。推荐设置为 SHA-256 或 SHA-512。

### 返回值

成功，返回原始二进制字符串 或者在失败时返回 `false`。

### 示例

示例 #1 openssl_pbkdf2() 示例

    <?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";
    ?>

### 参见

- hash_pbkdf2() - 生成所提供密码的 PBKDF2 密钥导出
- openssl_get_md_methods() - 获取可用的摘要算法

# openssl_pkcs12_export

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_export — 将 PKCS#12 兼容证书存储文件导出到变量

### 说明

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() 以 PKCS#12 文件格式将 `certificate` 导入到名为 `output` 的字符串变量中。

### 参数

`certificate`
  参见密钥／证书参数以获取有效值列表。
`output`

  成功，该字符串将为 PKCS#12 格式。

`private_key`

  PKCS#12 文件的私钥部分file， 参见 公/私钥参数 获取更多可用列表。

`passphrase`

  用来解锁 PKCS#12 文件的解密密码。

`options`

  可选数组，其他主键将被忽略。

  Key | 说明
  --- | ---
  `"extracerts"` | PKCS#12 文件中包含的额外证书或单个证书的数组。
  `"friendly_name"` | 被证书和密钥使用的字符串

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `certificate` 现在接受 OpenSSLCertificate 实例；之前接受类型 `OpenSSL X.509 CSR` 的 resource。
8.0.0 | `private_key` 现在接受 OpenSSLAsymmetricKey 或 OpenSSLCertificate 实例；之前接受类型 `OpenSSL key` 或 `OpenSSL X.509` 的 resource。

# openssl_pkcs12_export_to_file

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_export_to_file — 输出一个 PKCS#12 兼容的证书存储文件

### 说明

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() 以 PKCS#12 文件格式将 `certificate` 保存至 `output_filename` 文件中。

### 参数

`certificate`
  参见密钥／证书参数以获取有效值列表。
`output_filename`

  输出文件的路径。

`private_key`

  PKCS#12 文件的私钥部分。 参见 公/私钥参数 获取可用值的列表。

`passphrase`

  用于解锁 PKCS#12 文件的加密密码。

`options`

  可选数组，其他主键将被忽略。

  Key | 说明
  --- | ---
  `"extracerts"` | PKCS#12 文件中包含的额外证书或单个证书的数组。
  `"friendly_name"` | 被证书和密钥使用的字符串

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `certificate` 现在接受 OpenSSLCertificate 实例；之前接受类型 `OpenSSL X.509 CSR` 的 resource。
8.0.0 | `private_key` 现在接受 OpenSSLAsymmetricKey 或 OpenSSLCertificate 实例；之前接受类型 `OpenSSL key` 或 `OpenSSL X.509` 的 resource。

# openssl_pkcs12_read

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_read — 将 PKCS#12 证书存储区解析到数组中

### 说明

function openssl_pkcs12_read(string `$pkcs12`, array `&$certificates`, #[\SensitiveParameter] string `$passphrase`): bool

openssl_pkcs12_read() 将 `pkcs12` 提供的 PKCS#12 证书存储区解析到以 `certificates` 命名的变量中。

### 参数

`pkcs12`

  证书存储内容，而不是它的文件名。

`certificates`

  成功，将保存证书存储数据

`passphrase`

  用来解锁 PKCS#12 文件的解密密码

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 openssl_pkcs12_read() 示例

    <?php
    if (!$cert_store = file_get_contents("/certs/file.p12")) {
        echo "Error: Unable to read the cert file\n";
        exit;
    }

    if (openssl_pkcs12_read($cert_store, $cert_info, "my_secret_pass")) {
        echo "Certificate Information\n";
        print_r($cert_info);
    } else {
        echo "Error: Unable to read the cert store.\n";
        exit;
    }
    ?>

# openssl_pkcs7_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_decrypt — 解密一个 S/MIME 加密的消息

### 说明

function openssl_pkcs7_decrypt(
string `$input_filename`,
string `$output_filename`,
#[\SensitiveParameter] OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string|null `$private_key` = `null`
): bool

使用由 `certificate` 和 `private_key` 指定的证书和与之关联的私钥解密 `input_filename` 文件中包含的 S/MIME 加密消息。

### 参数

`input_filename`

`output_filename`

  解密的消息将被存入的文件中，以 `output_filename` 命名。

`certificate`

`private_key`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `private_key` 现在接受 OpenSSLAsymmetricKey 或 OpenSSLCertificate 实例；之前接受类型 `OpenSSL key` 或 `OpenSSL X.509 CSR` 的 resource。

### 示例

示例 #1 openssl_pkcs7_decrypt() 示例

    <?php
    // $cert and $key are assumed to contain your personal certificate and private
    // key pair, and that you are the recipient of an S/MIME message
    $infilename = "encrypted.msg";  // this file holds your encrypted message
    $outfilename = "decrypted.msg"; // make sure you can write to this file

    if (openssl_pkcs7_decrypt($infilename, $outfilename, $cert, $key)) {
        echo "decrypted!";
    } else {
        echo "failed to decrypt!";
    }
    ?>

# openssl_pkcs7_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_encrypt — 加密一个 S/MIME 消息

### 说明

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

openssl_pkcs7_encrypt() 获取名为 `input_filename` 的文件内容并使用 RC2 40 位的密码将之加密，以至于他们只能被预期的名为 `certificate` 的接收者阅读。

### 参数

`input_filename`

`output_filename`

`certificate`

  一个单独的X.509证书，或者一个X.509证书的数组。

`headers`

  `headers` 是包含头信息的数组，在被加密后将对数据进行预处理。

  `headers` 可以是以头名为键值的关联数组，也可以是一个索引数组，其中每个元素都包含一个单独的标题行

`flags`

  `flags`用来指定影响编码过程的选项 - 参见 PKCS7 常量.

`cipcipher_algoherid`

  密码常量之一。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 默认密码算法（`cipher_algo`）现在是 AES-128-CBC（`OPENSSL_CIPHER_AES_128_CBC`）。以前，使用 PKCS7/CMS (`OPENSSL_CIPHER_RC2_40`)。
8.0.0 | `certificate` 现在接受 OpenSSLCertificate 实例；之前接受类型 `OpenSSL X.509 CSR` 的 resource。

### 示例

示例 #1 openssl_pkcs7_encrypt() 示例

    <?php
    // the message you want to encrypt and send to your secret agent
    // in the field, known as nighthawk.  You have his certificate
    // in the file nighthawk.pem
    $data = <<<EOD
    Nighthawk,

    Top secret, for your eyes only!

    The enemy is closing in! Meet me at the cafe at 8.30am
    to collect your forged passport!

    HQ
    EOD;

    // load key
    $key = file_get_contents("nighthawk.pem");

    // save message to file
    $fp = fopen("msg.txt", "w");
    fwrite($fp, $data);
    fclose($fp);

    // encrypt it
    if (openssl_pkcs7_encrypt("msg.txt", "enc.txt", $key,
        array("To" => "nighthawk@example.com", // keyed syntax
              "From: HQ <hq@example.com>", // indexed syntax
              "Subject" => "Eyes only"))) {
        // message encrypted - send it!
        exec(ini_get("sendmail_path") . " < enc.txt");
    }
    ?>

# openssl_pkcs7_read

(PHP 7 >= 7.2.0, PHP 8)

openssl_pkcs7_read — 将 PKCS7 文件导出为 PEM 格式证书的数组

### 说明

function openssl_pkcs7_read(string `$data`, array `&$certificates`): bool

警告

本函数还未编写文档，仅有参数列表。

### 参数

`data`

  想要解析的字符串数据（p7b 格式）。

`certificates`

  PEM 格式证书的数组，来源于输入的 p7b 数据。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 根据 P7B 文件获取 PEM 数组

    <?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);
    ?>

### 参见

- openssl_csr_sign() - 用另一个证书签署 CSR（或者本身）并且生成一个证书

# openssl_pkcs7_sign

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_sign — 对一个 S/MIME 消息进行签名

### 说明

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

openssl_pkcs7_sign() 获取名为 `input_filename` 的文件内容，并使用由 `certificate` 和 `private_key` 指定的证书和与之匹配的私钥对其进行加密

### 参数

`input_filename`

  你打算用来进行数字签名的输入文件。

`output_filename`

  将写入数字签名的文件。

`certificate`

  用来对 `input_filename` 进行数字签名的 X.509 证书，参见 密钥/证书参数获取可用列表。

`private_key`

  `private_key` 是对应 `certificate` 证书的私钥。 参见 公/私钥参数获取可用列表。

`headers`

  `headers`是一个包含头信息的数组，在它被签名后，它将被预先对数据进行预处理 (参见 openssl_pkcs7_encrypt() 获取关于该参数格式的更多信息)。

`flags`

  `flags` 可以用来改变输出 - 参见 PKCS7常量。

`untrusted_certificates_filename`

  `untrusted_certificates_filename` 指定一个文件的名称，其中包含一组含有签名的额外的证书，这些证书可以用来帮助接收者验证您使用的证书。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `certificate` 现在接受 OpenSSLCertificate 实例；之前接受类型 `OpenSSL X.509 CSR` 的 resource。
8.0.0 | `private_key` 现在接受 OpenSSLAsymmetricKey 或 OpenSSLCertificate 实例；之前接受类型 `OpenSSL key` 或 `OpenSSL X.509 CSR` 的 resource。

### 示例

示例 #1 openssl_pkcs7_sign() 示例

    <?php
    // the message you want to sign so that recipient can be sure it was you that
    // sent it
    $data = <<<EOD

    You have my authorization to spend $10,000 on dinner expenses.

    The CEO
    EOD;
    // save message to file
    $fp = fopen("msg.txt", "w");
    fwrite($fp, $data);
    fclose($fp);
    // encrypt it
    if (openssl_pkcs7_sign("msg.txt", "signed.txt", "file://mycert.pem",
        array("file://mycert.pem", "mypassphrase"),
        array("To" => "joes@example.com", // keyed syntax
              "From: HQ <ceo@example.com>", // indexed syntax
              "Subject" => "Eyes only")
        )) {
        // message signed - send it!
        exec(ini_get("sendmail_path") . " < signed.txt");
    }
    ?>

# openssl_pkcs7_verify

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_verify — 校验一个已签名的 S/MIME 消息的签名

### 说明

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() 读取给定文件中的 S/MIME 消息并且检查数字签名。

### 参数

`input_filename`

  消息的路径。

`flags`

  `flags` 可以用来影响如何校验签名 - 参见 PKCS7 常量 获取更多信息。

`signers_certificates_filename`

  如果已指定 `signers_certificates_filename` 输出文件，它应该是一个用以保存文件的字符串名称，签名消息的个人证书将以 PEM 的格式保存起来。

`ca_info`

  如果 `ca_info` 被指定了，它应该保存关于受信任的CA证书的信息供在验证过程中使用 - 参见 证书校验 获取关于该参数的更多信息。

`untrusted_certificates_filename`

  如果 `untrusted_certificates_filename` 被指定了，该文件包含了一堆会被作为不受信任的ca使用的证书。

`content`

  你可以使用 `content` 来指定带有已被验证数据的文件名，该文件内容已去掉了签名信息。

`output_filename`

### 返回值

如果签名已被认证，返回 `true`, 如果不正确 (消息已被篡改或者签名证书不可用) 则返回 `false`, 或者 - 错误时返回1.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `signers_certificates_filename`、`untrusted_certificates_filename`、`content` 和 `output_filename` 现在可为 null。
7.2.0 | 新增 `output_filename` 参数。

### 注释

> 注意: 正如 RFC 2045 中指定的，`input_filename` 参数最多不可超过 76 个字符串。

# 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

### 说明

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.

### 参数

`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.

  警告

  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.

### 返回值

The derived secret on success 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.5.0 | The parameter `key_length` is now deprecated.

### 示例

示例 #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 — 将一个密钥的可输出表示转换为字符串

### 说明

function openssl_pkey_export(
#[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$key`,
string `&$output`,
#[\SensitiveParameter] ?string `$passphrase` = `null`,
?array `$options` = `null`
): bool

openssl_pkey_export() 将 `key` 当作 PEM 编码字符串导出并且将之保存到`output` (通过引用传递的)中。

> 注意: 必须安装有效的 openssl.cnf 以保证此函数正确运行。参考有关安装的说明以获得更多信息。

### 参数

`key`

`output`

`passphrase`

  密钥可以通过 `passphrase` 来保护。

`options`

  `options` 可以用来调整导出流程，通过指定或者覆盖openssl配置文件选项。参见 openssl_csr_new() 获取更多关于 `options` 的信息。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `key` 现在接受 OpenSSLAsymmetricKey 或 OpenSSLCertificate 实例；之前接受类型 `OpenSSL key` 或 `OpenSSL X.509` 的 resource。

# openssl_pkey_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_export_to_file — 将密钥导出到文件中

### 说明

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() 将 ascii 格式（PEM 编码）的 `key` 保存到名为 `output_filename` 文件中。

> 注意: 必须安装有效的 openssl.cnf 以保证此函数正确运行。参考有关安装的说明以获得更多信息。

### 参数

`key`

`output_filename`

  输出文件的路径。

`passphrase`

  密钥可以通过值为`passphrase`的密码来保护。

`options`

  `options` 可以用来调整导出流程，通过指定或者覆盖openssl配置文件选项。参见 openssl_csr_new() 获取更多关于 `options` 的信息。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `key` 现在接受 OpenSSLAsymmetricKey 或 OpenSSLCertificate 实例；之前接受类型 `OpenSSL key` 或 `OpenSSL X.509` 的 resource。

# openssl_pkey_free

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_free — 释放一个私钥

警告

本函数已自 PHP 8.0.0 起被废弃。强烈建议不要依赖本函数。

### 说明

#[\Deprecated]
function openssl_pkey_free(OpenSSLAsymmetricKey `$key`): void

> 注意: 此函数无效。在 PHP 8.0.0 之前，用于关闭资源。

该函数释放由 openssl_pkey_new() 创建的私钥。

### 参数

`key`

  持有该密钥的资源。

### 返回值

没有返回值。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 此函数现已弃用，因为不再有效。
8.0.0 | `key` 现在接受 OpenSSLAsymmetricKey；之前接受类型 `OpenSSL key` 的 resource。

# openssl_pkey_get_details

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_pkey_get_details — 返回包含密钥详情的数组

### 说明

function openssl_pkey_get_details(OpenSSLAsymmetricKey `$key`): array|false

该函数返回密钥详情（位长度，密钥，类型）。

### 参数

`key`

  持有密钥的资源。

### 返回值

成功时返回包含密钥详情的数组，失败时返回 `false`。 返回的数组中包含了如下索引： `bits` (位数)、 `key`（表示公钥的字符串）和 `type`（如下密钥类型之一： `OPENSSL_KEYTYPE_RSA`、`OPENSSL_KEYTYPE_DSA`、`OPENSSL_KEYTYPE_DH`、`OPENSSL_KEYTYPE_EC`、`OPENSSL_KEYTYPE_X25519`、`OPENSSL_KEYTYPE_ED25519`、`OPENSSL_KEYTYPE_X448`、`OPENSSL_KEYTYPE_ED448` 或者是 `-1`，代表未知类型）。

根据使用的密钥类型，可能会返回不同的额外信息。请注意，有些元素可能并不总是可用的。

- `OPENSSL_KEYTYPE_RSA`，一个额外的键名为 `"rsa"` 的数组，包含了以下密钥数据：

  Key | 说明
  --- | ---
  `"n"` | modulus
  `"e"` | public exponent
  `"d"` | private exponent
  `"p"` | prime 1
  `"q"` | prime 2
  `"dmp1"` | exponent1, d mod (p-1)
  `"dmq1"` | exponent2, d mod (q-1)
  `"iqmp"` | coefficient, (inverse of q) mod p

- `OPENSSL_KEYTYPE_DSA`, 一个额外的键为 `"dsa"` 的数组， 包含如下的密钥数据。

  Key | 说明
  --- | ---
  `"p"` | prime number (public)
  `"q"` | 160-bit subprime, q | p-1 (public)
  `"g"` | generator of subgroup (public)
  `"priv_key"` | private key x
  `"pub_key"` | public key y = g^x

- `OPENSSL_KEYTYPE_DH`, 一个额外的键为 `"dh"` 的数组，包含如下的密钥数据。

  Key | 说明
  --- | ---
  `"p"` | prime number (shared)
  `"g"` | generator of Z_p (shared)
  `"priv_key"` | private DH value x
  `"pub_key"` | public DH value g^x

- `OPENSSL_KEYTYPE_X25519`、`OPENSSL_KEYTYPE_ED25519`、`OPENSSL_KEYTYPE_X448`, 或 `OPENSSL_KEYTYPE_ED448`，分别返回名为 `"x25519"`、`"ed25519"`、`"x448"` 或 `"ed448"` 的附加数组 key，其中包含密钥数据。

  Key | 说明
  --- | ---
  `"priv_key"` | 私钥
  `"pub_key"` | 公钥

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 新增对基于 Curve25519 和 Curve448 的密钥支持。特别是引入了 `x25519`、`ed25519`、`x448` 和 `ed448` 字段。
8.0.0 | 现在参数 `key` 接受 OpenSSLAsymmetricKey； 在此之前，接受 `OpenSSL key` 类型的 resource。

# openssl_pkey_get_private

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_get_private — 获取私钥

### 说明

function openssl_pkey_get_private(#[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`, #[\SensitiveParameter] ?string `$passphrase` = `null`): OpenSSLAsymmetricKey|false

openssl_pkey_get_private() 解析 `private_key` 供其他函数使用。

### 参数

`private_key`

  `private_key` 可以是如下密钥之一：

  1. 如下格式的字符串 file://path/to/file.pem。该文件必须包含 PEM 编码的证书或者私钥 (可能都包含了).
  2. 一个 PEM 格式的私钥。
`passphrase`

  如果指定的密钥已被加密了(受密码保护)，可选参数 `passphrase` 是必须要的。

### 返回值

成功时现在返回 OpenSSLAsymmetricKey 实例，失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 成功时，此函数现在返回 OpenSSLAsymmetricKey 实例；之前返回类型 `OpenSSL key` 的 resource。
8.0.0 | `private_key` 现在接受 OpenSSLAsymmetricKey 或 OpenSSLCertificate 实例；之前接受类型 `OpenSSL key` 或 `OpenSSL X.509` 的 resource。
8.0.0 | `passphrase` 现在可为 null。

# openssl_pkey_get_public

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_get_public — 从证书中解析公钥，以供使用

### 说明

function openssl_pkey_get_public(OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`): OpenSSLAsymmetricKey|false

openssl_pkey_get_public() 从 `public_key` 中解析公钥，供其他函数使用。

### 参数

`public_key`

  `public_key` 可以是以下之一：

  1. OpenSSLAsymmetricKey 实例
  2. file://path/to/file.pem 格式的字符串。文件名必须包含一个 PEM 编码的证书或者密钥(也许二者都有).
  3. 一个 PEM 格式的公钥。

### 返回值

成功时返回 OpenSSLAsymmetricKey 实例，错误时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 成功时，此函数现在返回 OpenSSLAsymmetricKey 实例；之前返回类型 `OpenSSL key` 的 resource。
8.0.0 | `public_key` 现在接受 OpenSSLAsymmetricKey 或 OpenSSLCertificate 实例；之前接受类型 `OpenSSL key` 或 `OpenSSL X.509` 的 resource。

# openssl_pkey_new

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_new — 生成新的私钥

### 说明

function openssl_pkey_new(?array `$options` = `null`): OpenSSLAsymmetricKey|false

openssl_pkey_new() 生成一个新的私钥和公钥对。如何获取该密钥的公共组件参见以下示例。

> 注意: 必须安装有效的 openssl.cnf 以保证此函数正确运行。参考有关安装的说明以获得更多信息。

### 参数

`options`

  可以使用 `options` 参数微调密钥生成（例如指定位的数量或参数）。这些选项可以是用于密钥生成的特定于算法的参数，也可以是 CSR 生成中使用的通用选项（如果未指定）。有关在 CSR 中使用 `options` 的更多信息，参阅 openssl_csr_new()。在这些选项中，只有 `private_key_bits`、`private_key_type`、`curve_name` 和 `config` 用于密钥生成。如果关联数组包含某个特定 key，则使用特定算法选项。

  - `"rsa"` key 用于设置 RSA 参数。

    选项 | 类型 | 格式 | 是否必需 | 说明
    --- | --- | --- | --- | ---
    `"n"` | string | binary number | yes | modulus
    `"e"` | string | binary number | no | public exponent
    `"d"` | string | binary number | yes | private exponent
    `"p"` | string | binary number | no | prime 1
    `"q"` | string | binary number | no | prime 2
    `"dmp1"` | string | binary number | no | exponent1, d mod (p-1)
    `"dmq1"` | string | binary number | no | exponent2, d mod (q-1)
    `"iqmp"` | string | binary number | no | coefficient, (inverse of q) mod p

  - `"dsa"` key 用于设置 DSA 参数。

    选项 | 类型 | 格式 | 是否必需 | 说明
    --- | --- | --- | --- | ---
    `"p"` | string | binary number | no | prime number (public)
    `"q"` | string | binary number | no | 160-bit subprime, q | p-1 (public)
    `"g"` | string | binary number | no | generator of subgroup (public)
    `"priv_key"` | string | PEM key | no | private key x
    `"pub_key"` | string | PEM key | no | public key y = g^x

  - `"dh"` key 用于 DH（迪菲-赫尔曼密钥交换）参数。

    选项 | 类型 | 格式 | 是否必需 | 说明
    --- | --- | --- | --- | ---
    `"p"` | string | binary number | no | prime number (shared)
    `"g"` | string | binary number | no | generator of Z_p (shared)
    `"priv_key"` | string | PEM key | no | private DH value x
    `"pub_key"` | string | PEM key | no | public DH value g^x

  - `"ec"` key，用于椭圆曲线参数

    选项 | 类型 | 格式 | 是否必需 | 说明
    --- | --- | --- | --- | ---
    `"curve_name"` | string | name | no | name of curve, see openssl_get_curve_names()
    `"p"` | string | binary number | no | prime of the field for curve over Fp
    `"a"` | string | binary number | no | coofecient a of the curve for Fp: y^2 mod p = x^3 + ax + b mod p
    `"b"` | string | binary number | no | coofecient b of the curve for Fp: y^2 mod p = x^3 + ax + b mod p
    `"seed"` | string | binary number | no | 用于生成系数 b 的可选随机数种子
    `"generator"` | string | binary encoded point | no | 曲线生成点
    `"g_x"` | string | binary number | no | 曲线生成点 x 坐标
    `"g_y"` | string | binary number | no | 曲线生成点 y 坐标
    `"cofactor"` | string | binary number | no | curve cofactor
    `"order"` | string | binary number | no | curve order
    `"x"` | string | binary number | no | x coordinate (public)
    `"y"` | string | binary number | no | y coordinate (public)
    `"d"` | string | binary number | no | private key

  - `"x25519"`、`"x448"`、`"ed25519"`、`"ed448"` key 用于 Curve25519 和 Curve448 参数。

    选项 | 类型 | 格式 | 是否必需 | 说明
    --- | --- | --- | --- | ---
    `"priv_key"` | string | PEM key | no | 私钥
    `"pub_key"` | string | PEM key | no | 公钥

### 返回值

成功时此函数会返回 OpenSSLAsymmetricKey 的实例；在失败时则会返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 引入 `x25519`、`ed25519`、`x448` 和 `ed448` 字段，增加了对基于 Curve25519 和 Curve448 的密钥支持。
8.3.0 | 新增使用自定义 EC 参数生成 EC 秘钥的支持。特别是引入了 EC 选项：`p`、`a`、`b`、`seed`、`generator`、`g_x`、`g_y`、`cofactor` 和 `order`。
8.0.0 | 成功时此函数会返回 OpenSSLAsymmetricKey 的实例；在之前版本中，则会返回类似为 `OpenSSL key` 的 resource。
7.1.0 | `options` 参数中增加了 `curve_name` 键，以便基于椭圆曲线算法创建 EC 密钥。

### 示例

示例 #1 从私钥获取公钥

    <?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);

    ?>

以上示例的输出类似于：

    // Output prior to PHP 8.0.0; note, the function returns a resource
    -----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)

    // Output as of PHP 8.0.0; note, the function returns an object
    -----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) {
    }

# openssl_private_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_private_decrypt — 使用私钥解密数据

### 说明

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() 解密之前通过 openssl_public_encrypt() 加密的 `data`，并将结果保存至 `decrypted_data` 中。

可以使用该函数来解密只对个人有效的数据。

### 参数

`data`

`decrypted_data`

`private_key`

  `private_key` 必须是与用于加密数据的公钥对应的私钥。

`padding`

  `padding` 可以是如下值：`OPENSSL_PKCS1_PADDING`、`OPENSSL_SSLV23_PADDING`、`OPENSSL_PKCS1_OAEP_PADDING`、`OPENSSL_NO_PADDING`。

`digest_algo`
  OAEP 填充的摘要算法，或者 `null` 使用默认算法。

### 更新日志

版本 | 说明
--- | ---
8.5.0 | 添加了可选参数 `digest_algo`。
8.0.0 | `private_key` 现在接受 OpenSSLAsymmetricKey 或 OpenSSLCertificate 实例。之前接受 `OpenSSL key` 类型或 `OpenSSL X.509` 类型的 resource。

### 参见

- openssl_public_encrypt() - 使用公钥加密数据
- openssl_public_decrypt() - 使用公钥解密数据

# openssl_private_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_private_encrypt — 使用私钥加密数据

### 说明

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() 使用私钥 `private_key` 加密数据 `data` 并且将结果保存至变量 `encrypted_data`中。加密后的数据可以通过openssl_public_decrypt()函数来解密。

该函数用来签名数据（或者哈希）让别人相信数据并不是其他人写的。

### 参数

`data`

`encrypted_data`

`private_key`

  `private_key` 必须是与用于解密数据的公钥对应的私钥。

`padding`

  `padding` 可以是如下之一： `OPENSSL_PKCS1_PADDING`, `OPENSSL_NO_PADDING`.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `private_key` 现在接受 OpenSSLAsymmetricKey 或 OpenSSLCertificate 实例；之前接受类型 `OpenSSL key` 或 `OpenSSL X.509` 的 resource。

### 参见

- openssl_public_encrypt() - 使用公钥加密数据
- openssl_public_decrypt() - 使用公钥解密数据

# openssl_public_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_public_decrypt — 使用公钥解密数据

### 说明

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() 解密先前由 openssl_private_encrypt() 加密的数据 `data` 并且将结果保存至变量 `decrypted_data`中。

你可以用该函数来校验消息是否是私钥拥有者写的。

### 参数

`data`

`decrypted_data`

`public_key`

  `private_key` 必须是与用于加密数据的公钥对应的私钥。

`padding`

  `padding` 可以是如下至 `OPENSSL_PKCS1_PADDING`, `OPENSSL_NO_PADDING`.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `public_key` 现在接受 OpenSSLAsymmetricKey 或 OpenSSLCertificate 实例。之前接受类型 `OpenSSL key` 或 `OpenSSL X.509` 的 resource。

### 参见

- openssl_private_encrypt() - 使用私钥加密数据
- openssl_private_decrypt() - 使用私钥解密数据

# openssl_public_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_public_encrypt — 使用公钥加密数据

### 说明

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() 使用公钥 `public_key` 解密数据 `data` 并且将结果保存到变量 `encrypted_data` 中。加密的数据可以通过 openssl_private_decrypt() 函数解密。

该函数可以用来加密数据，供该公钥匹配的私钥拥有者读取。 它也可以用来在数据库中存储安全数据。

### 参数

`data`

`encrypted_data`

  这将保存加密的结果。

`public_key`

  `public_key` 必须是与用于解密数据的私钥对应的公钥。

`padding`

  `padding` can be one of `OPENSSL_PKCS1_PADDING`, `OPENSSL_SSLV23_PADDING`, `OPENSSL_PKCS1_OAEP_PADDING`, `OPENSSL_NO_PADDING`.

`digest_algo`
  OAEP 填充的摘要算法，或者 `null` 使用默认算法。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.5.0 | 添加了可选参数 `digest_algo`。
8.0.0 | `public_key` 现在接受 OpenSSLAsymmetricKey 或 OpenSSLCertificate 实例。之前接受类型 `OpenSSL key` 或 `OpenSSL X.509` 的 resource。

### 参见

- openssl_private_encrypt() - 使用私钥加密数据
- openssl_private_decrypt() - 使用私钥解密数据

# openssl_random_pseudo_bytes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_random_pseudo_bytes — 生成一个伪随机字节串

### 说明

function openssl_random_pseudo_bytes(int `$length`, bool `&$strong_result` = `null`): string

生成一个伪随机字节串 string ，字节数由 `length` 参数指定。

通过 `strong_result` 参数可以表示在生成随机字节的过程中是否使用了强加密算法。返回值为 `false` 的情况很少见，但已损坏或老化的有些系统上会出现。

### 参数

`length`

  所需字节串的长度，必须为正整数且小于等于 `2147483647`。PHP 会试着将该参数转换为非空整数来使用它。

`strong_result`

  如果传递到该函数中，将会保存为一个 bool 值来表明是否使用了“强加密”，如果被用于GPG和密码之类的将返回 `true`，否则返回 `false`

### 返回值

返回生成的字节 string。

### 错误／异常

openssl_random_pseudo_bytes() 失败时抛出 Exception。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `strong_result` 现在可为 null。
7.4.0 | 此函数失败时不再返回 `false`，而是会抛出 Exception。

### 示例

示例 #1 openssl_random_pseudo_bytes() 示例

    <?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;
    }
    ?>

以上示例的输出类似于：

    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)

### 参见

- random_bytes() - Get cryptographically secure random bytes
- bin2hex() - 将二进制数据转换为十六进制表示
- crypt() - 单向字符串散列
- random_int() - 获取生成加密安全、均匀分布的整数

# openssl_seal

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_seal — 密封 (加密) 数据

### 说明

function openssl_seal(
#[\SensitiveParameter] string `$data`,
string `&$sealed_data`,
array `&$encrypted_keys`,
array `$public_key`,
string `$cipher_algo`,
string `&$iv` = `null`
): int|false

openssl_seal() 使用指定 `cipher_algo` 和随机生成的密钥密封（加密）`data`。使用 `public_key` 数组中的每个公钥对秘钥加密，并在 `encrypted_keys` 返回每个加密的 envelope 密钥。 这允许将密封的数据发送给多个接收方（前提是公钥可用）。每个接收方都必须同时接收加密的数据和用接收方的公钥加密的 envelope 密钥。生成 IV（初始化向量），并在 `iv` 中返回其值。

### 参数

`data`

  要密封的数据。

`sealed_data`

  被密封后的数据。

`encrypted_keys`

  已被加密的密钥数组。

`public_key`

  包含公钥的 OpenSSLAsymmetricKey 实例数组。

`cipher_algo`

  加密算法。

  警告

  默认值在 PHP 8.0 之前为（`'RC4'`），这不安全。强烈建议明确指定安全密码方法。

`iv`

  用于解密 `data` 的初始化向量。如果密码方法需要 IV，则需要它。可以通过调用 openssl_cipher_iv_length() 时传入 `cipher_algo` 来找到它。

  警告

  IV 无法明确设置。其中设置的任何值都将被随机生成的值覆盖。

### 返回值

成功时返回密封后数据的长度，错误为 `false`。 如果密封后的数据成功地通过 `sealed_data` 变量返回，那么信封密钥也将会通过 `encrypted_keys` 变量返回。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `public_key` 现在接受 OpenSSLAsymmetricKey 实例 array；之前接受类型 `OpenSSL key` 的 resource 数组。
8.0.0 | `cipher_algo` 不再是可选参数。
8.0.0 | `iv` 现在可为 null。

### 示例

示例 #1 openssl_seal() 示例

    <?php
    // 假设 $data 包含要密封的数据
    $data = "test";

    // 获取公钥
    $pk1 = openssl_get_publickey("file://cert1.pem");
    $pk2 = openssl_get_publickey("file://cert2.pem");

    // 密封消息，只有 $pk1 和 $pk2 的所有者才能分别使用密钥
    // $ekeys[0] 和 $ekeys[1] 解密 $sealed。
    if (openssl_seal($data, $sealed, $ekeys, array($pk1, $pk2), 'AES256', $iv) > 0) {
        // 可能存储 $sealed 和 $iv 值并稍后在 openssl_open 中使用
        echo "success\n";
    }
    ?>

### 参见

- openssl_open() - 打开密封的数据

# openssl_sign

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_sign — Generate signature

### 说明

function openssl_sign(
string `$data`,
string `&$signature`,
#[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
string|int `$algorithm` = `OPENSSL_ALGO_SHA1`,
int `$padding` = 0
): bool

openssl_sign() computes a signature for the specified `data` by generating a cryptographic digital signature using the private key associated with `private_key`. Note that the data itself is not encrypted.

### 参数

`data`

  The string of data you wish to sign

`signature`

  If the call was successful the signature is returned in `signature`.

`private_key`

  OpenSSLAsymmetricKey - a key, returned by openssl_get_privatekey()

  string - a PEM formatted key

`algorithm`

  int - one of these Signature Algorithms.

  string - a valid string returned by openssl_get_md_methods() example, "sha256WithRSAEncryption" or "sha384".

`padding`
  RSA PSS padding to use.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.5.0 | The optional parameter `padding` has been added.
8.0.0 | `private_key` accepts an OpenSSLAsymmetricKey or OpenSSLCertificate instance now; previously, a resource of type `OpenSSL key` or `OpenSSL X.509` was accepted.

### 示例

示例 #1 openssl_sign() example

    <?php
    // $data is assumed to contain the data to be signed

    // fetch private key from file and ready it
    $pkeyid = openssl_pkey_get_private("file://src/openssl-0.9.6/demos/sign/key.pem");

    // compute signature
    openssl_sign($data, $signature, $pkeyid);

    // free the key from memory
    openssl_free_key($pkeyid);
    ?>

示例 #2 openssl_sign() example

    <?php
    //data you want to sign
    $data = 'my data';

    //create new private and public key
    $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'];

    //create signature
    openssl_sign($data, $signature, $private_key_pem, OPENSSL_ALGO_SHA256);

    //save for later
    file_put_contents('private_key.pem', $private_key_pem);
    file_put_contents('public_key.pem', $public_key_pem);
    file_put_contents('signature.dat', $signature);

    //verify signature
    $r = openssl_verify($data, $signature, $public_key_pem, "sha256WithRSAEncryption");
    var_dump($r);
    ?>

### 参见

- openssl_verify() - 验证签名

# openssl_spki_export

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_export — 通过签名公钥和 challenge 导出一个可用的 PEM 格式的公钥

### 说明

function openssl_spki_export(string `$spki`): string|false

从编码的签名公钥和 challenge 导出 PEM 格式的公钥。

### 参数

`spki`

  期望一个有效的签名公钥和 challenge 字符串。

### 返回值

返回关联的 PEM 格式的公钥，失败则返回 `false`。

### 错误／异常

如果传递给 `spki` 参数是不可用的参数，则会抛出 `E_WARNING` 级别的警告。

### 示例

示例 #1 openssl_spki_export() 示例

成功，返回关联的 PEM 格式的公钥，失败则返回 NULL.

    <?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;
    }
    ?>

示例 #2 openssl_spki_export() 来自 <keygen> 的示例

通过 <keygen> 元素导出关联的 PEM 格式的公钥：

    <?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">

### 参见

- openssl_spki_new() - 生成新的签名公钥和 challenge
- openssl_spki_verify() - 验证签名公钥和 challenge
- openssl_spki_export_challenge() - 导出与签名公钥和 challenge 相关的 challenge
- openssl_get_md_methods() - 获取可用的摘要算法
- openssl_csr_new() - 生成一个 CSR
- openssl_csr_sign() - 用另一个证书签署 CSR（或者本身）并且生成一个证书

# openssl_spki_export_challenge

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_export_challenge — 导出与签名公钥和 challenge 相关的 challenge

### 说明

function openssl_spki_export_challenge(string `$spki`): string|false

从编码的签名公钥和 challenge 中导出 challenge

### 参数

`spki`

  需要有效的签名公钥和 challenge

### 返回值

返回相关 challenge 字符串，失败返回 `false`。

### 错误／异常

如果 `spki` 参数传递的是不可用的参数，则抛出 `E_WARNING` 级别的错误。

### 示例

示例 #1 openssl_spki_export_challenge() 示例

成功，提取相关联的 challenge 字符串，失败则返回 NULL。

    <?php
    $pkey = openssl_pkey_new('secret password');
    $spkac = openssl_spki_new($pkey, 'challenge string');
    $challenge = openssl_spki_export_challenge(preg_replace('/SPKAC=/', '', $spkac));
    ?>

示例 #2 openssl_spki_export_challenge() 来自 <keygen> 的示例

从 <keygen> 元素中解压相关联的 challenge 字符串。

    <?php
    $challenge = openssl_spki_export_challenge(preg_replace('/SPKAC=/', '', $_POST['spkac']));
    ?>
    <keygen name="spkac" challenge="challenge string" keytype="RSA">

### 参见

- openssl_spki_new() - 生成新的签名公钥和 challenge
- openssl_spki_verify() - 验证签名公钥和 challenge
- openssl_spki_export() - 通过签名公钥和 challenge 导出一个可用的 PEM 格式的公钥
- openssl_get_md_methods() - 获取可用的摘要算法
- openssl_csr_new() - 生成一个 CSR
- openssl_csr_sign() - 用另一个证书签署 CSR（或者本身）并且生成一个证书

# openssl_spki_new

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_new — 生成新的签名公钥和 challenge

### 说明

function openssl_spki_new(#[\SensitiveParameter] OpenSSLAsymmetricKey `$private_key`, string `$challenge`, int `$digest_algo` = `OPENSSL_ALGO_MD5`): string|false

使用指定散列算法生成新的签名公钥和 challenge。

### 参数

`private_key`

  `private_key` 应该被设置为由 openssl_pkey_new() 函数预先生成（或者以其他方式从 openssl_pkey 函数家族集中获得）的私钥。该密钥的相应公共部分将用于签署 CSR。

`challenge`

  与 SPKAC 有关的 challenge。

`digest_algo`

  摘要算法。参见 openssl_get_md_method()。

### 返回值

返回签名的公钥和 challenge，失败返回 `false`。

### 错误／异常

如果传递给 `digest_algo` 的参数是未知的签名算法，将会抛出 `E_WARNING` 级别的错误。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `private_key` 现在接受 OpenSSLAsymmetricKey 实例；之前接受类型 `OpenSSL key` 的 resource。

### 示例

示例 #1 openssl_spki_new() 示例

使用默认的摘要算法（MD5）生成新的 SPKAC

    <?php
    $pkey = openssl_pkey_new('secret password');
    $spkac = openssl_spki_new($pkey, 'testing');

    if ($spkac !== NULL) {
        echo $spkac;
    } else {
        echo "SPKAC generation failed";
    }
    ?>

以上示例的输出类似于：

    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=

### 参见

- openssl_spki_verify() - 验证签名公钥和 challenge
- openssl_spki_export_challenge() - 导出与签名公钥和 challenge 相关的 challenge
- openssl_spki_export() - 通过签名公钥和 challenge 导出一个可用的 PEM 格式的公钥
- openssl_get_md_methods() - 获取可用的摘要算法
- openssl_csr_new() - 生成一个 CSR
- openssl_csr_sign() - 用另一个证书签署 CSR（或者本身）并且生成一个证书

# openssl_spki_verify

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_verify — 验证签名公钥和 challenge

### 说明

function openssl_spki_verify(string `$spki`): bool

验证提供的签名公钥和 challenge。

### 参数

`spki`

  期望有效的签名公钥和 challenge。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

如果传递给 `digest_algo` 的参数不是可用的参数，将会抛出 `E_WARNING` 级别的错误。

### 示例

示例 #1 openssl_spki_verify() 示例

验证现有签名公钥和 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";
    }
    ?>

示例 #2 openssl_spki_verify() 来自 <keygen> 的示例

通过 <keygen> 元素验证现有签名公钥和 challenge

    <?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">

### 参见

- openssl_spki_new() - 生成新的签名公钥和 challenge
- openssl_spki_export_challenge() - 导出与签名公钥和 challenge 相关的 challenge
- openssl_spki_export() - 通过签名公钥和 challenge 导出一个可用的 PEM 格式的公钥
- openssl_get_md_methods() - 获取可用的摘要算法
- openssl_csr_new() - 生成一个 CSR
- openssl_csr_sign() - 用另一个证书签署 CSR（或者本身）并且生成一个证书

# openssl_verify

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_verify — 验证签名

### 说明

function openssl_verify(
string `$data`,
string `$signature`,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`,
string|int `$algorithm` = `OPENSSL_ALGO_SHA1`,
int `$padding` = 0
): int|false

openssl_verify() 使用与 `public_key` 关联的公钥验证指定数据 `data` 的签名 `signature` 是否正确。这必须是与用于签名的私钥相对应的公钥。

### 参数

`data`

  以前用来生成签名的数据字符串。

`signature`

  原始二进制字符串，通过 openssl_sign() 或类似的函数生成。

`public_key`

  OpenSSLAsymmetricKey - 一个密钥, 通过 openssl_get_publickey() 函数返回。

  string - 一个 PEM 格式的密钥（比如 `-----BEGIN PUBLIC KEY----- MIIBCgK...`）

`algorithm`

  int - 以下签名算法之一 Signature Algorithms.

  string - 由 openssl_get_md_methods() 函数返回的可用字符串，比如，"sha1WithRSAEncryption" 或者 "sha512".

`padding`
  RSA PSS填充方案。

### 返回值

如果签名正确返回 1，签名错误返回 0，错误时返回 -1 或 `false`。

### 更新日志

版本 | 说明
--- | ---
8.5.0 | 添加了可选参数 `padding`。
8.0.0 | `public_key` 现在接受 OpenSSLAsymmetricKey 或 OpenSSLCertificate 实例；之前接受类型 `OpenSSL key` 或 `OpenSSL X.509` 的 resource。

### 示例

示例 #1 openssl_verify() 示例

    <?php
    // $data and $signature are assumed to contain the data and the signature

    // fetch public key from certificate and ready it
    $pubkeyid = openssl_pkey_get_public("file://src/openssl-0.9.6/demos/sign/cert.pem");

    // state whether signature is okay or not
    $ok = openssl_verify($data, $signature, $pubkeyid);
    if ($ok == 1) {
        echo "good";
    } elseif ($ok == 0) {
        echo "bad";
    } else {
        echo "ugly, error checking signature";
    }
    // free the key from memory
    openssl_free_key($pubkeyid);
    ?>

示例 #2 openssl_verify() 示例

    <?php
    //data you want to sign
    $data = 'my data';

    //create new private and public key
    $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']);

    //create signature
    openssl_sign($data, $signature, $private_key_res, "sha256WithRSAEncryption");

    //verify signature
    $ok = openssl_verify($data, $signature, $public_key_res, OPENSSL_ALGO_SHA256);
    if ($ok == 1) {
        echo "valid";
    } elseif ($ok == 0) {
        echo "invalid";
    } else {
        echo "error: ".openssl_error_string();
    }
    ?>

### 参见

- openssl_sign() - Generate signature

# openssl_x509_check_private_key

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_check_private_key — 检查私钥是否对应于证书

### 说明

function openssl_x509_check_private_key(OpenSSLCertificate|string `$certificate`, #[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`): bool

检查指定的私钥 `private_key` 是否和证书 `certificate` 对应。

警告

这个函数不会检查密钥 `private_key` 是否真的是私钥。 它只是比较了和密钥匹配的公共材料 (比如，RSA 密钥的指数和模量) 和/或密钥参数(比如，EC 密钥的参数)。

这也意味着，比如，提供给 `private_key` 赋一个公钥值，该函数可能返回 `true`。

### 参数

`certificate`

  证书。

`private_key`

  私钥。

### 返回值

如果指定的私钥 `private_key` 和证书 `certificate` 对应，返回 `true` 否则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `certificate` 现在接受 OpenSSLCertificate 实例；之前接受类型 `OpenSSL X.509` 的 resource。
8.0.0 | `private_key` 现在接受 OpenSSLAsymmetricKey 或 OpenSSLCertificate 实例；之前接受类型 `OpenSSL key` 或 `OpenSSL X.509` 的 resource。

# openssl_x509_checkpurpose

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_checkpurpose — 验证是否可以为特定目的使用证书

### 说明

function openssl_x509_checkpurpose(
OpenSSLCertificate|string `$certificate`,
int `$purpose`,
array `$ca_info` = [],
?string `$untrusted_certificates_file` = `null`
): bool|int

openssl_x509_checkpurpose() 检查证书以查看它是否可用于指定目的 `purpose`。

### 参数

`certificate`

  被检查的证书。

`purpose`

  openssl_x509_checkpurpose() 目的
  常量名 | 描述
  --- | ---
  X509_PURPOSE_SSL_CLIENT | 证书是否可以用于 SSL 连接的客户端?
  X509_PURPOSE_SSL_SERVER | 证书是否可以用于 SSL 连接的服务器端?
  X509_PURPOSE_NS_SSL_SERVER | 证书是否可以用于 Netscape SSL 服务器?
  X509_PURPOSE_SMIME_SIGN | 证书是否可以用来签名 S/MIME 邮件?
  X509_PURPOSE_SMIME_ENCRYPT | 正式是否可用用来加密 S/MIME 邮件?
  X509_PURPOSE_CRL_SIGN | 证书是否可以用来签名证书撤销列表（CRL）?
  X509_PURPOSE_ANY | 证书是否可以用于任何目的?

  这些选项不是位字段——只能指定一个字段!
`ca_info`

  `ca_info` 应该是一个受信任的 CA 文件/文件夹组成的数组，如 Certificate Verification 所描述的一样。

`untrusted_certificates_file`

  如果指定，这应该是 PEM 编码文件的名称，该文件持有证书，可以用来帮助验证证书,尽管从该文件中获得的证书不受信任。

### 返回值

如果证书可以用于预期目的，返回 `true`，如果不行，则返回 `false` 错误便会返回 -1。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `certificate` 现在接受 OpenSSLCertificate 实例；之前接受类型 `OpenSSL X.509` 的 resource。
8.0.0 | `untrusted_certificates_file` 现在可为 null。

# openssl_x509_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_export — 以字符串格式导出证书

### 说明

function openssl_x509_export(OpenSSLCertificate|string `$certificate`, string `&$output`, bool `$no_text` = `true`): bool

openssl_x509_export() 将 `certificate` 以 PEM 编码的格式导出到名为 `output` 的字符串类型的变量中。

### 参数

`certificate`
  参见密钥／证书参数以获取有效值列表。
`output`

  成功，将会存储 PEM。

`no_text`
  可选参数 `notext` 影响输出的冗余度。如果设为 `false`，输出内容将包含附加的人类可读信息。`notext` 的缺省值为 `true`。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `certificate` 现在接受 OpenSSLCertificate 实例；之前接受类型 `OpenSSL X.509` 的 resource。

# openssl_x509_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_export_to_file — 导出证书至文件

### 说明

function openssl_x509_export_to_file(OpenSSLCertificate|string `$certificate`, string `$output_filename`, bool `$no_text` = `true`): bool

openssl_x509_export_to_file() 将 `certificate` 以 PEM 编码的格式保存到名为 `output_filename` 的文件中。

### 参数

`certificate`
  参见密钥／证书参数以获取有效值列表。
`output_filename`

  输出文件的路径。

`no_text`
  可选参数 `notext` 影响输出的冗余度。如果设为 `false`，输出内容将包含附加的人类可读信息。`notext` 的缺省值为 `true`。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `certificate` 现在接受 OpenSSLCertificate 实例；之前接受类型 `OpenSSL X.509` 的 resource。

# openssl_x509_fingerprint

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_x509_fingerprint — 计算一个给定的 x.509 证书的指纹或摘要

### 说明

function openssl_x509_fingerprint(OpenSSLCertificate|string `$certificate`, string `$digest_algo` = "sha1", bool `$binary` = `false`): string|false

openssl_x509_fingerprint() 返回 `certificate` 的字符串类型的摘要。

### 参数

`certificate`
  参见密钥／证书参数以获取有效值列表。
`digest_algo`

  使用的摘要方法或散列算法，比如，"sha256"、openssl_get_md_methods() 摘要算法之一。

`binary`

  设置为 `true` 时，输出原始二进制数据。设置为 `false` 时，输出小写的 16 进制字符串。

### 返回值

将包含计算的证书指纹的字符串返回为小写 16 进制格式，除非将 `binary` 设置为 `true`，在这种情况下会返回消息摘要的原始二进制表示形式。

失败则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `certificate` 现在接受 OpenSSLCertificate 实例；之前接受类型 `OpenSSL X.509` 的 resource。

# openssl_x509_free

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_free — 释放证书资源

警告

本函数已自 PHP 8.0.0 起被废弃。强烈建议不要依赖本函数。

### 说明

#[\Deprecated]
function openssl_x509_free(OpenSSLCertificate `$certificate`): void

> 注意: 此函数无效。在 PHP 8.0.0 之前，用于关闭资源。

openssl_x509_free() 从内存中释放和指定 `certificate` 资源相关联的证书。

### 参数

`certificate`

### 返回值

没有返回值。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 此函数现已弃用，因为不再有效。
8.0.0 | `certificate` 现在接受 OpenSSLCertificate 实例；之前接受类型 `OpenSSL X.509` 的 resource。

# openssl_x509_parse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_parse — 解析 X509 证书并作为一个数组返回信息

### 说明

function openssl_x509_parse(OpenSSLCertificate|string `$certificate`, bool `$short_names` = `true`): array|false

openssl_x509_parse() 返回提供的 `certificate` 证书的信息，包括主题名称、发行方名称、目的、有效日期等字段。

### 参数

`certificate`

  X509 证书。有关有效值列表，参阅密钥/证书参数。

`short_names`

  `short_names` 控制数据在数组中的索引 - 如果 `short_names` 为 `true`，字段将以短名称的形式被索引，否则将会使用长名称的形式 - 比如 CN 就是 commonName 的短名称格式。

### 返回值

返回的数据的结构是（故意的）还没有文档化，因为它仍然会发生变化。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | OpenSSL 所有版本均不再允许解析不含秒数的 UTCTime 格式证书。自 OpenSSL 3.3 版本起，该格式已被明确禁止。
8.0.0 | `certificate` 现在接受 OpenSSLCertificate 实例；之前接受类型 `OpenSSL X.509` 的 resource。

# openssl_x509_read

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_read — 解析 x.509 证书并返回对象

### 说明

function openssl_x509_read(OpenSSLCertificate|string `$certificate`): OpenSSLCertificate|false

openssl_x509_read() 解析`certificate` 提供的证书，并返回它的 OpenSSLCertificate 对象。

### 参数

`certificate`

  X509 证书。参见 Key/Certificate parameters 获取可用的值。

### 返回值

成功时返回 OpenSSLCertificate， 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 此函数现在成功时返回 OpenSSLCertificate 实例；之前返回类型 `OpenSSL X.509` 的 resource。
8.0.0 | `certificate` 现在接受 OpenSSLCertificate 实例；之前接受类型 `OpenSSL X.509` 的 resource。

# openssl_x509_verify

(PHP 7 >= 7.4.0, PHP 8)

openssl_x509_verify — Verifies digital signature of x509 certificate against a public key

### 说明

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`.

### 参数

`certificate`
  参见密钥／证书参数以获取有效值列表。
`public_key`

  OpenSSLAsymmetricKey - a key, returned by openssl_get_publickey()

  string - a PEM formatted key (e.g. `-----BEGIN PUBLIC KEY----- MIIBCgK...`)

### 返回值

Returns 1 if the signature is correct, 0 if it is incorrect, and -1 on error.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `certificate` accepts an OpenSSLCertificate instance now; previously, a resource of type `OpenSSL X.509` was accepted.
8.0.0 | `public_key` accepts an OpenSSLAsymmetricKey or OpenSSLCertificate instance now; previously, a resource of type `OpenSSL key` or `OpenSSL X.509` was accepted.

### 示例

示例 #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";
        }
    }
    ?>

### 参见

- openssl_verify() - 验证签名
- openssl_get_publickey() - 别名 openssl_pkey_get_public

## 目录

- openssl_cipher_iv_length — 获取密码iv长度
- openssl_cipher_key_length — Gets the cipher key length
- 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 — 将 CSR 作为字符串导出
- openssl_csr_export_to_file — 将 CSR 导出到文件
- openssl_csr_get_public_key — 返回 CSR 的公钥
- openssl_csr_get_subject — 返回 CSR 的主题
- openssl_csr_new — 生成一个 CSR
- openssl_csr_sign — 用另一个证书签署 CSR（或者本身）并且生成一个证书
- openssl_decrypt — 解密数据
- openssl_dh_compute_key — 计算远程 DH 公钥和本地 DH 密钥的共享密钥
- openssl_digest — 计算摘要
- openssl_encrypt — 加密数据
- openssl_error_string — 返回 openSSL 错误消息
- openssl_free_key — 释放密钥资源
- openssl_get_cert_locations — 检索可用的证书位置
- openssl_get_cipher_methods — 获取可用的加密算法
- openssl_get_curve_names — 获得ECC的可用曲线名称列表
- openssl_get_md_methods — 获取可用的摘要算法
- openssl_get_privatekey — 别名 openssl_pkey_get_private
- openssl_get_publickey — 别名 openssl_pkey_get_public
- openssl_open — 打开密封的数据
- 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 — 生成 PKCS5 v2 PBKDF2 字符串
- openssl_pkcs12_export — 将 PKCS#12 兼容证书存储文件导出到变量
- openssl_pkcs12_export_to_file — 输出一个 PKCS#12 兼容的证书存储文件
- openssl_pkcs12_read — 将 PKCS#12 证书存储区解析到数组中
- openssl_pkcs7_decrypt — 解密一个 S/MIME 加密的消息
- openssl_pkcs7_encrypt — 加密一个 S/MIME 消息
- openssl_pkcs7_read — 将 PKCS7 文件导出为 PEM 格式证书的数组
- openssl_pkcs7_sign — 对一个 S/MIME 消息进行签名
- openssl_pkcs7_verify — 校验一个已签名的 S/MIME 消息的签名
- openssl_pkey_derive — Computes shared secret for public value of remote and local DH or ECDH key
- openssl_pkey_export — 将一个密钥的可输出表示转换为字符串
- openssl_pkey_export_to_file — 将密钥导出到文件中
- openssl_pkey_free — 释放一个私钥
- openssl_pkey_get_details — 返回包含密钥详情的数组
- openssl_pkey_get_private — 获取私钥
- openssl_pkey_get_public — 从证书中解析公钥，以供使用
- openssl_pkey_new — 生成新的私钥
- openssl_private_decrypt — 使用私钥解密数据
- openssl_private_encrypt — 使用私钥加密数据
- openssl_public_decrypt — 使用公钥解密数据
- openssl_public_encrypt — 使用公钥加密数据
- openssl_random_pseudo_bytes — 生成一个伪随机字节串
- openssl_seal — 密封 (加密) 数据
- openssl_sign — Generate signature
- openssl_spki_export — 通过签名公钥和 challenge 导出一个可用的 PEM 格式的公钥
- openssl_spki_export_challenge — 导出与签名公钥和 challenge 相关的 challenge
- openssl_spki_new — 生成新的签名公钥和 challenge
- openssl_spki_verify — 验证签名公钥和 challenge
- openssl_verify — 验证签名
- openssl_x509_check_private_key — 检查私钥是否对应于证书
- openssl_x509_checkpurpose — 验证是否可以为特定目的使用证书
- openssl_x509_export — 以字符串格式导出证书
- openssl_x509_export_to_file — 导出证书至文件
- openssl_x509_fingerprint — 计算一个给定的 x.509 证书的指纹或摘要
- openssl_x509_free — 释放证书资源
- openssl_x509_parse — 解析 X509 证书并作为一个数组返回信息
- openssl_x509_read — 解析 x.509 证书并返回对象
- openssl_x509_verify — Verifies digital signature of x509 certificate against a public key

# OpenSSLCertificate 类

(PHP 8)

## 简介

从 PHP 8.0.0 开始替换 `OpenSSL X.509` 资源的完全不透明类。

## 类摘要

final class OpenSSLCertificate {
}

# OpenSSLCertificateSigningRequest 类

(PHP 8)

## 简介

从 PHP 8.0.0 开始替换 `OpenSSL X.509 CSR` 资源的完全不透明类。

## 类摘要

final class OpenSSLCertificateSigningRequest {
}

# OpenSSLAsymmetricKey 类

(PHP 8)

## 简介

从 PHP 8.0.0 开始替换 `OpenSSL key` 资源的完全不透明类。

## 类摘要

final class OpenSSLAsymmetricKey {
}

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
  - 资源类型
- 预定义常量
  - 目的检查 flag
  - 非对称加密的填充标志
  - 密钥类型
  - PKCS7 flag/常量
  - CMS Flag/常量
  - 签名算法
  - Ciphers
  - 版本常量
  - Server Name Indication constants
  - 其它常量
- 密钥/证书参数
- 证书验证
- OpenSSL 函数
  - openssl_cipher_iv_length — 获取密码iv长度
  - openssl_cipher_key_length — Gets the cipher key length
  - 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 — 将 CSR 作为字符串导出
  - openssl_csr_export_to_file — 将 CSR 导出到文件
  - openssl_csr_get_public_key — 返回 CSR 的公钥
  - openssl_csr_get_subject — 返回 CSR 的主题
  - openssl_csr_new — 生成一个 CSR
  - openssl_csr_sign — 用另一个证书签署 CSR（或者本身）并且生成一个证书
  - openssl_decrypt — 解密数据
  - openssl_dh_compute_key — 计算远程 DH 公钥和本地 DH 密钥的共享密钥
  - openssl_digest — 计算摘要
  - openssl_encrypt — 加密数据
  - openssl_error_string — 返回 openSSL 错误消息
  - openssl_free_key — 释放密钥资源
  - openssl_get_cert_locations — 检索可用的证书位置
  - openssl_get_cipher_methods — 获取可用的加密算法
  - openssl_get_curve_names — 获得ECC的可用曲线名称列表
  - openssl_get_md_methods — 获取可用的摘要算法
  - openssl_get_privatekey — 别名 openssl_pkey_get_private
  - openssl_get_publickey — 别名 openssl_pkey_get_public
  - openssl_open — 打开密封的数据
  - 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 — 生成 PKCS5 v2 PBKDF2 字符串
  - openssl_pkcs12_export — 将 PKCS#12 兼容证书存储文件导出到变量
  - openssl_pkcs12_export_to_file — 输出一个 PKCS#12 兼容的证书存储文件
  - openssl_pkcs12_read — 将 PKCS#12 证书存储区解析到数组中
  - openssl_pkcs7_decrypt — 解密一个 S/MIME 加密的消息
  - openssl_pkcs7_encrypt — 加密一个 S/MIME 消息
  - openssl_pkcs7_read — 将 PKCS7 文件导出为 PEM 格式证书的数组
  - openssl_pkcs7_sign — 对一个 S/MIME 消息进行签名
  - openssl_pkcs7_verify — 校验一个已签名的 S/MIME 消息的签名
  - openssl_pkey_derive — Computes shared secret for public value of remote and local DH or ECDH key
  - openssl_pkey_export — 将一个密钥的可输出表示转换为字符串
  - openssl_pkey_export_to_file — 将密钥导出到文件中
  - openssl_pkey_free — 释放一个私钥
  - openssl_pkey_get_details — 返回包含密钥详情的数组
  - openssl_pkey_get_private — 获取私钥
  - openssl_pkey_get_public — 从证书中解析公钥，以供使用
  - openssl_pkey_new — 生成新的私钥
  - openssl_private_decrypt — 使用私钥解密数据
  - openssl_private_encrypt — 使用私钥加密数据
  - openssl_public_decrypt — 使用公钥解密数据
  - openssl_public_encrypt — 使用公钥加密数据
  - openssl_random_pseudo_bytes — 生成一个伪随机字节串
  - openssl_seal — 密封 (加密) 数据
  - openssl_sign — Generate signature
  - openssl_spki_export — 通过签名公钥和 challenge 导出一个可用的 PEM 格式的公钥
  - openssl_spki_export_challenge — 导出与签名公钥和 challenge 相关的 challenge
  - openssl_spki_new — 生成新的签名公钥和 challenge
  - openssl_spki_verify — 验证签名公钥和 challenge
  - openssl_verify — 验证签名
  - openssl_x509_check_private_key — 检查私钥是否对应于证书
  - openssl_x509_checkpurpose — 验证是否可以为特定目的使用证书
  - openssl_x509_export — 以字符串格式导出证书
  - openssl_x509_export_to_file — 导出证书至文件
  - openssl_x509_fingerprint — 计算一个给定的 x.509 证书的指纹或摘要
  - openssl_x509_free — 释放证书资源
  - openssl_x509_parse — 解析 X509 证书并作为一个数组返回信息
  - openssl_x509_read — 解析 x.509 证书并返回对象
  - openssl_x509_verify — Verifies digital signature of x509 certificate against a public key
- OpenSSLCertificate — OpenSSLCertificate 类
- OpenSSLCertificateSigningRequest — OpenSSLCertificateSigningRequest 类
- OpenSSLAsymmetricKey — OpenSSLAsymmetricKey 类

# 密码散列算法

# 简介

密码散列算法 API 提供了 crypt() 等密码算法的简单易用包装， 以一种简洁易用安全的方式创建和管理密码。

# 安装/配置

## 目录

- 需求
- 安装

## 需求

构建此扩展不需要其他扩展。

为了支持 Argon2 密码散列，需要安装 » libargon2 库， 或者从 PHP 8.4.0 开始，安装 OpenSSL 3.2 或更高版本。 作为 PHP 7.3.0 的要求，如果使用 libargon2，则需要 libargon2 版本 20161029 或更高版本。

## 安装

使用这些函数不需要安装，它们是 PHP 核心的一部分。

然而，要启用 Argon2 密码散列，PHP 必须使用 --with-password-argon2 配置选项来支持 libargon2，或者从 PHP 8.4.0 开始，使用 OpenSSL 和 --with-openssl 和 --with-openssl-argon2 进行构建。

在 PHP 8.1.0 之前，可以使用 --with-password-argon2[=DIR] 指定 argon2 目录。

# 预定义常量

下列常量作为 PHP 核心的一部分总是可用的。

`PASSWORD_BCRYPT` (string)

  `PASSWORD_BCRYPT` is used to create new password hashes using the `CRYPT_BLOWFISH` algorithm.

  This will always result in a hash using the "$2y$" crypt format, which is always 60 characters wide.

  Supported Options:

  - `salt` (string) - to manually provide a salt to use when hashing the password. Note that this will override and prevent a salt from being automatically generated.

    If omitted, a random salt will be generated by password_hash() for each password hashed. This is the intended mode of operation and as of PHP 7.0.0 the salt option has been deprecated.

  - `cost` (int) - which denotes the algorithmic cost that should be used. Examples of these values can be found on the crypt() page.

    If omitted, a default value of `12` will be used. This is a good baseline cost, but you may want to consider increasing it depending on your hardware.

`PASSWORD_BCRYPT_DEFAULT_COST` (int)

`PASSWORD_ARGON2I` (string)

  `PASSWORD_ARGON2I` is used to create new password hashes using the Argon2i algorithm.

  Supported Options:

  - `memory_cost` (int) - Maximum memory (in kibibytes) that may be used to compute the Argon2 hash. Defaults to `PASSWORD_ARGON2_DEFAULT_MEMORY_COST`.

  - `time_cost` (int) - Maximum amount of time it may take to compute the Argon2 hash. Defaults to `PASSWORD_ARGON2_DEFAULT_TIME_COST`.

  - `threads` (int) - Number of threads to use for computing the Argon2 hash. Defaults to `PASSWORD_ARGON2_DEFAULT_THREADS`. Only available with libargon2, not with libsodium implementation.

  Available as of PHP 7.2.0.

`PASSWORD_ARGON2ID` (string)

  `PASSWORD_ARGON2ID` is used to create new password hashes using the Argon2id algorithm. It supports the same options as `PASSWORD_ARGON2I`.

  Available as of PHP 7.3.0.

`PASSWORD_ARGON2_DEFAULT_MEMORY_COST` (int)

  Default amount of memory in bytes that will be used while trying to compute a hash.

  Available as of PHP 7.2.0.

`PASSWORD_ARGON2_DEFAULT_TIME_COST` (int)

  Default amount of time that will be spent trying to compute a hash.

  Available as of PHP 7.2.0.

`PASSWORD_ARGON2_DEFAULT_THREADS` (int)

  Default number of threads that Argon2lib will use. Not available with libsodium implementation.

  Available as of PHP 7.2.0.

`PASSWORD_ARGON2_PROVIDER` (string)

  Available as of PHP 7.4.0.

`PASSWORD_DEFAULT` (string)

  The default algorithm to use for hashing if no algorithm is provided. This may change in newer PHP releases when newer, stronger hashing algorithms are supported.

  It is worth noting that over time this constant can change. It is thus important to be aware that the length of the resulting hash can change. Therefore, when using `PASSWORD_DEFAULT` the resulting hash must be stored in a way that can store arbitrary hashes, the recommended width is `255` bytes.

  Currently is an alias for `PASSWORD_BCRYPT`.

##### 更新日志

版本 | 说明
--- | ---
7.4.0 | The values of the password algo IDs (`PASSWORD_BCRYPT`, `PASSWORD_ARGON2I`, `PASSWORD_ARGON2ID` and `PASSWORD_DEFAULT`) are now strings. Previously, they have been ints.

# 密码散列算法函数

# password_algos

(PHP 7 >= 7.4.0, PHP 8)

password_algos — Get available password hashing algorithm IDs

### 说明

function password_algos(): array

Returns a complete list of all registered password hashing algorithm IDs as an array of strings.

### 参数

此函数没有参数。

### 返回值

Returns the available password hashing algorithm IDs.

### 示例

示例 #1 Basic password_algos() usage

    <?php
    print_r(password_algos());
    ?>

以上示例的输出类似于：

    Array
    (
        [0] => 2y
        [1] => argon2i
        [2] => argon2id
    )

# password_get_info

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_get_info — 返回指定散列（hash）的相关信息

### 说明

function password_get_info(string `$hash`): array

如果传入的散列值（hash）是由 password_hash() 支持的算法生成的， 这个函数就会返回关于此散列的信息数组。

### 参数

`hash`

  一个由 password_hash() 创建的散列值。

### 返回值

返回三个元素的关联数组：

- `algo`， 匹配 密码算法的常量
- `algoName`，人类可读的算法名称
- `options`，调用 password_hash() 时提供的选项。

# password_hash

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_hash — 创建密码的散列（hash）

### 说明

function password_hash(#[\SensitiveParameter] string `$password`, string|int|null `$algo`, array `$options` = []): string

password_hash() 使用足够强度的单向散列算法创建密码的散列（hash）。

当前支持的算法：

- `PASSWORD_DEFAULT` - 使用 bcrypt 算法 (PHP 5.5.0 默认)。 注意，该常量会随着 PHP 加入更新更高强度的算法而改变。 所以，使用此常量生成结果的长度将在未来有变化。 因此，数据库里储存结果的列可超过60个字节（最好是255个字节）。
- `PASSWORD_BCRYPT` - 使用 bcrypt 算法创建散列。 这将使用 `$2y$` 标识生成标准的 crypt() 兼容散列。
- `PASSWORD_ARGON2I` - 使用 Argon2i 散列算法创建散列。 只有在 PHP 编译时加入 Argon2 支持时才能使用该算法。
- `PASSWORD_ARGON2ID` - 使用 Argon2id 散列算法创建散列。 只有在 PHP 编译时加入 Argon2 支持时才能使用该算法。

`PASSWORD_BCRYPT` 支持的选项：

- `salt`(string) - 手动提供散列密码的盐值（salt）。这将避免自动生成盐值（salt）。

  省略此值后，password_hash() 会为每个密码散列自动生成随机的盐值。这种操作是有意的模式。

  警告

  盐值（salt）选项已废弃（deprecated）。 现在最好仅选择使用默认产生的盐值。 从 PHP 8.0.0 起，明确指定的 salt 值会被忽略。

- `cost` (int) - 代表算法使用的 cost。crypt() 页面上有 cost 值的示例。

  省略时，默认值是 `12`。 这个 cost 是个不错的底线，但应根据使用的硬件进行调整。

`PASSWORD_ARGON2I` 和 `PASSWORD_ARGON2ID` 支持的选项：

- `memory_cost` (int) - 计算 Argon2 散列时的最大内存（单位：KB）。默认值： `PASSWORD_ARGON2_DEFAULT_MEMORY_COST`。

- `time_cost` (int) - 计算 Argon2 散列时最多的时间。默认值： `PASSWORD_ARGON2_DEFAULT_TIME_COST`。

- `threads` (int) - 计算 Argon2 散列时最多的线程数。默认值： `PASSWORD_ARGON2_DEFAULT_THREADS`。

  警告

  只有在 PHP 使用 libargon2 时可用；如果是 libsodium 的实现，则无法使用。

### 参数

`password`

  用户的密码。

  警告

  使用 `PASSWORD_BCRYPT` 做算法，将使 `password` 参数最长为72个字节，超过会被截断。

`algo`

  一个用来在散列密码时指示算法的密码算法常量。

`options`

  一个包含有选项的关联数组。详细的参数说明，请参考文档 密码算法常数。

### 返回值

返回散列后的密码。

使用的算法、cost 和盐值作为散列的一部分返回。所以验证散列值的所有信息都已经包含在内。 这使 password_verify() 函数验证的时候，不需要额外储存盐值或者算法的信息。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `PASSWORD_BCRYPT` 算法的 `cost` 选项的默认值从 `10` 增加到 `12`。
8.3.0 | 当由于盐值生成失败而抛出 ValueError 时， password_hash() 现在会将底层的 Random\RandomException 作为 Exception::$previous 异常。
8.0.0 | 失败时 password_hash() 不再返回 `false`，如果密码散列算法无效，则会抛出 ValueError，如果密码散列因未知错误失败，则会抛出 Error。
8.0.0 | 参数 `algo` 可以为 null。
7.4.0 | 现在 `algo` 参数可支持 string 类型，但为了向后兼容也支持 int 类型。
7.4.0 | 扩展 sodium 提供了 Argon2 密码的替代实现。
7.3.0 | 增加 `PASSWORD_ARGON2ID`，支持 Argon2id 密码算法。
7.2.0 | 增加 `PASSWORD_ARGON2I`，支持 Argon2i 密码算法。

### 示例

示例 #1 password_hash() 示例

    <?php
    echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);
    ?>

以上示例的输出类似于：

    $2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.

示例 #2 password_hash() 手动设置 cost 的示例

    <?php
    $options = [
        // Increase the bcrypt cost from 12 to 13.
        'cost' => 13,
    ];
    echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);
    ?>

以上示例的输出类似于：

    $2y$13$xeDfQumlmdm0Sco.4qmH1OGfUUmOcuRmfae0dPJhjX1Bq0yYhqbNi

示例 #3 寻找最佳 cost 的 password_hash() 示例

该代码将会基准测试机器，来确定可以使用多高的 cost 而不会影响用户体验。 建议设置最高的 cost，前提是不会减慢机器需要执行的其他操作。 11 是一个不错的基线，如果机器足够快，更多的 cost 更好。 下面的代码目标是 ≤ 350 毫秒的拉伸时间（stretching time），这是处理交互式登录的系统的适当延迟。

    <?php
    $timeTarget = 0.350; // 350 毫秒（milliseconds）

    $cost = 11;
    do {
        $cost++;
        $start = microtime(true);
        password_hash("test", PASSWORD_BCRYPT, ["cost" => $cost]);
        $end = microtime(true);
    } while (($end - $start) < $timeTarget);

    echo "Appropriate Cost Found: " . $cost - 1;
    ?>

以上示例的输出类似于：

    Appropriate Cost Found: 13

示例 #4 使用 Argon2i 的 password_hash() 示例

    <?php
    echo 'Argon2i hash: ' . password_hash('rasmuslerdorf', PASSWORD_ARGON2I);
    ?>

以上示例的输出类似于：

    Argon2i hash: $argon2i$v=19$m=1024,t=2,p=2$YzJBSzV4TUhkMzc3d3laeg$zqU/1IN0/AogfP4cmSJI1vc8lpXRW9/S0sYY2i2jHT0

### 注释

警告

强烈建议不要为此函数提供显式的盐值（salt）。 如果没有指定盐值（salt），将自动创建一个安全的盐值（salt）。

提供 `salt` 选项在 PHP 7.0.0 中会生成一个弃用（deprecated）警告。 在 PHP 8.0.0 中，显式提供盐值（salt）的支持已被删除。

> 注意:

> 建议在使用的机器上测试此函数，调整 cost 参数，使得函数执行时间小于 350 毫秒，适合交互式登录。 上面示例中的脚本将帮助选择适合给定机器的 bcrypt cost。

> 注意: 这个函数更新支持的算法时（或修改默认算法），必定会遵守以下规则：

> - 任何内核中的新算法必须在经历一次 PHP 完整发行才能成为默认算法。 比如，在 PHP 7.5.5 中添加的新算法，在 PHP 7.7 之前不能成为默认算法 （由于 7.6 是第一个完整发行版）。 但如果是在 7.6.0 里添加的不同算法，在 7.7.0 里也可以成为默认算法。
> - 仅仅允许在完整发行版中修改默认算法（比如 7.3.0, 8.0.0，等等），不能是在修订版。 唯一的例外是：在当前默认算法里发现了紧急的安全威胁。

### 参见

- password_verify() - 验证密码是否和散列值匹配
- password_needs_rehash() - 检测散列值是否匹配指定的选项
- crypt() - 单向字符串散列
- sodium_crypto_pwhash_str() - Get an ASCII-encoded hash

# password_needs_rehash

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_needs_rehash — 检测散列值是否匹配指定的选项

### 说明

function password_needs_rehash(string `$hash`, string|int|null `$algo`, array `$options` = []): bool

此函数检测指定的散列值是否实现了提供的算法和选项。 如果没有，需要重新生成散列值。

### 参数

`hash`

  一个由 password_hash() 创建的散列值。

`algo`

  一个用来在散列密码时指示算法的密码算法常量。

`options`

  一个包含有选项的关联数组。详细的参数说明，请参考文档 密码算法常数。

### 返回值

如果散列需要重新生成才能匹配指定的 `algo` 和 `options`， 则返回 `true`，否则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
7.4.0 | 现在 `algo` 参数可以支持 string 类型，但为了向后兼容性，同时支持 int 类型。

### 示例

示例 #1 password_needs_rehash()用法

    <?php

    $password = 'rasmuslerdorf';
    $hash = '$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.';

    $algorithm = PASSWORD_BCRYPT;
    // bcrypt 的成本参数随着硬件的改进而可能发生变化
    $options = ['cost' => 13];

    // 根据明文密码验证储存的散列
    if (password_verify($password, $hash)) {
        // 检查算法或选项是否已经更改
        if (password_needs_rehash($hash, $algorithm, $options)) {
            // 如果是这样，则创建新散列，替换旧散列
            $newHash = password_hash($password, $algorithm, $options);

            // 使用 $newHash 更新用户记录
        }

        // 执行登录
    }
    ?>

# password_verify

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_verify — 验证密码是否和散列值匹配

### 说明

function password_verify(#[\SensitiveParameter] string `$password`, string `$hash`): bool

验证密码是否和指定的散列值匹配。password_verify() 与 crypt() 兼容。因此，由 crypt() 创建的密码散列可以用于 password_verify() 一起使用。

注意 password_hash() 返回的散列包含了算法、 cost 和盐值。 因此，所有需要的信息都包含内。使得验证函数不需要储存额外盐值等信息即可验证散列。

时序攻击（timing attacks）对此函数不起作用。

### 参数

`password`

  用户的密码。

`hash`

  一个由 password_hash() 创建的散列值。

### 返回值

如果密码和散列值匹配则返回 `true`，否则返回 `false`。

### 示例

示例 #1 password_verify() 示例

这只是简单的示例，如果需要，建议重新生成正确的密码；请参见 password_needs_rehash() 示例。

    <?php
    // 想知道以下字符从哪里来，可参见 password_hash() 示例
    $hash = '$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.';

    if (password_verify('rasmuslerdorf', $hash)) {
        echo 'Password is valid!';
    } else {
        echo 'Invalid password.';
    }
    ?>

以上示例会输出：

    Password is valid!

### 参见

- password_needs_rehash() - 检测散列值是否匹配指定的选项
- password_hash() - 创建密码的散列（hash）
- sodium_crypto_pwhash_str_verify() - Verifies that a password matches a hash

## 目录

- password_algos — Get available password hashing algorithm IDs
- password_get_info — 返回指定散列（hash）的相关信息
- password_hash — 创建密码的散列（hash）
- password_needs_rehash — 检测散列值是否匹配指定的选项
- password_verify — 验证密码是否和散列值匹配

- 安装/配置
  - 需求
  - 安装
- 预定义常量
- 密码散列算法函数
  - password_algos — Get available password hashing algorithm IDs
  - password_get_info — 返回指定散列（hash）的相关信息
  - password_hash — 创建密码的散列（hash）
  - password_needs_rehash — 检测散列值是否匹配指定的选项
  - password_verify — 验证密码是否和散列值匹配

# Rnp

# 简介

警告

此扩展是实验性的。 此扩展的行为，包括其函数的名称和围绕此扩展的相关文档都可能会在未来的 PHP 版本中发生变化而不另行通知。使用本扩展应自行承担风险。

This module allows you to use » RNP library. RNP is a high performance C++ OpenPGP library used by Mozilla Thunderbird.

# 安装/配置

## 目录

- 需求
- 安装

## 需求

In order to use RNP library functions you need to install the» RNP library. RNP library version >= 0.16.2 is required.

## 安装

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/rnp

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`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.

# 示例

## 目录

- Clearsign text

## Clearsign text

This example will clearsign a given text.

示例 #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 函数

# rnp_backend_string

(PECL rnp >= 0.1.1)

rnp_backend_string — Return cryptographic backend library name

### 说明

function rnp_backend_string(): string

### 参数

此函数没有参数。

### 返回值

Backend name string. Currently supported backends are "Botan" and "OpenSSL".

# rnp_backend_version

(PECL rnp >= 0.1.1)

rnp_backend_version — Return cryptographic backend library version

### 说明

function rnp_backend_version(): string

### 参数

此函数没有参数。

### 返回值

Version string.

# rnp_decrypt

(PECL rnp >= 0.1.1)

rnp_decrypt — Decrypt PGP message

### 说明

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().

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`input`
  Encrypted message.

### 返回值

Decrypted message on success 或者在失败时返回 `false`.

# rnp_dump_packets

(PECL rnp >= 0.1.1)

rnp_dump_packets — Dump OpenPGP packets stream information in humand-readable format

### 说明

function rnp_dump_packets(string `$input`, int `$flags`): string|false

### 参数

`input`
  Input string containing OpenPGP data, either in binary or ASCII-armored format.
`flags`
  See `RNP_DUMP_*` predefined constants.

### 返回值

Text describing packet sequence 或者在失败时返回 `false`.

# rnp_dump_packets_to_json

(PECL rnp >= 0.1.1)

rnp_dump_packets_to_json — Dump OpenPGP packets stream information to the JSON string

### 说明

function rnp_dump_packets_to_json(string `$input`, int `$flags`): string|false

### 参数

`input`
  Input string containing OpenPGP data, either in binary or ASCII-armored format.
`flags`
  See `RNP_JSON_DUMP_*` predefined constants.

### 返回值

JSON string with dump 或者在失败时返回 `false`.

# rnp_ffi_create

(PECL rnp >= 0.1.1)

rnp_ffi_create — Create the top-level object used for interacting with the library

### 说明

function rnp_ffi_create(string `$pub_format`, string `$sec_format`): RnpFFI|false

### 参数

`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

### 返回值

Returns RnpFFI object on success 或者在失败时返回 `false`.

# rnp_ffi_destroy

(PECL rnp >= 0.1.1)

rnp_ffi_destroy — Destroy the top-level object used for interacting with the library

### 说明

function rnp_ffi_destroy(RnpFFI `$ffi`): void

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().

### 返回值

# rnp_ffi_set_pass_provider

(PECL rnp >= 0.1.1)

rnp_ffi_set_pass_provider — Set password provider callback function

### 说明

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.

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`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 set 或者在失败时返回 `false`.

### 返回值

Returns `true` on success 或者在失败时返回 `false`.

### 示例

示例 #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

### 说明

function rnp_import_keys(RnpFFI `$ffi`, string `$input`, int `$flags`): string|false

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`input`
  OpenPGP packets containing key(s) to be loaded. Can be either binary or ASCII armored.
`flags`
  See `RNP_LOAD_SAVE_*` predefined constants.

### 返回值

JSON string with information about new and updated keys on success 或者在失败时返回 `false`.

# rnp_import_signatures

(PECL rnp >= 0.1.1)

rnp_import_signatures — Import standalone signatures to the keyring and receive JSON describing updated keys

### 说明

function rnp_import_signatures(RnpFFI `$ffi`, string `$input`, int `$flags`): string|false

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`input`
  OpenPGP packets containing signatures to be imported. Can be either binary or ASCII armored.
`flags`
  Currently must be 0.

### 返回值

JSON string with information about updated keys on success 或者在失败时返回 `false`.

# rnp_key_export

(PECL rnp >= 0.1.1)

rnp_key_export — Export a key

### 说明

function rnp_key_export(RnpFFI `$ffi`, string `$key_fp`, int `$flags`): string|false

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`key_fp`
  Key fingerprint.
`flags`
  See `RNP_KEY_EXPORT_*` predefined constants (except `RNP_KEY_EXPORT_BASE64`).

### 返回值

OpenPGP packets of exported key (binary or ASCII-armored) on success 或者在失败时返回 `false`.

# 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)

### 说明

function rnp_key_export_autocrypt(
RnpFFI `$ffi`,
string `$key_fp`,
string `$subkey_fp`,
string `$uid`,
int `$flags`
): string|false

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`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.

### 返回值

OpenPGP packets of exported key on success 或者在失败时返回 `false`.

# rnp_key_export_revocation

(PECL rnp >= 0.1.1)

rnp_key_export_revocation — Generate and export primary key revocation signature

### 说明

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.

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`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 | 说明
  --- | --- | ---
  `"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.

### 返回值

Exported revocation signature on success 或者在失败时返回 `false`.

# rnp_key_get_info

(PECL rnp >= 0.1.1)

rnp_key_get_info — Get information about the key

### 说明

function rnp_key_get_info(RnpFFI `$ffi`, string `$key_fp`): array|false

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`key_fp`
  Key fingerprint.

### 返回值

An associative array with information about the key 或者在失败时返回 `false`.

Key | Data type | 说明
--- | --- | ---
`"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)

### 说明

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.

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`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.

### 返回值

Returns `true` on success 或者在失败时返回 `false`.

# rnp_key_revoke

(PECL rnp >= 0.1.1)

rnp_key_revoke — Revoke a key or subkey by generating and adding revocation signature

### 说明

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.

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`key_fp`
  Key fingerprint.
`flags`
  Currently must be 0.
`options`
  An associative array with options.

  Key | Data type | 说明
  --- | --- | ---
  `"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.

### 返回值

Returns `true` on success 或者在失败时返回 `false`.

# rnp_list_keys

(PECL rnp >= 0.1.1)

rnp_list_keys — Enumerate all keys present in a keyring by specified identifer type

### 说明

function rnp_list_keys(RnpFFI `$ffi`, string `$identifier_type`): array|false

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`identifier_type`
  Key identifier type ("userid", "keyid", "grip", "fingerprint").

### 返回值

An associative array where key is an identifier string and value is a PGP key fingerprint 或者在失败时返回 `false`.

# rnp_load_keys

(PECL rnp >= 0.1.1)

rnp_load_keys — Load keys from PHP string

### 说明

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).

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`format`
  The key format of the data (GPG, KBX, G10).
`input`
  OpenPGP packets containing key(s) to be loaded. Can be either binary or ASCII armored.
`flags`
  See `RNP_LOAD_SAVE_*` flags description.

### 返回值

Returns `true` on success 或者在失败时返回 `false`.

# rnp_load_keys_from_path

(PECL rnp >= 0.1.1)

rnp_load_keys_from_path — Load keys from specified path

### 说明

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).

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`format`
  The key format of the data (GPG, KBX, G10).
`input_path`
  file or directory containing the keys.
`flags`
  See `RNP_LOAD_SAVE_*` flags description.

### 返回值

Returns `true` on success 或者在失败时返回 `false`.

# rnp_locate_key

(PECL rnp >= 0.1.1)

rnp_locate_key — Search for the key

### 说明

function rnp_locate_key(RnpFFI `$ffi`, string `$identifier_type`, string `$identifier`): string|false

Note: only valid userids are checked while searching by userid.

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`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.

### 返回值

Returns hexadecimal fingerprint of the key found on success 或者在失败时返回 `false`.

# rnp_op_encrypt

(PECL rnp >= 0.1.1)

rnp_op_encrypt — Encrypt message

### 说明

function rnp_op_encrypt(
RnpFFI `$ffi`,
string `$message`,
array `$recipient_keys_fp`,
array `$options` = ?
): string|false

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`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 | 说明
  --- | --- | ---
  `"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.

### 返回值

Encrypted data on success 或者在失败时返回 `false`.

# rnp_op_generate_key

(PECL rnp >= 0.1.1)

rnp_op_generate_key — Generate key

### 说明

function rnp_op_generate_key(
RnpFFI `$ffi`,
string `$userid`,
string `$key_alg`,
string `$sub_alg` = ?,
array `$options` = ?
): string|false

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`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 | 说明
  --- | --- | ---
  `"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.

### 返回值

Fingerprint of the generated primary key 或者在失败时返回 `false`. 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)

### 说明

function rnp_op_sign(
RnpFFI `$ffi`,
string `$data`,
array `$keys_fp`,
array `$options` = ?
): string|false

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`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 | 说明
  --- | --- | ---
  `"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.

### 返回值

Data with embedded signature(s) on success 或者在失败时返回 `false`.

# rnp_op_sign_cleartext

(PECL rnp >= 0.1.1)

rnp_op_sign_cleartext — Perform signing operation on a textual data, return cleartext signed message

### 说明

function rnp_op_sign_cleartext(
RnpFFI `$ffi`,
string `$data`,
array `$keys_fp`,
array `$options` = ?
): string|false

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`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 | 说明
  --- | --- | ---
  `"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).

### 返回值

Cleartext signed message containing source data with additional headers and ASCII-armored signature on success 或者在失败时返回 `false`.

# rnp_op_sign_detached

(PECL rnp >= 0.1.1)

rnp_op_sign_detached — Perform signing operation, return detached signature(s)

### 说明

function rnp_op_sign_detached(
RnpFFI `$ffi`,
string `$data`,
array `$keys_fp`,
array `$options` = ?
): string|false

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`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 | 说明
  --- | --- | ---
  `"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).

### 返回值

Detached signature(s) data on success 或者在失败时返回 `false`.

# rnp_op_verify

(PECL rnp >= 0.1.1)

rnp_op_verify — Verify embedded or cleartext signatures

### 说明

function rnp_op_verify(RnpFFI `$ffi`, string `$data`): array|false

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`data`
  Signed data.

### 返回值

An associative array with information about verification results 或者在失败时返回 `false`.

Key | Data type | 说明
--- | --- | ---
`"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 | 说明
--- | --- | ---
"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

### 说明

function rnp_op_verify_detached(RnpFFI `$ffi`, string `$data`, string `$signature`): array|false

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`data`
  Source data.
`signature`
  Detached signature data.

### 返回值

An associative array with information about verification results 或者在失败时返回 `false`.

Key | Data type | 说明
--- | --- | ---
`"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 | 说明
--- | --- | ---
"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

### 说明

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).

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`format`
  The key format of the data (GPG, KBX, G10).
`output`
  key packets will be saved to the string referenced by `output`.
`flags`
  See `RNP_LOAD_SAVE_*` flags description.

### 返回值

Returns `true` on success 或者在失败时返回 `false`.

# rnp_save_keys_to_path

(PECL rnp >= 0.1.1)

rnp_save_keys_to_path — Save keys to specified path

### 说明

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.

### 参数

`ffi`
  The FFI object returned by rnp_ffi_create().
`format`
  The key format of the data (GPG, KBX, G10).
`output_path`
  File or directory path where keys should be saved to.
`flags`
  See `RNP_LOAD_SAVE_*` flags description.

### 返回值

Returns `true` on success 或者在失败时返回 `false`.

# rnp_supported_features

(PECL rnp >= 0.1.1)

rnp_supported_features — Get supported features in JSON format

### 说明

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.

### 参数

`type`
  See RNP_FEATURE_* constants for supported values.

### 返回值

String containing JSON formatted array of supported algorithms, curves, etc 或者在失败时返回 `false`.

# rnp_version_string

(PECL rnp >= 0.1.1)

rnp_version_string — RNP library version

### 说明

function rnp_version_string(): string

### 参数

此函数没有参数。

### 返回值

Returns RNP library version string.

# rnp_version_string_full

(PECL rnp >= 0.1.1)

rnp_version_string_full — Full version string of RNP library

### 说明

function rnp_version_string_full(): string

### 参数

此函数没有参数。

### 返回值

Returns full version string of RNP library.

## 目录

- rnp_backend_string — Return cryptographic backend library name
- rnp_backend_version — Return cryptographic backend library version
- 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 — RNP library version
- rnp_version_string_full — Full version string of RNP library

# The RnpFFI class

(PECL rnp >= 0.1.1)

## 简介

## 类摘要

class RnpFFI {
}

- 安装/配置
  - 需求
  - 安装
- 预定义常量
- 示例
  - Clearsign text
- Rnp 函数
  - rnp_backend_string — Return cryptographic backend library name
  - rnp_backend_version — Return cryptographic backend library version
  - 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 — RNP library version
  - rnp_version_string_full — Full version string of RNP library
- RnpFFI — The RnpFFI class

# Sodium

# 简介

Sodium is a modern, easy-to-use software library for encryption, decryption, signatures, password hashing and more. Its goal is to provide all of the core operations needed to build higher-level cryptographic tools.

# 安装/配置

## 目录

- 需求
- 安装

## 需求

This extension requires » libsodium ≥ 1.0.8.

## 安装

As of PHP 7.2.0 this extension is bundled with PHP. For older PHP versions this extension is available via PECL.

## Linux Systems

In order to use this extension you must compile PHP with sodium support by using the --with-sodium[=DIR] configure option.

## Windows

In order to use this extension you have to add `extension=php_sodium.dll` to php.ini.

## Installation via PECL

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/libsodium

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`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)
  Available as of PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS128L_NSECBYTES` (int)
  Available as of PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES` (int)
  Available as of PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS128L_ABYTES` (int)
  Available as of PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_KEYBYTES` (int)
  Available as of PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_NSECBYTES` (int)
  Available as of PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_NPUBBYTES` (int)
  Available as of PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_ABYTES` (int)
  Available as of 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)
  Available as of PHP 8.1.0.
`SODIUM_CRYPTO_CORE_RISTRETTO255_HASHBYTES` (int)
  Available as of PHP 8.1.0.
`SODIUM_CRYPTO_CORE_RISTRETTO255_NONREDUCEDSCALARBYTES` (int)
  Available as of PHP 8.1.0.
`SODIUM_CRYPTO_CORE_RISTRETTO255_SCALARBYTES` (int)
  Available as of PHP 8.1.0.
`SODIUM_CRYPTO_SCALARMULT_BYTES` (int)
`SODIUM_CRYPTO_SCALARMULT_SCALARBYTES` (int)
`SODIUM_CRYPTO_SCALARMULT_RISTRETTO255_BYTES` (int)
  Available as of PHP 8.1.0.
`SODIUM_CRYPTO_SCALARMULT_RISTRETTO255_SCALARBYTES` (int)
  Available as of 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)
  Available as of PHP 8.1.0.
`SODIUM_CRYPTO_STREAM_XCHACHA20_NONCEBYTES` (int)
  Available as of PHP 8.1.0.

# Sodium 函数

# sodium_add

(PHP 7 >= 7.2.0, PHP 8)

sodium_add — Add large numbers

### 说明

function sodium_add(string `&$string1`, string `$string2`): void

This adds the parameter `string2` to `string1`, overwriting the value stored in `string1`. This function assumes both parameters are binary strings that represent unsigned integers in little-endian byte order.

### 参数

`string1`
  String representing an arbitrary-length unsigned integer in little-endian byte order. This parameter is passed by reference and will hold the sum of the two parameters.
`string2`
  String representing an arbitrary-length unsigned integer in little-endian byte order.

### 返回值

没有返回值。

# sodium_base642bin

(PHP 7 >= 7.2.0, PHP 8)

sodium_base642bin — Decodes a base64-encoded string into raw binary.

### 说明

function sodium_base642bin(#[\SensitiveParameter] string `$string`, int `$id`, string `$ignore` = ""): string

Converts a base64 encoded string into raw binary. Unlike base64_decode(), sodium_base642bin() is constant-time (a property that is important for any code that touches cryptographic inputs, such as plaintexts or keys) and supports multiple character sets.

### 参数

`string`
  string; Encoded string.
`id`
  - `SODIUM_BASE64_VARIANT_ORIGINAL` for standard (`A-Za-z0-9/\+`) Base64 encoding.
  - `SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING` for standard (`A-Za-z0-9/\+`) Base64 encoding, without `=` padding characters.
  - `SODIUM_BASE64_VARIANT_URLSAFE` for URL-safe (`A-Za-z0-9\-_`) Base64 encoding.
  - `SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING` for URL-safe (`A-Za-z0-9\-_`) Base64 encoding, without `=` padding characters.
`ignore`
  Characters to ignore when decoding (e.g. whitespace characters).

### 返回值

Decoded string.

# sodium_bin2base64

(PHP 7 >= 7.2.0, PHP 8)

sodium_bin2base64 — Encodes a raw binary string with base64.

### 说明

function sodium_bin2base64(#[\SensitiveParameter] string `$string`, int `$id`): string

Converts a raw binary string into a base64-encoded string. Unlike base64_encode(), sodium_bin2base64() is constant-time (a property that is important for any code that touches cryptographic inputs, such as plaintexts or keys) and supports multiple character sets.

### 参数

`string`
  Raw binary string.
`id`
  - `SODIUM_BASE64_VARIANT_ORIGINAL` for standard (`A-Za-z0-9/\+`) Base64 encoding.
  - `SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING` for standard (`A-Za-z0-9/\+`) Base64 encoding, without `=` padding characters.
  - `SODIUM_BASE64_VARIANT_URLSAFE` for URL-safe (`A-Za-z0-9\-_`) Base64 encoding.
  - `SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING` for URL-safe (`A-Za-z0-9\-_`) Base64 encoding, without `=` padding characters.

### 返回值

Base64-encoded string.

# sodium_bin2hex

(PHP 7 >= 7.2.0, PHP 8)

sodium_bin2hex — Encode to hexadecimal

### 说明

function sodium_bin2hex(#[\SensitiveParameter] string `$string`): string

Converts a raw binary string into a hex-encoded string. Unlike the standard hex-encoding function, sodium_bin2hex() is constant-time (a property that is important for any code that touches cryptographic inputs, such as plaintexts or keys).

### 参数

`string`
  Raw binary string.

### 返回值

Hex encoded string.

# sodium_compare

(PHP 7 >= 7.2.0, PHP 8)

sodium_compare — Compare large numbers

### 说明

function sodium_compare(#[\SensitiveParameter] string `$string1`, #[\SensitiveParameter] string `$string2`): int

Compare two strings as if they were arbitrary-length, unsigned little-endian integers, without side-channel leakage.

### 参数

`string1`
  Left operand
`string2`
  Right operand

### 返回值

Returns `-1` if `string1` is less than `string2`.

Returns `1` if `string1` is greater than `string2`.

Returns `0` if both strings are equal.

# sodium_crypto_aead_aegis128l_decrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis128l_decrypt — Verify then decrypt a message with AEGIS-128L

### 说明

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.

### 参数

`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).

### 返回值

Returns the plaintext on success, 或者在失败时返回 `false`.

### 参见

- 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

### 说明

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.

### 参数

`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).

### 返回值

Returns the ciphertext and authentication tag as a string of raw binary bytes.

### 参见

- 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

### 说明

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().

### 参数

此函数没有参数。

### 返回值

Returns a 128-bit random key.

### 参见

- 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

### 说明

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.

### 参数

`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).

### 返回值

Returns the plaintext on success, 或者在失败时返回 `false`.

### 参见

- 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

### 说明

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.

### 参数

`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).

### 返回值

Returns the ciphertext and authentication tag as a string of raw binary bytes.

### 参见

- 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

### 说明

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().

### 参数

此函数没有参数。

### 返回值

Returns a 256-bit random 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_aes256gcm_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_decrypt — Verify then decrypt a message with AES-256-GCM

### 说明

function sodium_crypto_aead_aes256gcm_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter] string `$key`
): string|false

Verify then decrypt with AES-256-GCM. Only available if sodium_crypto_aead_aes256gcm_is_available() returns `true`.

### 参数

`ciphertext`
  Must be in the format provided by sodium_crypto_aead_aes256gcm_encrypt() (ciphertext and tag, concatenated).
`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. 12 bytes long.
`key`
  Encryption key (256-bit).

### 返回值

Returns the plaintext on success, 或者在失败时返回 `false`.

# sodium_crypto_aead_aes256gcm_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_encrypt — Encrypt then authenticate with AES-256-GCM

### 说明

function sodium_crypto_aead_aes256gcm_encrypt(
#[\SensitiveParameter] string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter] string `$key`
): string

Encrypt then authenticate with AES-256-GCM. Only available if sodium_crypto_aead_aes256gcm_is_available() returns `true`.

### 参数

`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. 12 bytes long.
`key`
  Encryption key (256-bit).

### 返回值

Returns the ciphertext and authentication tag as a string of raw binary bytes. (Format: ciphertext, then tag.)

# sodium_crypto_aead_aes256gcm_is_available

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_is_available — Check if hardware supports AES256-GCM

### 说明

function sodium_crypto_aead_aes256gcm_is_available(): bool

The return value of this function depends on whether or not the hardware supports hardware-accelerated AES.

### 参数

此函数没有参数。

### 返回值

Returns `true` if it is safe to encrypt with AES-256-GCM, and `false` otherwise.

# sodium_crypto_aead_aes256gcm_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_keygen — Generate a random AES-256-GCM key

### 说明

function sodium_crypto_aead_aes256gcm_keygen(): string

Generate a random key for use with sodium_crypto_aead_aes256gcm_encrypt() and sodium_crypto_aead_aes256gcm_decrypt().

### 参数

此函数没有参数。

### 返回值

Returns a 256-bit random key.

# sodium_crypto_aead_chacha20poly1305_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_decrypt — Verify then decrypt with ChaCha20-Poly1305

### 说明

function sodium_crypto_aead_chacha20poly1305_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter] string `$key`
): string|false

Verify then decrypt with ChaCha20-Poly1305.

### 参数

`ciphertext`
  Must be in the format provided by sodium_crypto_aead_chacha20poly1305_encrypt() (ciphertext and tag, concatenated).
`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. 8 bytes long.
`key`
  Encryption key (256-bit).

### 返回值

Returns the plaintext on success, 或者在失败时返回 `false`.

# sodium_crypto_aead_chacha20poly1305_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_encrypt — Encrypt then authenticate with ChaCha20-Poly1305

### 说明

function sodium_crypto_aead_chacha20poly1305_encrypt(
#[\SensitiveParameter] string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter] string `$key`
): string

Encrypt then authenticate with ChaCha20-Poly1305.

### 参数

`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. 8 bytes long.
`key`
  Encryption key (256-bit).

### 返回值

Returns the ciphertext and tag on success, 或者在失败时返回 `false`.

# sodium_crypto_aead_chacha20poly1305_ietf_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Verify that the ciphertext includes a valid tag

### 说明

function sodium_crypto_aead_chacha20poly1305_ietf_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter] string `$key`
): string|false

Verify then decrypt with ChaCha20-Poly1305 (IETF variant).

The IETF variant uses 96-bit nonces and 32-bit internal counters, instead of 64-bit for both.

### 参数

`ciphertext`
  Must be in the format provided by sodium_crypto_aead_chacha20poly1305_ietf_encrypt() (ciphertext and tag, concatenated).
`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. 12 bytes long.
`key`
  Encryption key (256-bit).

### 返回值

Returns the plaintext on success, 或者在失败时返回 `false`.

# sodium_crypto_aead_chacha20poly1305_ietf_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Encrypt a message

### 说明

function sodium_crypto_aead_chacha20poly1305_ietf_encrypt(
#[\SensitiveParameter] string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter] string `$key`
): string

Encrypt then authenticate with ChaCha20-Poly1305 (IETF variant).

The IETF variant uses 96-bit nonces and 32-bit internal counters, instead of 64-bit for both.

### 参数

`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. 12 bytes long.
`key`
  Encryption key (256-bit).

### 返回值

Returns the ciphertext and tag on success, 或者在失败时返回 `false`.

# sodium_crypto_aead_chacha20poly1305_ietf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_keygen — Generate a random ChaCha20-Poly1305 (IETF) key.

### 说明

function sodium_crypto_aead_chacha20poly1305_ietf_keygen(): string

Generate a random key for use with sodium_crypto_aead_chacha20poly1305_ietf_encrypt() and sodium_crypto_aead_chacha20poly1305_ietf_decrypt().

### 参数

此函数没有参数。

### 返回值

Returns a 256-bit random key.

# sodium_crypto_aead_chacha20poly1305_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_keygen — Generate a random ChaCha20-Poly1305 key.

### 说明

function sodium_crypto_aead_chacha20poly1305_keygen(): string

Generate a random key for use with sodium_crypto_aead_chacha20poly1305_encrypt() and sodium_crypto_aead_chacha20poly1305_decrypt().

### 参数

此函数没有参数。

### 返回值

Returns a 256-bit random key.

# sodium_crypto_aead_xchacha20poly1305_ietf_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — (Preferred) Verify then decrypt with XChaCha20-Poly1305

### 说明

function sodium_crypto_aead_xchacha20poly1305_ietf_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter] string `$key`
): string|false

Verify then decrypt with ChaCha20-Poly1305 (eXtended-nonce variant).

Generally, XChaCha20-Poly1305 is the best of the provided AEAD modes to use.

### 参数

`ciphertext`
  Must be in the format provided by sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() (ciphertext and tag, concatenated).
`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. 24 bytes long. This is a large enough bound to generate randomly (i.e. random_bytes()).
`key`
  Encryption key (256-bit).

### 返回值

Returns the plaintext on success, 或者在失败时返回 `false`.

# sodium_crypto_aead_xchacha20poly1305_ietf_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — (Preferred) Encrypt then authenticate with XChaCha20-Poly1305

### 说明

function sodium_crypto_aead_xchacha20poly1305_ietf_encrypt(
#[\SensitiveParameter] string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter] string `$key`
): string

Encrypt then authenticate with XChaCha20-Poly1305 (eXtended-nonce variant).

Generally, XChaCha20-Poly1305 is the best of the provided AEAD modes to use.

### 参数

`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. 24 bytes long. This is a large enough bound to generate randomly (i.e. random_bytes()).
`key`
  Encryption key (256-bit).

### 返回值

Returns the ciphertext and tag on success, 或者在失败时返回 `false`.

# sodium_crypto_aead_xchacha20poly1305_ietf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Generate a random XChaCha20-Poly1305 key.

### 说明

function sodium_crypto_aead_xchacha20poly1305_ietf_keygen(): string

Generate a random key for use with sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() and sodium_crypto_aead_xchacha20poly1305_ietf_decrypt().

### 参数

此函数没有参数。

### 返回值

Returns a 256-bit random key.

# sodium_crypto_auth

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth — Compute a tag for the message

### 说明

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.)

### 参数

`message`
  The message you intend to authenticate
`key`
  Authentication key

### 返回值

Authentication tag

# sodium_crypto_auth_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth_keygen — Generate a random key for sodium_crypto_auth

### 说明

function sodium_crypto_auth_keygen(): string

Generate a key for use with sodium_crypto_auth() and sodium_crypto_auth_verify().

### 参数

此函数没有参数。

### 返回值

Returns a 256-bit random key.

# sodium_crypto_auth_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth_verify — Verifies that the tag is valid for the message

### 说明

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.)

### 参数

`mac`
  Authentication tag produced by sodium_crypto_auth()
`message`
  Message
`key`
  Authentication key

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# sodium_crypto_box

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box — Authenticated public-key encryption

### 说明

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.

### 参数

`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.

### 返回值

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 — Randomly generate a secret key and a corresponding public key

### 说明

function sodium_crypto_box_keypair(): string

Generates a secret key and a public key as one string.

To get the secret key out of this unified keypair string, see sodium_crypto_box_secretkey(). To get the public key out of this unified keypair string, see sodium_crypto_box_publickey().

### 参数

此函数没有参数。

### 返回值

One string containing both the X25519 secret key and corresponding X25519 public key.

# 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

### 说明

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.

### 参数

`secret_key`
  Secret key.
`public_key`
  Public key.

### 返回值

X25519 Keypair.

# sodium_crypto_box_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_open — Authenticated public-key decryption

### 说明

function sodium_crypto_box_open(string `$ciphertext`, string `$nonce`, #[\SensitiveParameter] string `$key_pair`): string|false

Decrypt a message using asymmetric (public key) cryptography.

### 参数

`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.

### 返回值

Returns the plaintext message on success, 或者在失败时返回 `false`.

# sodium_crypto_box_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_publickey — Extract the public key from a crypto_box keypair

### 说明

function sodium_crypto_box_publickey(#[\SensitiveParameter] string `$key_pair`): string

Given a keypair, fetch only the public key.

### 参数

`key_pair`
  A keypair, such as one generated by sodium_crypto_box_keypair() or sodium_crypto_box_seed_keypair()

### 返回值

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

### 说明

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).

### 参数

`secret_key`
  X25519 secret key

### 返回值

X25519 public key.

# sodium_crypto_box_seal

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seal — Anonymous public-key encryption

### 说明

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.

### 参数

`message`
  The message to encrypt.
`public_key`
  The public key that corresponds to the only key that can decrypt the message.

### 返回值

A ciphertext string in the format of (one-time public key, encrypted message, authentication tag).

### 示例

示例 #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);
    ?>

以上示例的输出类似于：

    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

### 说明

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()

### 参数

`ciphertext`
  The encrypted message
`key_pair`
  The keypair of the recipient. Must include the secret key.

### 返回值

The plaintext on success, 或者在失败时返回 `false`.

### 示例

示例 #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);
    ?>

以上示例的输出类似于：

    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

### 说明

function sodium_crypto_box_secretkey(#[\SensitiveParameter] string `$key_pair`): string

Given a keypair, fetch only the secret key.

### 参数

`key_pair`
  A keypair, such as one generated by sodium_crypto_box_keypair() or sodium_crypto_box_seed_keypair()

### 返回值

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

### 说明

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.

### 参数

`seed`
  Some cryptographic input. Must be 32 bytes.

### 返回值

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

### 说明

function sodium_crypto_core_ristretto255_add(string `$p`, string `$q`): string

Adds an element `q` to `p`. Available as of libsodium 1.0.18.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`p`
  An element.
`q`
  An element.

### 返回值

Returns a 32-byte random string.

### 示例

示例 #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));
    ?>

以上示例会输出：

    bool(true)

### 参见

- 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

### 说明

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.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`s`
  A 64-bytes vector.

### 返回值

Returns a 32-byte random string.

### 示例

示例 #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)));
    ?>

以上示例会输出：

    string(64) "3066f82a1a747d45120d1740f14358531a8f04bbffe6a819f86dfe50f44a0a46"

### 参见

- sodium_hex2bin() - Decodes a hexadecimally encoded binary string
- sodium_bin2hex() - Encode to hexadecimal
- 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

### 说明

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.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`s`
  An Elliptic-curve point.

### 返回值

Returns `true` if `s` is on the ristretto255 curve, `false` otherwise.

### 示例

示例 #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));
    ?>

以上示例会输出：

    bool(true)

### 参见

- 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

### 说明

function sodium_crypto_core_ristretto255_random(): string

Generates a random key. Available as of libsodium 1.0.18.

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

Returns a 32-byte random string.

### 示例

示例 #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));
    ?>

以上示例会输出：

    bool(true)

### 参见

- 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

### 说明

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.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`x`
  Scalar, representing the X coordinate.
`y`
  Scalar, representing the Y coordinate.

### 返回值

Returns a 32-byte random string.

### 示例

示例 #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));
    ?>

以上示例会输出：

    bool(true)

### 参见

- 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

### 说明

function sodium_crypto_core_ristretto255_scalar_complement(string `$s`): string

Available as of libsodium 1.0.18.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`s`
  Scalar value.

### 返回值

Returns a 32-byte random string.

### 参见

- 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

### 说明

function sodium_crypto_core_ristretto255_scalar_invert(string `$s`): string

Inverts a scalar value. Available as of libsodium 1.0.18.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`s`
  Scalar value.

### 返回值

Returns a 32-byte random string.

### 示例

示例 #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));
    ?>

以上示例会输出：

    bool(true)

### 参见

- 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

### 说明

function sodium_crypto_core_ristretto255_scalar_mul(string `$x`, string `$y`): string

Multiplies a scalar value. Available as of libsodium 1.0.18.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`x`
  Scalar, representing the X coordinate.
`y`
  Scalar, representing the Y coordinate.

### 返回值

Returns a 32-byte random string.

### 参见

- 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

### 说明

function sodium_crypto_core_ristretto255_scalar_negate(string `$s`): string

Negates a scalar value. Available as of libsodium 1.0.18.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`s`
  Scalar value.

### 返回值

Returns a 32-byte random string.

### 示例

示例 #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));
    ?>

以上示例会输出：

    bool(true)

### 参见

- 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

### 说明

function sodium_crypto_core_ristretto255_scalar_random(): string

Generates a random key. Available as of libsodium 1.0.18.

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

Returns a 32-byte random string.

### 示例

示例 #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));
    ?>

以上示例会输出：

    bool(true)

### 参见

- 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

### 说明

function sodium_crypto_core_ristretto255_scalar_reduce(string `$s`): string

Reduces a scalar value. Available as of libsodium 1.0.18.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`s`
  Scalar value.

### 返回值

Returns a 32-byte random string.

### 参见

- 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

### 说明

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.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`x`
  Scalar, representing the X coordinate.
`y`
  Scalar, representing the Y coordinate.

### 返回值

Returns a 32-byte random string.

### 示例

示例 #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));
    ?>

以上示例会输出：

    bool(true)

### 参见

- 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

### 说明

function sodium_crypto_core_ristretto255_sub(string `$p`, string `$q`): string

Subtracts an element `q` from `p`. Available as of libsodium 1.0.18.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`p`
  An element.
`q`
  An element.

### 返回值

Returns a 32-byte random string.

### 示例

示例 #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));
    ?>

以上示例会输出：

    bool(true)

### 参见

- 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

### 说明

function sodium_crypto_generichash(string `$message`, #[\SensitiveParameter] string `$key` = "", int `$length` = `SODIUM_CRYPTO_GENERICHASH_BYTES`): string

Hash a message with BLAKE2b.

### 参数

`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.

### 返回值

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

### 说明

function sodium_crypto_generichash_final(string `&$state`, int `$length` = `SODIUM_CRYPTO_GENERICHASH_BYTES`): string

The finalization method for the streaming generichash API.

### 参数

`state`
  Hash state returned from sodium_crypto_generichash_init()
`length`
  Output length.

### 返回值

Cryptographic hash.

### 示例

示例 #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));
    ?>

以上示例的输出类似于：

    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

### 说明

function sodium_crypto_generichash_init(#[\SensitiveParameter] string `$key` = "", int `$length` = `SODIUM_CRYPTO_GENERICHASH_BYTES`): string

The initialization method for the streaming generichash API.

### 参数

`key`
  The generichash key.
`length`
  The expected output length of the hash function.

### 返回值

Returns a hash state, serialized as a raw binary string.

### 示例

示例 #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));
    ?>

以上示例的输出类似于：

    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"
    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"

# sodium_crypto_generichash_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_keygen — Generate a random generichash key

### 说明

function sodium_crypto_generichash_keygen(): string

Generate a random key for use with the generichash API.

### 参数

此函数没有参数。

### 返回值

A random 256-bit key.

# sodium_crypto_generichash_update

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_update — Add message to a hash

### 说明

function sodium_crypto_generichash_update(string `&$state`, string `$message`): true

Appends a message to the internal hash state.

### 参数

`state`
  The return value of sodium_crypto_generichash_init().
`message`
  Data to append to the hashing state.

### 返回值

总是返回 `true`。

### 示例

示例 #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));
    ?>

以上示例的输出类似于：

    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

### 说明

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().

### 参数

`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.

### 返回值

A string of pseudorandom (raw binary) bytes.

# sodium_crypto_kdf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kdf_keygen — Generate a random root key for the KDF interface

### 说明

function sodium_crypto_kdf_keygen(): string

Generates a random key suitable for serving as the root key for sodium_crypto_kdf_derive_from_key().

### 参数

此函数没有参数。

### 返回值

A random 256-bit key.

# 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.

### 说明

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.

### 参数

`client_key_pair`
  A crypto_kx keypair, such as one generated by sodium_crypto_kx_keypair().
`server_key`
  A crypto_kx public key.

### 返回值

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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the new keypair on success; throws an exception otherwise.

### 示例

示例 #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));
    ?>

以上示例的输出类似于：

    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

### 说明

function sodium_crypto_kx_publickey(#[\SensitiveParameter] string `$key_pair`): string

Extract the public key from a crypto_kx keypair.

### 参数

`key_pair`
  X25519 keypair, such as one generated by sodium_crypto_kx_keypair().

### 返回值

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.

### 说明

function sodium_crypto_kx_secretkey(#[\SensitiveParameter] string `$key_pair`): string

Extract the secret key from a crypto_kx keypair.

### 参数

`key_pair`
  X25519 keypair, such as one generated by sodium_crypto_kx_keypair().

### 返回值

X25519 secret key.

# sodium_crypto_kx_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_seed_keypair — Description

### 说明

function sodium_crypto_kx_seed_keypair(#[\SensitiveParameter] string `$seed`): string

警告

本函数还未编写文档，仅有参数列表。

### 参数

`seed`

### 返回值

# 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.

### 说明

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.

### 参数

`server_key_pair`
  A crypto_kx keypair, such as one generated by sodium_crypto_kx_keypair().
`client_key`
  A crypto_kx public key.

### 返回值

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

### 说明

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()).

### 参数

`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.

### 返回值

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.

### 示例

示例 #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
        )
    );
    ?>

以上示例的输出类似于：

    a18f346ba57992eb7e4ae6abf3fd30ee

# sodium_crypto_pwhash_scryptsalsa208sha256

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256 — Derives a key from a password, using scrypt

### 说明

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()).

### 参数

`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.

### 返回值

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

### 说明

function sodium_crypto_pwhash_scryptsalsa208sha256_str(#[\SensitiveParameter] string `$password`, int `$opslimit`, int `$memlimit`): string

警告

本函数还未编写文档，仅有参数列表。

### 参数

`password`
`opslimit`
`memlimit`

### 返回值

# 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

### 说明

function sodium_crypto_pwhash_scryptsalsa208sha256_str_verify(string `$hash`, #[\SensitiveParameter] string `$password`): bool

警告

本函数还未编写文档，仅有参数列表。

### 参数

`hash`
`password`

### 返回值

# sodium_crypto_pwhash_str

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str — Get an ASCII-encoded hash

### 说明

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.

### 参数

`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.

### 返回值

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.

### 示例

示例 #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
    );

以上示例的输出类似于：

    $argon2id$v=19$m=65536,t=2,p=1$oWIfdaXwWwhVmovOBc2NAQ$EbsZ+JnZyyavkafS0hoc4HdaOB0ILWZESAZ7kVGa+Iw

### 注释

> 注意: 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.

### 参见

- 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() - 创建密码的散列（hash）
- password_verify() - 验证密码是否和散列值匹配
- » 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

### 说明

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`.

### 参数

`password`
  Password hash
`opslimit`
  Configured opslimit; see sodium_crypto_pwhash_str()
`memlimit`
  Configured memlimit; see sodium_crypto_pwhash_str()

### 返回值

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

### 说明

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.

### 参数

`hash`
  一个由 password_hash() 创建的散列值。
`password`
  用户的密码。

### 返回值

Returns `true` if the password and hash match, or `false` otherwise.

### 注释

> 注意: Hashes are calculated using the Argon2ID algorithm, providing resistance to both GPU and side-channel attacks.

### 参见

- sodium_crypto_pwhash_str() - Get an ASCII-encoded hash
- password_hash() - 创建密码的散列（hash）
- password_verify() - 验证密码是否和散列值匹配

# 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

### 说明

function sodium_crypto_scalarmult(string `$n`, string `$p`): string

Elliptic Curve Diffie-Hellman. Calculates scalar n times point p, on an elliptic curve.

### 参数

`n`
  scalar, which is typically a secret key
`p`
  point (x-coordinate), which is typically a public key

### 返回值

A 32-byte random string.

# sodium_crypto_scalarmult_base

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_scalarmult_base — 别名 sodium_crypto_box_publickey_from_secretkey()

### 说明

此函数是该函数的别名： sodium_crypto_box_publickey_from_secretkey().

# sodium_crypto_scalarmult_ristretto255

(PHP 8 >= 8.1.1)

sodium_crypto_scalarmult_ristretto255 — Computes a shared secret

### 说明

function sodium_crypto_scalarmult_ristretto255(string `$n`, string `$p`): string

Calculates scalar `n` times point `p`. Available as of libsodium 1.0.18.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`n`
  A scalar, which is typically a secret key.
`p`
  A point (x-coordinate), which is typically a public key.

### 返回值

Returns a 32-byte random string.

### 参见

- 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

### 说明

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.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`n`
  A secret key.

### 返回值

Returns a 32-byte random string.

### 参见

- 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

### 说明

function sodium_crypto_secretbox(#[\SensitiveParameter] string `$message`, string `$nonce`, #[\SensitiveParameter] string `$key`): string

Encrypt a message with a symmetric (shared) key.

### 参数

`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).

### 返回值

Returns the encrypted string.

### 错误／异常

- 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.

### 示例

示例 #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));
    ?>

以上示例的输出类似于：

    string(78) "3a1fa3e9f7b72ef8be51d40abf8e296c6899c185d07b18b4c93e7f26aa776d24c50852cd6b1076"
    string(23) "message to be encrypted"

### 参见

- 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

### 说明

function sodium_crypto_secretbox_keygen(): string

Generate a key for use with sodium_crypto_secretbox() and sodium_crypto_secretbox_open().

### 参数

此函数没有参数。

### 返回值

Returns the generated string of cryptographically secure random bytes.

### 示例

示例 #1 sodium_crypto_secretbox_keygen() example

    <?php
    $key = sodium_crypto_secretbox_keygen();
    var_dump( sodium_bin2hex( $key ) );
    ?>

以上示例的输出类似于：

    string(64) "88bd1dc51ec81984f3ddc5a8f59a3d95b647e2da3e879f1b9ceb0abd89e7286c"

示例 #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' ) );
    ?>

以上示例会输出：

    bool(true)

### 参见

- sodium_bin2hex() - Encode to hexadecimal
- 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

### 说明

function sodium_crypto_secretbox_open(string `$ciphertext`, string `$nonce`, #[\SensitiveParameter] string `$key`): string|false

Decrypt an encrypted message with a symmetric (shared) key.

### 参数

`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).

### 返回值

The decrypted string on success 或者在失败时返回 `false`.

### 错误／异常

- 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.

### 示例

示例 #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;
    }
    ?>

以上示例会输出：

    message to be encrypted

### 参见

- 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

### 说明

function sodium_crypto_secretstream_xchacha20poly1305_init_pull(string `$header`, #[\SensitiveParameter] string `$key`): string

Initialize a secretstream context for decryption.

### 参数

`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).

### 返回值

Secretstream state.

### 示例

示例 #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'));
    ?>

以上示例的输出类似于：

    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

### 说明

function sodium_crypto_secretstream_xchacha20poly1305_init_push(#[\SensitiveParameter] string `$key`): array

Initialize a secretstream context for encryption.

### 参数

`key`
  Cryptography key. See sodium_crypto_secretstream_xchacha20poly1305_keygen().

### 返回值

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

### 示例

示例 #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')));
    ?>

以上示例的输出类似于：

    string(106) "971e33b255f0990ef3931caf761c59136efa77b434832f28ec719e3ff73f5aec38b3bba1574ab5b70a8844d8da36a668e802cfea2c"

# sodium_crypto_secretstream_xchacha20poly1305_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_keygen — Generate a random secretstream key.

### 说明

function sodium_crypto_secretstream_xchacha20poly1305_keygen(): string

Generate a random secretstream key.

### 参数

此函数没有参数。

### 返回值

Returns a string of random bytes.

# 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

### 说明

function sodium_crypto_secretstream_xchacha20poly1305_pull(string `&$state`, string `$ciphertext`, string `$additional_data` = ""): array|false

Decrypt a chunk of data from an encrypted stream.

### 参数

`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.

### 返回值

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

### 说明

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.

### 参数

`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.

### 返回值

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

### 说明

function sodium_crypto_secretstream_xchacha20poly1305_rekey(string `&$state`): void

Explicitly rotate the key in the secretstream state. Overwrites the value passed in.

### 参数

`state`
  Secretstream state.

### 返回值

没有返回值。

# sodium_crypto_shorthash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_shorthash — Compute a short hash of a message and key

### 说明

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.

### 参数

`message`
  The message to hash.
`key`
  The hash key.

### 返回值

# sodium_crypto_shorthash_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_shorthash_keygen — Get random bytes for key

### 说明

function sodium_crypto_shorthash_keygen(): string

Generate a key for use with sodium_crypto_shorthash().

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# sodium_crypto_sign

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign — Sign a message

### 说明

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.

### 参数

`message`
  Message to sign.
`secret_key`
  Secret key. See sodium_crypto_sign_secretkey()

### 返回值

Signed message (not encrypted).

# sodium_crypto_sign_detached

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_detached — Sign the message

### 说明

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.

### 参数

`message`
  Message to sign.
`secret_key`
  Secret key. See sodium_crypto_sign_secretkey()

### 返回值

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

### 说明

function sodium_crypto_sign_ed25519_pk_to_curve25519(string `$public_key`): string

Given an Ed25519 public key, calculate the birationally equivalent X25519 public key.

### 参数

`public_key`
  Public key suitable for the crypto_sign functions.

### 返回值

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

### 说明

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.

### 参数

`secret_key`
  Secret key suitable for the crypto_sign functions.

### 返回值

Secret key suitable for the crypto_box functions.

# sodium_crypto_sign_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_keypair — Randomly generate a secret key and a corresponding public key

### 说明

function sodium_crypto_sign_keypair(): string

Generate a random Ed25519 keypair as one string.

### 参数

此函数没有参数。

### 返回值

Ed25519 keypair.

# 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

### 说明

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.

### 参数

`secret_key`
  Ed25519 secret key
`public_key`
  Ed25519 public key

### 返回值

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

### 说明

function sodium_crypto_sign_open(string `$signed_message`, string `$public_key`): string|false

Verify the signature attached to a message and return the message

### 参数

`signed_message`
  A message signed with sodium_crypto_sign()
`public_key`
  An Ed25519 public key

### 返回值

Returns the original signed message on success, 或者在失败时返回 `false`.

# sodium_crypto_sign_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_publickey — Extract the Ed25519 public key from a keypair

### 说明

function sodium_crypto_sign_publickey(#[\SensitiveParameter] string `$key_pair`): string

Extract the Ed25519 public key from a keypair

### 参数

`key_pair`
  Ed25519 keypair (see: sodium_crypto_sign_keypair())

### 返回值

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

### 说明

function sodium_crypto_sign_publickey_from_secretkey(#[\SensitiveParameter] string `$secret_key`): string

Extract the Ed25519 public key from the secret key

### 参数

`secret_key`
  Ed25519 secret key

### 返回值

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

### 说明

function sodium_crypto_sign_secretkey(#[\SensitiveParameter] string `$key_pair`): string

Extract the Ed25519 secret key from a keypair

### 参数

`key_pair`
  Ed25519 keypair (see: sodium_crypto_sign_keypair())

### 返回值

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

### 说明

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.

### 参数

`seed`
  Some cryptographic input. Must be 32 bytes.

### 返回值

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

### 说明

function sodium_crypto_sign_verify_detached(string `$signature`, string `$message`, string `$public_key`): bool

Verify signature for the message

### 参数

`signature`
  The cryptographic signature obtained from sodium_crypto_sign_detached()
`message`
  The message being verified
`public_key`
  Ed25519 public key

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# sodium_crypto_stream

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream — Generate a deterministic sequence of bytes from a seed

### 说明

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.

### 参数

`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).

### 返回值

String of pseudorandom bytes.

# sodium_crypto_stream_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream_keygen — Generate a random sodium_crypto_stream key.

### 说明

function sodium_crypto_stream_keygen(): string

Generate a key for use with sodium_crypto_stream() and sodium_crypto_stream_xor().

### 参数

此函数没有参数。

### 返回值

Encryption key (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

### 说明

function sodium_crypto_stream_xchacha20(int `$length`, string `$nonce`, #[\SensitiveParameter] string `$key`): string

Expands the `key` and `nonce` into a keystream of pseudorandom bytes.

### 参数

`length`
  Number of bytes desired.
`nonce`
  24-byte nonce.
`key`
  Key, possibly generated from sodium_crypto_stream_xchacha20_keygen().

### 返回值

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 — Returns a secure random key

### 说明

function sodium_crypto_stream_xchacha20_keygen(): string

Returns a secure random key for use with sodium_crypto_stream_xchacha20().

### 参数

此函数没有参数。

### 返回值

Returns a 32-byte secure random key for use with sodium_crypto_stream_xchacha20().

# 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)

### 说明

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).

警告

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().

### 参数

`message`
  The message to encrypt.
`nonce`
  24-byte nonce.
`key`
  Key, possibly generated from sodium_crypto_stream_xchacha20_keygen().

### 返回值

Encrypted message.

### 参见

- 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)

### 说明

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.

警告

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().

### 参数

`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().

### 返回值

Encrypted message, 或者在失败时返回 `false`.

### 示例

示例 #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);
    ?>

以上示例的输出类似于：

    int(128)
    bool(true)

### 参见

- 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

### 说明

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.

### 参数

`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).

### 返回值

Encrypted message.

# sodium_hex2bin

(PHP 7 >= 7.2.0, PHP 8)

sodium_hex2bin — Decodes a hexadecimally encoded binary string

### 说明

function sodium_hex2bin(#[\SensitiveParameter] string `$string`, string `$ignore` = ""): string

Decodes a hexadecimally encoded binary string.

Like sodium_bin2hex(), sodium_hex2bin() is resistant to side-channel attacks while hex2bin() is not.

### 参数

`string`
  Hexadecimal representation of data.
`ignore`
  Optional string argument for characters to ignore.

### 返回值

Returns the binary representation of the given `string` data.

# sodium_increment

(PHP 7 >= 7.2.0, PHP 8)

sodium_increment — Increment large number

### 说明

function sodium_increment(string `&$string`): void

Treat the string as a little-endian unsigned integer, then increase it by 1. Constant-time.

### 参数

`string`
  String to increment.

### 返回值

没有返回值。

# sodium_memcmp

(PHP 7 >= 7.2.0, PHP 8)

sodium_memcmp — Test for equality in constant-time

### 说明

function sodium_memcmp(#[\SensitiveParameter] string `$string1`, #[\SensitiveParameter] string `$string2`): int

Compare two strings in constant-time.

In practice, you almost always want to use hash_equals() instead, since it provides the same logic but returns a bool instead of an int. However, if you're using the return value of a comparison in a calculation that's timing-sensitive, and worried about timing leaks with bool-to-int conversions, sodium_memcmp() is an ideal replacement.

### 参数

`string1`
  String to compare
`string2`
  Other string to compare

### 返回值

Returns `0` if both strings are equal; `-1` otherwise.

# sodium_memzero

(PHP 7 >= 7.2.0, PHP 8)

sodium_memzero — Overwrite a string with NUL characters

### 说明

function sodium_memzero(#[\SensitiveParameter] string `&$string`): void

sodium_memzero() zeroes out the string that is passed by reference.

### 参数

`string`
  String.

### 返回值

没有返回值。

# sodium_pad

(PHP 7 >= 7.2.0, PHP 8)

sodium_pad — Add padding data

### 说明

function sodium_pad(#[\SensitiveParameter] string `$string`, int `$block_size`): string

Right-pad a string to a desired length. Timing-safe.

### 参数

`string`
  Unpadded string.
`block_size`
  The string will be padded until it is an even multiple of the block size.

### 返回值

Padded string.

# sodium_unpad

(PHP 7 >= 7.2.0, PHP 8)

sodium_unpad — Remove padding data

### 说明

function sodium_unpad(#[\SensitiveParameter] string `$string`, int `$block_size`): string

Unpad a padded string. Timing-safe.

### 参数

`string`
  Padded string.
`block_size`
  The block size for padding.

### 返回值

Unpadded string.

## 目录

- sodium_add — Add large numbers
- sodium_base642bin — Decodes a base64-encoded string into raw binary.
- sodium_bin2base64 — Encodes a raw binary string with base64.
- sodium_bin2hex — Encode to hexadecimal
- sodium_compare — Compare large numbers
- 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 — Verify then decrypt a message with AES-256-GCM
- sodium_crypto_aead_aes256gcm_encrypt — Encrypt then authenticate with AES-256-GCM
- sodium_crypto_aead_aes256gcm_is_available — Check if hardware supports AES256-GCM
- sodium_crypto_aead_aes256gcm_keygen — Generate a random AES-256-GCM key
- sodium_crypto_aead_chacha20poly1305_decrypt — Verify then decrypt with ChaCha20-Poly1305
- sodium_crypto_aead_chacha20poly1305_encrypt — Encrypt then authenticate with ChaCha20-Poly1305
- sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Verify that the ciphertext includes a valid tag
- sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Encrypt a message
- sodium_crypto_aead_chacha20poly1305_ietf_keygen — Generate a random ChaCha20-Poly1305 (IETF) key.
- sodium_crypto_aead_chacha20poly1305_keygen — Generate a random ChaCha20-Poly1305 key.
- sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — (Preferred) Verify then decrypt with XChaCha20-Poly1305
- sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — (Preferred) Encrypt then authenticate with XChaCha20-Poly1305
- sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Generate a random XChaCha20-Poly1305 key.
- sodium_crypto_auth — Compute a tag for the message
- sodium_crypto_auth_keygen — Generate a random key for 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 — Randomly generate a secret key and a corresponding public key
- 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 — Generate a random generichash key
- sodium_crypto_generichash_update — Add message to a hash
- sodium_crypto_kdf_derive_from_key — Derive a subkey
- sodium_crypto_kdf_keygen — Generate a random root key for the KDF interface
- 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 — 别名 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 — Generate a random secretstream key.
- 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 — Get random bytes for key
- 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 — Randomly generate a secret key and a corresponding public key
- 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 — Generate a random sodium_crypto_stream key.
- sodium_crypto_stream_xchacha20 — Expands the key and nonce into a keystream of pseudorandom bytes
- sodium_crypto_stream_xchacha20_keygen — Returns a secure random key
- 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 — Decodes a hexadecimally encoded binary string
- sodium_increment — Increment large number
- sodium_memcmp — Test for equality in constant-time
- sodium_memzero — Overwrite a string with NUL characters
- sodium_pad — Add padding data
- sodium_unpad — Remove padding data

# The SodiumException class

(PHP 7 >= 7.2.0, PHP 8)

## 简介

Exceptions thrown by the sodium functions.

## 类摘要

class SodiumException extends Exception {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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
}

- 安装/配置
  - 需求
  - 安装
- 预定义常量
- Sodium 函数
  - sodium_add — Add large numbers
  - sodium_base642bin — Decodes a base64-encoded string into raw binary.
  - sodium_bin2base64 — Encodes a raw binary string with base64.
  - sodium_bin2hex — Encode to hexadecimal
  - sodium_compare — Compare large numbers
  - 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 — Verify then decrypt a message with AES-256-GCM
  - sodium_crypto_aead_aes256gcm_encrypt — Encrypt then authenticate with AES-256-GCM
  - sodium_crypto_aead_aes256gcm_is_available — Check if hardware supports AES256-GCM
  - sodium_crypto_aead_aes256gcm_keygen — Generate a random AES-256-GCM key
  - sodium_crypto_aead_chacha20poly1305_decrypt — Verify then decrypt with ChaCha20-Poly1305
  - sodium_crypto_aead_chacha20poly1305_encrypt — Encrypt then authenticate with ChaCha20-Poly1305
  - sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Verify that the ciphertext includes a valid tag
  - sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Encrypt a message
  - sodium_crypto_aead_chacha20poly1305_ietf_keygen — Generate a random ChaCha20-Poly1305 (IETF) key.
  - sodium_crypto_aead_chacha20poly1305_keygen — Generate a random ChaCha20-Poly1305 key.
  - sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — (Preferred) Verify then decrypt with XChaCha20-Poly1305
  - sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — (Preferred) Encrypt then authenticate with XChaCha20-Poly1305
  - sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Generate a random XChaCha20-Poly1305 key.
  - sodium_crypto_auth — Compute a tag for the message
  - sodium_crypto_auth_keygen — Generate a random key for 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 — Randomly generate a secret key and a corresponding public key
  - 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 — Generate a random generichash key
  - sodium_crypto_generichash_update — Add message to a hash
  - sodium_crypto_kdf_derive_from_key — Derive a subkey
  - sodium_crypto_kdf_keygen — Generate a random root key for the KDF interface
  - 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 — 别名 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 — Generate a random secretstream key.
  - 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 — Get random bytes for key
  - 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 — Randomly generate a secret key and a corresponding public key
  - 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 — Generate a random sodium_crypto_stream key.
  - sodium_crypto_stream_xchacha20 — Expands the key and nonce into a keystream of pseudorandom bytes
  - sodium_crypto_stream_xchacha20_keygen — Returns a secure random key
  - 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 — Decodes a hexadecimally encoded binary string
  - sodium_increment — Increment large number
  - sodium_memcmp — Test for equality in constant-time
  - sodium_memzero — Overwrite a string with NUL characters
  - sodium_pad — Add padding data
  - sodium_unpad — Remove padding data
- SodiumException — The SodiumException class

# Xpass

# 简介

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 via PECL

## 需求

This extension requires » libxcrypt version 4.4 or higher.

## Installation via PECL

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/xpass.

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

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 函数

# crypt_checksalt

(PECL xpass >= 1.1.0)

crypt_checksalt — Validate a crypt setting string

### 说明

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.

### 参数

`salt`
  Salt string to check.

### 返回值

Returns one of the `CRYPT_SALT_*` as an int.

### 示例

示例 #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);
    ?>

以上示例会输出：

    bool(true)
    bool(true)

### 参见

- 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

### 说明

function crypt_gensalt(string `$prefix` = `null`, int `$count` = 0): ?string

Compile a string for use as the salt argument to crypt().

### 参数

`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.

### 返回值

Returns a string with the setting, or `null` in case of an error.

### 示例

示例 #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);
    ?>

以上示例会输出：

    string(29) "$2y$05$GcPykP.Am8C1.dGamdpwW."
    string(60) "$2y$05$GcPykP.Am8C1.dGamdpwW.1RR.7uicWvJPZfJfCEizZHqVWwuaJLm"
    bool(true)

### 参见

- crypt_preferred_method() - Get the prefix of the preferred hash method
- crypt() - 单向字符串散列
- hash_equals() - 可防止时序攻击的字符串比较

# crypt_preferred_method

(PECL xpass >= 1.1.0)

crypt_preferred_method — Get the prefix of the preferred hash method

### 说明

function crypt_preferred_method(): ?string

Get the prefix of the preferred hash method.

### 参数

此函数没有参数。

### 返回值

Returns a string with the prefix, or `null` in case of an error.

### 示例

示例 #1 A crypt_preferred_method() example

    <?php
    var_dump(crypt_preferred_method());
    ?>

以上示例会输出：

    string(3) "$y$"

### 参见

- crypt_gensalt() - Compile a string for use as the salt argument to crypt

## 目录

- 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 via PECL
- 预定义常量
- Xpass 函数
  - 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 — 散列消息摘要框架
  - 安装/配置
  - 预定义常量
  - HashContext — HashContext 类
  - Hash 函数
- Mcrypt
  - 安装/配置
  - 预定义常量
  - Mcrypt 密码
  - Mcrypt 函数
- Mhash
  - 安装/配置
  - 预定义常量
  - 示例
  - Mhash 函数
- OpenSSL
  - 安装/配置
  - 预定义常量
  - 密钥/证书参数
  - 证书验证
  - OpenSSL 函数
  - OpenSSLCertificate — OpenSSLCertificate 类
  - OpenSSLCertificateSigningRequest — OpenSSLCertificateSigningRequest 类
  - OpenSSLAsymmetricKey — OpenSSLAsymmetricKey 类
- 密码散列算法
  - 安装/配置
  - 预定义常量
  - 密码散列算法函数
- Rnp
  - 安装/配置
  - 预定义常量
  - 示例
  - Rnp 函数
  - RnpFFI — The RnpFFI class
- Sodium
  - 安装/配置
  - 预定义常量
  - Sodium 函数
  - SodiumException — The SodiumException class
- Xpass
  - 安装/配置
  - 预定义常量
  - Xpass 函数

# 数据库扩展

# 数据库抽象层

# Database (dbm-style) Abstraction Layer

# 简介

These functions build the foundation for accessing Berkeley DB style databases.

This is a general abstraction layer for several file-based databases. As such, functionality is limited to a common subset of features supported by modern databases such as » Oracle Berkeley DB.

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置
- 资源类型

## 需求

The behaviour of various aspects depends on the implementation of the underlying database. Functions such as dba_optimize() and dba_sync() will do what they promise for one database and will do nothing for others. You have to download and install supported dba-Handlers.

List of DBA handlers
Handler | Notes
--- | ---
`dbm` | Dbm is the oldest (original) type of Berkeley DB style databases. You should avoid it, if possible. We do not support the compatibility functions built into DB2 and gdbm, because they are only compatible on the source code level, but cannot handle the original dbm format.
`ndbm` | Ndbm is a newer type and more flexible than dbm. It still has most of the arbitrary limits of dbm (therefore it is deprecated).
`gdbm` | Gdbm is the » GNU database manager.
`db2` | DB2 is for » Oracle Berkeley DB 2. It is described as "a programmatic toolkit that provides high-performance built-in database support for both standalone and client/server applications."
`db3` | DB3 is for » Oracle Berkeley DB 3.
`db4` | DB4 is for » Oracle Berkeley DB 4 or 5. This option can be used with BDB 5 as of PHP 5.3.3.
`cdb` | Cdb is "a fast, reliable, lightweight package for creating and reading constant databases." It is from the author of qmail and can be found at » http://cr.yp.to/cdb.html. Since it is constant, we support only reading operations. We support writing (not updating) through the internal cdb library.
`cdb_make` | We support creation (not updating) of cdb files when the bundled cdb library is used.
`flatfile` | This is available for compatibility with the deprecated `dbm` extension only and should be avoided. However you may use this where files were created in this format. That happens when configure could not find any external library.
`inifile` | This is available to be able to modify php.ini files from within PHP scripts. When working with ini files you can pass arrays of the form array(0=>group,1=>value_name) or strings of the form "[group]value_name" where group is optional. As the functions dba_firstkey() and dba_nextkey() return string representations of the key there is the function dba_key_split() which allows to convert the string keys into array keys without losing `false`.
`qdbm` | The qdbm library can be downloaded from » http://fallabs.com/qdbm/index.html.
`tcadb` | The Tokyo Cabinet library can be downloaded from » http://fallabs.com/tokyocabinet/.
`lmdb` | This is available since PHP 7.2.0. The Lightning Memory-Mapped Database library can be downloaded from » https://symas.com/lmdb/.

When invoking the dba_open() or dba_popen() functions, one of the handler names must be supplied as an argument. The actually available list of handlers is displayed by invoking phpinfo() or dba_handlers().

## 安装

By using the --enable-dba=shared configuration option you can build a dynamic loadable module to enable PHP for basic support of dbm-style databases. You also have to add support for at least one of the following handlers by specifying the --with-XXXX or --enable-XXXX configure switch to your PHP configure line.

警告

After configuring and compiling PHP you must execute the following test from commandline: `php run-tests.php ext/dba`. This shows whether your combination of handlers works. Most problematic are `dbm` and `ndbm` which conflict with many installations. The reason for this is that on several systems these libraries are part of more than one other library. The configuration test only prevents you from configuring malfunctioning single handlers but not combinations.

Supported DBA handlers
Handler | Configure Switch
--- | ---
`dbm` | To enable support for dbm add --with-dbm[=DIR]. 注意: dbm normally is a wrapper which often results in failures. This means you should only use dbm if you are sure it works and if you really need this format.
`ndbm` | To enable support for ndbm add --with-ndbm[=DIR]. 注意: ndbm normally is a wrapper which often results in failures. This means you should only use ndbm if you are sure it works and if you really need this format.
`gdbm` | To enable support for gdbm add --with-gdbm[=DIR].
`db2` | To enable support for Oracle Berkeley DB 2 add --with-db2[=DIR]. 注意: db2 conflicts with db3 and db4.
`db3` | To enable support for Oracle Berkeley DB 3 add --with-db3[=DIR]. 注意: db3 conflicts with db2 and db4.
`db4` | To enable support for Oracle Berkeley DB 4 or 5 add --with-db4[=DIR]. 注意: db4 conflicts with db2 and db3. 注意: The db libraries with versions 4.1 through 4.1.24 cannot be used in any PHP version. Support for BDB 5 was added in PHP 5.3.3.
`cdb` | To enable support for cdb add --with-cdb[=DIR]. 注意: You can omit DIR to use the bundled cdb library that adds the cdb_make handler which allows creation of cdb files and allows to access cdb files on the network using PHP's streams.
`flatfile` | To enable support for flatfile add --enable-flatfile. Before PHP 5.2.1 the --with-flatfile had to be used instead. 注意: This was added to add compatibility with deprecated `dbm` extension. Use this handler only when you cannot install one of the libraries required by the other handlers and when you cannot use bundled cdb handler.
`inifile` | To enable support for `inifile` add --enable-inifile. Before PHP 5.2.1 the --with-inifile had to be used instead. 注意: This was added to allow to read and set microsoft style .ini files (like the php.ini file).
`qdbm` | To enable support for qdbm add --with-qdbm[=DIR]. 注意: qdbm conflicts with dbm and gdbm. 注意: The qdbm library can be downloaded from » http://fallabs.com/qdbm/index.html.
`tcadb` | To enable support for Tokyo Cabinet add --with-tcadb[=DIR]. 注意: The Tokyo Cabinet library can be downloaded from » http://fallabs.com/tokyocabinet/.
`lmdb` | To enable support for the Lightning Memory-Mapped Database add --with-lmdb[=DIR]. 注意: This was added in PHP 7.2.0. The Lightning Memory-Mapped Database library can be downloaded from » https://symas.com/lmdb/.

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

DBA 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
dba.default_handler | DBA_DEFAULT | `INI_ALL` |

这是配置指令的简短说明。

`dba.default_handler` string
  The name of the default handler

## 资源类型

Prior to PHP 8.4.0, most DBA functions operate on or return resources (e.g. dba_open() returns a positive DBA link identifier required by most DBA functions).

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`DBA_LMDB_USE_SUB_DIR` (int)
  LMDB Driver flag to allow the creation of a subdirectory for the database files. Available as of PHP 8.2.0.
`DBA_LMDB_NO_SUB_DIR` (int)
  LMDB Driver flag to disallow the creation of a subdirectory for the database files. Available as of PHP 8.2.0.

# 示例

## 目录

- Basic usage

## Basic usage

示例 #1 DBA example

    <?php

    $id = dba_open("/tmp/test.db", "n", "db2");

    if (!$id) {
        echo "dba_open failed\n";
        exit;
    }

    dba_replace("key", "This is an example!", $id);

    if (dba_exists("key", $id)) {
        echo dba_fetch("key", $id);
        dba_delete("key", $id);
    }

    dba_close($id);
    ?>

DBA is binary safe and does not have any arbitrary limits. However, it inherits all limits set by the underlying database implementation.

All file-based databases must provide a way of setting the file mode of a new created database, if that is possible at all. The file mode is commonly passed as the fourth argument to dba_open() or dba_popen().

You can access all entries of a database in a linear way by using the dba_firstkey() and dba_nextkey() functions. You may not change the database while traversing it.

示例 #2 Traversing a database

    <?php

    // ...open database...

    $key = dba_firstkey($id);

    while ($key !== false) {
        if (true) {          // remember the key to perform some action later
            $handle_later[] = $key;
        }
        $key = dba_nextkey($id);
    }

    foreach ($handle_later as $val) {
        dba_delete($val, $id);
    }

    ?>

# The Dba\Connection class

(PHP 8 >= 8.4.0)

## 简介

A fully opaque class which replaces a `dba` resource as of PHP 8.4.0.

## 类摘要

namespace Dba;
final class Connection {
}

# DBA 函数

# dba_close

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_close — 关闭 DBA 数据库

### 说明

function dba_close(Dba\Connection `$dba`): void

dba_close() 关闭已建立的数据库并释放指定数据库句柄的所有资源。

### 参数

`dba`
  一个由 dba_open() 或 dba_popen() 返回的 Dba\Connection 实例。

### 返回值

没有返回值。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `dba` 参数现在接受 Dba\Connection 实例， 之前接受有效的 `dba` resource。

### 参见

- dba_open() - 打开数据库
- dba_popen() - 打开数据库持久化

# dba_delete

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_delete — 删除由键指定的 DBA 条目

### 说明

function dba_delete(string|array `$key`, Dba\Connection `$dba`): bool

dba_delete() 从数据库中删除指定的条目。

### 参数

`key`
  要删除的条目的键。
`dba`
  一个由 dba_open() 或 dba_popen() 返回的 Dba\Connection 实例。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `dba` 参数现在接受 Dba\Connection 实例， 之前接受有效的 `dba` resource。

### 参见

- dba_exists() - 检查键是否存在
- dba_fetch() - 获取由键指定的数据
- dba_insert() - 插入条目
- dba_replace() - 替换或插入条目

# dba_exists

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_exists — 检查键是否存在

### 说明

function dba_exists(string|array `$key`, Dba\Connection `$dba`): bool

dba_exists() 检查数据库中是否存在指定的 `key`。

### 参数

`key`
  要检查的键。
`dba`
  一个由 dba_open() 或 dba_popen() 返回的 Dba\Connection 实例。

### 返回值

如果键存在则返回 `true`，否则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `dba` 参数现在接受 Dba\Connection 实例， 之前接受有效的 `dba` resource。

### 参见

- dba_delete() - 删除由键指定的 DBA 条目
- dba_fetch() - 获取由键指定的数据
- dba_insert() - 插入条目
- dba_replace() - 替换或插入条目

# dba_fetch

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_fetch — 获取由键指定的数据

### 说明

function dba_fetch(string|array `$key`, Dba\Connection `$dba`, int `$skip` = 0): string|false

自 8.3.0 起，已废弃重载签名：

function dba_fetch(string|array `$key`, int `$skip`, resource `$dba`): string

dba_fetch() 从 `dba` 指定的数据库中获取由 `key` 指定的数据。

### 参数

`key`
  指定数据的键。

  > 注意: 在处理 inifiles 时，此函数接受数组作为键，其中索引 0 是组，索引 1 是值名称。参见： dba_key_split()。

`dba`
  一个由 dba_open() 或 dba_popen() 返回的 Dba\Connection 实例。
`skip`
  使用 cdb 数据库时要忽略的键值对数。 对于不支持同名多个键的所有其他数据库，此值将被忽略。

### 返回值

如果找到键/数据对，则返回关联的字符串，否则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `dba` 参数现在接受 Dba\Connection 实例， 之前接受有效的 `dba` resource。
8.3.0 | 废弃了使用 `dba` 作为第三个参数调用 dba_fetch() 的方法。
8.2.0 | dba_fetch() 的可选参数 `skip` 现在在最后， 与 PHP 用户空间语义一致。以前的重载签名仍然被接受，但不推荐使用。

### 参见

- dba_exists() - 检查键是否存在
- dba_delete() - 删除由键指定的 DBA 条目
- dba_insert() - 插入条目
- dba_replace() - 替换或插入条目
- dba_key_split() - 将键的字符串表示分割为数组表示

# dba_firstkey

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_firstkey — 获取第一个键

### 说明

function dba_firstkey(Dba\Connection `$dba`): string|false

dba_firstkey() 返回数据库的第一个键并重置内部键指针。 这允许通过整个数据库进行线性搜索。

### 参数

`dba`
  一个由 dba_open() 或 dba_popen() 返回的 Dba\Connection 实例。

### 返回值

成功时返回键， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `dba` 参数现在接受 Dba\Connection 实例， 之前接受有效的 `dba` resource。

### 参见

- dba_nextkey() - 获取下一个键
- dba_key_split() - 将键的字符串表示分割为数组表示
- Example 2 in the DBA examples

# dba_handlers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

dba_handlers — 列出所有可用的处理器

### 说明

function dba_handlers(bool `$full_info` = `false`): array

dba_handlers() 列出此扩展支持的所有处理器。

### 参数

`full_info`
  用于开启/关闭结果中的完整信息显示。

### 返回值

返回一个数据库处理器的数组。如果 `full_info` 设置为 `true`， 数组将是关联数组，处理器名称作为键，版本信息作为值。否则，结果将是处理器名称的索引数组。

> 注意: 当使用内部 cdb 库时，你会看到 `cdb` 和 `cdb_make`。

### 示例

示例 #1 dba_handlers() 示例

    <?php

    echo "Available DBA handlers:\n";
    foreach (dba_handlers(true) as $handler_name => $handler_version) {
      // clean the versions
      $handler_version = str_replace('$', '', $handler_version);
      echo " - $handler_name: $handler_version\n";
    }

    ?>

以上示例的输出类似于：

    Available DBA handlers:
     - 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 — 插入条目

### 说明

function dba_insert(string|array `$key`, string `$value`, Dba\Connection `$dba`): bool

dba_insert() 插入由 `key` 和 `value` 描述的条目到数据库中。

### 参数

`key`
  要插入的条目的键。如果这个键已经存在于数据库中，这个函数将失败。 如果需要替换已存在的键，请使用 dba_replace()。
`value`
  要插入的值。
`dba`
  一个由 dba_open() 或 dba_popen() 返回的 Dba\Connection 实例。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `dba` 参数现在接受 Dba\Connection 实例， 之前接受有效的 `dba` resource。

### 参见

- dba_exists() - 检查键是否存在
- dba_delete() - 删除由键指定的 DBA 条目
- dba_fetch() - 获取由键指定的数据
- dba_replace() - 替换或插入条目

# dba_key_split

(PHP 5, PHP 7, PHP 8)

dba_key_split — 将键的字符串表示分割为数组表示

### 说明

function dba_key_split(string|false|null `$key`): array|false

dba_key_split() 将键（字符串表示）分割为数组表示。

### 参数

`key`
  键的字符串表示。

### 返回值

返回一个数组，形式为 `array(0 => group, 1 => value_name)`。 如果 `key` 是 `null` 或 `false`，则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 将 `null` 或者 `false` 传递给 `key` 现在已经被弃用。

### 参见

- dba_firstkey() - 获取第一个键
- dba_nextkey() - 获取下一个键
- dba_fetch() - 获取由键指定的数据

# dba_list

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

dba_list — 列出所有打开的数据库文件

### 说明

function dba_list(): array

dba_list() 列出所有打开的数据库文件。

### 参数

此函数没有参数。

### 返回值

一个关联数组，形式为 `resourceid => filename`。

# dba_nextkey

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_nextkey — 获取下一个键

### 说明

function dba_nextkey(Dba\Connection `$dba`): string|false

dba_nextkey() 返回数据库的下一个键并移动内部键指针。

### 参数

`dba`
  一个由 dba_open() 或 dba_popen() 返回的 Dba\Connection 实例。

### 返回值

成功时返回键， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `dba` 参数现在接受 Dba\Connection 实例， 之前接受有效的 `dba` resource。

### 参见

- dba_firstkey() - 获取第一个键
- dba_key_split() - 将键的字符串表示分割为数组表示
- Example 2 in the DBA examples

# dba_open

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_open — 打开数据库

### 说明

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() 用 `mode` 和 `handler` 为 `path` 建立一个数据库实例。

### 参数

`path`
  数据库文件的路径。通常是文件系统中的一个常规路径。
`mode`
  一个字符串，指定数据库的访问模式。它是一个字符，可以是 `r` 用于读取访问， `w` 用于对已存在的数据库进行读写访问， `c` 用于读写访问和数据，如果目前不存在，则创建数据库， 以及 `n` 用于创建、截断和读写访问。 数据库是以 BTree 模式创建的，不支持其他模式（如 Hash 或 Queue）。 此外，您可以使用下一个字符设置数据库锁定方法。使用 `l` 用 .lck 文件锁定数据库，或使用 `d` 锁定数据库文件本身。重要的是您的所有应用程序都要一致地这样做。 如果您想测试访问并且不想等待锁定，可以将 `t` 作为第三个字符添加。当您确信不需要数据库锁定时， 可以使用 `-` 代替 `l` 或 `d`。当 `d`、 `l` 或 `-` 都没有使用时，dba 将锁定数据库文件，就像使用 `d` 一样。

  > 注意:

  > 一个数据库文件只能有一个写入者。当您在 web 服务器上使用 dba 时，如果有多个请求需要写入操作， 它们只能一个接一个地进行。在写入时不允许读取。dba 扩展使用锁来防止这种情况。请参阅下表：

  > DBA 锁定
  > 已经打开 | `mode` = "rl" | `mode` = "rlt" | `mode` = "wl" | `mode` = "wlt" | `mode` = "rd" | `mode` = "rdt" | `mode` = "wd" | `mode` = "wdt"
  > --- | --- | --- | --- | --- | --- | --- | --- | ---
  > 未打开 | ok | ok | ok | ok | ok | ok | ok | ok
  > `mode` = "rl" | ok | ok | wait | false | illegal | illegal | illegal | illegal
  > `mode` = "wl" | wait | false | wait | false | illegal | illegal | illegal | illegal
  > `mode` = "rd" | illegal | illegal | illegal | illegal | ok | ok | wait | false
  > `mode` = "wd" | illegal | illegal | illegal | illegal | wait | false | wait | false

  > - ok: 第二次调用将成功。
  > - wait: 第二次调用将等待，直到第一个调用 dba_close()。
  > - false: 第二次调用返回 false。
  > - illegal: 不能混合 `"l"` 和 `"d"` 修饰符用于 `mode` 参数。

`handler`
  用于访问 `path` 的 处理器 的名称。 它接收所有给定给 dba_open() 的可选参数， 并可以代表它们执行操作。如果 `handler` 是 `null`，则调用默认处理器。
`permission`
  可选的 int 参数，传递给驱动程序。它的含义与 chmod() 的 `permissions` 参数相同， 默认为 `0644`。 `db1`、`db2`、`db3`、`db4`、 `dbm`、`gdbm`、`ndbm` 和 `lmdb` 驱动程序支持 `permission` 参数。
`map_size`
  可选的 int 参数，传递给驱动程序。它的值应该是 OS 的页面大小的倍数，或者是零，以使用默认的映射大小。 只有 `lmdb` 驱动程序接受 `map_size` 参数。
`flags`
  传递给数据库驱动程序的标志。如果 `null`，将提供默认标志。 目前，只有 LMDB 驱动程序支持以下标志 `DBA_LMDB_USE_SUB_DIR` 和 `DBA_LMDB_NO_SUB_DIR`。

### 返回值

成功时返回一个 Dba\Connection 实例， 或者在失败时返回 `false`。

### 错误／异常

如果 `handler` 为 `null`，但没有默认处理器，则返回 `false` 并发出一个 `E_WARNING` 级别的错误。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 现在返回一个 Dba\Connection 实例； 以前返回一个 resource。
8.2.0 | `flags` 参数被添加。
8.2.0 | `handler` 现在可以为 `null`。
7.3.14, 7.4.2 | `lmdb` 驱动现在支持额外的 `map_size` 参数。

### 参见

- dba_popen() - 打开数据库持久化
- dba_close() - 关闭 DBA 数据库

# dba_optimize

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_optimize — 优化数据库

### 说明

function dba_optimize(Dba\Connection `$dba`): bool

dba_optimize() 优化底层数据库。

### 参数

`dba`
  一个由 dba_open() 或 dba_popen() 返回的 Dba\Connection 实例。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `dba` 参数现在接受 Dba\Connection 实例， 之前接受有效的 `dba` resource。

### 参见

- dba_sync() - 同步数据库

# dba_popen

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_popen — 打开数据库持久化

### 说明

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() 用 `mode` 和 `handler` 为 `path` 建立一个持久数据库实例。

### 参数

`path`
  数据库文件的路径。通常是文件系统中的一个常规路径。
`mode`
  一个字符串，指定数据库的访问模式。它是一个字符，可以是 `r` 用于读取访问， `w` 用于对已存在的数据库进行读写访问， `c` 用于读写访问和数据，如果目前不存在，则创建数据库， 以及 `n` 用于创建、截断和读写访问。
`handler`
  用于访问 `path` 的 处理器 的名称。 它接收所有给 dba_popen() 的可选参数，并可以代表它们执行操作。 如果 `handler` 是 `null`，则调用默认处理器。
`permission`
  可选 int 参数，传递给驱动程序。它的含义与 chmod() 的 `permissions` 参数相同， 默认为 `0644`。 `db1`、`db2`、`db3`、 `db4`、`dbm`、`gdbm`、 `ndbm` 和 `lmdb` 驱动程序支持 `permission` 参数。
`map_size`
  可选 int 参数，传递给驱动程序。它的值应该是 OS 的页面大小的倍数，或者是零，以使用默认的映射大小。 只有 `lmdb` 驱动程序接受 `map_size` 参数。
`flags`
  允许向 DB 驱动程序传递标志。目前，只支持 LMDB，使用 `DBA_LMDB_USE_SUB_DIR` 和 `DBA_LMDB_NO_SUB_DIR`。

### 返回值

成功时返回一个 Dba\Connection 实例， 或者在失败时返回 `false`。

### 错误／异常

如果 `handler` 为 `null`，但没有默认处理器，则返回 `false` 并发出一个 `E_WARNING` 级别的错误。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 现在返回一个 Dba\Connection 实例； 以前返回一个 resource。
8.2.0 | `flags` 参数被添加。
8.2.0 | `handler` 现在可以为 `null`。
7.3.14, 7.4.2 | `lmdb` 驱动现在支持额外的 `map_size` 参数。

### 参见

- dba_open() - 打开数据库
- dba_close() - 关闭 DBA 数据库

# dba_replace

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_replace — 替换或插入条目

### 说明

function dba_replace(string|array `$key`, string `$value`, Dba\Connection `$dba`): bool

dba_replace() 替换或插入由 `key` 和 `value` 描述的条目到 `dba` 指定的数据库中。

### 参数

`key`
  要替换的条目的键。
`value`
  要插入的值。
`dba`
  一个由 dba_open() 或 dba_popen() 返回的 Dba\Connection 实例。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `dba` 参数现在接受 Dba\Connection 实例， 之前接受有效的 `dba` resource。

### 参见

- dba_exists() - 检查键是否存在
- dba_delete() - 删除由键指定的 DBA 条目
- dba_fetch() - 获取由键指定的数据
- dba_insert() - 插入条目

# dba_sync

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_sync — 同步数据库

### 说明

function dba_sync(Dba\Connection `$dba`): bool

dba_sync() 同步数据库。这可能会触发一个物理写入到磁盘，如果支持的话。

### 参数

`dba`
  一个由 dba_open() 或 dba_popen() 返回的 Dba\Connection 实例。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `dba` 参数现在接受 Dba\Connection 实例， 之前接受有效的 `dba` resource。

### 参见

- dba_optimize() - 优化数据库

## 目录

- dba_close — 关闭 DBA 数据库
- dba_delete — 删除由键指定的 DBA 条目
- dba_exists — 检查键是否存在
- dba_fetch — 获取由键指定的数据
- dba_firstkey — 获取第一个键
- dba_handlers — 列出所有可用的处理器
- dba_insert — 插入条目
- dba_key_split — 将键的字符串表示分割为数组表示
- dba_list — 列出所有打开的数据库文件
- dba_nextkey — 获取下一个键
- dba_open — 打开数据库
- dba_optimize — 优化数据库
- dba_popen — 打开数据库持久化
- dba_replace — 替换或插入条目
- dba_sync — 同步数据库

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
  - 资源类型
- 预定义常量
- 示例
  - Basic usage
- Dba\Connection — The Dba\Connection class
- DBA 函数
  - dba_close — 关闭 DBA 数据库
  - dba_delete — 删除由键指定的 DBA 条目
  - dba_exists — 检查键是否存在
  - dba_fetch — 获取由键指定的数据
  - dba_firstkey — 获取第一个键
  - dba_handlers — 列出所有可用的处理器
  - dba_insert — 插入条目
  - dba_key_split — 将键的字符串表示分割为数组表示
  - dba_list — 列出所有打开的数据库文件
  - dba_nextkey — 获取下一个键
  - dba_open — 打开数据库
  - dba_optimize — 优化数据库
  - dba_popen — 打开数据库持久化
  - dba_replace — 替换或插入条目
  - dba_sync — 同步数据库

# ODBC (Unified)

# 简介

In addition to normal ODBC support, the Unified ODBC functions in PHP allow you to access several databases that have borrowed the semantics of the ODBC API to implement their own API. Instead of maintaining multiple database drivers that were all nearly identical, these drivers have been unified into a single set of ODBC functions.

The following databases are supported by the Unified ODBC functions: » Adabas D, » IBM DB2, » iODBC, » Solid, and » Sybase SQL Anywhere.

> 注意: With the exception of iODBC, there is no ODBC involved when connecting to the above databases. The functions that you use to speak natively to them just happen to share the same names and syntax as the ODBC functions. However, building PHP with iODBC support enables you to use any ODBC-compliant drivers with your PHP applications. More information on iODBC, is available at » www.iodbc.org with the alternative unixODBC available at » www.unixodbc.org.

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置
- 资源类型

## 需求

To access any of the supported databases you need to have the required libraries installed.

## 安装

--with-adabas[=DIR]

  Include Adabas D support. DIR is the Adabas base install directory, defaults to /usr/local.

--with-sapdb[=DIR]

  Include SAP DB support. DIR is SAP DB base install directory, defaults to /usr/local.

--with-solid[=DIR]

  Include Solid support. DIR is the Solid base install directory, defaults to /usr/local/solid.

--with-ibm-db2[=DIR]

  Include IBM DB2 support. DIR is the DB2 base install directory, defaults to /home/db2inst1/sqllib.

--with-empress[=DIR]

  Include Empress support. DIR is the Empress base install directory, defaults to $EMPRESSPATH. This option only supports Empress Version 8.60 and above.

--with-empress-bcs[=DIR]

  Include `"Empress Local Access"` support. DIR is the Empress base install directory, defaults to $EMPRESSPATH. This option only supports Empress Version 8.60 and above.

--with-birdstep[=DIR]

  Include Birdstep support. DIR is the Birdstep base install directory, defaults to /usr/local/birdstep.

--with-custom-odbc[=DIR]

  Include a user defined ODBC support. The DIR is ODBC install base directory, which defaults to /usr/local. Make sure to define CUSTOM_ODBC_LIBS and have some odbc.h in your include dirs. E.g., you should define following for Sybase SQL Anywhere 5.5.00 on QNX, prior to run configure script:

         CPPFLAGS="-DODBC_QNX -DSQLANY_BUG"
         LDFLAGS=-lunix
         CUSTOM_ODBC_LIBS="-ldblib -lodbc".

--with-iodbc[=DIR]

  Include iODBC support. DIR is the iODBC base install directory, defaults to /usr/local.

--with-esoob[=DIR]

  Include Easysoft OOB support. DIR is the OOB base install directory, defaults to /usr/local/easysoft/oob/client.

--with-unixODBC[=DIR]

  Include unixODBC support. DIR is the unixODBC base install directory, defaults to /usr/local.

--with-openlink[=DIR]

  Include OpenLink ODBC support. DIR is the OpenLink base install directory, defaults to /usr/local. This is the same as iODBC.

--with-dbmaker[=DIR]

  Include DBMaker support. DIR is the DBMaker base install directory, defaults to where the latest version of DBMaker is installed (such as /home/dbmaker/3.6).

Windows users must enable php_odbc.dll in order to use this extension.

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

Unified ODBC Configuration Options
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
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` |

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`odbc.default_db` string

  ODBC data source to use if none is specified in odbc_connect() or odbc_pconnect().

`odbc.default_user` string

  User name to use if none is specified in odbc_connect() or odbc_pconnect().

`odbc.default_pw` string

  Password to use if none is specified in odbc_connect() or odbc_pconnect().

`odbc.allow_persistent` bool

  Whether to allow persistent ODBC connections.

`odbc.check_persistent` bool

  Check that a connection is still valid before reuse.

`odbc.max_persistent` int

  The maximum number of persistent ODBC connections per process.

`odbc.max_links` int

  The maximum number of ODBC connections per process, including persistent connections.

`odbc.defaultlrl` int

  Handling of LONG fields. Specifies the number of bytes returned to variables. See odbc_longreadlen() for details.

  当使用 int 时, 其值以字节来衡量。还可以使用在 FAQ 中描述的速记符。
`odbc.defaultbinmode` int

  Handling of binary data. See odbc_binmode() for details.

`odbc.default_cursortype` int

  Controls the ODBC cursor model. Possible values are `SQL_CURSOR_FORWARD_ONLY`, `SQL_CURSOR_KEYSET_DRIVEN`, `SQL_CURSOR_DYNAMIC` and `SQL_CURSOR_STATIC` (default).

## 资源类型

Prior to PHP 8.4.0, this extension defined two resource types: an ODBC connection identifier and an ODBC result identifier.

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`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 character string of fixed string length.
`SQL_WVARCHAR` (int)
  Unicode variable-length character string.
`SQL_WLONGVARCHAR` (int)
  Unicode variable-length character data. Maximum length is data source-dependent.
`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)
  Return the first rowset.
`SQL_FETCH_NEXT` (int)
  Return the next rowset.

# ODBC 函数

# odbc_autocommit

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_autocommit — Toggle autocommit behaviour

### 说明

function odbc_autocommit(Odbc\Connection `$odbc`, ?bool `$enable` = `null`): int|bool

Toggles autocommit behaviour.

By default, auto-commit is on for a connection. Disabling auto-commit is equivalent with starting a transaction.

### 参数

`odbc`
  ODBC 连接对象，详见 odbc_connect()。
`enable`

  If `enable` is `true`, auto-commit is enabled, if it is `false` auto-commit is disabled. If `null` is passed, this function returns the auto-commit status for `odbc`.

### 返回值

With a `null` `enable` parameter, this function returns auto-commit status for `odbc`. Non-zero is returned if auto-commit is on, 0 if it is off, or `false` if an error occurs.

If `enable` is non-null, this function returns `true` on success and `false` on failure.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` 现在需要 Odbc\Connection 实例；之前需要 resource。
8.3.0 | `enable` is now nullable.

### 参见

- odbc_commit() - Commit an ODBC transaction
- odbc_rollback() - Rollback a transaction

# odbc_binmode

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_binmode — Handling of binary column data

### 说明

function odbc_binmode(Odbc\Result `$statement`, int `$mode`): true

Controls handling of binary column data. ODBC SQL types affected are `BINARY`, `VARBINARY`, and `LONGVARBINARY`. The default mode can be set using the uodbc.defaultbinmode php.ini directive.

When binary SQL data is converted to character C data (`ODBC_BINMODE_CONVERT`), each byte (8 bits) of source data is represented as two ASCII characters. These characters are the ASCII character representation of the number in its hexadecimal form. For example, a binary `00000001` is converted to `"01"` and a binary `11111111` is converted to `"FF"`.

While the handling of `BINARY` and `VARBINARY` columns only depend on the binmode, the handling of `LONGVARBINARY` columns also depends on the longreadlen as well:

LONGVARBINARY handling
binmode | longreadlen | result
--- | --- | ---
`ODBC_BINMODE_PASSTHRU` | 0 | passthru
`ODBC_BINMODE_RETURN` | 0 | passthru
`ODBC_BINMODE_CONVERT` | 0 | passthru
`ODBC_BINMODE_PASSTHRU` | >0 | passthru
`ODBC_BINMODE_RETURN` | >0 | return as is
`ODBC_BINMODE_CONVERT` | >0 | return as char

If odbc_fetch_into() is used, passthru means that an empty string is returned for these columns. If odbc_result() is used, passthru means that the data are sent directly to the client (i.e. printed).

### 参数

`statement`

  ODBC 结果对象.

`mode`

  Possible values for `mode` are:

  - `ODBC_BINMODE_PASSTHRU`: Passthru BINARY data
  - `ODBC_BINMODE_RETURN`: Return as is
  - `ODBC_BINMODE_CONVERT`: Convert to char and return

  > 注意: Handling of binary long columns is also affected by odbc_longreadlen().

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `statement` 现在需要 Odbc\Result 实例；之前需要 resource。

# odbc_close

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_close — Close an ODBC connection

### 说明

function odbc_close(Odbc\Connection `$odbc`): void

Closes down the connection to the database server.

### 参数

`odbc`
  ODBC 连接对象，详见 odbc_connect()。

### 返回值

没有返回值。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` 现在需要 Odbc\Connection 实例；之前需要 resource。

### 注释

> 注意:

> This function will fail if there are open transactions on this connection. The connection will remain open in this case.

# odbc_close_all

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_close_all — Close all ODBC connections

### 说明

function odbc_close_all(): void

odbc_close_all() will close down all connections to database server(s).

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 注释

> 注意:

> This function will fail if there are open transactions on a connection. This connection will remain open in this case.

# odbc_columnprivileges

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_columnprivileges — Lists columns and associated privileges for the given table

### 说明

function odbc_columnprivileges(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`,
string `$column`
): Odbc\Result|false

Lists columns and associated privileges for the given table.

### 参数

`odbc`
  ODBC 连接对象，详见 odbc_connect()。
`catalog`

  The catalog ('qualifier' in ODBC 2 parlance).

`schema`

  The schema ('owner' in ODBC 2 parlance). 此参数接受下列查询模式： `%` 来匹配零到多个字符， `_` 来匹配单个字符。

`table`

  The table name. 此参数接受下列查询模式： `%` 来匹配零到多个字符， `_` 来匹配单个字符。

`column`

  The column name. 此参数接受下列查询模式： `%` 来匹配零到多个字符， `_` 来匹配单个字符。

### 返回值

返回 ODBC 结果对象 或者在失败时返回 `false`。 This result object can be used to fetch a list of columns and associated privileges.

The result set has the following columns:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `COLUMN_NAME`
- `GRANTOR`
- `GRANTEE`
- `PRIVILEGE`
- `IS_GRANTABLE`

Drivers can report additional columns.

The result set is ordered by `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME`, `COLUMN_NAME` and `PRIVILEGE`.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` 现在需要 Odbc\Connection 实例；之前需要 resource。

### 示例

示例 #1 List Privileges for a Column

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $privileges = odbc_columnprivileges($conn, 'TutorialDB', 'dbo', 'test', 'id');
    while (($row = odbc_fetch_array($privileges))) {
        print_r($row);
        break; // further rows omitted for brevity
    }
    ?>

以上示例的输出类似于：

    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

### 说明

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.

### 参数

`odbc`
  ODBC 连接对象，详见 odbc_connect()。
`catalog`

  The catalog ('qualifier' in ODBC 2 parlance).

`schema`

  The schema ('owner' in ODBC 2 parlance). 此参数接受下列查询模式： `%` 来匹配零到多个字符， `_` 来匹配单个字符。

`table`

  The table name. 此参数接受下列查询模式： `%` 来匹配零到多个字符， `_` 来匹配单个字符。

`column`

  The column name. 此参数接受下列查询模式： `%` 来匹配零到多个字符， `_` 来匹配单个字符。

### 返回值

返回 ODBC 结果对象 或者在失败时返回 `false`。

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`

Drivers can report additional columns.

The result set is ordered by `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME` and `ORDINAL_POSITION`.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` 现在需要 Odbc\Connection 实例；之前需要 resource。
8.0.0 | `schema`, `table` and `column` are now nullable.

### 示例

示例 #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
    }
    ?>

以上示例的输出类似于：

    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
    )

### 参见

- odbc_columnprivileges() - Lists columns and associated privileges for the given table
- odbc_procedurecolumns() - Retrieve information about parameters to procedures

# odbc_commit

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_commit — Commit an ODBC transaction

### 说明

function odbc_commit(Odbc\Connection `$odbc`): bool

Commits all pending transactions on the connection.

### 参数

`odbc`
  ODBC 连接对象，详见 odbc_connect()。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` 现在需要 Odbc\Connection 实例；之前需要 resource。

# odbc_connect

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_connect — Connect to a datasource

### 说明

function odbc_connect(
string `$dsn`,
?string `$user` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
int `$cursor_option` = `SQL_CUR_USE_DRIVER`
): Odbc\Connection|false

The connection id returned by this functions is needed by other ODBC functions. You can have multiple connections open at once as long as they either use different db or different credentials.

With some ODBC drivers, executing a complex stored procedure may fail with an error similar to: "Cannot open a cursor on a stored procedure that has anything other than a single select statement in it". Using SQL_CUR_USE_ODBC may avoid that error. Also, some drivers don't support the optional row_number parameter in odbc_fetch_row(). SQL_CUR_USE_ODBC might help in that case, too.

### 参数

`dsn`

  The database source name for the connection. Alternatively, a DSN-less connection string can be used.

`user`

  The username. This parameter is ignored if `dsn` contains `uid`. To connect without specifying a `user`, use `null`.

`password`

  The password. This parameter is ignored if `dsn` contains `pwd`. To connect without specifying a `password`, use `null`.

`cursor_option`

  This sets the type of cursor to be used for this connection. This parameter is not normally needed, but can be useful for working around problems with some ODBC drivers.

  The following constants are defined for cursortype:

  - SQL_CUR_USE_IF_NEEDED
  - SQL_CUR_USE_ODBC
  - SQL_CUR_USE_DRIVER

### 返回值

Returns an ODBC connection, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 此函数现在返回 Odbc\Connection 实例；之前返回 resource。
8.4.0 | `user` and `password` are now nullable, they are now also optional and default to `null`.
8.4.0 | Previously, using an empty string for `password` would not include `pwd` in the generated connection string for `dsn`. It is now generated to include a `pwd` which has an empty string as its value. To restore the previous behaviour `password` can now be set to `null`.
8.4.0 | Previously, if `dsn` contained `uid` or `pwd` both `user` and `password` parameters were ignored. Now `user` is only ignored if `dsn` contains `uid`, and `password` is only ignored if `dsn` contains `pwd`.

### 示例

示例 #1 DSN-less connections

    <?php
    // Microsoft SQL Server using the SQL Native Client 10.0 ODBC Driver - allows connection to SQL 7, 2000, 2005 and 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" , '', '');
    ?>

### 参见

- For persistent connections: odbc_pconnect() - Open a persistent database connection

# odbc_connection_string_is_quoted

(PHP 8 >= 8.2.0)

odbc_connection_string_is_quoted — Determines if an ODBC connection string value is quoted

### 说明

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.

### 参数

`str`

  The string to check for quoting.

### 返回值

`true` if quoted properly, `false` if not.

### 参见

- 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

### 说明

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().

### 参数

`str`

  The unquoted string.

### 返回值

A quoted string, surrounded by curly braces, and properly escaped.

### 示例

示例 #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;
    ?>

以上示例的输出类似于：

    DSN=PHP;UserValue={foo}}bar}

### 参见

- 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

### 说明

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.

### 参数

`str`

  The string to check for.

### 返回值

`true` if the string should be quoted; `false` otherwise.

### 参见

- 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 — Get cursorname

### 说明

function odbc_cursor(Odbc\Result `$statement`): string|false

Gets the cursorname for the given result_id.

### 参数

`statement`

  ODBC 结果对象.

### 返回值

Returns the cursor name, as a string, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `statement` 现在需要 Odbc\Result 实例；之前需要 resource。

# odbc_data_source

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

odbc_data_source — Returns information about available DSNs

### 说明

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).

### 参数

`odbc`
  ODBC 连接对象，详见 odbc_connect()。
`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`.

### 返回值

Returns `false` on error, an array upon success, and `null` after fetching the last available DSN.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` 现在需要 Odbc\Connection 实例；之前需要 resource。

### 示例

示例 #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);
    }
    ?>

以上示例的输出类似于：

    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 — 别名 odbc_exec()

### 说明

此函数是该函数的别名： odbc_exec().

# odbc_error

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_error — Get the last error code

### 说明

function odbc_error(?Odbc\Connection `$odbc` = `null`): string

Returns a six-digit ODBC state, or an empty string if there has been no errors.

### 参数

`odbc`
  ODBC 连接对象，详见 odbc_connect()。

### 返回值

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`).

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` 现在需要 Odbc\Connection 实例；之前需要 resource。
8.0.0 | `odbc` is now nullable.

### 参见

- odbc_errormsg() - Get the last error message
- odbc_exec() - Directly execute an SQL statement

# odbc_errormsg

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_errormsg — Get the last error message

### 说明

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.

### 参数

`odbc`
  ODBC 连接对象，详见 odbc_connect()。

### 返回值

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`).

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` 现在需要 Odbc\Connection 实例；之前需要 resource。
8.0.0 | `odbc` is now nullable.

### 参见

- odbc_error() - Get the last error code
- odbc_exec() - Directly execute an SQL statement

# odbc_exec

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_exec — Directly execute an SQL statement

### 说明

function odbc_exec(Odbc\Connection `$odbc`, string `$query`): Odbc\Result|false

Sends an SQL statement to the database server.

### 参数

`odbc`
  ODBC 连接对象，详见 odbc_connect()。
`query`

  The SQL statement.

### 返回值

返回 ODBC 结果对象 if the SQL command was executed successfully, or `false` on error.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` 现在需要 Odbc\Connection 实例；之前需要 resource。
8.4.0 | 此函数现在返回 Odbc\Result 实例；之前返回 resource。
8.0.0 | `flags` was removed.

### 参见

- odbc_prepare() - Prepares a statement for execution
- odbc_execute() - Execute a prepared statement

# odbc_execute

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_execute — Execute a prepared statement

### 说明

function odbc_execute(Odbc\Result `$statement`, array `$params` = []): bool

Executes a statement prepared with odbc_prepare().

### 参数

`statement`

  ODBC 结果对象 from odbc_prepare().

`params`

  Parameters in `params` will be substituted for placeholders in the prepared statement in order. Elements of this array will be converted to strings by calling this function.

  Any parameters in `params` which start and end with single quotes will be taken as the name of a file to read and send to the database server as the data for the appropriate placeholder.

  If you wish to store a string which actually begins and ends with single quotes, you must add a space or other non-single-quote character to the beginning or end of the parameter, which will prevent the parameter from being taken as a file name. If this is not an option, then you must use another mechanism to store the string, such as executing the query directly with odbc_exec()).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 此函数现在返回 Odbc\Result 实例；之前返回 resource。
8.0.0 | The unused `flags` parameter was removed.

### 示例

示例 #1 odbc_execute() and odbc_prepare() example

In the following code, $success will only be `true` if all three parameters to myproc are IN parameters:

    <?php
    $a = 1;
    $b = 2;
    $c = 3;
    $stmt    = odbc_prepare($conn, 'CALL myproc(?,?,?)');
    $success = odbc_execute($stmt, array($a, $b, $c));
    ?>

If you need to call a stored procedure using INOUT or OUT parameters, the recommended workaround is to use a native extension for your database (for example, oci8 for Oracle).

### 参见

- odbc_prepare() - Prepares a statement for execution

# 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

### 说明

function odbc_fetch_array(Odbc\Result `$statement`, ?int `$row` = `null`): array|false

Fetch an associative array from an ODBC query.

### 参数

`statement`

  ODBC 结果对象 from odbc_exec().

`row`

  Optionally choose which row number to retrieve.

### 返回值

Returns an array that corresponds to the fetched row, or `false` if there are no more rows.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `statement` 现在需要 Odbc\Result 实例；之前需要 resource。
8.4.0 | `row` is now nullable.

### 注释

> 注意: This function exists when compiled with DBMaker, IBM DB2 or UnixODBC support.

### 参见

- odbc_fetch_row() - Fetch a row
- odbc_fetch_object() - Fetch a result row as an object
- odbc_num_rows() - Number of rows in a result

# odbc_fetch_into

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_fetch_into — Fetch one result row into array

### 说明

function odbc_fetch_into(Odbc\Result `$statement`, array `&$array`, ?int `$row` = `null`): int|false

Fetch one result row into array.

### 参数

`statement`

  ODBC 结果对象.

`array`

  The result array that can be of any type since it will be converted to type array. The array will contain the column values starting at array index 0.

`row`

  The row number.

### 返回值

Returns the number of columns in the result; `false` on error.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `statement` 现在需要 Odbc\Result 实例；之前需要 resource。
8.4.0 | `row` is now nullable.

### 示例

示例 #1 odbc_fetch_into() examples

    <?php
    $rc = odbc_fetch_into($res_id, $my_array);
    ?>

or

    <?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

### 说明

function odbc_fetch_object(Odbc\Result `$statement`, ?int `$row` = `null`): stdClass|false

Fetch an object from an ODBC query.

### 参数

`statement`

  ODBC 结果对象 from odbc_exec().

`row`

  Optionally choose which row number to retrieve.

### 返回值

Returns an object that corresponds to the fetched row, or `false` if there are no more rows.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `statement` 现在需要 Odbc\Result 实例；之前需要 resource。
8.4.0 | `row` is now nullable.

### 注释

> 注意: This function exists when compiled with DBMaker, IBM DB2 or UnixODBC support.

### 参见

- odbc_fetch_row() - Fetch a row
- odbc_fetch_array() - Fetch a result row as an associative array
- odbc_num_rows() - Number of rows in a result

# odbc_fetch_row

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_fetch_row — Fetch a row

### 说明

function odbc_fetch_row(Odbc\Result `$statement`, ?int `$row` = `null`): bool

Fetches a row of the data that was returned by odbc_do() or odbc_exec(). After odbc_fetch_row() is called, the fields of that row can be accessed with odbc_result().

### 参数

`statement`

  ODBC 结果对象.

`row`

  If `row` is not specified, odbc_fetch_row() will try to fetch the next row in the result set. Calls to odbc_fetch_row() with and without `row` can be mixed.

  To step through the result more than once, you can call odbc_fetch_row() with `row` 1, and then continue doing odbc_fetch_row() without `row` to review the result. If a driver doesn't support fetching rows by number, the `row` parameter is ignored.

### 返回值

Returns `true` if there was a row, `false` otherwise.

### 错误／异常

An `E_WARNING` is emitted when `row` is equal or less than zero.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `statement` 现在需要 Odbc\Result 实例；之前需要 resource。
8.4.0 | An `E_WARNING` is now emitted when `row` is equal or less than zero.
8.0.0 | `row` is now nullable.

# odbc_field_len

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_len — Get the length (precision) of a field

### 说明

function odbc_field_len(Odbc\Result `$statement`, int `$field`): int|false

Gets the length of the field referenced by number in the given result identifier.

### 参数

`statement`

  ODBC 结果对象.

`field`

  The field number. Field numbering starts at 1.

### 返回值

Returns the field length, or `false` on error.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `statement` 现在需要 Odbc\Result 实例；之前需要 resource。

### 参见

- odbc_field_scale() - Get the scale of a field to get the scale of a floating point number

# odbc_field_name

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_name — Get the columnname

### 说明

function odbc_field_name(Odbc\Result `$statement`, int `$field`): string|false

Gets the name of the field occupying the given column number in the given result object.

### 参数

`statement`

  ODBC 结果对象.

`field`

  The field number. Field numbering starts at 1.

### 返回值

Returns the field name as a string, or `false` on error.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `statement` 现在需要 Odbc\Result 实例；之前需要 resource。

# odbc_field_num

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_num — Return column number

### 说明

function odbc_field_num(Odbc\Result `$statement`, string `$field`): int|false

Gets the number of the column slot that corresponds to the named field in the given result object.

### 参数

`statement`

  ODBC 结果对象.

`field`

  The field name.

### 返回值

Returns the field number as an integer, or `false` on error. Field numbering starts at 1.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `statement` 现在需要 Odbc\Result 实例；之前需要 resource。

# odbc_field_precision

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_precision — 别名 odbc_field_len()

### 说明

此函数是该函数的别名： odbc_field_len().

### 参见

- 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

### 说明

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.

### 参数

`statement`

  ODBC 结果对象.

`field`

  The field number. Field numbering starts at 1.

### 返回值

Returns the field scale as an integer, or `false` on error.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `statement` 现在需要 Odbc\Result 实例；之前需要 resource。

# odbc_field_type

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_type — Datatype of a field

### 说明

function odbc_field_type(Odbc\Result `$statement`, int `$field`): string|false

Gets the SQL type of the field referenced by number in the given result identifier.

### 参数

`statement`

  ODBC 结果对象.

`field`

  The field number. Field numbering starts at 1.

### 返回值

Returns the field type as a string, or `false` on error.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `statement` 现在需要 Odbc\Result 实例；之前需要 resource。

# odbc_foreignkeys

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_foreignkeys — Retrieves a list of foreign keys

### 说明

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

### 参数

`odbc`
  ODBC 连接对象，详见 odbc_connect()。
`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.

### 返回值

返回 ODBC 结果对象 或者在失败时返回 `false`。

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`

Drivers can report additional columns.

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.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` 现在需要 Odbc\Connection 实例；之前需要 resource。
8.4.0 | 此函数现在返回 Odbc\Result 实例；之前返回 resource。

### 参见

- 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 — Free objects associated with a result

### 说明

function odbc_free_result(Odbc\Result `$statement`): true

Free objects associated with a result.

odbc_free_result() only needs to be called if you are worried about using too much memory while your script is running. All result memory will automatically be freed when the script is finished.

### 参数

`statement`

  ODBC 结果对象.

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `statement` 现在需要 Odbc\Result 实例；之前需要 resource。

### 注释

> 注意:

> If auto-commit is disabled (see odbc_autocommit()) and you call odbc_free_result() before committing, all pending transactions are rolled back.

# odbc_gettypeinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_gettypeinfo — Retrieves information about data types supported by the data source

### 说明

function odbc_gettypeinfo(Odbc\Connection `$odbc`, int `$data_type` = 0): Odbc\Result|false

Retrieves information about data types supported by the data source.

### 参数

`odbc`
  ODBC 连接对象，详见 odbc_connect()。
`data_type`

  The data type, which can be used to restrict the information to a single data type.

### 返回值

返回 ODBC 结果对象 或者在失败时返回 `false`。

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.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` 现在需要 Odbc\Connection 实例；之前需要 resource。
8.4.0 | 此函数现在返回 Odbc\Result 实例；之前返回 resource。

# odbc_longreadlen

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_longreadlen — Handling of LONG columns

### 说明

function odbc_longreadlen(Odbc\Result `$statement`, int `$length`): true

Controls handling of `LONG`, `LONGVARCHAR` and `LONGVARBINARY` columns. The default length can be set using the uodbc.defaultlrl php.ini directive.

### 参数

`statement`

  ODBC 结果对象.

`length`

  The number of bytes returned to PHP is controlled by the parameter length. If it is set to `0`, long column data is passed through to the client (i.e. printed) when retrieved with odbc_result().

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `statement` 现在需要 Odbc\Result 实例；之前需要 resource。

### 注释

> 注意:

> Handling of `LONGVARBINARY` columns is also affected by odbc_binmode().

# odbc_next_result

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_next_result — Checks if multiple results are available

### 说明

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.

### 参数

`statement`

  ODBC 结果对象.

### 返回值

Returns `true` if there are more result sets, `false` otherwise.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `statement` 现在需要 Odbc\Result 实例；之前需要 resource。

### 示例

示例 #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));
    ?>

以上示例会输出：

    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 — Number of columns in a result

### 说明

function odbc_num_fields(Odbc\Result `$statement`): int

Gets the number of fields (columns) in an ODBC result.

### 参数

`statement`

  ODBC 结果对象 returned by odbc_exec().

### 返回值

Returns the number of fields, or -1 on error.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `statement` 现在需要 Odbc\Result 实例；之前需要 resource。

# odbc_num_rows

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_num_rows — Number of rows in a result

### 说明

function odbc_num_rows(Odbc\Result `$statement`): int

Gets the number of rows in a result. For INSERT, UPDATE and DELETE statements odbc_num_rows() returns the number of rows affected. For a SELECT clause this can be the number of rows available.

### 参数

`statement`

  ODBC 结果对象 returned by odbc_exec().

### 返回值

Returns the number of rows in an ODBC result. This function will return -1 on error.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `statement` 现在需要 Odbc\Result 实例；之前需要 resource。

### 注释

> 注意:

> Using odbc_num_rows() to determine the number of rows available after a SELECT will return -1 with many drivers.

# odbc_pconnect

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_pconnect — Open a persistent database connection

### 说明

function odbc_pconnect(
string `$dsn`,
?string `$user` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
int `$cursor_option` = `SQL_CUR_USE_DRIVER`
): Odbc\Connection|false

Opens a persistent database connection.

This function is much like odbc_connect(), except that the connection is not really closed when the script has finished. Future requests for a connection with the same `dsn`, `user`, `password` combination (via odbc_connect() and odbc_pconnect()) can reuse the persistent connection.

### 参数

See odbc_connect() for details.

### 返回值

Returns an ODBC connection, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 此函数现在返回 Odbc\Connection 实例；之前返回 resource。
8.4.0 | `user` and `password` are now nullable, they are now also optional and default to `null`.
8.4.0 | Previously, using an empty string for `password` would not include `pwd` in the generated connection string for `dsn`. It is now generated to include a `pwd` which has an empty string as its value. To restore the previous behaviour `password` can now be set to `null`.
8.4.0 | Previously, if `dsn` contained `uid` or `pwd` both `user` and `password` parameters were ignored. Now `user` is only ignored if `dsn` contains `uid`, and `password` is only ignored if `dsn` contains `pwd`.

### 注释

> 注意: Persistent connections have no effect if PHP is used as a CGI program.

### 参见

- odbc_connect() - Connect to a datasource
- Persistent Database Connections

# odbc_prepare

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_prepare — Prepares a statement for execution

### 说明

function odbc_prepare(Odbc\Connection `$odbc`, string `$query`): Odbc\Result|false

Prepares a statement for execution. ODBC 结果对象 can be used later to execute the statement with odbc_execute().

Some databases (such as IBM DB2, MS SQL Server, and Oracle) support stored procedures that accept parameters of type IN, INOUT, and OUT as defined by the ODBC specification. However, the Unified ODBC driver currently only supports parameters of type IN to stored procedures.

### 参数

`odbc`
  ODBC 连接对象，详见 odbc_connect()。
`query`

  The query string statement being prepared.

### 返回值

返回 ODBC 结果对象 if the SQL command was prepared successfully. Returns `false` on error.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` 现在需要 Odbc\Connection 实例；之前需要 resource。
8.4.0 | 此函数现在返回 Odbc\Result 实例；之前返回 resource。

### 示例

示例 #1 odbc_execute() and odbc_prepare() example

In the following code, $success will only be `true` if all three parameters to myproc are IN parameters:

    <?php
    $a = 1;
    $b = 2;
    $c = 3;
    $stmt    = odbc_prepare($conn, 'CALL myproc(?,?,?)');
    $success = odbc_execute($stmt, array($a, $b, $c));
    ?>

If you need to call a stored procedure using INOUT or OUT parameters, the recommended workaround is to use a native extension for your database (for example, oci8 for Oracle).

### 参见

- odbc_execute() - Execute a prepared statement

# odbc_primarykeys

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_primarykeys — Gets the primary keys for a table

### 说明

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.

### 参数

`odbc`
  ODBC 连接对象，详见 odbc_connect()。
`catalog`

  The catalog ('qualifier' in ODBC 2 parlance).

`schema`

  The schema ('owner' in ODBC 2 parlance).

`table`

### 返回值

返回 ODBC 结果对象 或者在失败时返回 `false`。

The result set has the following columns:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `COLUMN_NAME`
- `KEY_SEQ`
- `PK_NAME`

Drivers can report additional columns.

The result set is ordered by `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME` and `KEY_SEQ`.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` 现在需要 Odbc\Connection 实例；之前需要 resource。
8.4.0 | 此函数现在返回 Odbc\Result 实例；之前返回 resource。

### 示例

示例 #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
    }
    ?>

以上示例的输出类似于：

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => TEST
        [COLUMN_NAME] => id
        [KEY_SEQ] => 1
        [PK_NAME] => PK__TEST__3213E83FE141F843
    )

### 参见

- 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

### 说明

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.

### 参数

`odbc`
  ODBC 连接对象，详见 odbc_connect()。
`catalog`

  The catalog ('qualifier' in ODBC 2 parlance).

`schema`

  The schema ('owner' in ODBC 2 parlance). 此参数接受下列查询模式： `%` 来匹配零到多个字符， `_` 来匹配单个字符。

`procedure`

  The proc. 此参数接受下列查询模式： `%` 来匹配零到多个字符， `_` 来匹配单个字符。

`column`

  The column. 此参数接受下列查询模式： `%` 来匹配零到多个字符， `_` 来匹配单个字符。

### 返回值

Returns the list of input and output parameters, as well as the columns that make up the result set for the specified procedures. 返回 ODBC 结果对象 或者在失败时返回 `false`。

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`

Drivers can report additional columns.

The result set is ordered by `PROCEDURE_CAT`, `PROCEDURE_SCHEM`, `PROCEDURE_NAME` and `COLUMN_TYPE`.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` 现在需要 Odbc\Connection 实例；之前需要 resource。
8.4.0 | 此函数现在返回 Odbc\Result 实例；之前返回 resource。
8.0.0 | Prior to this version, the function could only be called with either one or five arguments.

### 示例

示例 #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
    }
    ?>

以上示例的输出类似于：

    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
    )

### 参见

- 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

### 说明

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.

### 参数

`odbc`
  ODBC 连接对象，详见 odbc_connect()。
`catalog`

  The catalog ('qualifier' in ODBC 2 parlance).

`schema`

  The schema ('owner' in ODBC 2 parlance). 此参数接受下列查询模式： `%` 来匹配零到多个字符， `_` 来匹配单个字符。

`procedure`

  The name. 此参数接受下列查询模式： `%` 来匹配零到多个字符， `_` 来匹配单个字符。

### 返回值

返回 ODBC 结果对象 containing the information 或者在失败时返回 `false`.

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`

Drivers can report additional columns.

The result set is ordered by `PROCEDURE_CAT`, `PROCEDURE_SCHEMA` and `PROCEDURE_NAME`.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` 现在需要 Odbc\Connection 实例；之前需要 resource。
8.4.0 | 此函数现在返回 Odbc\Result 实例；之前返回 resource。
8.0.0 | Prior to this version, the function could only be called with either one or four arguments.

### 示例

示例 #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
    }
    ?>

以上示例的输出类似于：

    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
    )

### 参见

- 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 — Get result data

### 说明

function odbc_result(Odbc\Result `$statement`, string|int `$field`): string|bool|null

Get result data

### 参数

`statement`

  ODBC 结果对象.

`field`

  The field name being retrieved. It can either be an integer containing the column number of the field you want; or it can be a string containing the name of the field.

### 返回值

Returns the string contents of the field, `false` on error, `null` for NULL data, or `true` for binary data.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `statement` 现在需要 Odbc\Result 实例；之前需要 resource。

### 示例

The first call to odbc_result() returns the value of the third field in the current record of the query result. The second function call to odbc_result() returns the value of the field whose field name is "val" in the current record of the query result. An error occurs if a column number parameter for a field is less than one or exceeds the number of columns (or fields) in the current record. Similarly, an error occurs if a field with a name that is not one of the fieldnames of the table(s) that is(are) being queried.

示例 #1 odbc_result() examples

    <?php
    $item_3   = odbc_result($Query_ID, 3);
    $item_val = odbc_result($Query_ID, "val");
    ?>

### 注释

Field indices start from 1. Regarding the way binary or long column data is returned refer to odbc_binmode() and odbc_longreadlen().

# odbc_result_all

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_result_all — Print result as HTML table

警告

此函数自 PHP 8.1.0 起弃用。强烈建议不要应用此函数。

### 说明

#[\Deprecated]
function odbc_result_all(Odbc\Result `$statement`, string `$format` = ""): int|false

Prints all rows from a result object produced by odbc_exec(). The result is printed in HTML table format. The data is not escaped.

This function is not supposed to be used in production environments; it is merely meant for development purposes, to get a result set quickly rendered.

### 参数

`statement`

  ODBC 结果对象.

`format`

  Additional overall table formatting.

### 返回值

Returns the number of rows in the result or `false` on error.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `statement` 现在需要 Odbc\Result 实例；之前需要 resource。
8.1.0 | This function has been deprecated.

# odbc_rollback

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_rollback — Rollback a transaction

### 说明

function odbc_rollback(Odbc\Connection `$odbc`): bool

Rolls back all pending statements on the connection.

### 参数

`odbc`
  ODBC 连接对象，详见 odbc_connect()。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` 现在需要 Odbc\Connection 实例；之前需要 resource。

# odbc_setoption

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_setoption — Adjust ODBC settings

### 说明

function odbc_setoption(
Odbc\Connection|Odbc\Result `$odbc`,
int `$which`,
int `$option`,
int `$value`
): bool

This function allows fiddling with the ODBC options for a particular connection or query result. It was written to help find work around to problems in quirky ODBC drivers. You should probably only use this function if you are an ODBC programmer and understand the effects the various options will have. You will certainly need a good ODBC reference to explain all the different options and values that can be used. Different driver versions support different options.

Because the effects may vary depending on the ODBC driver, use of this function in scripts to be made publicly available is strongly discouraged. Also, some ODBC options are not available to this function because they must be set before the connection is established or the query is prepared. However, if on a particular job it can make PHP work so your boss doesn't tell you to use a commercial product, that's all that really matters.

### 参数

`odbc`

  Is a connection id or result id on which to change the settings. For SQLSetConnectOption(), this is a connection id. For SQLSetStmtOption(), this is a result id.

`which`

  Is the ODBC function to use. The value should be 1 for SQLSetConnectOption() and 2 for SQLSetStmtOption().

`option`

  The option to set.

`value`

  The value for the given `option`.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` expects an Odbc\Connection or an Odbc\Result instance now; previously, a resource was expected.

### 示例

示例 #1 odbc_setoption() examples

    <?php
    // 1. Option 102 of SQLSetConnectOption() is SQL_AUTOCOMMIT.
    //    Value 1 of SQL_AUTOCOMMIT is SQL_AUTOCOMMIT_ON.
    //    This example has the same effect as
    //    odbc_autocommit($conn, true);

    odbc_setoption($conn, 1, 102, 1);

    // 2. Option 0 of SQLSetStmtOption() is SQL_QUERY_TIMEOUT.
    //    This example sets the query to timeout after 30 seconds.

    $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

### 说明

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.

### 参数

`odbc`
  ODBC 连接对象，详见 odbc_connect()。
`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`

  The catalog ('qualifier' in ODBC 2 parlance).

`schema`

  The schema ('owner' in ODBC 2 parlance).

`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`.

### 返回值

返回 ODBC 结果对象 或者在失败时返回 `false`。

The result set has the following columns:

- `SCOPE`
- `COLUMN_NAME`
- `DATA_TYPE`
- `TYPE_NAME`
- `COLUMN_SIZE`
- `BUFFER_LENGTH`
- `DECIMAL_DIGITS`
- `PSEUDO_COLUMN`

Drivers can report additional columns.

The result set is ordered by `SCOPE`.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` 现在需要 Odbc\Connection 实例；之前需要 resource。
8.4.0 | 此函数现在返回 Odbc\Result 实例；之前返回 resource。

### 参见

- 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

### 说明

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.

### 参数

`odbc`
  ODBC 连接对象，详见 odbc_connect()。
`catalog`

  The catalog ('qualifier' in ODBC 2 parlance).

`schema`

  The schema ('owner' in ODBC 2 parlance).

`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.

### 返回值

返回 ODBC 结果对象 或者在失败时返回 `false`。

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`

Drivers can report additional columns.

The result set is ordered by `NON_UNIQUE`, `TYPE`, `INDEX_QUALIFIER`, `INDEX_NAME` and `ORDINAL_POSITION`.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` 现在需要 Odbc\Connection 实例；之前需要 resource。
8.4.0 | 此函数现在返回 Odbc\Result 实例；之前返回 resource。

### 示例

示例 #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
    }
    ?>

以上示例的输出类似于：

    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] =>
    )

### 参见

- 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

### 说明

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.

### 参数

`odbc`
  ODBC 连接对象，详见 odbc_connect()。
`catalog`

  The catalog ('qualifier' in ODBC 2 parlance).

`schema`

  The schema ('owner' in ODBC 2 parlance). 此参数接受下列查询模式： `%` 来匹配零到多个字符， `_` 来匹配单个字符。

`table`

  The name. 此参数接受下列查询模式： `%` 来匹配零到多个字符， `_` 来匹配单个字符。

### 返回值

返回 ODBC 结果对象 或者在失败时返回 `false`。

The result set has the following columns:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `GRANTOR`
- `GRANTEE`
- `PRIVILEGE`
- `IS_GRANTABLE`

Drivers can report additional columns.

The result set is ordered by `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME`, `PRIVILEGE` and `GRANTEE`.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` 现在需要 Odbc\Connection 实例；之前需要 resource。
8.4.0 | 此函数现在返回 Odbc\Result 实例；之前返回 resource。

### 示例

示例 #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
    }
    ?>

以上示例的输出类似于：

    Array
    (
        [TABLE_CAT] => SalesOrders
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => Orders
        [GRANTOR] => dbo
        [GRANTEE] => dbo
        [PRIVILEGE] => DELETE
        [IS_GRANTABLE] => YES
    )

### 参见

- 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

### 说明

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.)

### 参数

`odbc`
  ODBC 连接对象，详见 odbc_connect()。
`catalog`

  The catalog ('qualifier' in ODBC 2 parlance).

`schema`

  The schema ('owner' in ODBC 2 parlance). 此参数接受下列查询模式： `%` 来匹配零到多个字符， `_` 来匹配单个字符。

`table`

  The name. 此参数接受下列查询模式： `%` 来匹配零到多个字符， `_` 来匹配单个字符。

`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.

### 返回值

返回 ODBC 结果对象 containing the information 或者在失败时返回 `false`.

The result set has the following columns:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `TABLE_TYPE`
- `REMARKS`

Drivers can report additional columns.

The result set is ordered by `TABLE_TYPE`, `TABLE_CAT`, `TABLE_SCHEM` and `TABLE_NAME`.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `odbc` 现在需要 Odbc\Connection 实例；之前需要 resource。
8.4.0 | 此函数现在返回 Odbc\Result 实例；之前返回 resource。
8.0.0 | `schema`, `table` and `types` are now nullable.

### 示例

示例 #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
    }
    ?>

以上示例的输出类似于：

    Array
    (
        [TABLE_CAT] => SalesOrders
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => Orders
        [TABLE_TYPE] => TABLE
        [REMARKS] =>
    )

### 参见

- 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

## 目录

- odbc_autocommit — Toggle autocommit behaviour
- odbc_binmode — Handling of binary column data
- odbc_close — Close an ODBC connection
- odbc_close_all — Close all ODBC connections
- odbc_columnprivileges — Lists columns and associated privileges for the given table
- odbc_columns — Lists the column names in specified tables
- odbc_commit — Commit an ODBC transaction
- odbc_connect — Connect to a datasource
- 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 — Get cursorname
- odbc_data_source — Returns information about available DSNs
- odbc_do — 别名 odbc_exec
- odbc_error — Get the last error code
- odbc_errormsg — Get the last error message
- odbc_exec — Directly execute an SQL statement
- odbc_execute — Execute a prepared statement
- odbc_fetch_array — Fetch a result row as an associative array
- odbc_fetch_into — Fetch one result row into array
- odbc_fetch_object — Fetch a result row as an object
- odbc_fetch_row — Fetch a row
- odbc_field_len — Get the length (precision) of a field
- odbc_field_name — Get the columnname
- odbc_field_num — Return column number
- odbc_field_precision — 别名 odbc_field_len
- odbc_field_scale — Get the scale of a field
- odbc_field_type — Datatype of a field
- odbc_foreignkeys — Retrieves a list of foreign keys
- odbc_free_result — Free objects associated with a result
- odbc_gettypeinfo — Retrieves information about data types supported by the data source
- odbc_longreadlen — Handling of LONG columns
- odbc_next_result — Checks if multiple results are available
- odbc_num_fields — Number of columns in a result
- odbc_num_rows — Number of rows in a result
- odbc_pconnect — Open a persistent database connection
- odbc_prepare — Prepares a statement for execution
- 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 — Get result data
- odbc_result_all — Print result as HTML table
- odbc_rollback — Rollback a transaction
- odbc_setoption — Adjust ODBC settings
- 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

# The Odbc\Connection class

(PHP 8 >= 8.4.0)

## 简介

A fully opaque class which replaces an `odbc_connection` resource as of PHP 8.4.0.

## 类摘要

namespace Odbc;
class Connection {
}

# The Odbc\Result class

(PHP 8 >= 8.4.0)

## 简介

A fully opaque class which replaces an `odbc_result` resource as of PHP 8.4.0.

## 类摘要

namespace Odbc;
class Result {
}

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
  - 资源类型
- 预定义常量
- ODBC 函数
  - odbc_autocommit — Toggle autocommit behaviour
  - odbc_binmode — Handling of binary column data
  - odbc_close — Close an ODBC connection
  - odbc_close_all — Close all ODBC connections
  - odbc_columnprivileges — Lists columns and associated privileges for the given table
  - odbc_columns — Lists the column names in specified tables
  - odbc_commit — Commit an ODBC transaction
  - odbc_connect — Connect to a datasource
  - 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 — Get cursorname
  - odbc_data_source — Returns information about available DSNs
  - odbc_do — 别名 odbc_exec
  - odbc_error — Get the last error code
  - odbc_errormsg — Get the last error message
  - odbc_exec — Directly execute an SQL statement
  - odbc_execute — Execute a prepared statement
  - odbc_fetch_array — Fetch a result row as an associative array
  - odbc_fetch_into — Fetch one result row into array
  - odbc_fetch_object — Fetch a result row as an object
  - odbc_fetch_row — Fetch a row
  - odbc_field_len — Get the length (precision) of a field
  - odbc_field_name — Get the columnname
  - odbc_field_num — Return column number
  - odbc_field_precision — 别名 odbc_field_len
  - odbc_field_scale — Get the scale of a field
  - odbc_field_type — Datatype of a field
  - odbc_foreignkeys — Retrieves a list of foreign keys
  - odbc_free_result — Free objects associated with a result
  - odbc_gettypeinfo — Retrieves information about data types supported by the data source
  - odbc_longreadlen — Handling of LONG columns
  - odbc_next_result — Checks if multiple results are available
  - odbc_num_fields — Number of columns in a result
  - odbc_num_rows — Number of rows in a result
  - odbc_pconnect — Open a persistent database connection
  - odbc_prepare — Prepares a statement for execution
  - 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 — Get result data
  - odbc_result_all — Print result as HTML table
  - odbc_rollback — Rollback a transaction
  - odbc_setoption — Adjust ODBC settings
  - 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
- Odbc\Connection — The Odbc\Connection class
- Odbc\Result — The Odbc\Result class

# PHP 数据对象

# 简介

`PHP 数据对象`（PDO）扩展为 PHP 访问数据库定义了一个轻量级的一致接口。实现 PDO 接口的每个数据库驱动可以将特定具体数据库的特性公开作为标准扩展函数。注意不能单独使用 PDO 扩展执行任何数据库功能；必须使用具体数据库的 PDO 驱动程序来访问数据库服务器。

PDO 提供了数据访问抽象层，这意味着，不管使用哪种数据库，都可以用相同的函数来查询和获取数据。PDO 不提供数据库抽象；不会重写 SQL 或模拟缺失的特性。如果需要，应该使用成熟的抽象层。

PDO 随 PHP 一起提供。

# 安装/配置

## 目录

- 安装
- 运行时配置

## 安装

此扩展默认为启用，编译时可通过下列选项禁用： --disable-pdo

在 Unix 系统上安装 PDO

1. PDO 和 PDO_SQLITE 驱动默认可用。对所选的数据库应启用相应的 POD 驱动；查阅特定数据库的 PDO 驱动文档获取更多内容。

   > 注意:

   > 当以共享扩展（不推荐）构建 PDO 时，所有 PDO 驱动必须在 PDO 自身之后加载。

2. 当作为共享模块安装 PDO 时，需要更新 php.ini 文件以便 PHP 运行时能自动加载 PDO 扩展。还需在文件启用数据库专用驱动；确保这些驱动列在 extension=pdo 那一行之后，因为 PDO 必须在数据库专用扩展载入前完成初始化。如果以静态方式构建 PDO 和数据库专用扩展，此步骤可省略。

       extension=pdo

Windows 用户

1. PDO 默认启用。选择其他数据库专用 DLL 文件，可在运行时用 dl() 载入，或在 php.ini 中启用。例如以下配置加载了 PDO_SQLITE 驱动，但将 PDO_ODBC 驱动处于注释状态：

       ;extension=pdo_odbc
       extension=pdo_sqlite

   那些 DLL 文件应该在系统的extension_dir 中存在。

> 注意:

> 记住：更改 php.ini 文件后需要重启 PHP 服务才能使新的配置指令生效。

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

PDO 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
pdo.dsn.* |  | 仅 php.ini |

这是配置指令的简短说明。

`pdo.dsn.*` string

  定义 DSN 别名。 参见 PDO::__construct() 详细说明。

# 预定义常量

## 目录

- 获取模式

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

## 获取模式

参见 `PDO::FETCH_ORI_*` 游标常量的游标常量。

## 基本获取模式

获取模式 | 摘要
--- | ---
`PDO::FETCH_DEFAULT` | 用于当前默认获取模式的特殊值。
`PDO::FETCH_ASSOC` | 仅按列名索引的数组。
`PDO::FETCH_BOTH`（默认） | 同时按列号和列名索引的数组。
`PDO::FETCH_NAMED` | 保留重复列的 `PDO::FETCH_ASSOC` 变体。
`PDO::FETCH_NUM` | 仅按列号索引的数组。
`PDO::FETCH_COLUMN` | 单列。
`PDO::FETCH_KEY_PAIR` | 键值对，按第一列索引。
`PDO::FETCH_FUNC` | 使用函数创建返回值。（仅适用于 PDOStatement::fetchAll()）
`PDO::FETCH_OBJ` | 匿名（stdClass）对象。
`PDO::FETCH_CLASS` | 指定类的对象。

## PDO::FETCH_CLASS 选项

这些模式用于在使用 `PDO::FETCH_CLASS` 时实现选项。

获取模式 | 摘要
--- | ---
`PDO::FETCH_CLASSTYPE` | 使用第一列作为类名。
`PDO::FETCH_PROPS_LATE` | 在设置属性之前调用构造方法。
`PDO::FETCH_SERIALIZE` | 使用 PHP 序列化数据。自 PHP 8.1.0 起弃用。

## 单结果模式

以下模式无法与 PDOStatement::fetchAll() 一起使用。

获取模式 | 摘要
--- | ---
`PDO::FETCH_BOUND` | 将值绑定到指定变量。
`PDO::FETCH_INTO` | 更新现有对象。
`PDO::FETCH_LAZY` | 通过 PDORow 实现延迟获取，以支持类似数组和对象的访问方式。

## PDOStatement::fetchAll() 的特殊行为 flag

以下适用于多结果的特殊模式仅与 PDOStatement::fetchAll() 兼容，且不适用于某些其他获取模式。详情请参阅完整文档。

获取模式 | 摘要
--- | ---
`PDO::FETCH_GROUP` | 结果按第一列分组。
`PDO::FETCH_UNIQUE` | 结果按第一列（唯一）索引。

## 重复列名的处理方式

结果中可能包含使用相同名称的多个列。例如，在连接两个表时，这两个表都包含具有相同名称的列。

由于 PHP 的数组和对象等结构不支持使用相同名称的多个 key 或属性，返回的数组或对象将仅包含其中一个使用相同名称的值。

对于重复名称，指定返回哪个值应视为未定义行为。

为避免此问题，可以使用别名手动命名列。例如：

    SELECT table1.created_at AS t1_created_at,
           table2.created_at AS t2_created_at
    FROM table1
    JOIN table2 ON table1.table2id = table2.id

参见 `PDO::FETCH_NAMED`、`PDO::ATTR_FETCH_TABLE_NAMES` 和 `PDO::ATTR_FETCH_CATALOG_NAMES`。

## 设置默认获取模式

可以使用 PDO::__construct() 或 PDO::setAttribute()，通过 `PDO::ATTR_DEFAULT_FETCH_MODE` 设置所有查询的默认获取模式。

可以使用 PDOStatement::setFetchMode() 为特定语句设置默认获取模式。这会影响作为预处理语句的再次使用以及迭代（使用 foreach）。

警告

PDOStatement::setAttribute() 无法用于设置默认获取模式。它仅接受特定驱动程序的属性，并会静默忽略未识别的属性。

## PDO::FETCH_DEFAULT (int)

自 PHP 8.0.7 起可用。

这是一个特殊值，PDOStatement 是当前默认使用的获取模式。当扩展 PDOStatement 以与 `PDO::ATTR_STATEMENT_CLASS` 一起使用时，它作为方法参数的默认值非常有用。

此值不能与 `PDO::ATTR_DEFAULT_FETCH_MODE` 一起使用。

## PDO::FETCH_ASSOC (int)

`PDO::FETCH_ASSOC` 返回仅按列名索引的数组。

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_ASSOC);
    print_r($row);

以上示例会输出：

    Array
    (
        [userid] => 104
        [name] => Chris
        [country] => Ukraine
    )

## PDO::FETCH_BOTH (int)

这是默认的获取模式。

`PDO::FETCH_BOTH` 返回同时列号和列名索引的数组。这意味着每一行结果中的每个返回值都是重复的。

列号从 0 开始，由查询结果中的列顺序决定，而不是表中定义的列顺序。

> 注意: 不建议使用数字列索引，因为当查询发生更改时，或者在使用 `SELECT *` 时表结构发生更改，列索引可能会发生变化。

> 注意: 在多个返回列使用相同名称的情况下，按名称索引的条目数量可能与按数字索引的条目数量不匹配。

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_BOTH);
    print_r($row);

以上示例会输出：

    Array
    (
        [id] => 104,
        [0] => 104,
        [name] => Chris,
        [1] => Chris,
        [country] => Ukraine,
        [2] => Ukraine
    )

## PDO::FETCH_NAMED (int)

`PDO::FETCH_NAMED` 返回的结果格式与 `PDO::FETCH_ASSOC` 相同，但当多个列使用相同名称时，所有值将以列表形式返回。

有关重复列名的处理及其替代方法的更多信息，请参阅上文关于重复名称处理的部分。

重复值的返回顺序应视为未定义。无法确定每个值的来源。

    <?php
    $stmt = $pdo->query(
        "SELECT users.*, referrer.name
         FROM users
         LEFT JOIN users AS referrer ON users.referred_by = referrer.userid
         WHERE userid = 109"
    );
    $row = $stmt->fetch(\PDO::FETCH_NUM);
    print_r($row);

以上示例会输出：

    Array
    (
        [userid] => 109
        [name] => Array
            (
                [0] => Toni
                [1] => Chris
            )
        [country] => Germany
        [referred_by] = 104
    )

## PDO::FETCH_NUM (int)

`PDO::FETCH_NUM` 返回的数组仅按列号索引。列号从 0 开始，并由查询中的结果列顺序决定，而不是（例如）表中定义的列顺序。

> 注意: 不建议使用数字列索引，因为当查询发生更改时，或者在使用 `SELECT *` 时表结构发生更改，该索引可能会发生变化。

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_NUM);
    print_r($row);

以上示例会输出：

    Array
    (
        [0] => 104
        [1] => Chris
        [2] => Ukraine
    )

## PDO::FETCH_COLUMN (int)

`PDO::FETCH_COLUMN` 用于返回单列的值。可通过 PDOStatement::setFetchMode() 或 PDOStatement::fetchAll() 的第二个参数指定要返回的列。

若指定的列不存在，将抛出 ValueError。

    <?php
    $stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_COLUMN);
    print_r($row);

    $stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_COLUMN, 1);
    print_r($row);

以上示例会输出：

    Array
    (
        [0] => Chris
        [1] => Jamie
        [2] => Robin
    )

    Array
    (
        [0] => Ukraine
        [1] => England
        [2] => Germany
    )

## PDO::FETCH_KEY_PAIR (int)

`PDO::FETCH_KEY_PAIR` 返回以第一列为索引的键值对，结果必须仅包含两列。此获取模式仅适用于 PDOStatement::fetchAll()。

> 注意: 若第一列不唯一，将丢失部分值，具体哪些值会丢失属于未定义行为。

    <?php
    $stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_KEY_PAIR);
    print_r($row);

以上示例会输出：

    Array
    (
        [Chris] => Ukraine
        [Jamie] => England
        [Robin] => Germany
    )

## PDO::FETCH_FUNC (int)

指定用于创建返回值的函数。此模式仅可用于 PDOStatement::fetchAll()。

该函数以各列的值作为参数接收。因无法获知某个值原本关联的列名，因此必须确保查询中的列顺序与函数参数顺序一致。

> 注意: `PDO::FETCH_GROUP` 和 `PDO::FETCH_UNIQUE` 的效果会在调用该函数之前应用于结果。

    <?php
    function valueCreator($col1, $col2, $col3)
    {
        return [
            'col1' => $col1,
            'col2' => strtoupper($col2),
            'col3' => $col3,
            'customKey' => 'customValue',
        ];
    }

    $stmt = $pdo->query("SELECT userid, name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_FUNC, valueCreator(...));
    print_r($row);

以上示例会输出：

    Array
    (
        [0] => Array
            (
                [col1] => 104
                [col2] => SAM
                [col3] => Ukraine
                [customKey] => customValue
            )

        [1] => Array
            (
                [col1] => 105
                [col2] => JAMIE
                [col3] => England
                [customKey] => customValue
            )

        [2] => Array
            (
                [col1] => 107
                [col2] => ROBIN
                [col3] => Germany
                [customKey] => customValue
            )

    )

## PDO::FETCH_OBJ (int)

`PDO::FETCH_OBJ` 返回 stdClass 对象。

参见 PDOStatement::fetchObject() 和 `PDO::FETCH_CLASS`。

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_OBJ);
    print_r($row);

以上示例会输出：

    stdClass Object
    (
        [userid] => 104
        [name] => Chris
        [country] => Ukraine
    )

## PDO::FETCH_CLASS (int)

返回指定类的对象。有关附加行为，请参见选项 flag。

如果返回的列名与对象中已存在的属性名称不匹配，将会动态声明该属性。已废弃此行为，并自 PHP 9.0 起会引发错误。

参见 PDOStatement::fetchObject()。

    <?php

    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Constructor called with ". count(func_get_args()) ." args\n";
            print "Properties set when constructor called? "
                . (isset($this->name) ? 'Yes' : 'No') . "\n";
        }
    }

    $stmt = $db->query(
        "SELECT userid, name, country, referred_by_userid FROM users"
    );
    $stmt->setFetchMode(PDO::FETCH_CLASS, TestEntity::class);
    $result = $stmt->fetch();
    var_dump($result);

以上示例的输出类似于：

    Constructor called with 0 args
    Properties set when constructor called? Yes
    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_CLASSTYPE (int)

此获取模式仅可与 `PDO::FETCH_CLASS`（及其他选项）结合使用。

使用此获取模式时，PDO 会将返回结果的第一列作为要实例化的类名。

若指定的类未找到，将返回 stdClass 对象，且不产生警告或错误。

    <?php
    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Constructor called with ". count(func_get_args()) ." args\n";
            print "Properties set when constructor called? "
                . (isset($this->name) ? 'Yes' : 'No') . "\n";
        }
    }

    $stmt = $db->query(
        "SELECT 'TestEntity', userid, name, country, referred_by_userid FROM users"
    );
    $stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE);
    $result = $stmt->fetch();
    var_dump($result);

以上示例的输出类似于：

    Constructor called with 0 args
    Properties set when constructor called? Yes
    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_PROPS_LATE (int)

此获取模式仅可与 `PDO::FETCH_CLASS`（及其他选项）结合使用。

使用此获取模式时，会在属性赋值前调用构造方法。

    <?php
    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Constructor called with ". count(func_get_args()) ." args\n";
            print "Properties set when constructor called? "
                . (isset($this->name) ? 'Yes' : 'No') . "\n";
        }
    }

    $stmt = $db->query(
        "SELECT userid, name, country, referred_by_userid FROM users"
    );
    $stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_PROPS_LATE, TestEntity::class);
    $result = $stmt->fetch();
    var_dump($result);

以上示例的输出类似于：

    Constructor called with 0 args
    Properties set when constructor called? No
    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_SERIALIZE (int)

警告

此功能自 PHP 8.1.0 起弃用。强烈建议不要应用此功能。

此获取模式仅可与 `PDO::FETCH_CLASS`（及其他选项）结合使用。

使用此获取模式时，指定的类必须实现 Serializable。

警告

此功能不支持包含完整序列化对象（通过 serialize() 生成）的字符串。

警告

此获取模式不会调用构造方法。

    <?php
    class TestEntity implements Serializable
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Constructor called with " . count(func_get_args()) . " args\n";
            print "Properties set when constructor called? "
                . (isset($this->name) ? 'Yes' : 'No') . "\n";
        }

        public function serialize()
        {
            return join(
                "|",
                [$this->userid, $this->name, $this->country, $this->referred_by_userid]
            );
        }

        public function unserialize(string $data)
        {
            $parts = explode("|", $data);
            $this->userid = (int) $parts[0];
            $this->name = $parts[1];
            $this->country = $parts[2];

            $refId = $parts[3];
            $this->referred_by_userid = ($refId === "" ? null : (int) $refId);
        }
    }

    print "Set up record (constructor called manually):\n";
    $db->exec(
        "CREATE TABLE serialize (
            sdata TEXT
        )"
    );

    $origObj = new TestEntity();
    $origObj->userid = 200;
    $origObj->name = 'Seri';
    $origObj->country = 'Syria';
    $origObj->referred_by_userid = null;

    $insert = $db->prepare("INSERT INTO serialize (sdata) VALUES (:sdata)");
    $insert->execute(['sdata' => $origObj->serialize()]);

    print "\nRetrieve result:\n";
    $query = "SELECT sdata FROM serialize";
    $stmt = $db->query($query);
    // NOTE: Constructor is never called!
    $stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_SERIALIZE, TestEntity::class);
    $result = $stmt->fetch();
    var_dump($result);

以上示例的输出类似于：

    Deprecated: TestEntity implements the Serializable interface, which is deprecated. Implement __serialize() and __unserialize() instead (or in addition, if support for old PHP versions is necessary) in Standard input code on line 2
    Set up record (constructor called manually):
    Constructor called with 0 args
    Properties set when constructor called? No

    Retrieve result:
    Deprecated: PDOStatement::setFetchMode(): The PDO::FETCH_SERIALIZE mode is deprecated in Standard input code on line 58

    Deprecated: PDOStatement::fetch(): The PDO::FETCH_SERIALIZE mode is deprecated in Standard input code on line 59
    object(TestEntity)#5 (4) {
      ["userid"]=>
      int(200)
      ["name"]=>
      string(4) "Seri"
      ["country"]=>
      string(5) "Syria"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_BOUND (int)

此获取模式无法与 PDOStatement::fetchAll() 一起使用。

此获取模式不直接返回结果，而是将值绑定到通过 PDOStatement::bindColumn() 指定的变量，所调用的获取方法返回 `true`。

> 注意: 使用预处理语句时，为确保正确运行，变量必须在查询执行后进行绑定。

    <?php
    $query = "SELECT users.userid, users.name, users.country, referrer.name
        FROM users
        LEFT JOIN users AS referrer ON users.referred_by_userid = referrer.userid";
    $stmt = $db->prepare($query);
    $stmt->execute();

    $stmt->bindColumn('userid', $userId);
    $stmt->bindColumn('name', $name);
    $stmt->bindColumn('country', $country);
    // Bind by column position to resolve duplicated column name
    // To avoid this breaking if the query is changed, use an SQL alias instead
    // For example: referrer.name AS referrer_name
    $stmt->bindColumn(4, $referrerName);

    while ($stmt->fetch(\PDO::FETCH_BOUND)) {
        print join("\t", [$userId, $name, $country, ($referrerName ?? 'NULL')]) . "\n";
    }

以上示例会输出：

    104	Chris	Ukraine	NULL
    105	Jamie	England	NULL
    107	Robin	Germany	Chris
    108	Sean	Ukraine	NULL
    109	Toni	Germany	NULL
    110	Toni	Germany	NULL

## PDO::FETCH_INTO (int)

此获取模式无法与 PDOStatement::fetchAll() 一起使用。

此获取模式会更新指定对象中的属性。成功后，将返回该对象。

如果返回的列名对应的属性不存在，则会动态声明该属性。已弃用此行为，自 PHP 9.0 起会导致错误。

属性必须是 `public` 并且不能是 `readonly`。

警告

若不在每次获取记录之间使用 PDOStatement::setFetchMode()，则无法更改待更新的对象。

    <?php
    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;
    }

    $obj = new TestEntity();

    $stmt = $db->query("SELECT userid, name, country, referred_by_userid FROM users");

    $stmt->setFetchMode(\PDO::FETCH_INTO, $obj);
    $result = $stmt->fetch();

    var_dump($result);

以上示例的输出类似于：

    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_LAZY (int)

此获取模式无法与 PDOStatement::fetchAll() 一起使用。

此获取模式返回 PDORow 对象，以延迟方式检索，并同时支持类似数组和对象访问值的方式（即结合了 `PDO::FETCH_BOTH` 与 `PDO::FETCH_OBJ` 的行为）。

这种方式可在 PHP 端实现对数据库服务器上非缓冲结果的内存高效访问。PDO 是否对结果使用客户端缓冲，取决于所使用的数据库特定驱动及其配置。

警告

PDORow 在访问未定义的属性或 key 时会返回 `NULL`，且不产生任何错误或警告，这可能导致拼写错误或查询未返回预期数据等问题更难发现和调试。

警告

返回的 PDORow 对象在每次获取结果时都会更新。

    <?php
    $stmt = $db->query("SELECT userid, name, country, referred_by_userid FROM users");
    $result = $stmt->fetch(\PDO::FETCH_LAZY);

    print "ID: ". $result[0] ."\n";
    print "Name: {$result->name}\n";
    print "Country: " . $result['country'] ."\n";
    // 返回 NULL，不触发警告或错误
    print "Does not exist: " . var_export($result->does_not_exist, true) . "\n";

    $differentResult = $stmt->fetch(\PDO::FETCH_LAZY);
    // 先前检索的 PDORow 现在指向新的检索结果
    print "ID: ". $result[0] ."\n";

以上示例会输出：

    ID: 104
    Name: Chris
    Country: Ukraine
    Does not exist: NULL
    ID: 105

## PDO::FETCH_GROUP (int)

`PDO::FETCH_GROUP` 返回以某一（非唯一）列作为索引的关联数组列表。此获取模式仅适用于 PDOStatement::fetchAll()。

当与 `PDO::FETCH_UNIQUE` 组合使用时，两种模式会使用同一列，导致该组合失去实际作用。

此获取模式应与 `PDO::FETCH_ASSOC`、`PDO::FETCH_BOTH`、`PDO::FETCH_NAMED`、`PDO::FETCH_NUM`、`PDO::FETCH_COLUMN` 或 `PDO::FETCH_FUNC` 中的一种组合使用。

若未指定上述列表中的获取模式，则当前的默认获取模式用于 PDOStatement。

    <?php
    $stmt = $pdo->query("SELECT country, userid, name FROM users");
    $row = $stmt->fetchAll(\PDO::FETCH_GROUP | \PDO::FETCH_ASSOC);
    print_r($row);

以上示例会输出：

    Array
    (
        [Ukraine] => Array
            (
                [0] => Array
                    (
                        [userid] => 104
                        [name] => Chris
                    )

                [1] => Array
                    (
                        [userid] => 108
                        [name] => Sean
                    )

            )
        [England] => Array
            (
                [0] => Array
                    (
                        [userid] => 105
                        [name] => Jamie
                    )

            )

        [Germany] => Array
            (
                [0] => Array
                    (
                        [userid] => 107
                        [name] => Robin
                    )

                [1] => Array
                    (
                        [userid] => 109
                        [name] => Toni
                    )
            )
    )

在上述示例中需注意，每行数组中会省略第一列，该列仅作为 key 存在。若要将其包含在数组中，可重复该列，如下例所示：

    <?php
    $stmt = $pdo->query("SELECT country, userid, name, country FROM users");
    $row = $stmt->fetchAll(\PDO::FETCH_GROUP | \PDO::FETCH_ASSOC);
    print_r($row);

以上示例会输出：

    Array
    (
        [Ukraine] => Array
            (
                [0] => Array
                    (
                        [userid] => 104
                        [name] => Chris
                        [country] => Ukraine
                    )

                [1] => Array
                    (
                        [userid] => 108
                        [name] => Sean
                        [country] => Ukraine
                    )

            )
        [England] => Array
            (
                [0] => Array
                    (
                        [userid] => 105
                        [name] => Jamie
                        [country] => England
                    )

            )

        [Germany] => Array
            (
                [0] => Array
                    (
                        [userid] => 107
                        [name] => Robin
                        [country] => Germany
                    )

                [1] => Array
                    (
                        [userid] => 109
                        [name] => Toni
                        [country] => Germany
                    )
            )
    )

## PDO::FETCH_UNIQUE (int)

`PDO::FETCH_UNIQUE` 使用第一列作为索引记录，每个索引值返回一条记录。此获取模式仅适用于 PDOStatement::fetchAll()。

当与 `PDO::FETCH_GROUP` 组合使用时，两种模式会使用同一列，导致该组合失去实际作用。

此获取模式应与 `PDO::FETCH_ASSOC`、`PDO::FETCH_BOTH`、`PDO::FETCH_NAMED`、`PDO::FETCH_NUM`、`PDO::FETCH_COLUMN` 或 `PDO::FETCH_FUNC` 中的一种组合使用。

若未指定上述列表中的获取模式，则当前的默认获取模式用于 PDOStatement。

当与已知的唯一列（例如记录 ID）一起使用时，此模式可快速返回以该值为索引的结果。

> 注意: 若第一列不唯一，将丢失部分值，具体哪些值会丢失属于未定义行为。

警告

应尽可能在 SQL 中进行记录过滤。数据库会利用索引优化该过程，仅返回所需记录。若从数据库中选取了超出所需的记录，可能会显著增加内存占用和查询时间，尤其在结果集较大时。

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_UNIQUE | \PDO::FETCH_ASSOC);
    print_r($row);

以上示例会输出：

    Array
    (
        [104] => Array
            (
                [name] => Chris
                [country] => Ukraine
            )

        [105] => Array
            (
                [name] => Jamie
                [country] => England
            )

        [107] => Array
            (
                [name] => Robin
                [country] => Germany
            )

    )

在上述示例中需注意，每行数组中会省略第一列，该列仅作为 key 存在。若要将其包含在数组中，可重复该列，如下例所示：

    <?php
    $stmt = $pdo->query("SELECT userid, userid, name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_UNIQUE | \PDO::FETCH_ASSOC);
    print_r($row);

以上示例会输出：

    Array
    (
        [104] => Array
            (
                [userid] => 104
                [name] => Chris
                [country] => Ukraine
            )

        [105] => Array
            (
                [userid] => 105
                [name] => Jamie
                [country] => England
            )

        [107] => Array
            (
                [userid] => 107
                [name] => Robin
                [country] => Germany
            )

    )

## 游标

另见 `PDO::ATTR_CURSOR_NAME`。

`PDO::FETCH_ORI_NEXT` (int)
  获取结果集的下一行。仅对可滚动游标有效。
`PDO::FETCH_ORI_PRIOR` (int)
  获取结果集的上一行。仅对可滚动游标有效。
`PDO::FETCH_ORI_FIRST` (int)
  获取结果集的第一行。仅对可滚动游标有效。
`PDO::FETCH_ORI_LAST` (int)
  获取结果集的最后一行。仅对可滚动游标有效。
`PDO::FETCH_ORI_ABS` (int)
  按行号从结果集获取指定行。仅对可滚动游标有效。
`PDO::FETCH_ORI_REL` (int)
  根据游标在结果集的当前位置，按相对位置获取指定行。仅对可滚动游标有效。
`PDO::CURSOR_FWDONLY` (int)
  创建带只进游标的 PDOStatement 对象。这是默认游标选项，因为它是 PHP 中最快且最常见的数据访问模式。
`PDO::CURSOR_SCROLL` (int)
  创建带滚动游标的 PDOStatement 对象。传递 `PDO::FETCH_ORI_*` 常量以控制从结果集获取的行。

## 其它常量

`PDO::PARAM_BOOL` (int)
  表示 bool 数据类型。
`PDO::PARAM_NULL` (int)
  表示 SQL NULL 数据类型。
`PDO::PARAM_INT` (int)
  表示 SQL INTEGER 数据类型
`PDO::PARAM_STR` (int)
  表示 SQL CHAR、VARCHAR 或其它字符串类型。
`PDO::PARAM_STR_NATL` (int)
  表示字符使用的是国家字符集（national character set）的 flag。 自 PHP 7.2.0 起可用
`PDO::PARAM_STR_CHAR` (int)
  表示字符使用的是常规字符集（regular character set）的 flag。 自 PHP 7.2.0 起可用
`PDO::PARAM_LOB` (int)
  表示 SQL 大对象数据类型。
`PDO::PARAM_STMT` (int)
  表示记录集类型。目前没有任何驱动程序支持。
`PDO::PARAM_INPUT_OUTPUT` (int)
  指定参数是存储过程的 INOUT 参数。该常量必须与某个 `PDO::PARAM_*` 常量进行按位或运算。
`PDO::ATTR_AUTOCOMMIT` (int)
  如果值为 `false`，PDO 将尝试禁用自动提交，从而使连接开始一个事务。
`PDO::ATTR_PREFETCH` (int)
  设置预取大小来为你的应用平衡速度和内存使用。并非所有的数据库/驱动组合都支持设置预取大小。较大的预取大小导致性能提高的同时也会占用更多的内存。
`PDO::ATTR_TIMEOUT` (int)
  设置连接数据库的超时秒数。
`PDO::ATTR_ERRMODE` (int)
  关于此属性的更多信息请参见错误及错误处理部分。
`PDO::ATTR_SERVER_VERSION` (int)
  此为只读属性；返回 PDO 所连接的数据库服务的版本信息。
`PDO::ATTR_CLIENT_VERSION` (int)
  此为只读属性；返回 PDO 驱动所用客户端库的版本信息。
`PDO::ATTR_SERVER_INFO` (int)
  此为只读属性。返回一些关于 PDO 所连接的数据库服务的元信息。
`PDO::ATTR_CONNECTION_STATUS` (int)
`PDO::ATTR_CASE` (int)
  用类似 `PDO::CASE_*` 的常量强制列名为指定的大小写。
`PDO::ATTR_CURSOR_NAME` (int)
  获取或设置使用游标的名称。当使用可滚动游标和定位更新时候非常有用。
`PDO::ATTR_CURSOR` (int)
  选择游标类型。PDO 当前支持 `PDO::CURSOR_FWDONLY` 或 `PDO::CURSOR_SCROLL`。除非需要可滚动游标，否则应使用 `PDO::CURSOR_FWDONLY` 游标模式。
`PDO::ATTR_DRIVER_NAME` (int)
  返回驱动名称。

  示例 #1 使用 `PDO::ATTR_DRIVER_NAME`

      <?php
       if ($db->getAttribute(PDO::ATTR_DRIVER_NAME) == 'mysql') {
         echo "Running on mysql; doing something mysql specific here\n";
       }
       ?>

`PDO::ATTR_ORACLE_NULLS` (int)
  在获取数据时将空字符串转换成 SQL 中的 NULL。
`PDO::ATTR_PERSISTENT` (int)
  请求持久连接，而非创建新连接。关于此属性的更多信息请参见连接与连接管理。
`PDO::ATTR_STATEMENT_CLASS` (int)
  设置返回的 statement 类名。
`PDO::ATTR_FETCH_CATALOG_NAMES` (int)
  将包含的目录名添加到结果集中的每个列名前面。目录名和列名由一个小数点分开（.）。此属性在驱动层面支持，所使用的驱动程序可能不支持此功能。
`PDO::ATTR_FETCH_TABLE_NAMES` (int)
  将包含的表名添加到结果集中的每个列名前面。表名和列名由一个小数点分开（.）。此属性在驱动层面支持，所使用的驱动程序可能不支持此功能。
`PDO::ATTR_STRINGIFY_FETCHES` (int)
  强制将所有获取的值（`null` 除外）视为字符串。除非将 `PDO::ATTR_ORACLE_NULLS` 设置为 `PDO::NULL_TO_STRING`，否则 `null` 值保持不变。
`PDO::ATTR_MAX_COLUMN_LEN` (int)
  设置字段名最长的尺寸。
`PDO::ATTR_DEFAULT_FETCH_MODE` (int)
`PDO::ATTR_EMULATE_PREPARES` (int)
`PDO::ATTR_DEFAULT_STR_PARAM` (int)
  设置默认 string 参数类型可以是 `PDO::PARAM_STR_NATL` 和 `PDO::PARAM_STR_CHAR`。 自 PHP 7.2.0 起可用。
`PDO::ERRMODE_SILENT` (int)
  如果发生错误，则不引发错误或异常。开发人员需要显式地检查错误。PHP 8.0.0 前为默认模式。关于此属性的更多信息请参见错误与错误处理。
`PDO::ERRMODE_WARNING` (int)
  如果发生错误，则显示 PHP `E_WARNING` 消息。关于此属性的更多信息请参见错误与错误处理。
`PDO::ERRMODE_EXCEPTION` (int)
  如果发生错误，则抛出 PDOException 异常。自 PHP 8.0.0 起此为默认模式。关于此属性的更多信息请参见错误与错误处理。
`PDO::CASE_NATURAL` (int)
  保留数据库驱动返回的列名。
`PDO::CASE_LOWER` (int)
  强制列名小写。
`PDO::CASE_UPPER` (int)
  强制列名大写。
`PDO::NULL_NATURAL` (int)
`PDO::NULL_EMPTY_STRING` (int)
`PDO::NULL_TO_STRING` (int)
`PDO::ERR_NONE` (string)
  对应 SQLSTATE `'00000'`，表示 SQL 语句已成功执行，未发生任何错误或警告。该常量是一个便捷常量，用于在检查 PDO::errorCode() 或 PDOStatement::errorCode() 以确定是否发生错误时提供帮助。通常情况下，通过检查引发错误条件的方法的返回值即可获知结果。
`PDO::PARAM_EVT_ALLOC` (int)
  分配事件
`PDO::PARAM_EVT_FREE` (int)
  解除分配事件
`PDO::PARAM_EVT_EXEC_PRE` (int)
  在执行预处理语句之前触发的事件。
`PDO::PARAM_EVT_EXEC_POST` (int)
  在执行预处理语句之后触发的事件。
`PDO::PARAM_EVT_FETCH_PRE` (int)
  在从结果集中获取结果之前触发的事件。
`PDO::PARAM_EVT_FETCH_POST` (int)
  在从结果集中获取结果之后触发的事件。
`PDO::PARAM_EVT_NORMALIZE` (int)
  在绑定参数注册允许驱动程序正常化变量名时触发事件。
`PDO::SQLITE_DETERMINISTIC` (int)
  指定使用 PDO::sqliteCreateFunction() 创建的函数是确定性的，即在单个 SQL 语句中，函数的参数不变，该函数始终返回相同的结果。（自 PHP 7.1.4 起可用。）

# 连接与连接管理

连接是通过创建 PDO 基类的实例而建立的。使用哪种驱动程序并不重要，始终都会用 PDO 类名。构造函数接受用于指定数据库源（也称为 DSN）以及可选的用户名和密码（如果有）的参数。

示例 #1 连接到 MySQL

    <?php
    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
    ?>

如果有任何连接错误，将抛出 `PDOException` 对象。如果想处理错误状态，可以捕获异常，或者选择将其留给 set_exception_handler() 设置的应用程序全局异常处理程序。

示例 #2 处理连接错误

    <?php
    try {
        $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
    } catch (PDOException $e) {
        // 对于示例，尝试在超时后重新连接
    }

警告

就像其它任一 exception 一样，PDOException 可以通过 `catch` 语句手动捕获，也可以通过 set_exception_handler() 自动捕获。否则，默认行为是将未捕获的异常转换为 `E_FATAL_ERROR`。fatal 错误可能会包含泄漏连接详情的 backtrace。因此，生产服务器上的 php.ini 选项 `display_errors` 应设置为 `0`。

连接数据库成功后，返回 PDO 类的实例给脚本。此连接在 PDO 对象的生存周期中保持有效状态。要关闭连接，需要确保删除它的所有剩余引用来销毁对象——可以通过对对象变量赋值 `null` 来实现。如果没有明确这么做，PHP 在脚本结束时会自动关闭连接。

> 注意: 如果还有其它对此 PDO 实例的引用（比如来自 PDOStatement 实例，或来自其它同一 PDO 实例的其它变量），也必须删除这些引用（例如，通过将 `null` 赋值给引用 PDOStatement 的变量）。

示例 #3 关闭连接

    <?php
    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
    // 在此使用连接
    $sth = $dbh->query('SELECT * FROM foo');

    // 使用完毕，关闭连接
    $sth = null;
    $dbh = null;
    ?>

很多 web 应用程序通过与数据库建立持久连接获得好处。持久连接不会在脚本结束时关闭，而是会缓存，且当另一个脚本使用相同凭证请求连接时重用。持久连接缓存可以避免每次脚本需要与数据库通信时建立新连接的开销，从而让 web 应用程序更快。

示例 #4 持久化连接

    <?php
    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass, array(
        PDO::ATTR_PERSISTENT => true
    ));
    ?>

`PDO::ATTR_PERSISTENT` 选项的值转换为 bool（启用/禁用持久连接），除非它不是数字 string，在这种情况下允许使用多个持久连接池。如果不同的链接使用不兼容的设置，非常有用，例如 `PDO::MYSQL_ATTR_USE_BUFFERED_QUERY` 的值不同。

> 注意:

> 如果想使用持久连接，必须在传递给 PDO 构造函数的驱动程序选项数组中设置 `PDO::ATTR_PERSISTENT`。如果在对象实例化后用 PDO::setAttribute() 设置此属性，驱动程序将不会使用持久连接。

警告

PDO 不会对持久连接执行任何清理操作。临时表、锁、事务及其他有状态的更改可能会保留在连接的上一次使用中，从而导致意外问题。更多信息可参阅持久数据库连接部分。

> 注意:

> 如果使用 PDO ODBC 驱动程序且 ODBC 库支持 ODBC 连接池（有 unixODBC 和 Windows 是其中的两个；可能会有更多），建议不要使用持久 PDO 连接，而是把连接缓存留给 ODBC 连接池层。ODBC 连接池在进程中与其它模块共享；如果 PDO 缓存连接，则此连接永远不会被返回到 ODBC 连接池，从而导致创建额外的连接来服务其它模块。

# 事务与自动提交

现在通过 PDO 连接上了，在开始进行查询前，必须先理解 PDO 是如何管理事务的。事务支持四大特性（ACID）：原子性（Atomicity）、一致性（Consistency）、隔离性（Isolation）以及持久性（Durability）。通俗地讲，在一个事务中执行的任何操作，即使是分阶段执行的，也能保证安全地应用于数据库，并在提交时不会受到来自其他连接的干扰。事务操作也可以根据请求自动撤销（假设还没有提交），这使得在脚本中处理错误更加容易。

事务通常是通过把一批更改“积蓄”起来然后使之同时生效而实现的；这样做的好处是可以大大地提供这些更改的效率。换句话说，事务可以使脚本更快，而且可能更健壮（不过需要正确地使用事务才能获得这样的好处）。

不幸的是，并非每种数据库都支持事务，因此当第一次打开连接时，PDO 需要在所谓的“自动提交”模式下运行。自动提交模式意味着，如果数据库支持，运行的每个查询都有它自己的隐式事务，如果数据库不支持事务，则没有。如果需要一个事务，则必须用 PDO::beginTransaction() 方法来启动。如果底层驱动不支持事务，则抛出一个 PDOException 异常（不管错误处理设置是怎样的，这都是一个严重的错误状态）。一旦开始了事务，可用 PDO::commit() 或 PDO::rollBack() 来完成，这取决于事务中的代码是否运行成功。

警告

PDO 仅在驱动层检查是否具有事务处理能力。如果某些运行时条件意味着事务不可用，且数据库服务接受请求去启动一个事务，PDO::beginTransaction() 将仍然返回 `true` 而且没有错误。

试着在 MySQL 数据库的 MyISAM 数据表中使用事务就是一个很好的示例。

警告

DDL 语句的隐式提交： 某些数据库在事务中执行诸如 `DROP TABLE` 或 `CREATE TABLE` 等数据库定义语言（DDL）语句时，会自动发出隐式提交。这意味着在同一事务中之前所做的任何更改都将自动提交，且无法回滚。

`MySQL` 和 `Oracle` 就是表现出这种行为的示例数据库。

示例 #1 隐式提交示例

    <?php
    $pdo->beginTransaction();
    $pdo->exec("INSERT INTO users (name) VALUES ('Rasmus')");
    $pdo->exec("CREATE TABLE test (id INT PRIMARY KEY)"); // 这里发生了隐式提交
    $pdo->rollBack(); // 这不会撤销 MySQL 或 Oracle 中的 INSERT/CREATE 操作
    ?>

最佳实践：若使用强制此行为的数据库，则避免在事务内执行 DDL 语句。必要时，将 DDL 操作与事务逻辑分离。

当脚本结束或连接即将被关闭时，如果尚有一个未完成的事务，那么 PDO 将自动回滚该事务。这种安全措施有助于在脚本意外终止时避免出现不一致的情况——如果没有显式地提交事务，那么假设是某个地方出错了，所以执行回滚来保证数据安全。

警告

只有通过 PDO::beginTransaction() 启动一个事务后，才可能发生自动回滚。如果手动发出一条查询启动事务，则 PDO 无法知晓，从而在必要时不能进行回滚。

示例 #2 在事务中执行批处理

在下面示例中，假设为新员工创建一组条目，分配一个为 23 的 ID。除了登记此人的基本数据之外，还需要记录他的工资。两个更新分别完成起来很简单，但通过封闭在 PDO::beginTransaction() 和 PDO::commit() 调用中，可以保证在更改完成之前，其他人无法看到这些更改。如果发生了错误，catch 块回滚自事务启动以来发生的所有更改，并输出一条错误信息。

    <?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();
    }
    ?>

并不局限于在事务中更改，也可以发出复杂的查询来提取数据，还可以使用那些信息来构建更多的更改和查询；当事务激活时，可以保证其他人在操作进行当中无法作出更改。想更进一步阅读关于事务的信息，可参考数据库服务提供的文档。

# 预处理语句与存储过程

很多更成熟的数据库都支持预处理语句的概念。什么是预处理语句？可以把它看作是想要运行的 SQL 的一种编译过的模板，它可以使用变量参数进行定制。预处理语句可以带来两大好处：

- 查询仅需解析（或预处理）一次，但可以用相同或不同的参数执行多次。当查询准备好后，数据库将分析、编译和优化执行该查询的计划。对于复杂的查询，此过程要花费较长的时间，如果需要以不同参数多次重复相同的查询，那么该过程将大大降低应用程序的速度。通过使用预处理语句，可以避免重复分析/编译/优化周期。简言之，预处理语句占用更少的资源，因而运行得更快。
- 提供给预处理语句的参数不需要用引号括起来，驱动程序会自动处理。如果应用程序只使用预处理语句，可以确保不会发生SQL 注入。（然而，如果查询的其他部分是由未转义的输入来构建的，则仍存在 SQL 注入的风险）。

预处理语句如此有用，以至于它们唯一的特性是在驱动程序不支持的时PDO 将模拟处理。这样可以确保不管数据库是否具有这样的功能，都可以确保应用程序可以用相同的数据访问模式。

示例 #1 用预处理语句进行重复插入

下面示例通过用 `name` 和 `value` 替代相应的命名占位符来执行一个插入查询

    <?php
    $stmt = $dbh->prepare("INSERT INTO REGISTRY (name, value) VALUES (:name, :value)");
    $stmt->bindParam(':name', $name);
    $stmt->bindParam(':value', $value);

    // 插入一行
    $name = 'one';
    $value = 1;
    $stmt->execute();

    //  用不同的值插入另一行
    $name = 'two';
    $value = 2;
    $stmt->execute();
    ?>

示例 #2 用预处理语句进行重复插入

下面示例通过用 `name` 和 `value` 取代 `?` 占位符的位置来执行一条插入查询。

    <?php
    $stmt = $dbh->prepare("INSERT INTO REGISTRY (name, value) VALUES (?, ?)");
    $stmt->bindParam(1, $name);
    $stmt->bindParam(2, $value);

    // 插入一行
    $name = 'one';
    $value = 1;
    $stmt->execute();

    // 用不同的值插入另一行
    $name = 'two';
    $value = 2;
    $stmt->execute();
    ?>

示例 #3 使用预处理语句获取数据

下面示例获取数据基于键值已提供的形式。用户的输入被自动用引号括起来，因此不会有 SQL 注入攻击的危险。

    <?php
    $stmt = $dbh->prepare("SELECT * FROM REGISTRY where name = ?");
    $stmt->execute([$_GET['name']]);
    foreach ($stmt as $row) {
      print_r($row);
    }
    ?>

示例 #4 Calling a stored procedure with an output parameter

如果数据库驱动支持，应用程序还可以绑定输出和输入参数。 输出参数通常用于从存储过程获取值。 输出参数使用起来比输入参数要稍微复杂一些，因为当绑定一个输出参数时，必须知道给定参数的长度。 如果为参数绑定的值大于建议的长度，就会产生一个错误。

    <?php
    $stmt = $dbh->prepare("CALL sp_returns_string(?)");
    $stmt->bindParam(1, $return_value, PDO::PARAM_STR, 4000);

    // 调用存储过程
    $stmt->execute();

    print "procedure returned $return_value\n";
    ?>

示例 #5 带输入/输出参数调用存储过程

还可以指定同时具有输入和输出值的参数，其语法类似于输出参数。 在下一个示例中，字符串“hello”被传递给存储过程， 当存储过程返回时，hello 被替换为该存储过程返回的值。

    <?php
    $stmt = $dbh->prepare("CALL sp_takes_string_returns_string(?)");
    $value = 'hello';
    $stmt->bindParam(1, $value, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT, 4000);

    // 调用存储过程
    $stmt->execute();

    print "procedure returned $value\n";
    ?>

示例 #6 占位符的无效使用

    <?php
    $stmt = $dbh->prepare("SELECT * FROM REGISTRY where name LIKE '%?%'");
    $stmt->execute([$_GET['name']]);

    // 占位符必须被用在整个值的位置
    $stmt = $dbh->prepare("SELECT * FROM REGISTRY where name LIKE ?");
    $stmt->execute(["%$_GET[name]%"]);
    ?>

# 错误与错误处理

PDO 提供了三种不同的错误处理模式，以满足不同风格的应用开发：

- `PDO::ERRMODE_SILENT`

  在PHP8.0.0之前，此为默认模式。 PDO 将只简单地设置错误码，可使用 PDO::errorCode() 和 PDO::errorInfo() 方法来检查语句和数据库对象。如果错误是由于对语句对象的调用而产生的，那么可以调用那个对象的 PDOStatement::errorCode() 或 PDOStatement::errorInfo() 方法。如果错误是由于调用数据库对象而产生的，那么可以在数据库对象上调用上述两个方法。

- `PDO::ERRMODE_WARNING`

  除设置错误码之外，PDO 还将发出一条传统的 E_WARNING 信息。如果只是想看看发生了什么问题且不中断应用程序的流程，那么此设置在调试/测试期间非常有用。

- `PDO::ERRMODE_EXCEPTION`

  从PHP 8.0.0开始，这是默认模式。 除设置错误码之外，PDO 还将抛出一个 PDOException 异常类并设置它的属性来反射错误码和错误信息。此设置在调试期间也非常有用，因为它会有效地放大脚本中产生错误的点，从而可以非常快速地指出代码中有问题的潜在区域（记住：如果异常导致脚本终止，则事务被自动回滚）。

  异常模式另一个非常有用的是，相比传统 PHP 风格的警告，可以更清晰地构建自己的错误处理，而且比起静默模式和显式地检查每种数据库调用的返回值，异常模式需要的代码/嵌套更少。

  See Exceptions for more information about Exceptions in PHP.

PDO 使用 SQL-92 SQLSTATE 来规范错误码字符串；不同 PDO 驱动程序负责将它们的本地代码映射为适当的 SQLSTATE 代码。PDO::errorCode() 方法返回一个单独的 SQLSTATE 码。如果需要更多此错误的细节信息，PDO 还提供了一个 PDO::errorInfo() 方法来返回一个包含 SQLSTATE 码、特定驱动错误码以及此驱动的错误字符串的数组。

示例 #1 创建 PDO 实例并设置错误模式

    <?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");

以上示例会输出：

    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

> 注意:

> 不管当前是否设置了 `PDO::ATTR_ERRMODE` ，如果连接失败，PDO::__construct() 将总是抛出一个 PDOException 异常。

示例 #2 创建 PDO 实例并在构造函数中设置错误模式

    <?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));

    // 这里将导致 PDO 抛出一个 E_WARNING 级别的错误，而不是 一个异常 （当数据表不存在时）
    $dbh->query("SELECT wrongcolumn FROM wrongtable");

以上示例会输出：

    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

# 大对象 (LOB)

应用程序在某一时刻，可能需要在数据库中存储“大”数据。“大”通常意味着“大约 4kb 或以上”，尽管某些数据库在数据达到“大”之前可以轻松地处理多达 32kb 的数据。大对象本质上可能是文本或二进制。在 PDOStatement::bindParam() 或 PDOStatement::bindColumn()) 调用中使用 `PDO::PARAM_LOB` 类型码可以让 PDO 使用大数据类型。`PDO::PARAM_LOB` 告诉 PDO 作为流来映射数据，以便能使用 PHP Streams API 来操作。

示例 #1 从数据库中显示一张图片

下面示例绑定一个 LOB 到 $lob 变量，然后用 fpassthru() 将其发送到浏览器。因为 LOB 代表一个流，所以类似 fgets()、fread() 以及 stream_get_contents() 这样的函数都可以用在它上面。

    <?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);
    ?>

示例 #2 插入一张图片到数据库

下面示例打开一个文件并将文件句柄传给 PDO 来做为一个 LOB 插入。PDO尽可能地让数据库以最有效的方式获取文件内容。

    <?php
    $db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2');
    $stmt = $db->prepare("insert into images (id, contenttype, imagedata) values (?, ?, ?)");
    $id = get_new_id(); // 调用某个函数来分配一个新 ID

    // 假设处理一个文件上传
    // 可以在 PHP 文档中找到更多的信息

    $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();
    ?>

示例 #3 插入一张图片到数据库：Oracle

对于从文件插入一个 lob，Oracle略有不同。必须在事务之后进行插入，否则当执行查询时导致新近插入 LOB 将以0长度被隐式提交：

    <?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(); // 调用某个函数来分配一个新 ID

    // 假设处理一个文件上传
    // 可以在 PHP 文档中找到更多的信息

    $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();
    ?>

# PDO 类

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

## 简介

代表 PHP 和数据库服务之间的连接

## 类摘要

class PDO {
/* 常量 */
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;
/* 方法 */
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
}

## 更新日志

版本 | 说明
--- | ---
8.4.0 | 类常量现已类型化。

# PDO::beginTransaction

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::beginTransaction — 启动一个事务

### 说明

public function PDO::beginTransaction(): bool

关闭自动提交模式。自动提交模式被关闭的同时，通过 PDO 对象实例对数据库做出的更改直到调用 PDO::commit() 结束事务才被提交。调用 PDO::rollBack() 将回滚对数据库做出的更改并将数据库连接返回到自动提交模式。

包括 MySQL 在内的一些数据库，当发出一条类似 DROP TABLE 或 CREATE TABLE 这样的 DDL 语句时，会自动进行一个隐式地事务提交。隐式地提交将阻止你在此事务范围内回滚任何其他更改。

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

如果事务已启动或者驱动不支持事务，则抛出 PDOException。

> 注意: `PDO::ATTR_ERRMODE` 属性不是 `PDO::ERRMODE_EXCEPTION` 时会抛出一个异常。

### 示例

示例 #1 回滚一个事务

下面示例在回滚此更改前开始一个事务并发出两条修改数据库的语句。但在 MySQL 中，DROP TABLE 语句自动提交事务，使得在此事务中的任何更改都不会被回滚。

    <?php
    /* 开始一个事务，关闭自动提交 */
    $dbh->beginTransaction();

    /*  更改数据库架构及数据 */
    $sth = $dbh->exec("DROP TABLE fruit");
    $sth = $dbh->exec("UPDATE dessert
        SET name = 'hamburger'");

    /*  识别出错误并回滚更改 */
    $dbh->rollBack();

    /* 数据库连接现在返回到自动提交模式 */
    ?>

### 参见

- PDO::commit() - 提交一个事务
- PDO::rollBack() - 回滚事务
- 事务与自动提交

# PDO::commit

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::commit — 提交一个事务

### 说明

public function PDO::commit(): bool

提交一个事务，数据库连接返回到自动提交模式直到下次调用 PDO::beginTransaction() 开始一个新的事务为止。

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

如果没有活动中的事务，则抛出 PDOException。

> 注意: `PDO::ATTR_ERRMODE` 属性不是 `PDO::ERRMODE_EXCEPTION` 时会抛出一个异常。

### 示例

示例 #1 提交一个基础事务

    <?php
    /* 开始一个事务，关闭自动提交 */
    $dbh->beginTransaction();

    /* 在全有或全无的基础上插入多行记录（要么全部插入，要么全部不插入） */
    $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,
        ));
    }

    /* 提交更改 */
    $dbh->commit();

    /* 现在数据库连接返回到自动提交模式 */
    ?>

示例 #2 提交一个DDL事务

    <?php
    /*  开始一个事务，关闭自动提交 */
    $dbh->beginTransaction();

    /* Change the database schema */
    $sth = $dbh->exec("DROP TABLE fruit");

    /* 更改数据库架构 */
    $dbh->commit();

    /* 现在数据库连接返回到自动提交模式 */
    ?>

> 注意: 并不是所有数据库都允许使用DDL语句进行事务操作：有些会产生错误，而其他一些（包括MySQL）会在遇到第一个DDL语句后就自动提交事务。

### 参见

- PDO::beginTransaction() - 启动一个事务
- PDO::rollBack() - 回滚事务
- 事务和自动提交

# PDO::connect

(PHP 8 >= 8.4.0)

PDO::connect — Connect to a database and return a PDO subclass for drivers that support it

### 说明

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.

### 参数

`dsn`

  数据源名称或叫做 DSN，包含了请求连接到数据库的信息。

  通常，一个 DSN 由 PDO 驱动名、紧随其后的冒号、以及具体 PDO 驱动的连接语法组成。更深入的信息能从 PDO 具体驱动文档找到。

  `dsn` 参数支持三种不同的方式 创建一个数据库连接：

  驱动程序调用

    `dsn` 包含完整的DSN。

  URI 调用

    `dsn` 由 `uri:` 后跟 URI 组成，该 URI 包含定义 DSN 字符串的文件位置。URI 可以指定本地文件或远程 URL。

    `uri:file:///path/to/dsnfile`

  别名

    `dsn` 由映射到 php.ini 中定义 DSN 字符串的 `pdo.dsn.`name`` 的 `name` 名组成。

    > 注意:

    > 别名必须得在 php.ini 中定义了，不能是在 .htaccess 或 httpd.conf 中 。

`username`

  DSN字符串中的用户名。对于某些PDO驱动，此参数为可选项。

`password`

  DSN字符串中的密码。对于某些PDO驱动，此参数为可选项。

`options`

  一个具体驱动的连接选项的键=>值数组。

### 返回值

Returns an instance of a PDO subclass for the corresponding PDO driver if it exists, or a generic PDO instance.

### 错误／异常

如果试图连接到请求的数据库失败，无论当前设置了哪个 `PDO::ATTR_ERRMODE`，则会抛出 PDOException。

### 参见

- Pdo\Dblib
- Pdo\Firebird
- Pdo\Mysql
- Pdo\Odbc
- Pdo\Pgsql
- Pdo\Sqlite
- PDO::__construct() - 创建一个表示数据库连接的 PDO 实例

# PDO::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::__construct — 创建一个表示数据库连接的 PDO 实例

### 说明

public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?array `$options` = `null`
)

创建一个表示连接到请求数据库的数据库连接 PDO 实例。

### 参数

`dsn`

  数据源名称或叫做 DSN，包含了请求连接到数据库的信息。

  通常，一个 DSN 由 PDO 驱动名、紧随其后的冒号、以及具体 PDO 驱动的连接语法组成。更深入的信息能从 PDO 具体驱动文档找到。

  `dsn` 参数支持三种不同的方式 创建一个数据库连接：

  驱动程序调用

    `dsn` 包含完整的DSN。

  URI 调用

    `dsn` 由 `uri:` 后跟 URI 组成，该 URI 包含定义 DSN 字符串的文件位置。URI 可以指定本地文件或远程 URL。

    `uri:file:///path/to/dsnfile`

  别名

    `dsn` 由映射到 php.ini 中定义 DSN 字符串的 `pdo.dsn.`name`` 的 `name` 名组成。

    > 注意:

    > 别名必须得在 php.ini 中定义了，不能是在 .htaccess 或 httpd.conf 中 。

`username`

  DSN字符串中的用户名。对于某些PDO驱动，此参数为可选项。

`password`

  DSN字符串中的密码。对于某些PDO驱动，此参数为可选项。

`options`

  一个具体驱动的连接选项的键=>值数组。

### 错误／异常

如果试图连接到请求的数据库失败，无论当前设置了哪个 `PDO::ATTR_ERRMODE`，则会抛出 PDOException。

### 示例

示例 #1 通过驱动程序调用创建 PDO 实例

    <?php

    $dsn = 'mysql:dbname=testdb;host=127.0.0.1';
    $user = 'dbuser';
    $password = 'dbpass';

    $dbh = new PDO($dsn, $user, $password);

    ?>

示例 #2 通过 URI 调用创建 PDO 实例

以下示例假设存在文件 /usr/local/dbconnect，并且具有允许 PHP 读取该文件的权限。该文件包含通过 PDO_ODBC 驱动程序连接到 DB2 数据库的 PDO DSN：

    odbc:DSN=SAMPLE;UID=john;PWD=mypass

PHP 脚本可以简单的传递指向文件 URI 的 `uri:` 参数来创建数据库连接：

    <?php

    $dsn = 'uri:file:///usr/local/dbconnect';
    $user = '';
    $password = '';

    $dbh = new PDO($dsn, $user, $password);

    ?>

示例 #3 使用别名创建 PDO 实例

以下示例假定 php.ini 包含以下条目，以仅使用别名 `mydb` 启用与 MySQL 数据库的连接：

    [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 — 获取跟数据库句柄上一次操作相关的 SQLSTATE

### 说明

public function PDO::errorCode(): ?string

### 参数

此函数没有参数。

### 返回值

返回一个 SQLSTATE，一个由 5 个字母或数字组成的在 ANSI SQL 标准中定义的标识符。 简要地说，一个 SQLSTATE 由前面两个字符的类值和后面三个字符的子类值组成。 A class value of 01 indicates a warning and is accompanied by a return code of SQL_SUCCESS_WITH_INFO. Class values other than '01', except for the class 'IM', indicate an error. The class 'IM' is specific to warnings and errors that derive from the implementation of PDO (or perhaps ODBC, if you're using the ODBC driver) itself. The subclass value '000' in any class indicates that there is no subclass for that SQLSTATE.

PDO::errorCode() 仅检索直接在数据库句柄上操作执行的错误代码。如果通过 PDO::prepare() 或 PDO::query() 创建的 PDOStatement 对象并且在 statement 句柄上调用错误，PDO::errorCode() 将不会反映该错误。必须在特定 statement 句柄上调用 PDOStatement::errorCode() 返回操作执行的错误代码。

如果数据库句柄没有进行操作，则返回 `null` 。

### 示例

示例 #1 取得一个 SQLSTATE 码

    <?php
    /* 引发一个错误 -- BONES 数据表不存在 */
    $dbh->exec("INSERT INTO bones(skull) VALUES ('lucy')");

    echo "\nPDO::errorCode(): ", $dbh->errorCode();
    ?>

以上示例会输出：

    PDO::errorCode(): 42S02

### 参见

- PDO::errorInfo() - Fetch extended error information associated with the last operation on the database handle
- PDOStatement::errorCode() - 获取跟上一次语句句柄操作相关的 SQLSTATE
- PDOStatement::errorInfo() - 获取跟上一次语句句柄操作相关的扩展错误信息

# PDO::errorInfo

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::errorInfo — Fetch extended error information associated with the last operation on the database handle

### 说明

public function PDO::errorInfo(): array

### 参数

此函数没有参数。

### 返回值

PDO::errorInfo() returns an array of error information about the last operation performed by this database handle. The array consists of at least the following fields:

Element | Information
--- | ---
0 | SQLSTATE error code (a five characters alphanumeric identifier defined in the ANSI SQL standard).
1 | Driver-specific error code.
2 | Driver-specific error message.

> 注意:

> If the SQLSTATE error code is not set or there is no driver-specific error, the elements following element 0 will be set to `null`.

PDO::errorInfo() only retrieves error information for operations performed directly on the database handle. If you create a PDOStatement object through PDO::prepare() or PDO::query() and invoke an error on the statement handle, PDO::errorInfo() will not reflect the error from the statement handle. You must call PDOStatement::errorInfo() to return the error information for an operation performed on a particular statement handle.

### 示例

示例 #1 Displaying errorInfo() fields for a PDO_ODBC connection to a DB2 database

    <?php
    /* Provoke an error -- bogus SQL syntax */
    $stmt = $dbh->prepare('bogus sql');
    if (!$stmt) {
        echo "\nPDO::errorInfo():\n";
        print_r($dbh->errorInfo());
    }
    ?>

以上示例会输出：

    PDO::errorInfo():
    Array
    (
        [0] => HY000
        [1] => 1
        [2] => near "bogus": syntax error
    )

### 参见

- PDO::errorCode() - 获取跟数据库句柄上一次操作相关的 SQLSTATE
- PDOStatement::errorCode() - 获取跟上一次语句句柄操作相关的 SQLSTATE
- PDOStatement::errorInfo() - 获取跟上一次语句句柄操作相关的扩展错误信息

# PDO::exec

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::exec — 执行 SQL 语句，并返回受影响的行数

### 说明

public function PDO::exec(string `$statement`): int|false

PDO::exec() 在单独的函数调用中执行 SQL 语句，返回受此语句影响的行数。

PDO::exec() 不会从 SELECT 语句中返回结果。对于在程序中只需要发出一次的 SELECT 语句，可以考虑使用 PDO::query()。对于需要发出多次的语句，可用 PDO::prepare() 来预处理 PDOStatement 对象并用 PDOStatement::execute() 发出语句。

### 参数

`statement`

  要被预处理和执行的 SQL 语句。

  查询中的数据应正确转义。

### 返回值

PDO::exec() 返回 SQL 语句修改或删除影响的行数。如果没有受影响的行，则 PDO::exec() 返回 `0`。

警告

此函数可能返回布尔值 `false`，但也可能返回等同于 `false` 的非布尔值。请阅读 布尔类型章节以获取更多信息。应使用 === 运算符来测试此函数的返回值。

下列示例错误依赖 PDO::exec() 的返回值，其中受影响行数为 0 的语句会导致调用 die()：

    <?php
    $db->exec() or die(print_r($db->errorInfo(), true)); // 错误
    ?>

### 错误／异常

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_WARNING`，则发出级别为 `E_WARNING` 的错误。

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_EXCEPTION`，则抛出 PDOException。

### 示例

示例 #1 发出 DELETE 语句

计算不带 WHERE 子句的 DELETE 语句删除的行数。

    <?php
    $dbh = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');

    /*  删除 FRUIT 数据表中满足条件的所有行 */
    $count = $dbh->exec("DELETE FROM fruit");

    /* 返回被删除的行数 */
    print "Deleted $count rows.\n";
    ?>

以上示例会输出：

    Deleted 1 rows.

### 参见

- PDO::prepare() - 预处理要执行的语句，并返回语句对象
- PDO::query() - 预处理并执行没有占位符的 SQL 语句
- PDOStatement::execute() - 执行预处理语句

# PDO::getAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDO::getAttribute — 取回一个数据库连接的属性

### 说明

public function PDO::getAttribute(int `$attribute`): mixed

此方法返回数据库连接属性的值。要检索 PDOStatement 属性，请参阅 PDOStatement::getAttribute()。

注意有些数据库/驱动可能不支持所有的数据库连接属性。

### 参数

`attribute`

  `PDO::ATTR_*` 常量之一。下列为应用到数据库连接中的通用属性：

  - `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`
  一些驱动程序可能会使用额外的特定驱动程序属性。请注意，特定驱动程序的属性不能与其它驱动程序一起使用。

### 返回值

成功调用则返回请求的 PDO 属性值。不成功则返回 `null`。

### 错误／异常

当底层驱动程序不支持请求的 `attribute` 时， PDO::getAttribute() 可能会抛出 PDOException。

### 示例

示例 #1 取回数据库连接属性

    <?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";
    }
    ?>

### 参见

- PDO::setAttribute() - 设置属性
- PDOStatement::getAttribute() - 检索语句属性
- PDOStatement::setAttribute() - 设置一个语句属性

# PDO::getAvailableDrivers

# pdo_drivers

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.3)

PDO::getAvailableDrivers -- pdo_drivers — 返回一个可用驱动的数组

### 说明

public static function PDO::getAvailableDrivers(): array
function pdo_drivers(): array

此方法返回所有当前可用在 PDO::__construct() 的 `DSN` 参数中的 PDO 驱动。

### 参数

此函数没有参数。

### 返回值

PDO::getAvailableDrivers() 返回包含可用 PDO 驱动名字的数组。如果没有可用的驱动，则返回空数组。

### 示例

示例 #1 PDO::getAvailableDrivers() 示例

    <?php
    print_r(PDO::getAvailableDrivers());
    ?>

以上示例的输出类似于：

    Array
    (
        [0] => mysql
        [1] => sqlite
    )

# PDO::inTransaction

(PHP 5 >= 5.3.3, Bundled pdo_pgsql, PHP 7, PHP 8)

PDO::inTransaction — 检查是否在事务内

### 说明

public function PDO::inTransaction(): bool

检查驱动内的事务当前是否处于激活。此方法仅对支持事务的数据库驱动起作用。

### 参数

此函数没有参数。

### 返回值

如果当前事务处于激活，则返回 `true` ，否则返回 `false` 。

# PDO::lastInsertId

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::lastInsertId — 返回最后插入行的ID或序列值

### 说明

public function PDO::lastInsertId(?string `$name` = `null`): string|false

返回最后插入行的 ID，或者是序列对象最后的值，取决于底层的驱动。比如，PDO_PGSQL 允许为 `name` 参数指定任何序列对象的名称。

> 注意:

> 在不同的 PDO 驱动之间，此方法可能不会返回有意义或一致的结果，因为底层数据库可能不支持自增字段或序列的概念。

### 参数

`name`

  应该返回 ID 的序列对象的名称。

### 返回值

如果没有为参数 `name` 指定序列名称，PDO::lastInsertId() 返回表示最后插入数据库行的 ID 的字符串。

如果为参数 `name` 指定了序列名称，PDO::lastInsertId() 则返回表示从指定序列对象取回最后的值的字符串。

如果当前 PDO 驱动不支持此功能，则 PDO::lastInsertId() 触发一个 `IM001` SQLSTATE 。

### 错误／异常

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_WARNING`，则发出级别为 `E_WARNING` 的错误。

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_EXCEPTION`，则抛出 PDOException。

# PDO::prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PHP 8,PECL pdo >= 0.1.0)

PDO::prepare — 预处理要执行的语句，并返回语句对象

### 说明

public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false

为 PDOStatement::execute() 方法预处理待执行的 SQL 语句。 语句模板可以包含零个或多个参数占位标记，格式是命名（:name）或问号（?）的形式，当它执行时将用真实数据取代。 在同一个语句模板里，命名形式和问号形式不能同时使用；只能选择其中一种参数形式。 请用参数形式绑定用户输入的数据，不要直接字符串拼接到查询里。

调用 PDOStatement::execute() 时，每一个值的参数占位标记，名称必须唯一。 除非启用模拟（emulation）模式，同一个语句里无法使用重名的参数。

> 注意:

> 参数占位符仅能字面上展示完整的数据。不能是字面的一部分，不能是关键词，不能是标识符，不能是其他任意的范围。 举例说明：不能把多个值绑到单个参数里，然后在 SQL 语句里用 IN() 查询。

如果用不同参数，通过 PDO::prepare() 和 PDOStatement::execute() 多次调用同一个 SQL 语句，将提升应用的性能 —— 驱动可以让客户端/服务器缓存查询和元信息。 同时，调用 PDO::prepare() 和 PDOStatement::execute() 还能阻止 SQL 注入攻击，不需要给参数手动加引号与转义。

如果内置驱动不支持参数，PDO 将模拟出参数的功能；如果驱动仅仅支持其中一种风格（命名参数和问号参数两种），也会自动重写到另外一种风格。

> 注意: The parser used for emulated prepared statements and for rewriting named or question mark style parameters supports the non standard backslash escapes for single- and double quotes. That means that terminating quotes immediately preceeded by a backslash are not recognized as such, which may result in wrong detection of parameters causing the prepared statement to fail when it is executed. A work-around is to not use emulated prepares for such SQL queries, and to avoid rewriting of parameters by using a parameter style which is natively supported by the driver.

自 PHP 7.4.0 起，可以通过两个问号来转义问号。这意味着 `??` 在发送查询到数据库时会转换成 `?`。

### 参数

`query`

  必须是对目标数据库服务器有效的 SQL 语句模板。

`options`

  数组包含一个或多个 key=>value 键值对，为返回的 PDOStatement 对象设置属性。 常见用法是：设置 `PDO::ATTR_CURSOR` 为 `PDO::CURSOR_SCROLL`，将得到可滚动的光标。 某些驱动有驱动级的选项，在 prepare 时就设置。

### 返回值

如果数据库服务器已经成功预处理语句，PDO::prepare() 返回 PDOStatement 对象。 如果数据库服务器无法预处理语句，PDO::prepare() 返回 `false` 或抛出 PDOException (取决于 错误处理)。

> 注意:

> 模拟模式下的预处理语句不会和数据库服务器交互，所以 PDO::prepare() 不会检查语句。

### 错误／异常

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_WARNING`，则发出级别为 `E_WARNING` 的错误。

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_EXCEPTION`，则抛出 PDOException。

### 示例

示例 #1 命名参数形式的 SQL 语句模板

    <?php
    /* 传入数组的值，并执行已预处理的语句 */
    $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();
    /* Array keys can be prefixed with colons ":" too (optional) */
    $sth->execute([':calories' => 175, ':colour' => 'yellow']);
    $yellow = $sth->fetchAll();
    ?>

示例 #2 问号形式的 SQL 语句模板

    <?php
    /* 传入数组的值，并执行已预处理的语句 */
    $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();
    ?>

示例 #3 问号转义的 SQL 语句模板

    <?php
    /* note: this is only valid on PostgreSQL databases */
    $sth = $dbh->prepare('SELECT * FROM issues WHERE tag::jsonb ?? ?');
    $sth->execute(['feature']);
    $featureIssues = $sth->fetchAll();
    $sth->execute(['performance']);
    $performanceIssues = $sth->fetchAll();
    ?>

### 参见

- PDO::exec() - 执行 SQL 语句，并返回受影响的行数
- PDO::query() - 预处理并执行没有占位符的 SQL 语句
- PDOStatement::execute() - 执行预处理语句

# PDO::query

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDO::query — 预处理并执行没有占位符的 SQL 语句

### 说明

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

PDO::query() 在单次函数调用内预处理并执行 SQL 语句，以 PDOStatement 对象形式返回结果集（如果有数据的话）。

如果反复调用同一个查询，用 PDO::prepare() 准备 PDOStatement 对象，并用 PDOStatement::execute() 执行语句，将具有更好的性能。

如果没有完整获取结果集内的数据，就调用下一个 PDO::query()，将可能调用失败。应当在执行下一个 PDO::query() 前，先用 PDOStatement::closeCursor() 释放数据库 PDOStatement 关联的资源。

> 注意:

> 如果 `query` 包含占位符，则必须使用 PDO::prepare() 和 PDOStatement::execute() 方法分别预处理和执行语句。

### 参数

`query`

  预处理和执行的 SQL 语句。

  如果 SQL 包含占位符，则必须使用 PDO::prepare() 和 PDOStatement::execute()。或者在调用 PDO::query() 之前手动预处理 SQL，如果驱动程序支持，使用 PDO::quote() 正确格式化数据。

`fetchMode`

  返回 PDOStatement 的默认获取模式。必须是 `PDO::FETCH_*` 常量之一。

  If this argument is passed to the function, the remaining arguments will be treated as though PDOStatement::setFetchMode() was called on the resultant statement object. The subsequent arguments vary depending on the selected fetch mode.

### 返回值

返回 PDOStatement 对象 或者在失败时返回 `false`

### 错误／异常

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_WARNING`，则发出级别为 `E_WARNING` 的错误。

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_EXCEPTION`，则抛出 PDOException。

### 示例

示例 #1 没有占位符的 SQL 可以使用 PDO::query() 执行

    <?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";
    }
    ?>

以上示例会输出：

    apple   red     150
    banana  yellow  250
    kiwi    brown   75
    lemon   yellow  25
    orange  orange  300
    pear    green   150
    watermelon      pink    90

### 参见

- PDO::exec() - 执行 SQL 语句，并返回受影响的行数
- PDO::prepare() - 预处理要执行的语句，并返回语句对象
- PDOStatement::execute() - 执行预处理语句

# PDO::quote

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.1)

PDO::quote — 为 SQL 查询里的字符串添加引号

### 说明

public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false

PDO::quote() 为输入的字符串添加引号，并对特殊字符进行转义，且引号的风格和底层驱动适配。

如果使用此函数构建 SQL 语句，强烈建议使用 PDO::prepare() 配合参数构建，而不是用 PDO::quote() 把用户输入的数据拼接进 SQL 语句。使用 prepare 语句处理参数，不仅仅可移植性更好，而且更方便、免疫 SQL 注入；相对于拼接 SQL 更快，客户端和服务器都能缓存编译后的 SQL 查询。

不是所有的 PDO 驱动都实现了此功能（例如 PDO_ODBC）。 考虑使用 prepare 代替。

警告

# 安全性：默认字符集

字符集不仅仅要在数据库服务器上设置，也要为数据库连接设置（取决于驱动），它影响了 PDO::quote()。 更多信息可参考PDO 驱动文档。

### 参数

`string`

  要添加引号的字符串。

`type`

  为驱动程序的数据类型提供引号风格的提示。例如 `PDO_PARAM_LOB` 将告诉驱动程序转义二进制数据。

### 返回值

返回加引号的字符串，理论上可以安全用于 SQL 语句。 如果驱动不支持这种方式，将返回 `false` 。

### 示例

示例 #1 普通字符串加引号

    <?php
    $conn = new PDO('sqlite:/home/lynn/music.sql3');

    /* 简单字符串 */
    $string = 'Nice';
    print "Unquoted string: $string\n";
    print "Quoted string: " . $conn->quote($string) . "\n";
    ?>

以上示例会输出：

    Unquoted string: Nice
    Quoted string: 'Nice'

示例 #2 危险字符串加引号

    <?php
    $conn = new PDO('sqlite:/home/lynn/music.sql3');

    /* 危险字符串 */
    $string = 'Naughty \' string';
    print "Unquoted string: $string\n";
    print "Quoted string:" . $conn->quote($string) . "\n";
    ?>

以上示例会输出：

    Unquoted string: Naughty ' string
    Quoted string: 'Naughty '' string'

示例 #3 复杂字符串加引号

    <?php
    $conn = new PDO('sqlite:/home/lynn/music.sql3');

    /* 复杂字符串 */
    $string = "Co'mpl''ex \"st'\"ring";
    print "Unquoted string: $string\n";
    print "Quoted string: " . $conn->quote($string) . "\n";
    ?>

以上示例会输出：

    Unquoted string: Co'mpl''ex "st'"ring
    Quoted string: 'Co''mpl''''ex "st''"ring'

### 参见

- PDO::prepare() - 预处理要执行的语句，并返回语句对象
- PDOStatement::execute() - 执行预处理语句

# PDO::rollBack

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::rollBack — 回滚事务

### 说明

public function PDO::rollBack(): bool

回滚由 PDO::beginTransaction() 发起的当前事务。如果没有事务激活，将抛出一个 PDOException 异常。

如果数据库被设置成自动提交模式，此函数（方法）在回滚事务之后将恢复自动提交模式。

包括 MySQL 在内的一些数据库， 当在一个事务内有类似删除或创建数据表等 DLL 语句时，会自动导致一个隐式地提交。隐式地提交将无法回滚此事务范围内的任何更改。

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

如果没有活动的事务，则抛出 PDOException。

> 注意: `PDO::ATTR_ERRMODE` 属性不是 `PDO::ERRMODE_EXCEPTION` 时会抛出一个异常。

### 示例

示例 #1 回滚一个事务

下面示例在回滚更改之前开始一个事务并发出两条修改数据库的语句。但在 MySQL 中，DROP TABLE 语句自动提交事务，因此在此事务内的任何更改都不会被回滚。

    <?php
    /* 开始一个事务，关闭自动提交 */
    $dbh->beginTransaction();

    /* 更改数据库架构和数据  */
    $sth = $dbh->exec("DROP TABLE fruit");
    $sth = $dbh->exec("UPDATE dessert
        SET name = 'hamburger'");

    /*  识别错误且回滚更改  */
    $dbh->rollBack();

    /*  此时数据库连接恢复到自动提交模式  */
    ?>

### 参见

- PDO::beginTransaction() - 启动一个事务
- PDO::commit() - 提交一个事务
- 事务和自动提交

# PDO::setAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::setAttribute — 设置属性

### 说明

public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool

设置数据库句柄属性。下面列出了一些可用的通用属性；有些驱动可能使用另外的特定属性。 请注意，特定的驱动程序属性不得用于其他驱动程序。

`PDO::ATTR_CASE`

  强制列名为指定的大小写。可以采用以下某个值：

  `PDO::CASE_LOWER`
    强制列名小写。
  `PDO::CASE_NATURAL`
    保留数据库驱动返回的列名。
  `PDO::CASE_UPPER`
    强制列名大写。
`PDO::ATTR_ERRMODE`

  PDO 的报错方式。可以采用以下某个值：

  `PDO::ERRMODE_SILENT`
    仅设置错误代码。
  `PDO::ERRMODE_WARNING`
    引发 `E_WARNING` 警告。
  `PDO::ERRMODE_EXCEPTION`
    抛出 PDOException。
`PDO::ATTR_ORACLE_NULLS`

  > 注意: 此属性适用于所有驱动程序，而不仅仅是 Oracle。

  确定是否以及如何转换 `null` 和空字符串。可以采用以下值之一：

  `PDO::NULL_NATURAL`
    不发生转换。
  `PDO::NULL_EMPTY_STRING`
    空字符串转换为 `null`。
  `PDO::NULL_TO_STRING`
    `null` 被转换为空字符串。
`PDO::ATTR_STRINGIFY_FETCHES`

  控制是否将获取的值（`null` 除外）转换为字符串。采用 bool 类型的值：`true` 表示启用，`false` 表示禁用（默认）。除非将 `PDO::ATTR_ORACLE_NULLS` 设置为 `PDO::NULL_TO_STRING`，否则 `null` 值保持不变。

`PDO::ATTR_STATEMENT_CLASS`

  设置从 PDOStatement 派生的用户提供的语句类。 需要 `array(string classname, array(mixed constructor_args))`。

  警告

  不能用于持久 PDO 实例。

`PDO::ATTR_TIMEOUT`

  指定超时的秒数。需要 int 类型的值。

  > 注意:

  > 并非所有驱动都支持此选项，这意味着驱动和驱动之间可能会有差异。比如，SQLite 等待的时间达到此值后就放弃获取可写锁，但其他驱动可能会将此值解释为一个连接或读取超时的间隔。

`PDO::ATTR_AUTOCOMMIT`

  > 注意: 仅适用于 OCI、Firebird 和 MySQL 驱动程序。

  是否自动提交每个单独的语句。采用 bool 类型的值：`true` 表示启用，`false` 表示禁用。默认为 `true`。

`PDO::ATTR_EMULATE_PREPARES`

  > 注意: 仅适用于 OCI、Firebird 和 MySQL 驱动程序。

  是否启用或禁用预处理语句的模拟。有些驱动天然不支持或有限度地支持预处理语句。如果设置为 `true`，PDO 始终模拟预处理语句，否则 PDO 将会尝试使用本地预处理语句。如果驱动不能成功预处理当前查询，PDO 将始终回退到模拟预处理语句上。

`PDO::MYSQL_ATTR_USE_BUFFERED_QUERY`

  > 注意: 仅适用于 MySQL 驱动程序。

  是否使用缓冲查询。采用 bool 类型的值：`true` 表示启用，`false` 表示禁用。默认情况下，默认为 `true`。

`PDO::ATTR_DEFAULT_FETCH_MODE`

  设置默认获取模式。关于模式的说明以及如何使用可以在 PDOStatement::fetch() 文档找到。

### 参数

`attribute`

  要修改的属性。

`value`

  设置 `attribute` 的值，属性的不同导致需要的类型也会不同。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- PDO::getAttribute() - 取回一个数据库连接的属性
- PDOStatement::getAttribute() - 检索语句属性
- PDOStatement::setAttribute() - 设置一个语句属性

## 目录

- PDO::beginTransaction — 启动一个事务
- PDO::commit — 提交一个事务
- PDO::connect — Connect to a database and return a PDO subclass for drivers that support it
- PDO::__construct — 创建一个表示数据库连接的 PDO 实例
- PDO::errorCode — 获取跟数据库句柄上一次操作相关的 SQLSTATE
- PDO::errorInfo — Fetch extended error information associated with the last operation on the database handle
- PDO::exec — 执行 SQL 语句，并返回受影响的行数
- PDO::getAttribute — 取回一个数据库连接的属性
- PDO::getAvailableDrivers — 返回一个可用驱动的数组
- PDO::inTransaction — 检查是否在事务内
- PDO::lastInsertId — 返回最后插入行的ID或序列值
- PDO::prepare — 预处理要执行的语句，并返回语句对象
- PDO::query — 预处理并执行没有占位符的 SQL 语句
- PDO::quote — 为 SQL 查询里的字符串添加引号
- PDO::rollBack — 回滚事务
- PDO::setAttribute — 设置属性

# PDOStatement 类

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

## 简介

代表一条预处理语句，并在该语句被执行后代表一个相关的结果集。

## 类摘要

class PDOStatement {
/* 属性 */
public string $queryString;
/* 方法 */
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`): bool
public function setFetchMode(int `$mode` = PDO::FETCH_COLUMN, int `$colno`): bool
public function setFetchMode(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs` = `null`): bool
public function setFetchMode(int `$mode` = PDO::FETCH_INTO, object `$object`): bool
}

## 属性

queryString

  所用的查询字符串

## 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 PDOStatement 的实现不是 Traversable 而是 IteratorAggregate。

# PDOStatement::bindColumn

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::bindColumn — 绑定一列到一个 PHP 变量

### 说明

public function PDOStatement::bindColumn(
string|int `$column`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool

PDOStatement::bindColumn() 安排特定变量绑定到查询结果集中的指定列。每次调用 PDOStatement::fetch() 或 PDOStatement::fetchAll() 都将更新所有绑定到列的变量。

> 注意:

> 在语句执行前 PDO 有关列的信息并非总是可用，可移植的应用应在 PDOStatement::execute() 之后 调用此函数（方法）。

> 但是，当使用 PgSQL 驱动时，要想能绑定 LOB 列作为流，应用程序必须在调用 PDOStatement::execute() 之前 调用此方法，否则大对象 OID 作为整数返回。

### 参数

`column`

  结果集中的列号（从1开始索引）或列名。如果使用列名，注意名称应该与由驱动返回的列名大小写保持一致。

`var`

  将绑定到列的 PHP 变量名称

`type`

  通过 `PDO::PARAM_*` 常量指定的参数的数据类型。

`maxLength`

  预分配提示。

`driverOptions`

  驱动的可选参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_WARNING`，则发出级别为 `E_WARNING` 的错误。

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_EXCEPTION`，则抛出 PDOException。

### 示例

示例 #1 把结果集输出绑定到 PHP 变量

绑定结果集中的列到PHP变量是一种使每行包含的数据在应用程序中立即可用的有效方法。下面的示例演示了 PDO 怎样用多种选项和缺省值绑定和检索列。

    <?php
    $stmt = $dbh->prepare('SELECT name, colour, calories FROM fruit');
    $stmt->execute();

    /* 通过列号绑定 */
    $stmt->bindColumn(1, $name);
    $stmt->bindColumn(2, $colour);

    /* 通过列名绑定 */
    $stmt->bindColumn('calories', $cals);

    while ($stmt->fetch(PDO::FETCH_BOUND)) {
        print $name . "\t" . $colour . "\t" . $cals . "\n";
    }

以上示例的输出类似于：

    apple   red     150
    banana  yellow  175
    kiwi    green   75
    orange  orange  150
    mango   red     200
    strawberry      red     25

### 参见

- PDOStatement::execute() - 执行预处理语句
- PDOStatement::fetch() - 从结果集中获取下一行
- PDOStatement::fetchAll() - 从结果集中获取剩余的行
- PDOStatement::fetchColumn() - 从结果集中的下一行返回单独的一列

# PDOStatement::bindParam

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::bindParam — 绑定一个参数到指定的变量名

### 说明

public function PDOStatement::bindParam(
string|int `$param`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool

绑定一个PHP变量到用作预处理的SQL语句中的对应命名占位符或问号占位符。 不同于 PDOStatement::bindValue() ，此变量作为引用被绑定，并只在 PDOStatement::execute() 被调用的时候才取其值。

大多数参数是输入参数，即，参数以只读的方式用来建立查询（但仍然可以根据 `type` 进行转换）。一些驱动支持调用存储过程并作为输出参数返回数据，一些支持作为输入/输出参数，既发送数据又接收更新后的数据。

### 参数

`param`

  参数标识符。对于使用命名占位符的预处理语句，应是类似 :name 形式的参数名。对于使用问号占位符的预处理语句，应是以1开始索引的参数位置。

`var`

  绑定到 SQL 语句参数的 PHP 变量名。

`type`

  使用 `PDO::PARAM_*` 常量明确地指定参数的类型。要从存储过程中返回 INOUT 参数，需要为 `type` 参数使用按位或操作符去设置 `PDO::PARAM_INPUT_OUTPUT` 位。

`maxLength`

  数据类型的长度。为表明参数是一个存储过程的 OUT 参数，必须明确地设置此长度。 仅当 `type` 参数为 `PDO::PARAM_INPUT_OUTPUT` 时才有意义。

`driverOptions`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_WARNING`，则发出级别为 `E_WARNING` 的错误。

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_EXCEPTION`，则抛出 PDOException。

### 示例

示例 #1 执行一条使用命名占位符的预处理语句

    <?php
    /* 通过绑定的 PHP 变量执行一条预处理语句  */
    $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->bindParam(':colour', $colour, PDO::PARAM_STR);
    $sth->execute();
    ?>

示例 #2 执行一条使用问号占位符的预处理语句

    <?php
    /*  通过绑定的 PHP 变量执行一条预处理语句 */
    $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();
    ?>

示例 #3 使用 INOUT 参数调用一个存储过程

    <?php
    /* 使用 INOUT 参数调用一个存储过程 */
    $colour = 'red';
    $sth = $dbh->prepare('CALL puree_fruit(?)');
    $sth->bindParam(1, $colour, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT, 12);
    $sth->execute();
    print "After pureeing fruit, the colour is: $colour";
    ?>

### 参见

- PDO::prepare() - 预处理要执行的语句，并返回语句对象
- PDOStatement::execute() - 执行预处理语句
- PDOStatement::bindValue() - 把一个值绑定到一个参数

# PDOStatement::bindValue

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

PDOStatement::bindValue — 把一个值绑定到一个参数

### 说明

public function PDOStatement::bindValue(string|int `$param`, mixed `$value`, int `$type` = `PDO::PARAM_STR`): bool

绑定一个值到用作预处理的 SQL 语句中的对应命名占位符或问号占位符。

### 参数

`param`

  参数标识符。对于使用命名占位符的预处理语句，应是类似 :name 形式的参数名。对于使用问号占位符的预处理语句，应是以1开始索引的参数位置。

`value`

  绑定到参数的值

`type`

  使用 `PDO::PARAM_*` 常量明确地指定参数的类型。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_WARNING`，则发出级别为 `E_WARNING` 的错误。

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_EXCEPTION`，则抛出 PDOException。

### 示例

示例 #1 执行一条使用命名占位符的预处理语句

    <?php
    /* 通过绑定的 PHP 变量执行一条预处理语句 */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour');

    /* 使用名字设置参数值 */
    $sth->bindValue('calories', $calories, PDO::PARAM_INT);
    /* 视需要，参数名也可以以冒号“:”为前缀 */
    $sth->bindValue(':colour', $colour, PDO::PARAM_STR);
    $sth->execute();
    ?>

示例 #2 执行一条使用问号占位符的预处理语句

    <?php
    /* 通过绑定的 PHP 变量执行一条预处理语句 */
    $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();
    ?>

### 参见

- PDO::prepare() - 预处理要执行的语句，并返回语句对象
- PDOStatement::execute() - 执行预处理语句
- PDOStatement::bindParam() - 绑定一个参数到指定的变量名

# PDOStatement::closeCursor

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::closeCursor — 关闭游标，使语句能再次被执行

### 说明

public function PDOStatement::closeCursor(): bool

PDOStatement::closeCursor() 释放到数据库服务的连接，以便发出其他 SQL 语句，但使语句处于一个可以被再次执行的状态。

当上一个执行的 PDOStatement 对象仍有未取行时，此方法对那些不支持再执行一个 PDOStatement 对象的数据库驱动非常有用。 如果数据库驱动受此限制，则可能出现失序错误的问题。

PDOStatement::closeCursor() 要么是一个可选驱动的特有方法（效率最高）来实现，要么是在没有驱动特定的功能时作为一般的PDO 备用来实现。一般的备用语义上与下面的 PHP 代码相同：

    <?php
    do {
        while ($stmt->fetch())
            ;
        if (!$stmt->nextRowset())
            break;
    } while (true);
    ?>

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_WARNING`，则发出级别为 `E_WARNING` 的错误。

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_EXCEPTION`，则抛出 PDOException。

### 示例

示例 #1 PDOStatement::closeCursor() 示例

在下面示例中，$stmt PDOStatement 对象返回多行，但应用程序只取第一行，让 PDOStatement 对象处于一个有未取行的状态。为确保应用程序对所有数据库驱动都能正常运行，在执行 $otherStmt PDOStatement 对象前，在 $stmt 调用 PDOStatement::closeCursor()。

    <?php
    /* 创建一个 PDOStatement 对象 */
    $stmt = $dbh->prepare('SELECT foo FROM bar');

    /* 创建第二个 PDOStatement 对象 */
    $otherStmt = $dbh->prepare('SELECT foobaz FROM foobar');

    /* 执行第一条语句 */
    $stmt->execute();

    /*  从结果集中只取出第一行 */
    $stmt->fetch();

    /* The following call to closeCursor() may be required by some drivers */
    $stmt->closeCursor();

    /*  现在可以执行第二条语句了 */
    $otherStmt->execute();
    ?>

### 参见

- PDOStatement::execute() - 执行预处理语句

# PDOStatement::columnCount

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::columnCount — 返回结果集中的列数

### 说明

public function PDOStatement::columnCount(): int

使用 PDOStatement::columnCount() 返回由 PDOStatement 对象代表的结果集中的列数。

如果是由 PDO::query() 返回的 PDOStatement 对象，则列数计算立即可用。

如果是由 PDO::prepare() 返回的 PDOStatement 对象，则在调用 PDOStatement::execute() 之前都不能准确地计算出列数。

### 参数

此函数没有参数。

### 返回值

返回由 PDOStatement 对象代表的结果集中的列数，即便结果集为空。如果没有结果集，则 PDOStatement::columnCount() 返回 `0`。

### 错误／异常

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_WARNING`，则发出级别为 `E_WARNING` 的错误。

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_EXCEPTION`，则抛出 PDOException。

### 示例

示例 #1 计算列数

下面示例演示如何使用 PDOStatement::columnCount() 操作一个结果集和一个空集。

    <?php
    $dbh = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");

    /*  计算一个（不存在）的结果集中的列数 */
    $colcount = $sth->columnCount();
    print "Before execute(), result set has $colcount columns (should be 0)\n";

    $sth->execute();

    /* 计算结果集中的列数 */
    $colcount = $sth->columnCount();
    print "After execute(), result set has $colcount columns (should be 2)\n";

    ?>

以上示例会输出：

    Before execute(), result set has 0 columns (should be 0)
    After execute(), result set has 2 columns (should be 2)

### 参见

- PDO::prepare() - 预处理要执行的语句，并返回语句对象
- PDOStatement::execute() - 执行预处理语句
- PDOStatement::rowCount() - 返回受上一个 SQL 语句影响的行数

# PDOStatement::debugDumpParams

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::debugDumpParams — 打印一条 SQL 预处理命令

### 说明

public function PDOStatement::debugDumpParams(): ?bool

直接打印出一条预处理语句包含的信息。提供正在使用的 `SQL` 查询、所用参数（`Params`）的数目、参数列表及其键名或位置、名称以及查询中的位置（如果当前 POD 驱动不支持，则为 -1），类型（`param_type`）为整数且 `is_param` 为布尔值。

这是调试函数，在正常输出的情况下直接输出数据。

小技巧

和直接将结果输出到浏览器一样，可使用输出控制函数来捕获当前函数的输出，然后(例如)保存到一个 string 中。

只打印此时此刻语句中的参数。额外的参数不存储在语句中，也就不会被输出。

### 参数

此函数没有参数。

### 返回值

返回 `null`, 或者错误时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
7.2.0 | PDOStatement::debugDumpParams() 现在返回发送到数据库的 SQL，包括完整的原始查询（包括替换的占位符及其边界值）。请注意，这仅在打开模拟预处理语句时才可用。

### 示例

示例 #1 PDOStatement::debugDumpParams() 使用命名参数的示例

    <?php
    /* 通过绑定 PHP 变量执行一条预处理语句 */
    $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();

    ?>

以上示例会输出：

    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

示例 #2 PDOStatement::debugDumpParams() 使用未命名参数的示例

    <?php

    /* 通过绑定 PHP 变量执行一条预处理语句 */
    $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();

    ?>

以上示例会输出：

    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

### 参见

- PDO::prepare() - 预处理要执行的语句，并返回语句对象
- PDOStatement::bindParam() - 绑定一个参数到指定的变量名
- PDOStatement::bindValue() - 把一个值绑定到一个参数

# PDOStatement::errorCode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::errorCode — 获取跟上一次语句句柄操作相关的 SQLSTATE

### 说明

public function PDOStatement::errorCode(): ?string

### 参数

此函数没有参数。

### 返回值

与 PDO::errorCode() 相同，只是 PDOStatement::errorCode() 只取回 PDOStatement 对象执行操作中的错误码。

### 示例

示例 #1 检索 SQLSTATE 码

    <?php
    /* 引发一个错误 --  BONES 数据表不存在 */
    $err = $dbh->prepare('SELECT skull FROM bones');
    $err->execute();

    echo "\nPDOStatement::errorCode(): ";
    print $err->errorCode();
    ?>

以上示例会输出：

    PDOStatement::errorCode(): 42S02

### 参见

- PDO::errorCode() - 获取跟数据库句柄上一次操作相关的 SQLSTATE
- PDO::errorInfo() - Fetch extended error information associated with the last operation on the database handle
- PDOStatement::errorInfo() - 获取跟上一次语句句柄操作相关的扩展错误信息

# PDOStatement::errorInfo

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::errorInfo — 获取跟上一次语句句柄操作相关的扩展错误信息

### 说明

public function PDOStatement::errorInfo(): array

### 参数

此函数没有参数。

### 返回值

PDOStatement::errorInfo() 返回一个关于上一次语句句柄执行操作的错误信息的数组。该数组至少包含下列字段：

Element | Information
--- | ---
0 | SQLSTATE 错误码（一个由5个字母或数字组成的在 ANSI SQL 标准中定义的标识符）。
1 | 具体驱动错误码。
2 | 具体驱动错误信息。

### 示例

示例 #1 显示连接到DB2数据库的 PDO_ODBC 连接的 errorInfo() 的字段

    <?php
    /* 激发一个错误 --  BONES 数据表不存在 */
    $sth = $dbh->prepare('SELECT skull FROM bones');
    $sth->execute();

    echo "\nPDOStatement::errorInfo():\n";
    $arr = $sth->errorInfo();
    print_r($arr);
    ?>

以上示例会输出：

    PDOStatement::errorInfo():
    Array
    (
        [0] => 42S02
        [1] => -204
        [2] => [IBM][CLI Driver][DB2/LINUX] SQL0204N  "DANIELS.BONES" is an undefined name.  SQLSTATE=42704
    )

### 参见

- PDO::errorCode() - 获取跟数据库句柄上一次操作相关的 SQLSTATE
- PDO::errorInfo() - Fetch extended error information associated with the last operation on the database handle
- PDOStatement::errorCode() - 获取跟上一次语句句柄操作相关的 SQLSTATE

# PDOStatement::execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::execute — 执行预处理语句

### 说明

public function PDOStatement::execute(?array `$params` = `null`): bool

执行预处理语句。如果预处理语句含有参数标记，必须选择下面其中一种做法：

- 必须调用 PDOStatement::bindParam() 和/或 PDOStatement::bindValue() 以将变量或值（分别）绑定到参数标记。如果有的话，通过关联参数标记绑定的变量来传递输入值和取得输出值

- 或必须传递只作为输入参数值的数组

### 参数

`params`

  一个元素个数和将被执行的 SQL 语句中绑定的参数一样多的数组。所有的值作为 `PDO::PARAM_STR` 对待。

  多个值不能绑定到一个参数；比如，不允许绑定两个值到 IN（）子句中一个单独的命名参数。

  绑定的值不能比指定的多；如果在 `params` 中存在比 PDO::prepare() 预处理的SQL 指定的多的键名，则此语句将会失败并发出一个错误。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_WARNING`，则发出级别为 `E_WARNING` 的错误。

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_EXCEPTION`，则抛出 PDOException。

### 示例

示例 #1 执行绑定变量和值的预处理语句

    <?php
    /* 通过绑定变量和值执行预处理语句 */
    $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);
    /* 名称也可以以冒号“:”为前缀（可选）*/
    $sth->bindValue(':colour', "%$colour%");
    $sth->execute();
    ?>

示例 #2 使用命名值数组执行预处理语句

    <?php
    /* 通过传递一个含有插入值的数组执行一条预处理语句 */
    $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));
    /* 数组键也可以以冒号“:”为前缀（可选）*/
    $sth->execute(array(':calories' => $calories, ':colour' => $colour));
    ?>

示例 #3 使用位置值数组执行预处理语句

    <?php
    /* 通过传递一个插入值的数组执行一条预处理语句 */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?');
    $sth->execute(array($calories, $colour));
    ?>

示例 #4 使用绑定到位置占位符的变量执行预处理语句

    <?php
    /* 通过绑定 PHP 变量执行一条预处理语句 */
    $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();
    ?>

示例 #5 使用数组执行一条含有 IN 子句的预处理语句

    <?php
    /*  使用一个数组的值执行一条含有 IN 子句的预处理语句 */
    $params = array(1, 21, 63, 171);
    /*  创建一个填充了和params相同数量占位符的字符串 */
    $place_holders = '?' . str_repeat(', ?', count($params) - 1);

    /*
        对于 $params 数组中的每个值，要预处理的语句包含足够的未命名占位符 。
        语句被执行时， $params 数组中的值被绑定到预处理语句中的占位符。
        这和使用 PDOStatement::bindParam() 不一样，因为它需要一个引用变量。
        PDOStatement::execute() 仅作为通过值绑定的替代。
    */
    $sth = $dbh->prepare("SELECT id, name FROM contacts WHERE id IN ($place_holders)");
    $sth->execute($params);
    ?>

### 注释

> 注意:

> 有些驱动在执行下一条语句前需要 关闭游标 。

### 参见

- PDO::prepare() - 预处理要执行的语句，并返回语句对象
- PDOStatement::bindParam() - 绑定一个参数到指定的变量名
- PDOStatement::fetch() - 从结果集中获取下一行
- PDOStatement::fetchAll() - 从结果集中获取剩余的行
- PDOStatement::fetchColumn() - 从结果集中的下一行返回单独的一列

# PDOStatement::fetch

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::fetch — 从结果集中获取下一行

### 说明

public function PDOStatement::fetch(int `$mode` = `PDO::FETCH_DEFAULT`, int `$cursorOrientation` = `PDO::FETCH_ORI_NEXT`, int `$cursorOffset` = 0): mixed

从一个 PDOStatement 对象相关的结果集中获取下一行。`mode` 参数决定 POD 如何返回行。

### 参数

`mode`

  控制下一行如何返回给调用者。此值必须是 `PDO::FETCH_*` 系列常量中的一个，缺省为 `PDO::ATTR_DEFAULT_FETCH_MODE` 的值 （默认为 `PDO::FETCH_BOTH` ）。

  - `PDO::FETCH_ASSOC`：返回一个索引为结果集列名的数组

  - `PDO::FETCH_BOTH`（默认）：返回一个索引为结果集列名和以0开始的列号的数组

  - `PDO::FETCH_BOUND`：返回 `true` ，并分配结果集中的列值给 PDOStatement::bindColumn() 方法绑定的 PHP 变量。

  - `PDO::FETCH_CLASS`：返回请求类的新实例，通过将结果集的列映射到类的属性以实现对象初始化。此过程发生于构造方法调用之前，允许填充属性，无论其可见性如何，也不管是否被标记为 `readonly`。若类中不存在对应属性且存在魔术方法 __set()，则调用该方法；否则创建动态 public 属性。但如果同时指定了 `PDO::FETCH_PROPS_LATE` flag，则将在填充属性前调用构造函数。若 `mode` 包含 `PDO::FETCH_CLASSTYPE`（例如 `PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE` ），类名由第一列的值确定。

  - `PDO::FETCH_INTO`：更新一个被请求类已存在的实例，映射结果集中的列到类中命名的属性

  - `PDO::FETCH_LAZY`：`PDO::FETCH_BOTH` 和 `PDO::FETCH_OBJ` 组合使用，返回 PDORow 对象，该对象在访问时创建对象属性名。

  - `PDO::FETCH_NAMED`：返回与 `PDO::FETCH_ASSOC` 具有相同形式的数组，除了如果有多个同名列，则该键引用的值将是具有该列名的行中所有值的数组

  - `PDO::FETCH_NUM`：返回一个索引为以0开始的结果集列号的数组

  - `PDO::FETCH_OBJ`：返回一个属性名对应结果集列名的匿名对象

  - `PDO::FETCH_PROPS_LATE`：当与 `PDO::FETCH_CLASS` 一起使用时，类的构造方法在从相应的列值分配属性之前被调用。

`cursorOrientation`

  对于 一个 PDOStatement 对象表示的可滚动游标，该值决定了哪一行将被返回给调用者。此值必须是 `PDO::FETCH_ORI_*` 系列常量中的一个，默认为 `PDO::FETCH_ORI_NEXT`。要想让 PDOStatement 对象使用可滚动游标，必须在用 PDO::prepare() 预处理SQL语句时，设置 `PDO::ATTR_CURSOR` 属性为 `PDO::CURSOR_SCROLL`。

`cursorOffset`

  对于一个 `cursorOrientation` 参数设置为 `PDO::FETCH_ORI_ABS` 的 PDOStatement 对象代表的可滚动游标，此值指定结果集中想要获取行的绝对行号。

  对于一个 `cursorOrientation` 参数设置为 `PDO::FETCH_ORI_REL` 的 PDOStatement 对象代表的可滚动游标，此值指定想要获取行相对于调用 PDOStatement::fetch() 前游标的位置

### 返回值

此方法成功时返回的值依赖于获取类型。在所有情况下，失败或没有更多记录时都返回 `false`。

### 错误／异常

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_WARNING`，则发出级别为 `E_WARNING` 的错误。

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_EXCEPTION`，则抛出 PDOException。

### 示例

示例 #1 使用不同的提取方式获取行

    <?php
    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* 运用 PDOStatement::fetch 风格 */
    print "PDO::FETCH_ASSOC: ";
    print "Return next row as an array indexed by column name\n";
    $result = $sth->fetch(PDO::FETCH_ASSOC);
    print_r($result);
    print "\n";

    print "PDO::FETCH_BOTH: ";
    print "Return next row as an array indexed by both column name and number\n";
    $result = $sth->fetch(PDO::FETCH_BOTH);
    print_r($result);
    print "\n";

    print "PDO::FETCH_LAZY: ";
    print "Return next row as a PDORow object with column names as properties\n";
    $result = $sth->fetch(PDO::FETCH_LAZY);
    print_r($result);
    print "\n";

    print "PDO::FETCH_OBJ: ";
    print "Return next row as an anonymous object with column names as properties\n";
    $result = $sth->fetch(PDO::FETCH_OBJ);
    print $result->name;
    print "\n";
    ?>

以上示例会输出：

    PDO::FETCH_ASSOC: Return next row as an array indexed by column name
    Array
    (
        [name] => apple
        [colour] => red
    )

    PDO::FETCH_BOTH: Return next row as an array indexed by both column name and number
    Array
    (
        [name] => banana
        [0] => banana
        [colour] => yellow
        [1] => yellow
    )

    PDO::FETCH_LAZY: Return next row as a PDORow object with column names as properties
    PDORow Object
    (
        [name] => orange
        [colour] => orange
    )

    PDO::FETCH_OBJ: Return next row as an anonymous object with column names as properties
    kiwi

示例 #2 使用一个可滚动游标获取行

    <?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 "Reading forwards:\n";
    readDataForwards($conn);

    print "Reading backwards:\n";
    readDataBackwards($conn);
    ?>

以上示例会输出：

    Reading forwards:
    21    10    5
    16    0     5
    19    20    10

    Reading backwards:
    19    20    10
    16    0     5
    21    10    5

示例 #3 构造顺序

当通过 `PDO::FETCH_CLASS` 获取对象时，首先分配对象属性，然后调用类的构造方法。然而，当指定了 `PDO::FETCH_PROPS_LATE` 时，则此顺序相反，即首先调用构造方法，然后分配属性。

    <?php
    class Person
    {
        private $name;

        public function __construct()
        {
            $this->tell();
        }

        public function tell()
        {
            if (isset($this->name)) {
                echo "I am {$this->name}.\n";
            } else {
                echo "I don't have a name yet.\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();
    ?>

以上示例的输出类似于：

    I am Alice.
    I am Alice.
    I don't have a name yet.
    I am Bob.

### 参见

- PDO::prepare() - 预处理要执行的语句，并返回语句对象
- PDOStatement::execute() - 执行预处理语句
- PDOStatement::fetchAll() - 从结果集中获取剩余的行
- PDOStatement::fetchColumn() - 从结果集中的下一行返回单独的一列
- PDOStatement::fetchObject() - 获取下一行并作为一个对象返回
- PDOStatement::setFetchMode() - 为语句设置默认的获取模式

# PDOStatement::fetchAll

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::fetchAll — 从结果集中获取剩余的行

### 说明

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

### 参数

`mode`

  控制返回数组的内容如同 PDOStatement::fetch() 文档中记载的一样。默认为 `PDO::ATTR_DEFAULT_FETCH_MODE` 的值（ 其缺省值为 `PDO::FETCH_BOTH` ）

  想要返回一个包含结果集中单独一列所有值的数组，需要指定 `PDO::FETCH_COLUMN` 。通过指定 `column` 参数获取想要的列。

  要根据某一列的值（而不是连续的数字）来索引结果数组，在 SQL 的列（column）列表中将该列名放在首位，并使用 `PDO::FETCH_UNIQUE`。这一列必须仅包含唯一值，否则部分数据将会丢失。

  要将结果以三维数组的形式对指定列的值进行分组，在 SQL 的列（column）列表中将该列名放在首位，并使用 `PDO::FETCH_GROUP`。

  要将结果以二维数组的形式进行分组，使用 `PDO::FETCH_GROUP` 与 `PDO::FETCH_COLUMN` 的按位或（OR）操作。结果将会按照第一列进行分组，数组元素的值将是来自第二列的相应条目的列表数组。

以下是依赖获取模式的动态参数。它们不能与命名参数一起使用。

`column`

  与 `PDO::FETCH_COLUMN` 一起使用。返回指定以 0 开始索引的列。

`class`

  与 `PDO::FETCH_CLASS`一起使用。返回指定类的实例，映射每行的列到类中对应的属性名。

`constructorArgs`

  当 `mode` 参数为 `PDO::FETCH_CLASS` 时自定义类构造方法的参数。

`callback`

  与 `PDO::FETCH_FUNC`一起使用。将每行的列作为参数传递给指定的函数，并返回调用函数后的结果。

### 返回值

PDOStatement::fetchAll() 返回一个包含结果集中所有剩余行的数组。此数组的每一行要么是一个列值的数组，要么是属性对应每个列名的一个对象。如果获取到的结果为 0，则返回空数组。

使用此方法获取大结果集将导致系统负担加重且可能占用大量网络资源。与其取回所有数据后用PHP来操作，倒不如考虑使用数据库服务来处理结果集。例如，在取回数据并通过PHP处理前，在 SQL 中使用 WHERE 和 ORDER BY 子句来限定结果。

### 错误／异常

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_WARNING`，则发出级别为 `E_WARNING` 的错误。

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_EXCEPTION`，则抛出 PDOException。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在此方法始终返回 array，之前可能在失败时返回 `false`。

### 示例

示例 #1 获取结果集中所有剩余的行

    <?php
    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* 获取结果集中所有剩余的行 */
    print "Fetch all of the remaining rows in the result set:\n";
    $result = $sth->fetchAll();
    print_r($result);
    ?>

以上示例的输出类似于：

    Fetch all of the remaining rows in the result set:
    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
            )

    )

示例 #2 获取结果集中单独一列的所有值

下面示例演示了如何从一个结果集中返回单独一列所有的值，尽管 SQL 语句自身可能返回每行多列。

    <?php
    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* 获取第一列所有值 */
    $result = $sth->fetchAll(PDO::FETCH_COLUMN, 0);
    var_dump($result);
    ?>

以上示例的输出类似于：

    Array(3)
    (
        [0] =>
        string(5) => apple
        [1] =>
        string(4) => pear
        [2] =>
        string(10) => watermelon
    )

示例 #3 根据单独的一列把所有值分组

下面示例演示了如何返回一个根据结果集中指定列的值分组的关联数组。该数组包含三个键：返回的 `apple` 和 `pear` 数组包含了两种不同的颜色，而返回的 `watermelon` 数组仅包含一种颜色。

    <?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();

    /* 根据第一列分组  */
    var_dump($sth->fetchAll(PDO::FETCH_COLUMN|PDO::FETCH_GROUP));
    ?>

以上示例的输出类似于：

    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"
      }
    }

示例 #4 每行结果实例化一个类

下面列子演示了 `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);
    ?>

以上示例的输出类似于：

    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"
      }
    }

示例 #5 每行调用一次函数

下面列子演示了 `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);
    ?>

以上示例的输出类似于：

    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"
    }

### 参见

- PDO::query() - 预处理并执行没有占位符的 SQL 语句
- PDOStatement::fetch() - 从结果集中获取下一行
- PDOStatement::fetchColumn() - 从结果集中的下一行返回单独的一列
- PDO::prepare() - 预处理要执行的语句，并返回语句对象
- PDOStatement::setFetchMode() - 为语句设置默认的获取模式

# PDOStatement::fetchColumn

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::fetchColumn — 从结果集中的下一行返回单独的一列

### 说明

public function PDOStatement::fetchColumn(int `$column` = 0): mixed

从结果集中的下一行返回单独的一列，如果没有了，则返回 `false` 。

> 注意:

> PDOStatement::fetchColumn() 不应该用于检索 boolean 列，因为无法区分 `false` 值和没有更多行可检索。请改用 PDOStatement::fetch()。

### 参数

`column`

  你想从行里取回的列的索引数字（以0开始的索引）。如果没有提供值，则 PDOStatement::fetchColumn() 获取第一列。

### 返回值

PDOStatement::fetchColumn() 从结果集中的下一行返回单独的一列，如果没有更多行，则返回 `false`。

警告

如果使用 PDOStatement::fetchColumn() 取回数据，则没有办法返回同一行的另外一列。

### 错误／异常

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_WARNING`，则发出级别为 `E_WARNING` 的错误。

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_EXCEPTION`，则抛出 PDOException。

### 示例

示例 #1 返回下一行的第一列

    <?php
    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    print "Fetch the first column from the first row in the result set:\n";
    $result = $sth->fetchColumn();
    print "name = $result\n";

    print "Fetch the second column from the second row in the result set:\n";
    $result = $sth->fetchColumn(1);
    print "colour = $result\n";
    ?>

以上示例会输出：

    Fetch the first column from the first row in the result set:
    name = lemon
    Fetch the second column from the second row in the result set:
    colour = red

### 参见

- PDO::query() - 预处理并执行没有占位符的 SQL 语句
- PDOStatement::fetch() - 从结果集中获取下一行
- PDOStatement::fetchAll() - 从结果集中获取剩余的行
- PDO::prepare() - 预处理要执行的语句，并返回语句对象
- PDOStatement::setFetchMode() - 为语句设置默认的获取模式

# PDOStatement::fetchObject

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.4)

PDOStatement::fetchObject — 获取下一行并作为一个对象返回

### 说明

public function PDOStatement::fetchObject(?string `$class` = "stdClass", array `$constructorArgs` = []): object|false

获取下一行并作为一个对象返回。此函数（方法）是使用 `PDO::FETCH_CLASS` 或 `PDO::FETCH_OBJ` 风格的 PDOStatement::fetch() 的一种替代。

当获取对象时，它的属性从各自的列值中分配，然后调用它的构造函数。

### 参数

`class`

  创建类的名称。

`constructorArgs`

  此数组的元素被传递给构造方法。

### 返回值

返回一个属性名对应于列名的所要求类的实例， 或者在失败时返回 `false`.

### 错误／异常

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_WARNING`，则发出级别为 `E_WARNING` 的错误。

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_EXCEPTION`，则抛出 PDOException。

### 参见

- PDOStatement::fetch() - 从结果集中获取下一行

# PDOStatement::getAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::getAttribute — 检索语句属性

### 说明

public function PDOStatement::getAttribute(int `$name`): mixed

得到语句的属性。当前，不存在通用的属性，只有驱动特定的属性：

- `PDO::ATTR_CURSOR_NAME` （Firebird 和 ODBC 特性）： 获取 `UPDATE ... WHERE CURRENT OF` 的游标名称。

请注意，驱动特定的属性不得与其他驱动程序一起使用。

### 参数

`name`

  要查询的属性。

### 返回值

返回属性值。

### 参见

- PDO::getAttribute() - 取回一个数据库连接的属性
- PDO::setAttribute() - 设置属性
- PDOStatement::setAttribute() - 设置一个语句属性

# PDOStatement::getColumnMeta

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::getColumnMeta — 返回结果集中一列的元数据

### 说明

public function PDOStatement::getColumnMeta(int `$column`): array|false

检索一个在结果集中以0开始索引的列的元数据作为一个关联数组。

警告

一些驱动程序可能没有实现 PDOStatement::getColumnMeta()，因为它是可选的。但是，手册中记录的所有 PDO 驱动程序都实现了此功能。

### 参数

`column`

  结果集中以0开始索引的列。

### 返回值

返回一个关联数组，它包含了下列表示一个单独列的元数据的值：

列的元数据
名称 | 值
--- | ---
`native_type` | 用于表示列值的 PHP 原生类型。
`driver:decl_type` | 在数据库中用于表示列值的 SQL 类型。如果结果集中的列是一个函数的结果，则该值不能被 PDOStatement::getColumnMeta() 返回。
`flags` | 任何设置于此列的标记。
`name` | 通过数据库返回的列名。
`table` | 通过数据库返回的该列的表名
`len` | 该列的长度。除浮点小数外通常为 `-1`
`precision` | 该列的数值精度。除浮点小数外通常为 `0`。
`pdo_type` | 以 `PDO::PARAM_*` 常量为代表的列类型。

如果结果集不存在，或者是请求的列在结果集中不存在，则返回 `false`。

### 示例

示例 #1 检索列的元数据

下面示例展示了在 PDO_SQLITE 中，检索一个通过函数（COUNT）生成单独列的元数据的结果。

    <?php
    $select = $DB->query('SELECT COUNT(*) FROM fruit');
    $meta = $select->getColumnMeta(0);
    var_dump($meta);
    ?>

以上示例会输出：

    array(6) {
      ["native_type"]=>
      string(7) "integer"
      ["flags"]=>
      array(0) {
      }
      ["name"]=>
      string(8) "COUNT(*)"
      ["len"]=>
      int(-1)
      ["precision"]=>
      int(0)
      ["pdo_type"]=>
      int(2)
    }

### 参见

- PDOStatement::columnCount() - 返回结果集中的列数
- PDOStatement::rowCount() - 返回受上一个 SQL 语句影响的行数

# PDOStatement::getIterator

(PHP 8)

PDOStatement::getIterator — Gets result set iterator

### 说明

public function PDOStatement::getIterator(): Iterator

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# PDOStatement::nextRowset

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::nextRowset — 在一个多行集合语句句柄中推进到下一个行集合

### 说明

public function PDOStatement::nextRowset(): bool

一些数据库服务支持返回一个以上行集合（也被称为结果集）的存储过程。PDOStatement::nextRowset() 使你能够结合一个 PDOStatement 对象访问第二个以及后续的行集合。上述的每个行集合可以有不同的列集合。

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 获取由一个存储过程返回的多个行集合

下面示例展示了怎样调用一个存储过程，返回三个行集合的 `MULTIPLE_ROWSETS`。用 do-while 循环来循环调用 PDOStatement::nextRowset() 方法，直到返回 `false` 并且不再有行集合可用时结束循环。

    <?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 "Result set $i:\n";
        foreach ($rowset as $row) {
            foreach ($row as $col) {
                print $col . "\t";
            }
            print "\n";
        }
        print "\n";
    }
    ?>

以上示例会输出：

    Result set 1:
    apple    red
    banana   yellow

    Result set 2:
    orange   orange    150
    banana   yellow    175

    Result set 3:
    lime     green
    apple    red
    banana   yellow

### 参见

- PDOStatement::columnCount() - 返回结果集中的列数
- PDOStatement::execute() - 执行预处理语句
- PDOStatement::getColumnMeta() - 返回结果集中一列的元数据
- PDO::query() - 预处理并执行没有占位符的 SQL 语句

# PDOStatement::rowCount

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::rowCount — 返回受上一个 SQL 语句影响的行数

### 说明

public function PDOStatement::rowCount(): int

PDOStatement::rowCount() 返回上一个由对应的 `PDOStatement` 对象执行 DELETE、INSERT 或 UPDATE 语句受影响的行数。

对于生成结果集的语句，例如 `SELECT`，行为是未定义的，并且对于每个驱动程序可能不同。某些数据库可能会返回该语句生成的行数（例如缓冲模式下的 MySQL），但不能保证所有数据库都具有这种行为，并且对于可移植的应用不应依赖于此方式。

> 注意:

> 对 PostgreSQL 驱动程序，仅当将 `PDO::ATTR_CURSOR` 语句属性设置为 `PDO::CURSOR_SCROLL` 时此方法返回“0”（零）。

### 参数

此函数没有参数。

### 返回值

返回行数。

### 错误／异常

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_WARNING`，则发出级别为 `E_WARNING` 的错误。

如果属性 `PDO::ATTR_ERRMODE` 设置为 `PDO::ERRMODE_EXCEPTION`，则抛出 PDOException。

### 示例

示例 #1 返回删除的行数

PDOStatement::rowCount() 返回受 DELETE、INSERT 或 UPDATE 语句影响的行数。

    <?php
    /*  从 FRUIT 数据表中删除所有行 */
    $del = $dbh->prepare('DELETE FROM fruit');
    $del->execute();

    /*  返回被删除的行数 */
    print "Return number of rows that were deleted:\n";
    $count = $del->rowCount();
    print "Deleted $count rows.\n";
    ?>

以上示例的输出类似于：

    Return number of rows that were deleted:
    Deleted 9 rows.

示例 #2 计算由一个 SELECT 语句返回的行数

对于大多数数据库，PDOStatement::rowCount() 不能返回受一条 SELECT 语句影响的行数。替代的方法是，使用 PDO::query() 来发出一条和原打算中的 SELECT 语句有相同条件表达式的 SELECT COUNT(*) 语句，然后用 PDOStatement::fetchColumn() 来取得匹配的行数。

    <?php
    $sql = "SELECT COUNT(*) FROM fruit WHERE calories > 100";
    $res = $conn->query($sql);
    $count = $res->fetchColumn();

    print "There are " .  $count . " matching records.";

以上示例的输出类似于：

    There are 2 matching records.

### 参见

- PDOStatement::columnCount() - 返回结果集中的列数
- PDOStatement::fetchColumn() - 从结果集中的下一行返回单独的一列
- PDO::query() - 预处理并执行没有占位符的 SQL 语句

# PDOStatement::setAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::setAttribute — 设置一个语句属性

### 说明

public function PDOStatement::setAttribute(int `$attribute`, mixed `$value`): bool

给语句设置一个属性。当前，没有通用的属性可以设置，只有驱动特定的属性：

- `PDO::ATTR_CURSOR_NAME` （Firebird 和 ODBC 特性）： 为 `UPDATE ... WHERE CURRENT OF` 设置游标名称。

请注意，驱动特定的属性不得与其他驱动程序一起使用。

### 参数

`attribute`

  要修改的属性。

`value`

  设置 `attribute` 的值，属性的不同导致需要的类型也会不同。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- PDO::getAttribute() - 取回一个数据库连接的属性
- PDO::setAttribute() - 设置属性
- PDOStatement::getAttribute() - 检索语句属性

# PDOStatement::setFetchMode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::setFetchMode — 为语句设置默认的获取模式

### 说明

public function PDOStatement::setFetchMode(int `$mode`): bool
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_COLUMN, int `$colno`): bool
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs` = `null`): bool
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_INTO, object `$object`): bool

### 参数

`mode`

  获取模式必须是 `PDO::FETCH_*` 常量中的一个。

`colno`

  列号。

`class`

  类名。

`constructorArgs`

  构造方法参数。

`object`

  对象。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 设置获取模式

以下示例演示了 PDOStatement::setFetchMode() 如何更改 PDOStatement 对象的默认获取模式。

    <?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";
    }

以上示例的输出类似于：

    apple   red     150
    banana  yellow  250
    orange  orange  300
    kiwi    brown   75
    lemon   yellow  25
    pear    green   150

## 目录

- PDOStatement::bindColumn — 绑定一列到一个 PHP 变量
- PDOStatement::bindParam — 绑定一个参数到指定的变量名
- PDOStatement::bindValue — 把一个值绑定到一个参数
- PDOStatement::closeCursor — 关闭游标，使语句能再次被执行
- PDOStatement::columnCount — 返回结果集中的列数
- PDOStatement::debugDumpParams — 打印一条 SQL 预处理命令
- PDOStatement::errorCode — 获取跟上一次语句句柄操作相关的 SQLSTATE
- PDOStatement::errorInfo — 获取跟上一次语句句柄操作相关的扩展错误信息
- PDOStatement::execute — 执行预处理语句
- PDOStatement::fetch — 从结果集中获取下一行
- PDOStatement::fetchAll — 从结果集中获取剩余的行
- PDOStatement::fetchColumn — 从结果集中的下一行返回单独的一列
- PDOStatement::fetchObject — 获取下一行并作为一个对象返回
- PDOStatement::getAttribute — 检索语句属性
- PDOStatement::getColumnMeta — 返回结果集中一列的元数据
- PDOStatement::getIterator — Gets result set iterator
- PDOStatement::nextRowset — 在一个多行集合语句句柄中推进到下一个行集合
- PDOStatement::rowCount — 返回受上一个 SQL 语句影响的行数
- PDOStatement::setAttribute — 设置一个语句属性
- PDOStatement::setFetchMode — 为语句设置默认的获取模式

# The PDORow class

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

## 简介

Represents a row from a result set returned by PDOStatement::fetch() called with `PDO::FETCH_LAZY` fetch mode.

Objects of this class cannot be instantiated and are not serializable.

The PDORow object allows access to the returned data as if both `PDO::FETCH_OBJ` and `PDO::FETCH_BOTH` mode was used. This means that the returned data can be accessed as object properties, and as an array both indexed by the column name and a column offset number.

警告

Accessing an undefined property returns `null` without emitting a warning.

## 类摘要

final class PDORow {
/* 属性 */
public string $queryString;
}

## 属性

queryString

  Query string used by the PDOStatement that returned the PDORow object.

## 错误／异常

Throws an Error when trying to write to or unset() any property.

# PDOException 异常类

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## 简介

代表一个由 PDO 产生的错误。在自己的代码不应抛出一个 PDOException 异常。关于 PHP 异常的更多信息请参见 异常 。

## 类摘要

class PDOException extends RuntimeException {
/* 属性 */
protected int|string $code;
public ?array $errorInfo = null;
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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
}

## 属性

errorInfo

  相当于 PDO::errorInfo() 或 PDOStatement::errorInfo()

code

  `SQLSTATE` 错误码。用 Exception::getCode() 来访问。

# PDO 驱动

## 目录

- CUBRID PDO Driver
- MS SQL Server PDO Driver
- Pdo\Dblib
- Firebird PDO Driver
- Pdo\Firebird
- IBM PDO Driver
- Informix PDO Driver
- MySQL PDO Driver
- Pdo\Mysql
- MS SQL Server PDO Driver
- Oracle PDO Driver
- ODBC and DB2 PDO Driver
- Pdo\Odbc
- PostgreSQL PDO Driver
- Pdo\Pgsql
- SQLite PDO Driver
- Pdo\Sqlite

下列驱动目前实现了 PDO 接口：

驱动名称 | 支持的数据库
--- | ---
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 和 win32 ODBC）
PDO_PGSQL | PostgreSQL
PDO_SQLITE | SQLite 3 及 SQLite 2
PDO_SQLSRV | Microsoft SQL Server / SQL Azure

# CUBRID PDO Driver (PDO_CUBRID)

## 简介

PDO_CUBRID is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to CUBRID databases.

> 注意: Current version of PDO_CUBRID doesn't support persistent connection now.

## 安装

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 PECL 扩展安装 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.

PECL 扩展的 DLL 当前不可用。参见 在 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().

> 注意: 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:

示例 #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();
    ?>

示例 #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:

示例 #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);
    ?>

示例 #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

## 预定义常量

下列常量由此驱动定义，且仅在扩展编译入 PHP 或在运行时动态载入时可用。另外，使用此驱动时，仅会使用这些驱动特定的常量。使用其他驱动的驱动特定的常量可能会导致不可预见的情况。如果代码可运行于多个驱动，PDO::getAttribute() 可被用于获取 `PDO_ATTR_DRIVER_NAME` 属性以检查驱动。

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

### 说明

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.

### 注释

> 注意: When you establish the connection to CUBRID, you should give username and password except DSN.

### 示例

示例 #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

### 说明

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 |

### 参数

`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.

### 返回值

Array containing the schema information, when process is successful;

FALSE, when process is unsuccessful

### 示例

示例 #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);
    ?>

以上示例会输出：

    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
            )

    )

## 目录

- PDO_CUBRID DSN — Connecting to CUBRID databases
- PDO::cubrid_schema — Get the requested schema information

# Microsoft SQL Server and Sybase PDO Driver (PDO_DBLIB)

## 简介

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

### 说明

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.

### 示例

示例 #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

## 目录

- PDO_DBLIB DSN — Connecting to Microsoft SQL Server and Sybase databases

# The Pdo\Dblib class

(PHP 8 >= 8.4.0)

## 简介

A PDO subclass representing a connection using the DBLib PDO driver.

## 类摘要

namespace Pdo;
class Dblib extends PDO {
/* 继承的常量 */
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;
/* 常量 */
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;
/* 继承的方法 */
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
}

## 预定义常量

`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)

## 简介

PDO_FIREBIRD is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to Firebird database.

## 安装

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

## 预定义常量

下列常量由此驱动定义，且仅在扩展编译入 PHP 或在运行时动态载入时可用。另外，使用此驱动时，仅会使用这些驱动特定的常量。使用其他驱动的驱动特定的常量可能会导致不可预见的情况。如果代码可运行于多个驱动，PDO::getAttribute() 可被用于获取 `PDO_ATTR_DRIVER_NAME` 属性以检查驱动。

`PDO::FB_ATTR_DATE_FORMAT` (int)

  别名 `Pdo\Firebird::ATTR_DATE_FORMAT`.

`PDO::FB_ATTR_TIME_FORMAT` (int)

  别名 `Pdo\Firebird::ATTR_TIME_FORMAT`.

`PDO::FB_ATTR_TIMESTAMP_FORMAT` (int)

  别名 `Pdo\Firebird::ATTR_TIMESTAMP_FORMAT`.

# PDO_FIREBIRD DSN

(PECL PDO_FIREBIRD >= 0.1.0)

PDO_FIREBIRD DSN — Connecting to Firebird databases

### 说明

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.

### 示例

示例 #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

示例 #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

示例 #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

示例 #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

## 目录

- PDO_FIREBIRD DSN — Connecting to Firebird databases

# The Pdo\Firebird class

(PHP 8 >= 8.4.0)

## 简介

A PDO subclass representing a connection using the Firebird PDO driver.

## 类摘要

namespace Pdo;
class Firebird extends PDO {
/* 继承的常量 */
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;
/* 常量 */
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;
/* 方法 */
public static function getApiVersion(): int
/* 继承的方法 */
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
}

## 预定义常量

`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

### 说明

public static function Pdo\Firebird::getApiVersion(): int

Returns the Firebird API version as defined by the C constant `FB_API_VER` in ibase.h.

### 参数

此函数没有参数。

### 返回值

Returns the FireBird API as an int.

## 目录

- Pdo\Firebird::getApiVersion — Get the API version

# IBM PDO Driver (PDO_IBM)

## 简介

PDO_IBM is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to IBM databases.

## 安装

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.

> 注意: 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 PECL 扩展安装 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.

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

PDO_IBM Configuration Options
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
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

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`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

### 说明

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.

### 示例

示例 #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

示例 #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");

## 目录

- PDO_IBM DSN — Connecting to IBM databases

# Informix PDO Driver (PDO_INFORMIX)

## 简介

PDO_INFORMIX is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to Informix databases.

## 安装

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 PECL 扩展安装 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

### 说明

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.

### 示例

示例 #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

示例 #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");

## 目录

- PDO_INFORMIX DSN — Connecting to Informix databases

# MySQL PDO Driver (PDO_MYSQL)

## 简介

PDO_MYSQL is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to MySQL databases.

PDO_MYSQL uses emulated prepares by default.

MySQL 8

When running a PHP version before 7.1.16, or PHP 7.2 before 7.2.4, set MySQL 8 Server's default password plugin to mysql_native_password or else you will see errors similar to The server requested authentication method unknown to the client [caching_sha2_password] even when caching_sha2_password is not used.

This is because MySQL 8 defaults to caching_sha2_password, a plugin that is not recognized by the older PHP (mysqlnd) releases. Instead, change it by setting `default_authentication_plugin=mysql_native_password` in my.cnf. The caching_sha2_password plugin is fully supported as of PHP 7.4.4. For older releases, the mysql_xdevapi extension does support it.

警告

Beware: Some MySQL table types (storage engines) do not support transactions. When writing transactional database code using a table type that does not support transactions, MySQL will pretend that a transaction was initiated successfully. In addition, any DDL queries issued will implicitly commit any pending transactions.

> 注意:

> The MySQL driver does not properly support `PDO::PARAM_INPUT_OUTPUT` via PDOStatement::bindParam(); while such parameters can be used, they are not updated (i.e. the actual output is ignored).

## 安装

The common Unix distributions include binary versions of PHP that can be installed. Although these binary versions are typically built with support for the MySQL extensions, the extension libraries themselves may need to be installed using an additional package. Check the package manager that comes with your chosen distribution for availability.

For example, on Ubuntu the `php5-mysql` package installs the ext/mysql, ext/mysqli, and PDO_MYSQL PHP extensions. On CentOS, the `php-mysql` package also installs these three PHP extensions.

Alternatively, you can compile this extension yourself. Building PHP from source allows you to specify the MySQL extensions you want to use, as well as your choice of client library for each extension.

When compiling, use --with-pdo-mysql[=DIR] to install the PDO MySQL extension, where the optional `[=DIR]` is the MySQL base library. Mysqlnd is the default library. For details about choosing a library, see Choosing a MySQL library.

Optionally, the --with-mysql-sock[=DIR] sets to location to the MySQL unix socket pointer for all MySQL extensions, including PDO_MYSQL. If unspecified, the default locations are searched.

Optionally, the --with-zlib-dir[=DIR] is used to set the path to the libz install prefix.

    $ ./configure --with-pdo-mysql --with-mysql-sock=/var/mysql/mysql.sock

SSL support is enabled using the appropriate `Pdo\Mysql::ATTR_SSL_*`, which is equivalent to calling the » MySQL C API function mysql_ssl_set(). Also, SSL cannot be enabled with PDO::setAttribute() because the connection already exists. See also the MySQL documentation about » connecting to MySQL with SSL.

## 预定义常量

下列常量由此驱动定义，且仅在扩展编译入 PHP 或在运行时动态载入时可用。另外，使用此驱动时，仅会使用这些驱动特定的常量。使用其他驱动的驱动特定的常量可能会导致不可预见的情况。如果代码可运行于多个驱动，PDO::getAttribute() 可被用于获取 `PDO_ATTR_DRIVER_NAME` 属性以检查驱动。

`PDO::MYSQL_ATTR_USE_BUFFERED_QUERY` (int)
  别名 `Pdo\Mysql::ATTR_USE_BUFFERED_QUERY`
`PDO::MYSQL_ATTR_LOCAL_INFILE` (int)
  别名 `Pdo\Mysql::ATTR_LOCAL_INFILE`
`PDO::MYSQL_ATTR_LOCAL_INFILE_DIRECTORY` (int)
  别名 `Pdo\Mysql::ATTR_LOCAL_INFILE_DIRECTORY`. Available as of PHP 8.1.0.
`PDO::MYSQL_ATTR_INIT_COMMAND` (int)
  别名 `Pdo\Mysql::ATTR_INIT_COMMAND`
`PDO::MYSQL_ATTR_READ_DEFAULT_FILE` (int)
  别名 `Pdo\Mysql::ATTR_READ_DEFAULT_FILE`
`PDO::MYSQL_ATTR_READ_DEFAULT_GROUP` (int)
  别名 `Pdo\Mysql::ATTR_READ_DEFAULT_GROUP`
`PDO::MYSQL_ATTR_MAX_BUFFER_SIZE` (int)
  别名 `Pdo\Mysql::ATTR_MAX_BUFFER_SIZE`
`PDO::MYSQL_ATTR_DIRECT_QUERY` (bool)
  别名 `PDO::ATTR_EMULATE_PREPARES` As of PHP 8.4.0 this constant is typed as bool; previously, it was typed as int.
`PDO::MYSQL_ATTR_FOUND_ROWS` (int)
  别名 `Pdo\Mysql::ATTR_FOUND_ROWS`
`PDO::MYSQL_ATTR_IGNORE_SPACE` (int)
  别名 `Pdo\Mysql::ATTR_IGNORE_SPACE`
`PDO::MYSQL_ATTR_COMPRESS` (int)
  别名 `Pdo\Mysql::ATTR_COMPRESS`
`PDO::MYSQL_ATTR_SERVER_PUBLIC_KEY` (int)
  别名 `Pdo\Mysql::ATTR_SERVER_PUBLIC_KEY`
`PDO::MYSQL_ATTR_SSL_CA` (int)
  别名 `Pdo\Mysql::ATTR_SSL_CA`
`PDO::MYSQL_ATTR_SSL_CAPATH` (int)
  别名 `Pdo\Mysql::ATTR_SSL_CAPATH`
`PDO::MYSQL_ATTR_SSL_CERT` (int)
  别名 `Pdo\Mysql::ATTR_SSL_CERT`
`PDO::MYSQL_ATTR_SSL_CIPHER` (int)
  别名 `Pdo\Mysql::ATTR_SSL_CIPHER`
`PDO::MYSQL_ATTR_SSL_KEY` (int)
  别名 `Pdo\Mysql::ATTR_SSL_KEY`
`PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT` (int)
  别名 `Pdo\Mysql::ATTR_SSL_VERIFY_SERVER_CERT` Available as of PHP 7.0.18 and PHP 7.1.4.
`PDO::MYSQL_ATTR_MULTI_STATEMENTS` (int)
  别名 `Pdo\Mysql::ATTR_MULTI_STATEMENTS`

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

PDO_MYSQL Configuration Options
名字 | 默认 | 可修改范围
--- | --- | ---
pdo_mysql.default_socket | "/tmp/mysql.sock" | `INI_SYSTEM`
pdo_mysql.debug | NULL | `INI_SYSTEM`

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`pdo_mysql.default_socket` string

  Sets a Unix domain socket. This value can either be set at compile time if a domain socket is found at configure. This ini setting is Unix only.

`pdo_mysql.debug` bool

  Enables debugging for PDO_MYSQL. This setting is only available when PDO_MYSQL is compiled against mysqlnd and in PDO debug mode.

# PDO_MYSQL DSN

(PECL PDO_MYSQL >= 0.1.0)

PDO_MYSQL DSN — Connecting to MySQL databases

### 说明

The PDO_MYSQL Data Source Name (DSN) is composed of the following elements:

DSN prefix

  The DSN prefix is `mysql:`.

`host`

  The hostname on which the database server resides.

`port`

  The port number where the database server is listening.

`dbname`

  The name of the database.

`unix_socket`

  The MySQL Unix socket (shouldn't be used with `host` or `port`).

`charset`

  The character set. See the character set concepts documentation for more information.

### 示例

示例 #1 PDO_MYSQL DSN examples

The following example shows a PDO_MYSQL DSN for connecting to MySQL databases:

    mysql:host=localhost;dbname=testdb

More complete examples:

    mysql:host=localhost;port=3307;dbname=testdb
    mysql:unix_socket=/tmp/mysql.sock;dbname=testdb

### 注释

> 注意: Unix only:

> When the host name is set to `"localhost"`, then the connection to the server is made through a domain socket. If PDO_MYSQL is compiled against libmysqlclient then the location of the socket file is at libmysqlclient's compiled in location. If PDO_MYSQL is compiled against mysqlnd a default socket can be set through the pdo_mysql.default_socket setting.

## 目录

- PDO_MYSQL DSN — Connecting to MySQL databases

# The Pdo\Mysql class

(PHP 8 >= 8.4.0)

## 简介

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.

## 类摘要

class Pdo\Mysql extends PDO {
/* 继承的常量 */
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;
/* 常量 */
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;
/* 方法 */
public function getWarningCount(): int
/* 继承的方法 */
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
}

## 预定义常量

`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.

  示例 #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`.

  > 注意: 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.

  > 注意: 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.

  > 注意: 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.

  > 注意: 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`.

  > 注意: 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`
  别名 `PDO::ATTR_EMULATE_PREPARES`.
`Pdo\Mysql::ATTR_FOUND_ROWS`
  Return the number of found (matched) rows, not the number of changed rows.

  > 注意: 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.

  > 注意: 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.

  > 注意: 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`.

  > 注意: 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.

  > 注意: 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.

  > 注意: 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.

  > 注意: 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.

  > 注意: 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.

  > 注意: 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`

  > 注意: 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.

  > 注意: This option is available only with mysqlnd.

  > 注意: 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

### 说明

public function Pdo\Mysql::getWarningCount(): int

Returns the number of warnings from the last executed query.

> 注意: For retrieving warning messages the following SQL command can be used: `SHOW WARNINGS [limit row_count]`.

### 参数

此函数没有参数。

### 返回值

Returns an int representing the number of warnings generated by the last query.

### 示例

示例 #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]);
    }

    ?>

以上示例会输出：

    Warning (1365): Division by 0

## 目录

- Pdo\Mysql::getWarningCount — Returns the number of warnings from the last executed query

# Microsoft SQL Server PDO Driver (PDO_SQLSRV)

## 简介

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.

## 安装

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.

## 预定义常量

下列常量由此驱动定义，且仅在扩展编译入 PHP 或在运行时动态载入时可用。另外，使用此驱动时，仅会使用这些驱动特定的常量。使用其他驱动的驱动特定的常量可能会导致不可预见的情况。如果代码可运行于多个驱动，PDO::getAttribute() 可被用于获取 `PDO_ATTR_DRIVER_NAME` 属性以检查驱动。

`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

### 说明

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.

### 示例

示例 #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");

## 目录

- PDO_SQLSRV DSN — Connecting to MS SQL Server and SQL Azure databases

# Oracle PDO Driver (PDO_OCI)

## 安装

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

此扩展已被移至 » PECL 资源库；不再与 PHP 捆绑，从 PHP 8.4.0

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » 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

## 预定义常量

下列常量由此驱动定义，且仅在扩展编译入 PHP 或在运行时动态载入时可用。另外，使用此驱动时，仅会使用这些驱动特定的常量。使用其他驱动的驱动特定的常量可能会导致不可预见的情况。如果代码可运行于多个驱动，PDO::getAttribute() 可被用于获取 `PDO_ATTR_DRIVER_NAME` 属性以检查驱动。

`PDO::OCI_ATTR_ACTION` (int)

  Provides a way to specify the action on the database session.

  自以下版本起 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.

  自以下版本起 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.

  自以下版本起 PHP 7.2.16 and 7.3.3

`PDO::OCI_ATTR_MODULE` (int)

  Provides a way to specify the module on the database session.

  自以下版本起 PHP 7.2.16 and 7.3.3

# PDO_OCI DSN

(PECL PDO_OCI >= 0.1.0)

PDO_OCI DSN — Connecting to Oracle databases

### 说明

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.

### 示例

示例 #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

## 目录

- PDO_OCI DSN — Connecting to Oracle databases

# ODBC and DB2 PDO Driver (PDO_ODBC)

## 简介

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.

## 安装

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

## 预定义常量

下列常量由此驱动定义，且仅在扩展编译入 PHP 或在运行时动态载入时可用。另外，使用此驱动时，仅会使用这些驱动特定的常量。使用其他驱动的驱动特定的常量可能会导致不可预见的情况。如果代码可运行于多个驱动，PDO::getAttribute() 可被用于获取 `PDO_ATTR_DRIVER_NAME` 属性以检查驱动。

`PDO_ODBC_TYPE` (string)

`PDO::ODBC_ATTR_USE_CURSOR_LIBRARY` (int)
  别名 `Pdo\Odbc::ATTR_USE_CURSOR_LIBRARY`.
`PDO::ODBC_SQL_USE_IF_NEEDED` (int)
  别名 `Pdo\Odbc::SQL_USE_IF_NEEDED`.
`PDO::ODBC_SQL_USE_DRIVER` (int)
  别名 `Pdo\Odbc::SQL_USE_DRIVER`.
`PDO::ODBC_SQL_USE_ODBC` (int)
  别名 `Pdo\Odbc::SQL_USE_ODBC`.
`PDO::ODBC_ATTR_ASSUME_UTF8` (bool)
  别名 `Pdo\Odbc::ATTR_ASSUME_UTF8`.

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

PDO_ODBC Configuration Options
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
pdo_odbc.connection_pooling | "strict" | `INI_ALL` |
pdo_odbc.db2_instance_name | NULL | `INI_SYSTEM` | 本过时特性将肯定会在未来被移除。

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`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.

  警告

  `relaxed` matching should not be used on a shared server, for security reasons.

  小技巧

  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

### 说明

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.

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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

示例 #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;

示例 #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

## 目录

- PDO_ODBC DSN — Connecting to ODBC or DB2 databases

# The Pdo\Odbc class

(PHP 8 >= 8.4.0)

## 简介

A PDO subclass representing a connection using the ODBC PDO driver.

## 类摘要

namespace Pdo;
class Odbc extends PDO {
/* 继承的常量 */
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;
/* 常量 */
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;
/* 继承的方法 */
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
}

## 预定义常量

`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)

## 简介

PDO_PGSQL is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to PostgreSQL databases.

## 资源类型

This extension defines a stream resource returned by Pdo\Pgsql::lobOpen().

## 安装

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

## 预定义常量

下列常量由此驱动定义，且仅在扩展编译入 PHP 或在运行时动态载入时可用。另外，使用此驱动时，仅会使用这些驱动特定的常量。使用其他驱动的驱动特定的常量可能会导致不可预见的情况。如果代码可运行于多个驱动，PDO::getAttribute() 可被用于获取 `PDO_ATTR_DRIVER_NAME` 属性以检查驱动。

`PDO::PGSQL_ATTR_DISABLE_PREPARES` (int)
  别名 `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

> 注意: `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

### 说明

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.

> 注意: 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.

### 示例

示例 #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 — 别名 Pdo\Pgsql::copyFromArray()

警告

此函数自 PHP 8.5.0 起弃用。强烈建议不要应用此函数。

### 说明

#[\Deprecated]
public function PDO::pgsqlCopyFromArray(
string `$tableName`,
array|Traversable `$rows`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

此方法是该方法的别名： Pdo\Pgsql::copyFromArray().

### 更新日志

版本 | 说明
--- | ---
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 — 别名 Pdo\Pgsql::copyFromFile()

警告

此函数自 PHP 8.5.0 起弃用。强烈建议不要应用此函数。

### 说明

#[\Deprecated]
public function PDO::pgsqlCopyFromFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

此方法是该方法的别名： Pdo\Pgsql::copyFromFile().

# PDO::pgsqlCopyToArray

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyToArray — 别名 Pdo\Pgsql::copyToArray()

警告

此函数自 PHP 8.5.0 起弃用。强烈建议不要应用此函数。

### 说明

#[\Deprecated]
public function PDO::pgsqlCopyToArray(
string `$tableName`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): array|false

此方法是该方法的别名： Pdo\Pgsql::copyToArray().

# PDO::pgsqlCopyToFile

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyToFile — 别名 Pdo\Pgsql::copyToFile()

警告

此函数自 PHP 8.5.0 起弃用。强烈建议不要应用此函数。

### 说明

#[\Deprecated]
public function PDO::pgsqlCopyToFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

此方法是该方法的别名： Pdo\Pgsql::copyToFile().

# PDO::pgsqlGetNotify

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

PDO::pgsqlGetNotify — 别名 Pdo\Pgsql::getNotify()

警告

此函数自 PHP 8.5.0 起弃用。强烈建议不要应用此函数。

### 说明

#[\Deprecated]
public function PDO::pgsqlGetNotify(int `$fetchMode` = PDO::FETCH_DEFAULT, int `$timeoutMilliseconds` = 0): array|false

此方法是该方法的别名： Pdo\Pgsql::getNotify().

# PDO::pgsqlGetPid

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

PDO::pgsqlGetPid — 别名 Pdo\Pgsql::getPid()

警告

此函数自 PHP 8.5.0 起弃用。强烈建议不要应用此函数。

### 说明

#[\Deprecated]
public function PDO::pgsqlGetPid(): int

此方法是该方法的别名： Pdo\Pgsql::getPid().

# PDO::pgsqlLOBCreate

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBCreate — 别名 Pdo\Pgsql::lobCreate()

警告

此函数自 PHP 8.5.0 起弃用。强烈建议不要应用此函数。

### 说明

#[\Deprecated]
public function PDO::pgsqlLOBCreate(): string

此方法是该方法的别名： Pdo\Pgsql::lobCreate().

# PDO::pgsqlLOBOpen

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBOpen — 别名 Pdo\Pgsql::lobOpen()

警告

此函数自 PHP 8.5.0 起弃用。强烈建议不要应用此函数。

### 说明

#[\Deprecated]
public function PDO::pgsqlLOBOpen(string `$oid`, string `$mode` = "rb"): resource|false

此方法是该方法的别名： Pdo\Pgsql::lobOpen().

# PDO::pgsqlLOBUnlink

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBUnlink — 别名 Pdo\Pgsql::lobUnlink()

警告

此函数自 PHP 8.5.0 起弃用。强烈建议不要应用此函数。

### 说明

#[\Deprecated]
public function PDO::pgsqlLOBUnlink(string `$oid`): bool

此方法是该方法的别名： Pdo\Pgsql::lobUnlink().

## 目录

- PDO_PGSQL DSN — Connecting to PostgreSQL databases
- PDO::pgsqlCopyFromArray — 别名 Pdo\Pgsql::copyFromArray
- PDO::pgsqlCopyFromFile — 别名 Pdo\Pgsql::copyFromFile
- PDO::pgsqlCopyToArray — 别名 Pdo\Pgsql::copyToArray
- PDO::pgsqlCopyToFile — 别名 Pdo\Pgsql::copyToFile
- PDO::pgsqlGetNotify — 别名 Pdo\Pgsql::getNotify
- PDO::pgsqlGetPid — 别名 Pdo\Pgsql::getPid
- PDO::pgsqlLOBCreate — 别名 Pdo\Pgsql::lobCreate
- PDO::pgsqlLOBOpen — 别名 Pdo\Pgsql::lobOpen
- PDO::pgsqlLOBUnlink — 别名 Pdo\Pgsql::lobUnlink

# The Pdo\Pgsql class

(PHP 8 >= 8.4.0)

## 简介

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.

## 类摘要

namespace Pdo;
class Pgsql extends PDO {
/* 继承的常量 */
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;
/* 常量 */
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;
/* 方法 */
public function copyFromArray(
string `$tableName`,
array `$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
/* 继承的方法 */
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
}

## 预定义常量

`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\Pgsql::TRANSACTION_IDLE`
  警告

  This constant has no effect, and is deprecated as of PHP 8.5.0.

`Pdo\Pgsql::TRANSACTION_ACTIVE`
  警告

  This constant has no effect, and is deprecated as of PHP 8.5.0.

`Pdo\Pgsql::TRANSACTION_INTRANS`
  警告

  This constant has no effect, and is deprecated as of PHP 8.5.0.

`Pdo\Pgsql::TRANSACTION_INERROR`
  警告

  This constant has no effect, and is deprecated as of PHP 8.5.0.

`Pdo\Pgsql::TRANSACTION_UNKNOWN`
  警告

  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

### 说明

public function Pdo\Pgsql::copyFromArray(
string `$tableName`,
array `$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.

### 参数

`tableName`
  String containing table name.
`rows`
  An indexed array 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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.5.0 | `rows` now also accepts a Traversable; previously only an array was accepted.

### 示例

示例 #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";
    }
    ?>

以上示例会输出：

    1 apple 10
    2 banana 20
    3 cherry 30

### 参见

- 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

### 说明

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

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 示例

示例 #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";
    ?>

以上示例会输出：

    2

### 参见

- 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

### 说明

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

### 参数

`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.

### 返回值

Returns an array of rows, 或者在失败时返回 `false`.

### 示例

示例 #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);
    ?>

以上示例会输出：

    array (
      0 => '1	apple	10
    ',
      1 => '2	banana	20
    ',
    )

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 示例

示例 #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');
    ?>

以上示例会输出：

    1	apple	10
    2	banana	20

### 参见

- 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

### 说明

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.

### 参数

`input`
  A string containing text to be escaped.

### 返回值

A string containing the escaped data.

### 示例

示例 #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 ()");
    ?>

以上示例的输出类似于：

    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 ()

### 参见

- PDO::quote() - 为 SQL 查询里的字符串添加引号

# Pdo\Pgsql::getNotify

(PHP 8 >= 8.4.0)

Pdo\Pgsql::getNotify — Get asynchronous notification

### 说明

public function Pdo\Pgsql::getNotify(int `$fetchMode` = `PDO::FETCH_DEFAULT`, int `$timeoutMilliseconds` = 0): array|false

Returns a result set representing a pending asynchronous notification.

### 参数

`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.

### 返回值

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`.

### 错误／异常

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.

### 示例

示例 #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);
    ?>

以上示例的输出类似于：

    array (
      'message' => 'messages',
      'pid' => 1928,
      'payload' => 'hello',
    )

### 参见

- PDO::query() - 预处理并执行没有占位符的 SQL 语句
- PDOStatement::fetch() - 从结果集中获取下一行
- PDOStatement::fetchAll() - 从结果集中获取剩余的行

# Pdo\Pgsql::getPid

(PHP 8 >= 8.4.0)

Pdo\Pgsql::getPid — Get the PID of the backend process handling this connection

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the PID as an int.

### 示例

示例 #1 Pdo\Pgsql::getPid() example

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    echo $db->getPid();
    ?>

以上示例的输出类似于：

    12345

### 参见

- pg_get_pid() - 获取后端的进程 ID

# Pdo\Pgsql::lobCreate

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobCreate — Creates a new large object

### 说明

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.

> 注意: This function, and all manipulations of the large object, must be called and carried out within a transaction.

### 参数

此函数没有参数。

### 返回值

Returns the OID of the newly created large object on success, 或者在失败时返回 `false`.

### 示例

示例 #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();
    ?>

### 参见

- Pdo\Pgsql::lobOpen() - Opens an existing large object stream
- Pdo\Pgsql::lobUnlink() - Deletes the large object
- pg_lo_create() - 新建大对象
- pg_lo_open() - 打开大对象

# Pdo\Pgsql::lobOpen

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobOpen — Opens an existing large object stream

### 说明

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.

> 注意: This function, and all manipulations of the large object, must be called and carried out within a transaction.

### 参数

`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.

### 返回值

Returns a stream resource on success, 或者在失败时返回 `false`.

### 示例

示例 #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);
    ?>

### 参见

- Pdo\Pgsql::lobCreate() - Creates a new large object
- Pdo\Pgsql::lobUnlink() - Deletes the large object
- pg_lo_create() - 新建大对象
- pg_lo_open() - 打开大对象

# Pdo\Pgsql::lobUnlink

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobUnlink — Deletes the large object

### 说明

public function Pdo\Pgsql::lobUnlink(string `$oid`): bool

Deletes a large object from the database identified by OID.

> 注意: This function, and all manipulations of the large object, must be called and carried out within a transaction.

### 参数

`oid`
  A large object identifier.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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();
    ?>

### 参见

- Pdo\Pgsql::lobCreate() - Creates a new large object
- Pdo\Pgsql::lobOpen() - Opens an existing large object stream
- pg_lo_create() - 新建大对象
- pg_lo_open() - 打开大对象

# Pdo\Pgsql::setNoticeCallback

(PHP 8 >= 8.4.0)

Pdo\Pgsql::setNoticeCallback — Set a callback to handle notice and warning messages generated by the backend

### 说明

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`.

### 参数

`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.

### 返回值

没有返回值。

### 示例

示例 #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');
    ?>

以上示例的输出类似于：

    NOTICE:  truncate cascades to table "child"

## 目录

- 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 Driver (PDO_SQLITE)

## 简介

PDO_SQLITE is a driver that implements the PHP Data Objects (PDO) interface to enable access to SQLite 3 databases.

> 注意:

> PDO_SQLITE allows using strings apart from streams together with `PDO::PARAM_LOB`.

## 安装

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.

> 注意: Additional setup on Windows as of PHP 7.4.0

> 为了使此扩展生效， DLL 文件必须能在 Windows 系统的 PATH 指示的路径下找到。如何操作的信息，请参见题为“如何在 Windows 中将 PHP 目录加到 PATH 中”的FAQ。虽然将 DLL 文件从 PHP 文件夹复制到 Windows 系统目录也行，但不建议这样做。 此扩展需要下列文件在 PATH 路径中： libsqlite3.dll.

# PDO_SQLITE DSN

(PHP 5 >= 5.1.0, PHP 7, PECL PDO_SQLITE >= 0.2.0)

PDO_SQLITE DSN — Connecting to SQLite databases

### 说明

The PDO_SQLITE Data Source Name (DSN) is composed of the following elements:

DSN prefix (SQLite 3)

  The DSN prefix is `sqlite:`.

  - To access a database on disk, the absolute path has to be appended to the DSN prefix.

  - To create a database in memory, `:memory:` has to be appended to the DSN prefix.

  - If the DSN consists of the DSN prefix only, a temporary database is used, which is deleted when the connection is closed.

### 示例

示例 #1 PDO_SQLITE DSN examples

The following examples show PDO_SQLITE DSN for connecting to SQLite databases:

    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 — 别名 Pdo\Sqlite::createAggregate()

### 说明

public function PDO::sqliteCreateAggregate(
string `$name`,
callable `$step`,
callable `$finalize`,
int `$numArgs` = -1
): bool

此方法是该方法的别名： Pdo\Sqlite::createAggregate().

# PDO::sqliteCreateCollation

(PHP 5 >= 5.3.11, PHP 7, PHP 8)

PDO::sqliteCreateCollation — 别名 Pdo\Sqlite::createCollation()

### 说明

public function PDO::sqliteCreateCollation(string `$name`, callable `$callback`): bool

此方法是该方法的别名： Pdo\Sqlite::createCollation().

# PDO::sqliteCreateFunction

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo_sqlite >= 1.0.0)

PDO::sqliteCreateFunction — 别名 Pdo\Sqlite::createFunction()

### 说明

public function PDO::sqliteCreateFunction(
string `$function_name`,
callable `$callback`,
int `$num_args` = -1,
int `$flags` = 0
): bool

此方法是该方法的别名： Pdo\Sqlite::createFunction().

### 更新日志

版本 | 说明
--- | ---
7.1.4 | The `flags` parameter has been added.

## 目录

- PDO_SQLITE DSN — Connecting to SQLite databases
- PDO::sqliteCreateAggregate — 别名 Pdo\Sqlite::createAggregate
- PDO::sqliteCreateCollation — 别名 Pdo\Sqlite::createCollation
- PDO::sqliteCreateFunction — 别名 Pdo\Sqlite::createFunction

# The Pdo\Sqlite class

(PHP 8 >= 8.4.0)

## 简介

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).

## 类摘要

class Pdo\Sqlite extends PDO {
/* 继承的常量 */
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;
/* 常量 */
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;
/* 方法 */
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
/* 继承的方法 */
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
}

## 预定义常量

`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 — Registers an aggregating user-defined function for use in SQL statements

### 说明

public function Pdo\Sqlite::createAggregate(
string `$name`,
callable `$step`,
callable `$finalize`,
int `$numArgs` = -1
): bool

This method is similar to Pdo\Sqlite::createFunction() except that it registers functions that can be used to calculate a result aggregated across all the rows of a query.

The key difference between this method and Pdo\Sqlite::createFunction() is that two functions are required to manage the aggregate.

小技巧

By using this method it is possible to override native SQL functions.

### 参数

`name`
  The name of the function used in SQL statements.
`step`
  Callback function called for each row of the result set. The callback should accumulate the result and store it in the aggregation context.

  This function need to be defined as:

  function step(
  mixed `$context`,
  int `$rownumber`,
  mixed `$value`,
  mixed `...$values`
  ): mixed
  `context`
    `null` for the first row; on subsequent rows it will have the value that was previously returned from the step function; you should use this to maintain the aggregate state.
  `rownumber`
    The current row number.
  `value`
    The first argument passed to the aggregate.
  `values`
    Further arguments passed to the aggregate.
  The return value of this function will be used as the `context` argument in the next call of the step or finalize functions.
`finalize`
  Callback function to aggregate the "stepped" data from each row. Once all the rows have been processed, this function will be called, and it should then take the data from the aggregation context and return the result. This callback function should return a type understood by SQLite (i.e. scalar type).

  This function need to be defined as:

  function fini(mixed `$context`, int `$rowcount`): mixed
  `context`

    Holds the return value from the very last call to the step function.

  `rowcount`

    Holds the number of rows over which the aggregate was performed.

  The return value of this function will be used as the return value for the aggregate.
`numArgs`
  Hint to the SQLite parser if the callback function accepts a predetermined number of arguments.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Pdo\Sqlite::createAggregate() example

In this example we will create a custom aggregate function named `max_length` that can be used in SQL queries.

In this example, we are creating an aggregating function, named `max_length`, that will calculate the length of the longest string in one of the columns of the table. For each row, the `max_len_step` function is called and passed a `$context` parameter. The context parameter is just like any other PHP variable and be set to hold an array or even an object. In this example, we are using it to hold the maximum length we have seen so far; if the $string has a length longer than the current maximum, we update the context to hold this new maximum length.

After all the rows have been processed, SQLite calls the `max_len_finalize` function to determine the aggregate result. It is possible to perform some kind of calculation based on the data in `$context`. In this basic example the result was calculated as the query progressed, thus so the context value can be directly returned.

    <?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());

    ?>

小技巧

It is NOT recommended for you to store a copy of the values in the context and then process them at the end, as you would cause SQLite to use a lot of memory to process the query - just think of how much memory you would need if a million rows were stored in memory, each containing a string 32 bytes in length.

### 参见

- Pdo\Sqlite::createFunction() - Registers a user-defined function for use in SQL statements
- 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

### 说明

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.

### 参数

`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

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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";
    }
    ?>

以上示例会输出：

    a1
    a10
    a2

    a1
    a2
    a10

### 参见

- Pdo\Sqlite::createFunction() - Registers a user-defined function for use in SQL statements
- Pdo\Sqlite::createAggregate() - Registers an aggregating user-defined function for use in SQL statements
- sqlite_create_function()
- sqlite_create_aggregate()

# Pdo\Sqlite::createFunction

(PHP 8 >= 8.4.0)

Pdo\Sqlite::createFunction — Registers a user-defined function for use in SQL statements

### 说明

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.

小技巧

By using this method it is possible to override native SQL functions.

### 参数

`function_name`
  The name of the function used in SQL statements.
`callback`
  Callback function to handle the defined SQL function.

  > 注意: Callback functions should return a type understood by SQLite (i.e. scalar type).

  This function need to be defined as:

  function callback(mixed `$value`, mixed `...$values`): mixed
  `value`

    The first argument passed to the SQL function.

  `values`

    Further arguments passed to the SQL function.

`num_args`
  The number of arguments that the SQL function takes. If this parameter is `-1`, then the SQL function may take any number of arguments.
`flags`
  A bitmask of flags. Currently, only `Pdo\Sqlite::DETERMINISTIC` is supported, which specifies that the function always returns the same result given the same inputs within a single SQL statement.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Pdo\Sqlite::createFunction() example

In this example, we have a function that calculates the SHA256 sum of a string, and then reverses it. When the SQL statement executes, it returns the value of the filename transformed by our function. The data returned in $rows contains the processed result.

The beauty of this technique is that there is no need to process the result using a `foreach` loop after the query.

    <?php
    function sha256_and_reverse($string)
    {
        return strrev(hash('sha256', $string));
    }

    $db = new Pdo\Sqlite('sqlite::sqlitedb');
    $db->createFunction('sha256rev', 'sha256_and_reverse', 1);
    $rows = $db->query('SELECT sha256rev(filename) FROM files')->fetchAll();
    ?>

### 参见

- Pdo\Sqlite::createAggregate() - Registers an aggregating user-defined function for use in SQL statements
- 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

### 说明

public function Pdo\Sqlite::loadExtension(string `$name`): void
警告

本函数还未编写文档，仅有参数列表。

Description.

### 参数

`name`
  Description.

### 返回值

没有返回值。

### 错误／异常

When does this function issue `E_*` level errors, and/or throw Exceptions.

### 示例

示例 #1 Pdo\Sqlite::loadExtension() example

Description.

    <?php
    echo "Code example";
    ?>

以上示例会输出：

    Code example

### 注释

> 注意: Any notes that don't fit anywhere else should go here.

### 参见

- ClassName::otherMethodName()
- some_function()

# Pdo\Sqlite::openBlob

(PHP 8 >= 8.4.0)

Pdo\Sqlite::openBlob — Description

### 说明

public function Pdo\Sqlite::openBlob(
string `$table`,
string `$column`,
int `$rowid`,
?string `$dbname` = "main",
int `$flags` = `Pdo\Sqlite::OPEN_READONLY`
): resource|false
警告

本函数还未编写文档，仅有参数列表。

Description.

### 参数

`table`
  Description.
`column`
  Description.
`rowid`
  Description.
`dbname`
  Description.
`flags`
  One of the `Pdo\Sqlite::OPEN_*`

### 返回值

Description.

### 错误／异常

When does this function issue `E_*` level errors, and/or throw Exceptions.

### 示例

示例 #1 Pdo\Sqlite::openBlob() example

Description.

    <?php
    echo "Code example";
    ?>

以上示例会输出：

    Code example

### 注释

> 注意: Any notes that don't fit anywhere else should go here.

### 参见

- ClassName::otherMethodName()
- some_function()

## 目录

- Pdo\Sqlite::createAggregate — Registers an aggregating user-defined function for use in SQL statements
- Pdo\Sqlite::createCollation — Registers a user-defined function for use as a collating function in SQL statements
- Pdo\Sqlite::createFunction — Registers a user-defined function for use in SQL statements
- Pdo\Sqlite::loadExtension — Description
- Pdo\Sqlite::openBlob — Description

- 安装/配置
  - 安装
  - 运行时配置
- 预定义常量
  - 获取模式
- 连接与连接管理
- 事务与自动提交
- 预处理语句与存储过程
- 错误与错误处理
- 大对象 (LOB)
- PDO — PDO 类
  - PDO::beginTransaction — 启动一个事务
  - PDO::commit — 提交一个事务
  - PDO::connect — Connect to a database and return a PDO subclass for drivers that support it
  - PDO::__construct — 创建一个表示数据库连接的 PDO 实例
  - PDO::errorCode — 获取跟数据库句柄上一次操作相关的 SQLSTATE
  - PDO::errorInfo — Fetch extended error information associated with the last operation on the database handle
  - PDO::exec — 执行 SQL 语句，并返回受影响的行数
  - PDO::getAttribute — 取回一个数据库连接的属性
  - PDO::getAvailableDrivers — 返回一个可用驱动的数组
  - PDO::inTransaction — 检查是否在事务内
  - PDO::lastInsertId — 返回最后插入行的ID或序列值
  - PDO::prepare — 预处理要执行的语句，并返回语句对象
  - PDO::query — 预处理并执行没有占位符的 SQL 语句
  - PDO::quote — 为 SQL 查询里的字符串添加引号
  - PDO::rollBack — 回滚事务
  - PDO::setAttribute — 设置属性
- PDOStatement — PDOStatement 类
  - PDOStatement::bindColumn — 绑定一列到一个 PHP 变量
  - PDOStatement::bindParam — 绑定一个参数到指定的变量名
  - PDOStatement::bindValue — 把一个值绑定到一个参数
  - PDOStatement::closeCursor — 关闭游标，使语句能再次被执行
  - PDOStatement::columnCount — 返回结果集中的列数
  - PDOStatement::debugDumpParams — 打印一条 SQL 预处理命令
  - PDOStatement::errorCode — 获取跟上一次语句句柄操作相关的 SQLSTATE
  - PDOStatement::errorInfo — 获取跟上一次语句句柄操作相关的扩展错误信息
  - PDOStatement::execute — 执行预处理语句
  - PDOStatement::fetch — 从结果集中获取下一行
  - PDOStatement::fetchAll — 从结果集中获取剩余的行
  - PDOStatement::fetchColumn — 从结果集中的下一行返回单独的一列
  - PDOStatement::fetchObject — 获取下一行并作为一个对象返回
  - PDOStatement::getAttribute — 检索语句属性
  - PDOStatement::getColumnMeta — 返回结果集中一列的元数据
  - PDOStatement::getIterator — Gets result set iterator
  - PDOStatement::nextRowset — 在一个多行集合语句句柄中推进到下一个行集合
  - PDOStatement::rowCount — 返回受上一个 SQL 语句影响的行数
  - PDOStatement::setAttribute — 设置一个语句属性
  - PDOStatement::setFetchMode — 为语句设置默认的获取模式
- PDORow — The PDORow class
- PDOException — PDOException 异常类
- PDO 驱动
  - 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 Driver — MySQL PDO Driver (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 Driver — SQLite PDO Driver (PDO_SQLITE)
  - Pdo\Sqlite — The Pdo\Sqlite class

- DBA — Database (dbm-style) Abstraction Layer
  - 安装/配置
  - 预定义常量
  - 示例
  - Dba\Connection — The Dba\Connection class
  - DBA 函数
- ODBC — ODBC (Unified)
  - 安装/配置
  - 预定义常量
  - ODBC 函数
  - Odbc\Connection — The Odbc\Connection class
  - Odbc\Result — The Odbc\Result class
- PDO — PHP 数据对象
  - 安装/配置
  - 预定义常量
  - 连接与连接管理
  - 事务与自动提交
  - 预处理语句与存储过程
  - 错误与错误处理
  - 大对象 (LOB)
  - PDO — PDO 类
  - PDOStatement — PDOStatement 类
  - PDORow — The PDORow class
  - PDOException — PDOException 异常类
  - PDO 驱动

# 针对各数据库系统对应的扩展

# CUBRID

# 简介

这些函数可以让你访问CUBRID数据库服务。更多关于CUBRID的信息可以在» CUBRID找到。

在» CUBRID 参考资料 可以找到关于CUBRID的参考资料。

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置
- 资源类型

## 需求

为使这些函数可用，必须安装CUBRID和编译CUBRID PHP库，提供CUBRID支持。

## 安装

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/cubrid.

PECL 扩展的 DLL 当前不可用。参见 在 Windows 上构建章节。

关于在 Linux 和 Windows 系统上的安装手册信息，请阅读包含在包中的这个文件build-guide.html。

## 运行时配置

无运行时配置

## 资源类型

在CUBRID中使用四种资源类型。第一个用于连接数据库的链接标识符，第二个是保存一个查询结果的资源类型，以及最后两个保存BLOB/CLOB查询结果的资源数据类型。

## connection 标识符

由 cubrid_connect(), cubrid_connect_with_url(), cubrid_pconnect() 以及 cubrid_pconnect_with_url()返回的一个连接标识符。

## request 标识符

由 cubrid_prepare() 和 cubrid_execute()返回的一个请求标识符。

## LOB 标识符

由cubrid_lob_get()返回的一个LOB 标识符。

## LOB2 标识符

由 cubrid_lob2_new()返回或从结果集中获取的一个LOB 标识符

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

以下常量可在执行 SQL 语句时使用，可传递给 cubrid_prepare() 和 cubrid_execute()。

CUBRID SQL 执行 flag
常量 | 说明
--- | ---
`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.

以下常量可在获取结果时用于指定获取行为，可传递给 cubrid_fetch() 和 cubrid_fetch_array()。

CUBRID 获取 flag
常量 | 说明
--- | ---
`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 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().

以下常量可在查询结果中定位游标时使用，可传递给或由 cubrid_move_cursor() 返回。

CUBRID 游标定位 flag
常量 | 说明
--- | ---
`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.

以下常量可在设置数据库连接的自动提交模式时使用，可传递给 cubrid_set_autocommit() 或由 cubrid_get_autocommit() 返回。

CUBRID 自动提交 flag
常量 | 说明
--- | ---
`CUBRID_AUTOCOMMIT_TRUE` | Enable the auto-commit mode.
`CUBRID_AUTOCOMMIT_FALSE` | Disable the auto-commit mode.

以下常量可在设置数据库参数时使用，可传递给 cubrid_set_db_parameter()。

CUBRID 参数 flag
常量 | 说明
--- | ---
`CUBRID_PARAM_ISOLATION_LEVEL` | Transaction isolation level for the database connection.
`CUBRID_PARAM_LOCK_TIMEOUT` | Transaction timeout in seconds.

以下常量可在设置事务隔离级别时使用，可传递给 cubrid_set_db_parameter() 或由 cubrid_get_db_parameter() 返回。

CUBRID 事务级别 flag
常量 | 说明
--- | ---
`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.

以下常量可在获取模式信息时使用，可传递给 cubrid_schema()。

CUBRID 模式 flag
常量 | 说明
--- | ---
`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.

以下常量可在报告错误时使用，可由 cubrid_error_code_facility() 返回。

CUBRID 错误设施（facility）代码
常量 | 说明
--- | ---
`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.

# 示例

下面是一个在PHP和CUBRID建立连接的简单的例子。本节将覆盖最基本和最显著的特性。下面的代码需要连接CUBRID数据库，这意味着 CUBRID服务和 CUBRID Broker已经运行。

下面用demodb数据库作为例子举例。默认在安装时就创建了。确认此数据库已经被创建。

示例 #1 数据查询的例子

    <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>

示例 #2 数据插入的例子

    <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 函数

# cubrid_bind

(PECL CUBRID >= 8.3.0)

cubrid_bind — Bind variables to a prepared statement as parameters

### 说明

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.

> 注意: 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

### 参数

`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).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.3.1 | Added BLOB/CLOB data types support.

### 示例

示例 #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);
    ?>

以上示例会输出：

    --- 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

示例 #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);
    }
    ?>

示例 #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);
    }
    ?>

### 参见

- 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

### 说明

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().

### 参数

`req_identifier`
  Request identifier.

### 返回值

Return `true` on success.

### 示例

示例 #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);
    }
    ?>

### 参见

- cubrid_close_request() - Close the request handle

# cubrid_close_request

(PECL CUBRID >= 8.3.0)

cubrid_close_request — Close the request handle

### 说明

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().

### 参数

`req_identifier`
  Request identifier.

### 返回值

Return `true` on success.

### 示例

示例 #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);
    }
    ?>

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`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.

### 返回值

Number of elements, when process is successful, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.3.1 | Change return value: when process is unsuccessful, return false, not -1.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 说明

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`.

### 参数

`req_identifier`
  Request identifier.

### 返回值

Array of string values containing the column names, when process is successful, 或者在失败时返回 `false`.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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_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

### 说明

function cubrid_column_types(resource `$req_identifier`): array

The cubrid_column_types() function gets column types of query results by using `req_identifier`.

### 参数

`req_identifier`
  Request identifier.

### 返回值

Array of string values containing the column types, when process is successful, 或者在失败时返回 `false`.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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_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

### 说明

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.

### 参数

`conn_identifier`
  Connection identifier.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

Connection identifier, when process is successful, 或者在失败时返回 `false`.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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_pconnect() - Open a persistent 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_connect_with_url

(PECL CUBRID >= 8.3.1)

cubrid_connect_with_url — Establish the environment for connecting to CUBRID server

### 说明

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.

> 注意: `?` 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:::";

### 参数

`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.

### 返回值

Connection identifier, when process is successful, 或者在失败时返回 `false`.

### 示例

示例 #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);
    }
    ?>

示例 #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);
    }
    ?>

### 参见

- cubrid_connect() - Open a connection to a CUBRID Server
- cubrid_pconnect() - Open a persistent connection to a 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

### 说明

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.

### 参数

`req_identifier`
  Request identifier.

### 返回值

Oid of current cursor location, when process is successful, 或者在失败时返回 `false`.

### 示例

示例 #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);
    ?>

以上示例会输出：

    Array
    (
        [s_name] => X
        [f_name] => Mixed
    )

### 参见

- cubrid_execute() - Execute a prepared SQL statement

# cubrid_disconnect

(PECL CUBRID >= 8.3.0)

cubrid_disconnect — Close a database connection

### 说明

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().

### 参数

`conn_identifier`
  Connection identifier.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    }
    ?>

### 参见

- 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

### 说明

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.

### 参数

`conn_identifier`
  Connection identifier.
`oid`
  Oid of the instance that you want to delete.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

以上示例会输出：

    --- 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         "
    }

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Error code of the error that occurred, or `0` (zero) if no error occurred.

### 示例

示例 #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;
    }
    ?>

以上示例会输出：

    Error facility: 4
    Error code: -30015
    Error msg: Some parameter not binded

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Facility code of the error code that occurred: `CUBRID_FACILITY_DBMS`, `CUBRID_FACILITY_CAS`, `CUBRID_FACILITY_CCI`, `CUBRID_FACILITY_CLIENT`.

### 示例

示例 #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;
    }
    ?>

以上示例会输出：

    Error facility: 1
    Error code: -493
    Error msg: Syntax: In line 1, column 15 before END OF STATEMENT
    Syntax error: unexpected 'unknown'

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Error message that occurred.

### 示例

示例 #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;
    }
    ?>

以上示例会输出：

    Error facility: 2
    Error code: -10015
    Error msg: Invalid T_CCI_SCH_TYPE value

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

Request identifier, when process is successful and first param is conn_identifier; `true`, when process is successful and first argument is request_identifier, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | Add new option `CUBRID_EXEC_QUERY_ALL`.

### 示例

示例 #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);
    ?>

以上示例会输出：

    athlete              host_year score      unit
    Phelps Michael       2004      51.25      time

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 参见

- 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

### 说明

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().

### 参数

`req_identifier`
  This is the request identifier.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`conn_identifier`
  Connection identifier.
`oid`
  OID of the instance that you want to read.
`attr`
  Name of the attribute that you want to read.

### 返回值

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())

### 示例

示例 #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);
    ?>

以上示例会输出：

    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         "
    }

### 参见

- 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

### 说明

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.

### 参数

`conn_identifier`
  Connection identifier.

### 返回值

`true`, when auto-commit is on.

`false`, when auto-commit is off.

`null` on error.

### 参见

- 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

### 说明

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().

### 参数

`conn_identifier`
  The CUBRID connection.

### 返回值

A string that represents the CUBRID connection charset on success, 或者在失败时返回 `false`.

### 示例

示例 #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));

    ?>

以上示例会输出：

    CUBRID current charset: iso8859-1

### 参见

- 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

### 说明

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.

### 参数

`conn_identifier`
  Connection identifier.
`oid`
  OID of the instance that you want to check the existence.

### 返回值

Class name when process is successful, 或者在失败时返回 `false`.

### 示例

示例 #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);
    ?>

以上示例会输出：

    code

### 参见

- 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

### 说明

function cubrid_get_client_info(): string

This function returns a string that represents the client library version.

### 参数

### 返回值

A string that represents the client library version on success, 或者在失败时返回 `false`.

### 示例

示例 #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);

    ?>

以上示例会输出：

    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

### 说明

function cubrid_get_db_parameter(resource `$conn_identifier`): array

This function returns the CUBRID database parameters, 或者在失败时返回 `false`. 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.

### 参数

`conn_identifier`
  The CUBRID connection. If the connection identifier is not specified, the last link opened by cubrid_connect() is assumed.

### 返回值

An associative array with CUBRID database parameters; on success, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | Change LOCK_TIMEOUT to PARAM_LOCK_TIMEOUT, and MAX_STRING_LENGTH to PARAM_MAX_STRING_LENGTH in result.

### 示例

示例 #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);

    ?>

以上示例会输出：

    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_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

### 说明

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.

### 参数

`req_identifier`
  Request identifier.

### 返回值

Returns the query timeout value in milliseconds of the current request on success, 或者在失败时返回 `false`.

### 示例

示例 #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);
    ?>

以上示例会输出：

    int(5000)
    int(1000)

### 参见

- 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

### 说明

function cubrid_get_server_info(resource `$conn_identifier`): string

This function returns a string that represents the CUBRID server version.

### 参数

`conn_identifier`
  The CUBRID connection.

### 返回值

A string that represents the CUBRID server version on success, 或者在失败时返回 `false`.

### 示例

示例 #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);

    ?>

以上示例会输出：

    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

### 说明

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.

> 注意: 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.

### 参数

`conn_identifier`
  The connection identifier previously obtained by a call to cubrid_connect().

### 返回值

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.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | Change the return value from an array to string; Remove the first parameter class_name.

### 示例

示例 #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);
    ?>

以上示例会输出：

    string(2) "19"

# cubrid_is_instance

(PECL CUBRID >= 8.3.0)

cubrid_is_instance — Check whether the instance pointed by OID exists

### 说明

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.

### 参数

`conn_identifier`
  Connection identifier.
`oid`
  OID of the instance that you want to check the existence.

### 返回值

1, if such instance exists;

0, if such instance does not exist;

-1, in case of error

### 示例

示例 #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);
    ?>

以上示例会输出：

    Instance pointed by @0|0|0 doesn't exist.

### 参见

- 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

### 说明

function cubrid_lob_close(array `$lob_identifier_array`): bool

cubrid_lob_close() is used to close all BLOB/CLOB returned from cubrid_lob_get().

### 参数

`lob_identifier_array`
  LOB identifier array returned from cubrid_lob_get().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

### 参见

- 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

### 说明

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.

### 参数

`conn_identifier`
  Connection identifier.
`lob_identifier`
  LOB identifier.
`path_name`
  Path name of the file.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

### 参见

- 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

### 说明

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.

### 参数

`conn_identifier`
  Connection identifier.
`sql`
  SQL statement to be executed.

### 返回值

Return an array of LOB resources, when process is successful, 或者在失败时返回 `false`.

### 示例

示例 #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);
    ?>

### 参见

- 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

### 说明

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.

### 参数

`conn_identifier`
  Connection identifier.
`lob_identifier`
  LOB identifier.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

### 参见

- 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

### 说明

function cubrid_lob_size(resource `$lob_identifier`): string

cubrid_lob_size() is used to get BLOB/CLOB data size.

### 参数

`lob_identifier`
  LOB identifier.

### 返回值

A string representing LOB data size, when process is successful, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | Change return value type from int to string.

### 示例

示例 #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);
    ?>

### 参见

- 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

### 说明

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.

### 参数

`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".

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

### 参见

- 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

### 说明

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.

### 参数

`lob_identifier`
  Lob identifier as a result of cubrid_lob2_new() or get from the result set.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

### 参见

- cubrid_lob2_new() - Create a lob object
- cubrid_lob2_close() - Close LOB object
- cubrid_lob2_import() - Import BLOB/CLOB data from a file
- 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 — Import BLOB/CLOB data from a file

### 说明

function cubrid_lob2_import(resource `$lob_identifier`, string `$file_name`): bool

The cubrid_lob2_import() function is used to save the contents of BLOB/CLOB data from a file. To use this function, you must use cubrid_lob2_new() or fetch a lob object from CUBRID database first. If the file does not exist, the operation will fail. This function will not influence the cursor position of the lob object. It operates the entire lob object.

### 参数

`lob_identifier`
  Lob identifier as a result of cubrid_lob2_new() or get from the result set.
`filename`
  File name you want to import BLOB/CLOB data. It also supports the path of the file.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 cubrid_lob2_export() example

    <?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'); // or cubrid_lob2_bind($req, 2, $lob);

    cubrid_execute($req);

    cubrid_lob2_close($lob);
    cubrid_disconnect($conn);
    ?>

### 参见

- 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

### 说明

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.

### 参数

`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".

### 返回值

Lob identifier when it is successful, 或者在失败时返回 `false`.

### 参见

- cubrid_lob2_close() - Close LOB object

# cubrid_lob2_read

(PECL CUBRID >= 8.4.1)

cubrid_lob2_read — Read from BLOB/CLOB data

### 说明

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.

### 参数

`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.

### 返回值

Returns the contents as a string, `false` when there is no more data, or `null` on failure.

### 示例

示例 #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);
    ?>

示例 #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);
    ?>

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

### 参见

- 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

### 说明

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.

> 注意: If you use this function to move the cursor position of the lob object, you should pass `offset` as a string.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

### 参见

- 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

### 说明

function cubrid_lob2_size(resource `$lob_identifier`): int

The cubrid_lob2_size() function is used to get the size of a lob object.

### 参数

`lob_identifier`
  Lob identifier as a result of cubrid_lob2_new() or get from the result set.

### 返回值

It will return the size of the LOB object when it processes successfully, 或者在失败时返回 `false`.

### 参见

- 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

### 说明

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.

### 参数

`lob_identifier`
  Lob identifier as a result of cubrid_lob2_new() or get from the result set.

### 返回值

It will return the size of the LOB object as a string when it processes successfully, 或者在失败时返回 `false`.

### 参见

- 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

### 说明

function cubrid_lob2_tell(resource `$lob_identifier`): int

The cubrid_lob2_tell() function is used to tell the cursor position of the LOB object.

### 参数

`lob_identifier`
  Lob identifier as a result of cubrid_lob2_new() or get from the result set.

### 返回值

It will return the cursor position on the LOB object when it processes successfully, 或者在失败时返回 `false`.

### 参见

- 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

### 说明

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.

### 参数

`lob_identifier`
  Lob identifier as a result of cubrid_lob2_new() or get from the result set.

### 返回值

It will return the cursor position on the LOB object as a string when it processes successfully, 或者在失败时返回 `false`.

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

示例 #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);
    ?>

### 参见

- 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

### 说明

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`.

### 参数

`conn_identifier`
  Connection identifier.
`oid`
  OID of the instance that you want to put read lock on.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

以上示例会输出：

    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         "
    }

### 参见

- 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

### 说明

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`.

### 参数

`conn_identifier`
  Connection identifier.
`oid`
  OID of the instance that you want to put write lock on.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

以上示例会输出：

    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"
    }

### 参见

- 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

### 说明

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`.

### 参数

`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`.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

以上示例会输出：

    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"
    }

### 参见

- 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

### 说明

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().

### 参数

`result`
  `result` comes from a call to cubrid_execute()

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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");
    }
    ?>

以上示例会输出：

    ------------ 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

### 参见

- 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

### 说明

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.

### 参数

`result`
  Result.

### 返回值

Number of columns, when process is successful.

`false`, if SQL statement is not SELECT.

### 示例

示例 #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);
    ?>

以上示例会输出：

    Row Num: 6
    Column Num: 2

### 参见

- 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

### 说明

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.

### 参数

`result`
  `result` comes from a call to cubrid_execute(), cubrid_query() and cubrid_prepare()

### 返回值

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.

### 示例

示例 #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);
    ?>

以上示例会输出：

    Row Num: 6
    Column Num: 2

### 参见

- 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 — Open a persistent connection to a CUBRID server

### 说明

function cubrid_pconnect(
string `$host`,
int `$port`,
string `$dbname`,
string `$userid` = ?,
string `$passwd` = ?
): resource

Establishes a persistent connection to a CUBRID server.

cubrid_pconnect() acts very much like cubrid_connect() 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()).

This type of link is therefore called 'persistent'.

### 参数

`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.
`passwd`
  User password.

### 返回值

Connection identifier, when process is successful, 或者在失败时返回 `false`.

### 示例

示例 #1 cubrid_pconnect() example

    <?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);
    ?>

以上示例会输出：

    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_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

### 说明

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.

> 注意: `?` 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:::";

### 参数

`conn_url`
  A character string that contains server connection information.
`userid`
  User name for the database.
`passwd`
  User password.

### 返回值

Connection identifier, when process is successful, 或者在失败时返回 `false`.

### 示例

示例 #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);
    }
    ?>

示例 #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);
    }
    ?>

### 参见

- cubrid_connect() - Open a connection to a CUBRID Server
- cubrid_connect_with_url() - Establish the environment for connecting to CUBRID server
- cubrid_pconnect() - Open a persistent connection to a 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

### 说明

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.

### 参数

`conn_identifier`
  Connection identifier.
`prepare_stmt`
  Prepare query.
`option`
  OID return option `CUBRID_INCLUDE_OID`.

### 返回值

Request identifier, if process is successful, 或者在失败时返回 `false`.

### 示例

示例 #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);
    ?>

以上示例会输出：

    There are 27 event that exits in 2004 olympic but not in 2000. For example:

    Event_code      Event_name
    ----------------------------
    20063           +91kg
    20070           64kg

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

以上示例会输出：

    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"
    }

### 参见

- 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() - Insert an element to a sequence type column using OID
- 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

### 说明

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.

### 参数

`conn_identifier`
  Connection identifier.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 参见

- 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

### 说明

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 |

### 参数

`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.

### 返回值

Array containing the schema information, when process is successful, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.3.1 | Change return value: when process is unsuccessful, return false, not -1.

### 示例

示例 #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);
    ?>

以上示例会输出：

    --- 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

### 说明

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.

### 参数

`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).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

以上示例会输出：

    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"
    }

### 参见

- cubrid_seq_insert() - Insert an element to a sequence type column using OID
- cubrid_seq_put() - Update the element value of sequence type column using OID

# cubrid_seq_insert

(PECL CUBRID >= 8.3.0)

cubrid_seq_insert — Insert an element to a sequence type column using OID

### 说明

function cubrid_seq_insert(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
int `$index`,
string `$seq_element`
): bool

The cubrid_seq_insert() function is used to insert an element to a sequence type attribute in a requested location.

### 参数

`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 instance to.
`index`
  Location of the element, you want to insert the element to (1-based).
`seq_element`
  Content of the element that you want to insert.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 cubrid_seq_insert() 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_insert($conn, $oid, "c", 5, "44");

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

以上示例会输出：

    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"
    }

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

以上示例会输出：

    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"
    }

### 参见

- cubrid_seq_drop() - Delete an element from sequence type column using OID
- cubrid_seq_insert() - Insert an element to a sequence type column using OID

# cubrid_set_add

(PECL CUBRID >= 8.3.0)

cubrid_set_add — Insert a single element to set type column using OID

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

以上示例会输出：

    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"
    }

### 参见

- 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

### 说明

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.

### 参数

`conn_identifier`
  Connection identifier.
`mode`
  Auto-commit mode. The following constants can be used:
  - `CUBRID_AUTOCOMMIT_FALSE`
  - `CUBRID_AUTOCOMMIT_TRUE`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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`

> 注意: The auto-commit mode can be set by using cubrid_set_autocommit().

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

以上示例会输出：

    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)
    }

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

以上示例会输出：

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(2) {
      [0]=>
      string(1) "2"
      [1]=>
      string(1) "3"
    }

### 参见

- 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

### 说明

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.

### 参数

`req_identifier`
  Request identifier.
`timeout`
  Timeout time in milliseconds.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function cubrid_version(): string

The cubrid_version() function is used to get the CUBRID PHP module's version.

### 参数

此函数没有参数。

### 返回值

Version information (eg. "8.3.1.0001").

### 示例

示例 #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);

    ?>

以上示例会输出：

    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_error_code() - Get error code for the most recent function call
- cubrid_error_code_facility() - Get the facility code of error

## 目录

- 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 — Import BLOB/CLOB data from a file
- 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 — Open a persistent connection to a 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 — Insert an element to a sequence type column using OID
- 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 兼容性函数

# cubrid_affected_rows

(PECL CUBRID >= 8.3.0)

cubrid_affected_rows — Return the number of rows affected by the last SQL statement

### 说明

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).

### 参数

`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.

### 返回值

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.

### 示例

示例 #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!";
    ?>

以上示例会输出：

    int(10)
    int(10)
    int(10)
    done!

### 参见

- cubrid_execute() - Execute a prepared SQL statement

# cubrid_client_encoding

(PECL CUBRID >= 8.3.1)

cubrid_client_encoding — Return the current CUBRID connection charset

### 说明

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().

### 参数

`conn_identifier`
  The CUBRID connection. If the connection identifier is not specified, the last link opened by cubrid_connect() is assumed.

### 返回值

A string that represents the CUBRID connection charset; on success.

`false` on failure.

### 示例

示例 #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));

    ?>

以上示例会输出：

    CUBRID current charset: iso8859-1

### 参见

- cubrid_get_charset() - Return the current CUBRID connection charset

# cubrid_close

(PECL CUBRID >= 8.3.1)

cubrid_close — Close CUBRID connection

### 说明

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().

### 参数

`conn_identifier`
  The CUBRID connection identifier. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

### 返回值

`true`, when process is successful.

`false`, when process is unsuccessful.

### 示例

示例 #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);
    }
    ?>

### 参见

- 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

### 说明

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.

### 参数

`result`
  The result.
`row_number`
  This is the desired row number of the new result pointer.

### 返回值

Returns `true` on success or `false` on failure.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 说明

function cubrid_db_name(array `$result`, int `$index`): string

Retrieve the database name from a call to cubrid_list_dbs().

### 参数

`result`
  The result pointer from a call to cubrid_list_dbs().
`index`
  The index into the result set.

### 返回值

Returns the database name on success, and `false` on failure. If `false` is returned, use cubrid_error() to determine the nature of the error.

### 示例

示例 #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++;
    }
    ?>

以上示例会输出：

    demodb

### 参见

- 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

### 说明

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.

### 参数

`conn_identifier`
  The CUBRID connection identifier. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

### 返回值

Returns the error number from the last CUBRID function, or `0` (zero) if no error occurred.

### 示例

示例 #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);
    }
    ?>

以上示例会输出：

    Error Code: -493 Error Message: Syntax: Unknown class "person". select id, [name] from person

### 参见

- 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

### 说明

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.

### 参数

`connection`
  The CUBRID connection.

### 返回值

Error message that occurred.

### 示例

示例 #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);
    }
    ?>

以上示例会输出：

    Error Code: -493 Error Message: Syntax: Unknown class "person". select id, [name] from person

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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)

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

Associative array, when process is successful.

`false`, when there are no more rows; NULL, when process is unsuccessful.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 参见

- 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

### 说明

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

### 参数

`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.

### 返回值

Object with certain properties of the specific column, when process is successful.

`false` on failure.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 说明

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.

> 注意: If field data type is BLOB/CLOB, you should get its length by using cubrid_lob_size().

### 参数

`result`
  `result` comes from a call to cubrid_execute()

### 返回值

A numeric array, when process is successful.

`false` on failure.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`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.

### 返回值

An object, when process is successful.

`false`, when there are no more rows; NULL, when process is unsuccessful.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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"
    }

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

A numerical array, when process is successful.

`false`, when there are no more rows; NULL, when process is unsuccessful.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 参见

- 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

### 说明

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`.

### 参数

`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.

### 返回值

A string with flags, when process is successful.

`false` when invalid field_offset value.

-1 if SQL sentence is not SELECT.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`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.

### 返回值

Maximum length, when process is successful.

`false` on failure.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`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.

### 返回值

Name of specified field index, on success.

`false` on failure.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`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.

### 返回值

`true` on success.

`false` on failure.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`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.

### 返回值

Name of the table of the specified field, on success.

`false` when invalid field_offset value.

-1 if SQL sentence is not SELECT.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`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.

### 返回值

Type of the column, on success.

`false` when invalid field_offset value.

-1 if SQL sentence is not SELECT.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 说明

function cubrid_list_dbs(resource `$conn_identifier` = ?): array

This function returns an array with the list of all existing Cubrid databases.

### 参数

`conn_identifier`
  The CUBRID connection.

### 返回值

An numeric array with all existing Cubrid databases; on success.

`false` on failure.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`result`
  `result` comes from a call to cubrid_execute(), cubrid_query() and cubrid_prepare()

### 返回值

Number of columns, on success.

-1 if SQL sentence is not SELECT.

`false` when process is unsuccessful.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 说明

function cubrid_ping(resource `$conn_identifier` = ?): bool

Checks whether or not the connection to the server is working.

### 参数

`conn_identifier`
  The CUBRID connection identifier. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

### 返回值

Returns `true` if the connection to the CUBRID server is working, otherwise `false`.

### 示例

示例 #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

### 说明

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`.

### 参数

`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.

### 返回值

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.

### 示例

示例 #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());
    }

    ?>

示例 #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);
    ?>

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

Escaped string version of the given string, on success.

`false` on failure.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`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.

### 返回值

Value of a specific field, on success (NULL if value if null).

`false` on failure.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 示例

示例 #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);
    ?>

### 注释

> 注意: 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().

## 目录

- 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 过时的别名和函数

# 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

### 说明

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.

### 参数

`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.

### 返回值

`true`, when process is successful.

`false`, when process is unsuccessful.

### 示例

示例 #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";
       }
    }
    ?>

### 注释

> 注意: 为了向下兼容，可以使用下列已废弃的别名： cubrid_load_from_glo()

> 注意: This function is removed from CUBRID 3.1.

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

Oid of the instance created, when process is successful.

`false`, when process is unsuccessful.

### 示例

示例 #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);
       }
    }
    ?>

### 注释

> 注意: 为了向下兼容，可以使用下列已废弃的别名： cubrid_new_glo()

> 注意: This function is removed from CUBRID 3.1.

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

`true`, when process is successful.

`false`, when process is unsuccessful.

### 示例

示例 #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";
       }
    }
    ?>

### 注释

> 注意: 为了向下兼容，可以使用下列已废弃的别名： cubrid_save_to_glo()

> 注意: This function is removed from CUBRID 3.1.

### 参见

- 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

### 说明

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.

### 参数

`conn_identifier`
  Connection identifier.
`oid`
  Oid of the glo instance that you want to read data from.

### 返回值

`true`, when process is successful.

`false`, when process is unsuccessful.

### 示例

示例 #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);
    }
    ?>

### 注释

> 注意: 为了向下兼容，可以使用下列已废弃的别名： cubrid_send_glo()

> 注意: This function is removed from CUBRID 3.1.

### 参见

- 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

## 目录

- 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

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
  - 资源类型
- 预定义常量
- 示例
- CUBRID 函数
  - 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 — Import BLOB/CLOB data from a file
  - 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 — Open a persistent connection to a 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 — Insert an element to a sequence type column using OID
  - 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 兼容性函数
  - 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 过时的别名和函数
  - 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

# 简介

> 注意:

> 此扩展已被移至 » PECL 资源库；不再与 PHP 捆绑，从 PHP 5.3.0.

These functions allow you to access records stored in dBase-format (dbf) databases.

警告

We recommend against using dBase files as your production database. Use » SQLite or choose any real SQL server instead; » MySQL or » Postgres are common choices with PHP. dBase support is here to allow you to import and export data to and from your web database, because the file format is commonly understood by Windows spreadsheets and organizers.

警告

As of dbase 7.0.0 the databases are automatically locked via flock(). There has been no support for locking earlier, so two concurrent web server processes modifying the same dBase file would have very likely ruined your database. This can happen even with dbase 7.0.0+ on systems which implement the locks at the process level with multithreaded SAPIs.

dBase files are simple sequential files of fixed length records. Records are appended to the end of the file and deleted records are kept until you call dbase_pack().

Only dbf file levels 3 (dBASE III+) - 5 (dBASE V) are supported. The types of dBase fields available are:

Available types of fields
Field | dBase Type | Format | Additional information
--- | --- | --- | ---
`M` | Memo | n/a | This type is not supported by PHP, such field will be ignored
`D` | Date | `YYYYMMDD` | The field length is limited to 8
`T` | DateTime | `YYYYMMDDhhmmss.uuu` | (FoxPro) No validity checks are done. Available as of dbase 7.0.0.
`N` | Number | A number | You must declare a length and a precision (the number of digits after the decimal point).
`F` | Float | A float number | Same as `N`.
`C` | String | A string | You must declare a length. When retrieving data, the string will be right-padded with spaces to fit the declared length. Overlong strings will be silently truncated when storing data.
`L` | Boolean | `T` or `Y` for `true`, `F` or `N` for `false`, `?` for uninitialized. | As of dbase 7.0.0, returned as a bool (`true` or `false`), or `null` for uninitialized fields. Formerly, returned as an int (`1` or `0`).

> 注意:

> As of dbase 7.0.0 nullable fields are supported for `DBASE_TYPE_FOXPRO` databases. If a field is nullable, passing `null` will set the respective flag, and on later retrieval the field value will be `null`.

> 注意:

> There is no support for indexes or memo fields.

# 安装/配置

## 目录

- 安装
- 资源类型

## 安装

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/dbase.

## 资源类型

As of dbase 7.0.0, the resource type `dbase` is defined, which is returned by dbase_open() and dbase_create().

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`DBASE_VERSION` (string)
  The extension version. (Available as of dbase 7.0.0)
`DBASE_RDONLY` (int)
  Open database for reading only. Used with dbase_open(). (Available as of dbase 7.0.0)
`DBASE_RDWR` (int)
  Open database for reading and writing. Used with dbase_open(). (Available as of dbase 7.0.0)
`DBASE_TYPE_DBASE` (int)
  Create dBASE style database. Used with dbase_create(). (Available as of dbase 7.0.0)
`DBASE_TYPE_FOXPRO` (int)
  Create FoxPro style database. Used with dbase_create(). (Available as of dbase 7.0.0)

# dBase 函数

## 示例

Many examples in this reference require a dBase database. We will use /tmp/test.dbf that will be created in the example of dbase_create().

# dbase_add_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_add_record — Adds a record to a database

### 说明

function dbase_add_record(resource `$database`, array `$data`): bool

Adds the given data to the database.

### 参数

`database`

  The database resource, returned by dbase_open() or dbase_create().

`data`

  An indexed array of data. The number of items must be equal to the number of fields in the database, otherwise dbase_add_record() will fail.

  > 注意:

  > If you're using dbase_get_record() return value for this parameter, remember to reset the key named `deleted`.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
PECL dbase 7.0.0 | `database` is now a resource instead of an int.

### 示例

示例 #1 Inserting a record in a dBase database

    <?php

    // open in read-write mode
    $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);
    }

    ?>

### 参见

- dbase_delete_record() - Deletes a record from a database
- dbase_replace_record() - Replaces a record in a database

# dbase_close

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_close — Closes a database

### 说明

function dbase_close(resource `$database`): bool

Closes the given database resource.

### 参数

`database`

  The database resource, returned by dbase_open() or dbase_create().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
PECL dbase 7.0.0 | `database` is now a resource instead of an int.

### 示例

示例 #1 Closing a dBase database file

    <?php

    // open in read-only mode
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
      // read some data ..

      dbase_close($db);
    }

    ?>

### 参见

- dbase_open() - Opens a database
- dbase_create() - Creates a database

# dbase_create

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_create — Creates a database

### 说明

function dbase_create(string `$path`, array `$fields`, int `$type` = DBASE_TYPE_DBASE): resource

dbase_create() creates a dBase database with the given definition. If the file already exists, it is not truncated. dbase_pack() can be called to force truncation.

> 注意: 此函数受 open_basedir 影响。

### 参数

`path`

  The path of the database. It can be a relative or absolute path to the file where dBase will store your data.

`fields`

  An array of arrays, each array describing the format of one field of the database. Each field consists of a name, a character indicating the field type, and optionally, a length, a precision and a nullable flag. The supported field types are listed in the introduction section.

  > 注意:

  > The fieldnames are limited in length and must not exceed 10 chars.

`type`

  The type of database to be created. Either `DBASE_TYPE_DBASE` or `DBASE_TYPE_FOXPRO`.

### 返回值

Returns a database resource if the database is successfully created, or `false` if an error occurred.

### 更新日志

版本 | 说明
--- | ---
PECL dbase 7.0.0 | The `type` parameter has been added.
PECL dbase 7.0.0 | The return value is now a resource instead of an int.

### 示例

示例 #1 Creating a dBase database file

    <?php

    // database "definition"
    $def = array(
      array("date",     "D"),
      array("name",     "C",  50),
      array("age",      "N",   3, 0),
      array("email",    "C", 128),
      array("ismember", "L")
    );

    // creation
    if (!dbase_create('/tmp/test.dbf', $def)) {
      echo "Error, can't create the database\n";
    }

    ?>

### 参见

- dbase_open() - Opens a database
- dbase_close() - Closes a database

# dbase_delete_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_delete_record — Deletes a record from a database

### 说明

function dbase_delete_record(resource `$database`, int `$number`): bool

Marks the given record to be deleted from the database.

> 注意:

> To actually remove the record from the database, you must also call dbase_pack().

### 参数

`database`

  The database resource, returned by dbase_open() or dbase_create().

`number`

  An integer which spans from 1 to the number of records in the database (as returned by dbase_numrecords()).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
PECL dbase 7.0.0 | `database` is now a resource instead of an int.

### 参见

- dbase_add_record() - Adds a record to a database
- dbase_replace_record() - Replaces a record in a database

# dbase_get_header_info

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_header_info — Gets the header info of a database

### 说明

function dbase_get_header_info(resource `$database`): array

Returns information on the column structure of the given database resource.

### 参数

`database`

  The database resource, returned by dbase_open() or dbase_create().

### 返回值

An indexed array with an entry for each column in the database. The array index starts at 0.

Each array element contains an associative array of column information, as described here:

name
  The name of the column
type
  The human-readable name for the dbase type of the column (i.e. date, boolean, etc.) The supported field types are listed in the introduction section.
length
  The number of bytes this column can hold
precision
  The number of digits of decimal precision for the column
format
  A suggested printf() format specifier for the column
offset
  The byte offset of the column from the start of the row

If the database header information cannot be read, `false` is returned.

### 更新日志

版本 | 说明
--- | ---
PECL dbase 7.0.0 | `database` is now a resource instead of an int.

### 示例

示例 #1 Showing header information for a dBase database file

    <?php
    // Path to dbase file
    $db_path = "/tmp/test.dbf";

    // Open dbase file
    $dbh = dbase_open($db_path, 0)
      or die("Error! Could not open dbase database file '$db_path'.");

    // Get column information
    $column_info = dbase_get_header_info($dbh);

    // Display information
    print_r($column_info);
    ?>

# dbase_get_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_record — Gets a record from a database as an indexed array

### 说明

function dbase_get_record(resource `$database`, int `$number`): array

Gets a record from a database as an indexed array.

### 参数

`database`

  The database resource, returned by dbase_open() or dbase_create().

`number`

  The index of the record between `1` and `dbase_numrecords($dbase_identifier)`.

### 返回值

An indexed array with the record. This array will also include an associative key named `deleted` which is set to 1 if the record has been marked for deletion (see dbase_delete_record()).

每个字段都会被转换为对应的 PHP 类型，除了以下场景：

- 日期会被转换成字符串。
- DateTime 会被转换成字符串。
- 范围之外的整数 `PHP_INT_MIN`..`PHP_INT_MAX` 将返回字符串。
- dbase 7.0.0 之前的版本， 布尔型 (`L`) 将被转换为 `1` 或 `0`。

On error, dbase_get_record() will return `false`.

### 更新日志

版本 | 说明
--- | ---
PECL dbase 7.0.0 | `database` is now a resource instead of an int.

### 参见

- dbase_get_record_with_names() - Gets a record from a database as an associative array

# dbase_get_record_with_names

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_record_with_names — Gets a record from a database as an associative array

### 说明

function dbase_get_record_with_names(resource `$database`, int `$number`): array

Gets a record from a dBase database as an associative array.

### 参数

`database`

  The database resource, returned by dbase_open() or dbase_create().

`number`

  The index of the record between `1` and `dbase_numrecords($dbase_identifier)`.

### 返回值

An associative array with the record. This will also include a key named `deleted` which is set to 1 if the record has been marked for deletion (see dbase_delete_record()). Therefore it is not possible to retrieve the value of a field named `deleted` with this function.

每个字段都会被转换为对应的 PHP 类型，除了以下场景：

- 日期会被转换成字符串。
- DateTime 会被转换成字符串。
- 范围之外的整数 `PHP_INT_MIN`..`PHP_INT_MAX` 将返回字符串。
- dbase 7.0.0 之前的版本， 布尔型 (`L`) 将被转换为 `1` 或 `0`。

On error, dbase_get_record_with_names() will return `false`.

### 更新日志

版本 | 说明
--- | ---
PECL dbase 7.0.0 | `database` is now a resource instead of an int.

### 示例

示例 #1 Listing all the registered members in the database

    <?php
    // open in read-only mode
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
      $record_numbers = dbase_numrecords($db);
      for ($i = 1; $i <= $record_numbers; $i++) {
          $row = dbase_get_record_with_names($db, $i);
          if ($row['ismember'] == 1) {
              echo "Member #$i: " . trim($row['name']) . "\n";
          }
      }
    }
    ?>

### 参见

- dbase_get_record() - Gets a record from a database as an indexed array

# dbase_numfields

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_numfields — Gets the number of fields of a database

### 说明

function dbase_numfields(resource `$database`): int

Gets the number of fields (columns) in the specified database.

> 注意:

> Field numbers are between 0 and `dbase_numfields($db)-1`, while record numbers are between 1 and `dbase_numrecords($db)`.

### 参数

`database`

  The database resource, returned by dbase_open() or dbase_create().

### 返回值

The number of fields in the database, or `false` if an error occurs.

### 更新日志

版本 | 说明
--- | ---
PECL dbase 7.0.0 | `database` is now a resource instead of an int.

### 示例

示例 #1 dbase_numfields() Example

    <?php

    $rec = dbase_get_record($db, $recno);
    $nf  = dbase_numfields($db);
    for ($i = 0; $i < $nf; $i++) {
      echo $rec[$i], "\n";
    }

    ?>

### 参见

- dbase_numrecords() - Gets the number of records in a database

# dbase_numrecords

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_numrecords — Gets the number of records in a database

### 说明

function dbase_numrecords(resource `$database`): int

Gets the number of records (rows) in the specified database.

> 注意:

> Records which are marked as deleted are counted as well.

> 注意:

> Record numbers are between 1 and `dbase_numrecords($db)`, while field numbers are between 0 and `dbase_numfields($db)-1`.

### 参数

`database`

  The database resource, returned by dbase_open() or dbase_create().

### 返回值

The number of records in the database, or `false` if an error occurs.

### 更新日志

版本 | 说明
--- | ---
PECL dbase 7.0.0 | `database` is now a resource instead of an int.

### 示例

示例 #1 Looping over all the records of the database

    <?php

    // open in read-only mode
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
      $record_numbers = dbase_numrecords($db);
      for ($i = 1; $i <= $record_numbers; $i++) {
          $record = dbase_get_record($db, $i);
          if (!$record['deleted']) {
              // do something with the $record
          } else {
              // do something with the deleted $record or ignore it
          }
      }
    }

    ?>

### 参见

- dbase_numfields() - Gets the number of fields of a database

# dbase_open

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_open — Opens a database

### 说明

function dbase_open(string `$path`, int `$mode`): resource|false

dbase_open() opens a dBase database with the given access mode.

> 注意: 此函数受 open_basedir 影响。

### 参数

`path`

  The path of the database. It can be a relative or absolute path to the file where dBase will store your data.

`mode`

  An integer which correspond to those for the open() system call (Typically 0 means read-only, 1 means write-only, and 2 means read and write).

  > 注意:

  > You can't open a dBase file in write-only mode as the function will fail to read the headers information and thus you can't use 1 as `mode`.

  As of dbase 7.0.0 you can use `DBASE_RDONLY` and `DBASE_RDWR`, respectively, to specify the `mode`.

### 返回值

Returns a database resource on success, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
PECL dbase 7.0.0 | The return value is now a resource instead of an int.

### 示例

示例 #1 Opening a dBase database file

    <?php

    // open in read-only mode
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
      // read some data ..

      dbase_close($db);
    }

    ?>

### 参见

- dbase_create() - Creates a database
- dbase_close() - Closes a database

# dbase_pack

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_pack — Packs a database

### 说明

function dbase_pack(resource `$database`): bool

Packs the specified database by permanently deleting all records marked for deletion using dbase_delete_record(). Note that the file will be truncated after successful packing (contrary to dBASE III's PACK command).

### 参数

`database`

  The database resource, returned by dbase_open() or dbase_create().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
PECL dbase 7.0.0 | `database` is now a resource instead of an int.

### 示例

示例 #1 Emptying a dBase database

    <?php

    // open in read-write mode
    $db = dbase_open('/tmp/test.dbf', 2);

    if ($db) {
      $record_numbers = dbase_numrecords($db);
      for ($i = 1; $i <= $record_numbers; $i++) {
          dbase_delete_record($db, $i);
      }
      // expunge the database
      dbase_pack($db);
    }

    ?>

### 参见

- dbase_delete_record() - Deletes a record from a database

# dbase_replace_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_replace_record — Replaces a record in a database

### 说明

function dbase_replace_record(resource `$database`, array `$data`, int `$number`): bool

Replaces the given record in the database with the given data.

### 参数

`database`

  The database resource, returned by dbase_open() or dbase_create().

`data`

  An indexed array of data. The number of items must be equal to the number of fields in the database, otherwise dbase_replace_record() will fail.

  > 注意:

  > If you're using dbase_get_record() return value for this parameter, remember to reset the key named `deleted`.

`number`

  An integer which spans from 1 to the number of records in the database (as returned by dbase_numrecords()).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
PECL dbase 7.0.0 | `database` is now a resource instead of an int.

### 示例

示例 #1 Updating a record in the database

    <?php

    // open in read-write mode
    $db = dbase_open('/tmp/test.dbf', 2);

    if ($db) {
      // gets the old row
      $row = dbase_get_record_with_names($db, 1);

      // remove the 'deleted' entry
      unset($row['deleted']);

      // Update the date field with the current timestamp
      $row['date'] = date('Ymd');

      // convert the row to an indexed array
      $row = array_values($row);

      // Replace the record
      dbase_replace_record($db, $row, 1);
      dbase_close($db);
    }

    ?>

### 注释

> 注意:

> Boolean fields result in an int element value (`0` or `1`) when retrieved via dbase_get_record() or dbase_get_record_with_names(). If they are written back, this results in the value becoming `0`, so care has to be taken to properly adjust the values.

### 参见

- dbase_add_record() - Adds a record to a database
- dbase_delete_record() - Deletes a record from a database

## 目录

- dbase_add_record — Adds a record to a database
- dbase_close — Closes a database
- dbase_create — Creates a database
- dbase_delete_record — Deletes a record from a database
- dbase_get_header_info — Gets the header info of a database
- dbase_get_record — Gets a record from a database as an indexed array
- dbase_get_record_with_names — Gets a record from a database as an associative array
- dbase_numfields — Gets the number of fields of a database
- dbase_numrecords — Gets the number of records in a database
- dbase_open — Opens a database
- dbase_pack — Packs a database
- dbase_replace_record — Replaces a record in a database

- 安装/配置
  - 安装
  - 资源类型
- 预定义常量
- dBase 函数
  - dbase_add_record — Adds a record to a database
  - dbase_close — Closes a database
  - dbase_create — Creates a database
  - dbase_delete_record — Deletes a record from a database
  - dbase_get_header_info — Gets the header info of a database
  - dbase_get_record — Gets a record from a database as an indexed array
  - dbase_get_record_with_names — Gets a record from a database as an associative array
  - dbase_numfields — Gets the number of fields of a database
  - dbase_numrecords — Gets the number of records in a database
  - dbase_open — Opens a database
  - dbase_pack — Packs a database
  - dbase_replace_record — Replaces a record in a database

# Firebird/InterBase

# 简介

警告

此扩展被认为已无人维护及已消亡。然而，此扩展的源代码还可在 PECL GIT 找到： » 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/.

> 注意: 此扩展已被移至 » PECL 资源库；不再与 PHP 捆绑，从 PHP 7.4.0 This extension supports InterBase versions 6 and up and Firebird version 2.0 and up.

# 安装/配置

## 目录

- 安装
- 运行时配置

## 安装

此扩展已被移至 » PECL 资源库；不再与 PHP 捆绑，从 PHP 7.4.0

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » 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.

> 注意: Note to Win32/Win64 Users
> 为了使此扩展生效， DLL 文件必须能在 Windows 系统的 PATH 指示的路径下找到。如何操作的信息，请参见题为“如何在 Windows 中将 PHP 目录加到 PATH 中”的FAQ。虽然将 DLL 文件从 PHP 文件夹复制到 Windows 系统目录也行，但不建议这样做。 此扩展需要下列文件在 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.

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

InterBase configuration options
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
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` |

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`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.

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

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 函数

# fbird_add_user

(PHP 5, PHP 7 < 7.4.0)

fbird_add_user — 别名 ibase_add_user()

### 说明

此函数是该函数的别名： ibase_add_user().

### 参见

- fbird_modify_user() - 别名 ibase_modify_user
- fbird_delete_user() - 别名 ibase_delete_user

# fbird_affected_rows

(PHP 5, PHP 7 < 7.4.0)

fbird_affected_rows — 别名 ibase_affected_rows()

### 说明

此函数是该函数的别名： ibase_affected_rows().

### 参见

- fbird_query() - 别名 ibase_query
- fbird_execute() - 别名 ibase_execute

# fbird_backup

(PHP 5, PHP 7 < 7.4.0)

fbird_backup — 别名 ibase_backup()

### 说明

此函数是该函数的别名： ibase_backup().

# fbird_blob_add

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_add — 别名 ibase_blob_add()

### 说明

此函数是该函数的别名： ibase_blob_add().

### 参见

- fbird_blob_cancel() - Cancel creating blob
- fbird_blob_close() - 别名 ibase_blob_close
- fbird_blob_create() - 别名 ibase_blob_create
- fbird_blob_import() - 别名 ibase_blob_import

# fbird_blob_cancel

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_cancel — Cancel creating blob

### 说明

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().

### 参数

`blob_handle`
  A BLOB handle opened with fbird_blob_create().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- fbird_blob_close() - 别名 ibase_blob_close
- fbird_blob_create() - 别名 ibase_blob_create
- fbird_blob_import() - 别名 ibase_blob_import

# fbird_blob_close

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_close — 别名 ibase_blob_close()

### 说明

此函数是该函数的别名： ibase_blob_close().

### 参见

- fbird_blob_create() - 别名 ibase_blob_create
- fbird_blob_cancel() - Cancel creating blob
- fbird_blob_open() - 别名 ibase_blob_open
- fbird_blob_import() - 别名 ibase_blob_import

# fbird_blob_create

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_create — 别名 ibase_blob_create()

### 说明

此函数是该函数的别名： ibase_blob_create().

### 参见

- fbird_blob_add() - 别名 ibase_blob_add
- fbird_blob_cancel() - Cancel creating blob
- fbird_blob_close() - 别名 ibase_blob_close
- fbird_blob_import() - 别名 ibase_blob_import

# fbird_blob_echo

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_echo — 别名 ibase_blob_echo()

### 说明

此函数是该函数的别名： ibase_blob_echo().

### 参见

- fbird_blob_open() - 别名 ibase_blob_open
- fbird_blob_close() - 别名 ibase_blob_close
- fbird_blob_get() - 别名 ibase_blob_get

# fbird_blob_get

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_get — 别名 ibase_blob_get()

### 说明

此函数是该函数的别名： ibase_blob_get().

### 参见

- fbird_blob_open() - 别名 ibase_blob_open
- fbird_blob_close() - 别名 ibase_blob_close
- fbird_blob_echo() - 别名 ibase_blob_echo

# fbird_blob_import

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_import — 别名 ibase_blob_import()

### 说明

此函数是该函数的别名： ibase_blob_import().

### 参见

- fbird_blob_add() - 别名 ibase_blob_add
- fbird_blob_cancel() - Cancel creating blob
- fbird_blob_close() - 别名 ibase_blob_close
- fbird_blob_create() - 别名 ibase_blob_create

# fbird_blob_info

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_info — 别名 ibase_blob_info()

### 说明

此函数是该函数的别名： ibase_blob_info().

# fbird_blob_open

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_open — 别名 ibase_blob_open()

### 说明

此函数是该函数的别名： ibase_blob_open().

### 参见

- fbird_blob_close() - 别名 ibase_blob_close
- fbird_blob_echo() - 别名 ibase_blob_echo
- fbird_blob_get() - 别名 ibase_blob_get

# fbird_close

(PHP 5, PHP 7 < 7.4.0)

fbird_close — 别名 ibase_close()

### 说明

此函数是该函数的别名： ibase_close().

### 参见

- fbird_connect() - 别名 ibase_connect
- fbird_pconnect() - 别名 ibase_pconnect

# fbird_commit

(PHP 5, PHP 7 < 7.4.0)

fbird_commit — 别名 ibase_commit()

### 说明

此函数是该函数的别名： ibase_commit().

# fbird_commit_ret

(PHP 5, PHP 7 < 7.4.0)

fbird_commit_ret — 别名 ibase_commit_ret()

### 说明

此函数是该函数的别名： ibase_commit_ret().

# fbird_connect

(PHP 5, PHP 7 < 7.4.0)

fbird_connect — 别名 ibase_connect()

### 说明

此函数是该函数的别名： ibase_connect().

### 参见

- fbird_pconnect() - 别名 ibase_pconnect
- fbird_close() - 别名 ibase_close

# fbird_db_info

(PHP 5, PHP 7 < 7.4.0)

fbird_db_info — 别名 ibase_db_info()

### 说明

此函数是该函数的别名： ibase_db_info().

# fbird_delete_user

(PHP 5, PHP 7 < 7.4.0)

fbird_delete_user — 别名 ibase_delete_user()

### 说明

此函数是该函数的别名： ibase_delete_user().

### 参见

- fbird_add_user() - 别名 ibase_add_user
- fbird_modify_user() - 别名 ibase_modify_user

# fbird_drop_db

(PHP 5, PHP 7 < 7.4.0)

fbird_drop_db — 别名 ibase_drop_db()

### 说明

此函数是该函数的别名： ibase_drop_db().

### 参见

- fbird_connect() - 别名 ibase_connect
- fbird_pconnect() - 别名 ibase_pconnect

# fbird_errcode

(PHP 5, PHP 7 < 7.4.0)

fbird_errcode — 别名 ibase_errcode()

### 说明

此函数是该函数的别名： ibase_errcode().

### 参见

- fbird_errmsg() - 别名 ibase_errmsg

# fbird_errmsg

(PHP 5, PHP 7 < 7.4.0)

fbird_errmsg — 别名 ibase_errmsg()

### 说明

此函数是该函数的别名： ibase_errmsg().

### 参见

- fbird_errcode() - 别名 ibase_errcode

# fbird_execute

(PHP 5, PHP 7 < 7.4.0)

fbird_execute — 别名 ibase_execute()

### 说明

此函数是该函数的别名： ibase_execute().

### 参见

- fbird_query() - 别名 ibase_query

# fbird_fetch_assoc

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_assoc — 别名 ibase_fetch_assoc()

### 说明

此函数是该函数的别名： ibase_fetch_assoc().

### 参见

- fbird_fetch_row() - 别名 ibase_fetch_row
- fbird_fetch_object() - 别名 ibase_fetch_object

# fbird_fetch_object

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_object — 别名 ibase_fetch_object()

### 说明

此函数是该函数的别名： ibase_fetch_object().

### 参见

- fbird_fetch_row() - 别名 ibase_fetch_row
- fbird_fetch_assoc() - 别名 ibase_fetch_assoc

# fbird_fetch_row

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_row — 别名 ibase_fetch_row()

### 说明

此函数是该函数的别名： ibase_fetch_row().

### 参见

- fbird_fetch_assoc() - 别名 ibase_fetch_assoc
- fbird_fetch_object() - 别名 ibase_fetch_object

# fbird_field_info

(PHP 5, PHP 7 < 7.4.0)

fbird_field_info — 别名 ibase_field_info()

### 说明

此函数是该函数的别名： ibase_field_info().

### 参见

- fbird_num_fields() - 别名 ibase_num_fields

# fbird_free_event_handler

(PHP 5, PHP 7 < 7.4.0)

fbird_free_event_handler — 别名 ibase_free_event_handler()

### 说明

此函数是该函数的别名： ibase_free_event_handler().

### 参见

- fbird_set_event_handler() - 别名 ibase_set_event_handler

# fbird_free_query

(PHP 5, PHP 7 < 7.4.0)

fbird_free_query — 别名 ibase_free_query()

### 说明

此函数是该函数的别名： ibase_free_query().

# fbird_free_result

(PHP 5, PHP 7 < 7.4.0)

fbird_free_result — 别名 ibase_free_result()

### 说明

此函数是该函数的别名： ibase_free_result().

# fbird_gen_id

(PHP 5, PHP 7 < 7.4.0)

fbird_gen_id — 别名 ibase_gen_id()

### 说明

此函数是该函数的别名： ibase_gen_id().

# fbird_maintain_db

(PHP 5, PHP 7 < 7.4.0)

fbird_maintain_db — 别名 ibase_maintain_db()

### 说明

此函数是该函数的别名： ibase_maintain_db().

# fbird_modify_user

(PHP 5, PHP 7 < 7.4.0)

fbird_modify_user — 别名 ibase_modify_user()

### 说明

此函数是该函数的别名： ibase_modify_user().

### 参见

- fbird_add_user() - 别名 ibase_add_user
- fbird_delete_user() - 别名 ibase_delete_user

# fbird_name_result

(PHP 5, PHP 7 < 7.4.0)

fbird_name_result — 别名 ibase_name_result()

### 说明

此函数是该函数的别名： ibase_name_result().

### 参见

- fbird_prepare() - 别名 ibase_prepare
- fbird_execute() - 别名 ibase_execute

# fbird_num_fields

(PHP 5, PHP 7 < 7.4.0)

fbird_num_fields — 别名 ibase_num_fields()

### 说明

此函数是该函数的别名： ibase_num_fields().

### 参见

- fbird_field_info() - 别名 ibase_field_info

# fbird_num_params

(PHP 5, PHP 7 < 7.4.0)

fbird_num_params — 别名 ibase_num_params()

### 说明

此函数是该函数的别名： ibase_num_params().

### 参见

- fbird_prepare() - 别名 ibase_prepare
- fbird_param_info() - 别名 ibase_param_info

# fbird_param_info

(PHP 5, PHP 7 < 7.4.0)

fbird_param_info — 别名 ibase_param_info()

### 说明

此函数是该函数的别名： ibase_param_info().

### 参见

- fbird_field_info() - 别名 ibase_field_info
- fbird_num_params() - 别名 ibase_num_params

# fbird_pconnect

(PHP 5, PHP 7 < 7.4.0)

fbird_pconnect — 别名 ibase_pconnect()

### 说明

此函数是该函数的别名： ibase_pconnect().

### 参见

- fbird_close() - 别名 ibase_close
- fbird_connect() - 别名 ibase_connect

# fbird_prepare

(PHP 5, PHP 7 < 7.4.0)

fbird_prepare — 别名 ibase_prepare()

### 说明

此函数是该函数的别名： ibase_prepare().

# fbird_query

(PHP 5, PHP 7 < 7.4.0)

fbird_query — 别名 ibase_query()

### 说明

此函数是该函数的别名： ibase_query().

### 参见

- fbird_errmsg() - 别名 ibase_errmsg
- fbird_fetch_row() - 别名 ibase_fetch_row
- fbird_fetch_object() - 别名 ibase_fetch_object
- fbird_free_result() - 别名 ibase_free_result

# fbird_restore

(PHP 5, PHP 7 < 7.4.0)

fbird_restore — 别名 ibase_restore()

### 说明

此函数是该函数的别名： ibase_restore().

# fbird_rollback

(PHP 5, PHP 7 < 7.4.0)

fbird_rollback — 别名 ibase_rollback()

### 说明

此函数是该函数的别名： ibase_rollback().

# fbird_rollback_ret

(PHP 5, PHP 7 < 7.4.0)

fbird_rollback_ret — 别名 ibase_rollback_ret()

### 说明

此函数是该函数的别名： ibase_rollback_ret().

# fbird_server_info

(PHP 5, PHP 7 < 7.4.0)

fbird_server_info — 别名 ibase_server_info()

### 说明

此函数是该函数的别名： ibase_server_info().

# fbird_service_attach

(PHP 5, PHP 7 < 7.4.0)

fbird_service_attach — 别名 ibase_service_attach()

### 说明

此函数是该函数的别名： ibase_service_attach().

# fbird_service_detach

(PHP 5, PHP 7 < 7.4.0)

fbird_service_detach — 别名 ibase_service_detach()

### 说明

此函数是该函数的别名： ibase_service_detach().

# fbird_set_event_handler

(PHP 5, PHP 7 < 7.4.0)

fbird_set_event_handler — 别名 ibase_set_event_handler()

### 说明

此函数是该函数的别名： ibase_set_event_handler().

### 参见

- fbird_free_event_handler() - 别名 ibase_free_event_handler
- fbird_wait_event() - 别名 ibase_wait_event

# fbird_trans

(PHP 5, PHP 7 < 7.4.0)

fbird_trans — 别名 ibase_trans()

### 说明

此函数是该函数的别名： ibase_trans().

# fbird_wait_event

(PHP 5, PHP 7 < 7.4.0)

fbird_wait_event — 别名 ibase_wait_event()

### 说明

此函数是该函数的别名： ibase_wait_event().

### 参见

- fbird_set_event_handler() - 别名 ibase_set_event_handler
- fbird_free_event_handler() - 别名 ibase_free_event_handler

# ibase_add_user

(PHP 5, PHP 7 < 7.4.0)

ibase_add_user — Add a user to a security database

### 说明

function ibase_add_user(
resource `$service_handle`,
string `$user_name`,
string `$password`,
string `$first_name` = ?,
string `$middle_name` = ?,
string `$last_name` = ?
): bool

### 参数

`service_handle`
  The handle on the database server service.
`user_name`
  The login name of the new database user.
`password`
  The password of the new user.
`first_name`
  The first name of the new database user.
`middle_name`
  The middle name of the new database user.
`last_name`
  The last name of the new database user.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ibase_modify_user() - Modify a user to a security database
- ibase_delete_user() - Delete a user from a security database

# ibase_affected_rows

(PHP 5, PHP 7 < 7.4.0)

ibase_affected_rows — Return the number of rows that were affected by the previous query

### 说明

function ibase_affected_rows(resource `$link_identifier` = ?): int

This function returns the number of rows that were affected by the previous query (INSERT, UPDATE or DELETE) that was executed from within the specified transaction context.

### 参数

`link_identifier`
  A transaction context. If `link_identifier` is a connection resource, its default transaction is used.

### 返回值

Returns the number of rows as an integer.

### 参见

- ibase_query() - Execute a query on an InterBase database
- ibase_execute() - Execute a previously prepared query

# ibase_backup

(PHP 5, PHP 7 < 7.4.0)

ibase_backup — Initiates a backup task in the service manager and returns immediately

### 说明

function ibase_backup(
resource `$service_handle`,
string `$source_db`,
string `$dest_file`,
int `$options` = 0,
bool `$verbose` = `false`
): mixed

This function passes the arguments to the (remote) database server. There it starts a new backup process. Therefore you won't get any responses.

### 参数

`service_handle`
  A previously opened connection to the database server.
`source_db`
  The absolute file path to the database on the database server. You can also use a database alias.
`dest_file`
  The path to the backup file on the database server.
`options`

  Additional options to pass to the database server for backup. The `options` parameter can be a combination of the following constants: `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`. Read the section about 预定义常量 for further information.

`verbose`
  Since the backup process is done on the database server, you don't have any chance to get its output. This argument is useless.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

Since the backup process is done on the (remote) server, this function just passes the arguments to it. While the arguments are legal, you won't get `false`.

### 示例

示例 #1 ibase_backup() example

    <?php

    // Attach to database server by ip address and port
    $service = ibase_service_attach ('10.1.11.200/3050', 'sysdba', 'masterkey');

    // Start the backup process on database server
    // Backup employee database using full path to /srv/backup/employees.fbk
    // Don't use any special arguments
    ibase_backup($service, '/srv/firebird/employees.fdb', '/srv/backup/employees.fbk');

    // Free the attached connection
    ibase_service_detach ($service);
    ?>

示例 #2 ibase_backup() example with arguments

    <?php

    // Attach to database server by name and default port
    $service = ibase_service_attach ('fb-server.contoso.local', 'sysdba', 'masterkey');

    // Start the backup process on database server
    // Backup employee database using alias to /srv/backup/employees.fbk.
    // Backup only the metadata. Don't create a transportable backup.
    ibase_backup($service, 'employees.fdb', '/srv/backup/employees.fbk', IBASE_BKP_METADATA_ONLY | IBASE_BKP_NON_TRANSPORTABLE);

    // Free the attached connection
    ibase_service_detach ($service);
    ?>

### 参见

- ibase_restore() - Initiates a restore task in the service manager and returns immediately

# ibase_blob_add

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_add — Add data into a newly created blob

### 说明

function ibase_blob_add(resource `$blob_handle`, string `$data`): void

ibase_blob_add() adds data into a blob created with ibase_blob_create().

### 参数

`blob_handle`
  A blob handle opened with ibase_blob_create().
`data`
  The data to be added.

### 返回值

没有返回值。

### 参见

- ibase_blob_cancel() - Cancel creating blob
- ibase_blob_close() - Close blob
- ibase_blob_create() - Create a new blob for adding data
- ibase_blob_import() - Create blob, copy file in it, and close it

# ibase_blob_cancel

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_cancel — Cancel creating blob

### 说明

function ibase_blob_cancel(resource `$blob_handle`): bool

This function will discard a BLOB if it has not yet been closed by ibase_blob_close().

### 参数

`blob_handle`
  A BLOB handle opened with ibase_blob_create().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ibase_blob_close() - Close blob
- ibase_blob_create() - Create a new blob for adding data
- ibase_blob_import() - Create blob, copy file in it, and close it

# ibase_blob_close

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_close — Close blob

### 说明

function ibase_blob_close(resource `$blob_handle`): mixed

This function closes a BLOB that has either been opened for reading by ibase_blob_open() or has been opened for writing by ibase_blob_create().

### 参数

`blob_handle`
  A BLOB handle opened with ibase_blob_create() or ibase_blob_open().

### 返回值

If the BLOB was being read, this function returns `true` on success, if the BLOB was being written to, this function returns a string containing the BLOB id that has been assigned to it by the database. On failure, this function returns `false`.

### 参见

- ibase_blob_cancel() - Cancel creating blob
- ibase_blob_open() - Open blob for retrieving data parts

# ibase_blob_create

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_create — Create a new blob for adding data

### 说明

function ibase_blob_create(resource `$link_identifier` = `null`): resource|false

ibase_blob_create() creates a new BLOB for filling with data.

### 参数

`link_identifier`
  An InterBase link identifier. If omitted, the last opened link is assumed.

### 返回值

Returns a BLOB handle for later use with ibase_blob_add() 或者在失败时返回 `false`.

### 参见

- ibase_blob_add() - Add data into a newly created blob
- ibase_blob_cancel() - Cancel creating blob
- ibase_blob_close() - Close blob
- ibase_blob_import() - Create blob, copy file in it, and close it

# ibase_blob_echo

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_echo — Output blob contents to browser

### 说明

function ibase_blob_echo(string `$blob_id`): bool
function ibase_blob_echo(resource `$link_identifier`, string `$blob_id`): bool

This function opens a BLOB for reading and sends its contents directly to standard output (the browser, in most cases).

### 参数

`link_identifier`
  An InterBase link identifier. If omitted, the last opened link is assumed.
`blob_id`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ibase_blob_open() - Open blob for retrieving data parts
- ibase_blob_close() - Close blob
- ibase_blob_get() - Get len bytes data from open blob

# ibase_blob_get

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_get — Get len bytes data from open blob

### 说明

function ibase_blob_get(resource `$blob_handle`, int `$len`): string

This function returns at most `len` bytes from a BLOB that has been opened for reading by ibase_blob_open().

> 注意: It is not possible to read from a BLOB that has been opened for writing by ibase_blob_create().

### 参数

`blob_handle`
  A BLOB handle opened with ibase_blob_open().
`len`
  Size of returned data.

### 返回值

Returns at most `len` bytes from the BLOB, or `false` on failure.

### 示例

示例 #1 ibase_blob_get() example

    <?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]);
    ?>

Whilst this example doesn't do much more than a 'ibase_blob_echo($data->BLOB_VALUE)' would do, it does show you how to get information into a $variable to manipulate as you please.

### 参见

- ibase_blob_open() - Open blob for retrieving data parts
- ibase_blob_close() - Close blob
- ibase_blob_echo() - Output blob contents to browser

# ibase_blob_import

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_import — Create blob, copy file in it, and close it

### 说明

function ibase_blob_import(resource `$link_identifier`, resource `$file_handle`): string
function ibase_blob_import(resource `$file_handle`): string

This function creates a BLOB, reads an entire file into it, closes it and returns the assigned BLOB id.

### 参数

`link_identifier`
  An InterBase link identifier. If omitted, the last opened link is assumed.
`file_handle`
  The file handle is a handle returned by fopen().

### 返回值

Returns the BLOB id on success, or `false` on error.

### 示例

示例 #1 ibase_blob_import() example

    <?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 failed
        } else {
            $query = "INSERT INTO foo (name, data) VALUES ('$filename', ?)";
            $prepared = ibase_prepare($dbh, $query);
            if (!ibase_execute($prepared, $blob)) {
                // record insertion failed
            }
        }
    } else {
        // unable to open the data file
    }
    ?>

### 参见

- ibase_blob_add() - Add data into a newly created blob
- ibase_blob_cancel() - Cancel creating blob
- ibase_blob_close() - Close blob
- ibase_blob_create() - Create a new blob for adding data

# ibase_blob_info

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_info — Return blob length and other useful info

### 说明

function ibase_blob_info(resource `$link_identifier`, string `$blob_id`): array
function ibase_blob_info(string `$blob_id`): array

Returns the BLOB length and other useful information.

### 参数

`link_identifier`
  An InterBase link identifier. If omitted, the last opened link is assumed.
`blob_id`
  A BLOB id.

### 返回值

Returns an array containing information about a BLOB. The information returned consists of the length of the BLOB, the number of segments it contains, the size of the largest segment, and whether it is a stream BLOB or a segmented BLOB.

# ibase_blob_open

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_open — Open blob for retrieving data parts

### 说明

function ibase_blob_open(resource `$link_identifier`, string `$blob_id`): resource|false
function ibase_blob_open(string `$blob_id`): resource|false

Opens an existing BLOB for reading.

### 参数

`link_identifier`
  An InterBase link identifier. If omitted, the last opened link is assumed.
`blob_id`
  A BLOB id.

### 返回值

Returns a BLOB handle for later use with ibase_blob_get() 或者在失败时返回 `false`.

### 参见

- ibase_blob_close() - Close blob
- ibase_blob_echo() - Output blob contents to browser
- ibase_blob_get() - Get len bytes data from open blob

# ibase_close

(PHP 5, PHP 7 < 7.4.0)

ibase_close — Close a connection to an InterBase database

### 说明

function ibase_close(resource `$connection_id` = `null`): bool

Closes the link to an InterBase database that's associated with a connection id returned from ibase_connect(). Default transaction on link is committed, other transactions are rolled back.

### 参数

`connection_id`
  An InterBase link identifier returned from ibase_connect(). If omitted, the last opened link is assumed.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ibase_connect() - Open a connection to a database
- ibase_pconnect() - Open a persistent connection to an InterBase database

# ibase_commit

(PHP 5, PHP 7 < 7.4.0)

ibase_commit — Commit a transaction

### 说明

function ibase_commit(resource `$link_or_trans_identifier` = `null`): bool

Commits a transaction.

### 参数

`link_or_trans_identifier`
  If called without an argument, this function commits the default transaction of the default link. If the argument is a connection identifier, the default transaction of the corresponding connection will be committed. If the argument is a transaction identifier, the corresponding transaction will be committed.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# ibase_commit_ret

(PHP 5, PHP 7 < 7.4.0)

ibase_commit_ret — Commit a transaction without closing it

### 说明

function ibase_commit_ret(resource `$link_or_trans_identifier` = `null`): bool

Commits a transaction without closing it.

### 参数

`link_or_trans_identifier`
  If called without an argument, this function commits the default transaction of the default link. If the argument is a connection identifier, the default transaction of the corresponding connection will be committed. If the argument is a transaction identifier, the corresponding transaction will be committed. The transaction context will be retained, so statements executed from within this transaction will not be invalidated.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# ibase_connect

(PHP 5, PHP 7 < 7.4.0)

ibase_connect — Open a connection to a database

### 说明

function ibase_connect(
string `$database` = ?,
string `$username` = ?,
string `$password` = ?,
string `$charset` = ?,
int `$buffers` = ?,
int `$dialect` = ?,
string `$role` = ?,
int `$sync` = ?
): resource

Establishes a connection to an Firebird/InterBase server.

In case a second call is made to ibase_connect() with the same arguments, no new link will be established, but instead, the link identifier of the already opened link will be returned. The link to the server will be closed as soon as the execution of the script ends, unless it's closed earlier by explicitly calling ibase_close().

### 参数

`database`
  The `database` argument has to be a valid path to database file on the server it resides on. If the server is not local, it must be prefixed with either 'hostname:' (TCP/IP), 'hostname/port:' (TCP/IP with interbase server on custom TCP port), '//hostname/' (NetBEUI), depending on the connection protocol used.
`username`
  The user name. Can be set with the `ibase.default_user` php.ini directive.
`password`
  The password for `username`. Can be set with the `ibase.default_password` php.ini directive.
`charset`
  `charset` is the default character set for a database.
`buffers`
  `buffers` is the number of database buffers to allocate for the server-side cache. If 0 or omitted, server chooses its own default.
`dialect`
  `dialect` selects the default SQL dialect for any statement executed within a connection, and it defaults to the highest one supported by client libraries.
`role`
  Functional only with InterBase 5 and up.
`sync`

### 返回值

Returns an Firebird/InterBase link identifier on success, or `false` on error.

### 错误／异常

If you get some error like "arithmetic exception, numeric overflow, or string truncation. Cannot transliterate character between character sets" (this occurs when you try use some character with accents) when using this and after ibase_query() you must set the character set (i.e. ISO8859_1 or your current character set).

### 示例

示例 #1 ibase_connect() example

    <?php
    $host = 'localhost:/path/to/your.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);
    ?>

### 参见

- ibase_pconnect() - Open a persistent connection to an InterBase database
- ibase_close() - Close a connection to an InterBase database

# ibase_db_info

(PHP 5, PHP 7 < 7.4.0)

ibase_db_info — Request statistics about a database

### 说明

function ibase_db_info(
resource `$service_handle`,
string `$db`,
int `$action`,
int `$argument` = 0
): string
警告

本函数还未编写文档，仅有参数列表。

# ibase_delete_user

(PHP 5, PHP 7 < 7.4.0)

ibase_delete_user — Delete a user from a security database

### 说明

function ibase_delete_user(resource `$service_handle`, string `$user_name`): bool

### 参数

`service_handle`
  The handle on the database server service.
`user_name`
  The login name of the user you want to delete from the database.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ibase_add_user() - Add a user to a security database
- ibase_modify_user() - Modify a user to a security database

# ibase_drop_db

(PHP 5, PHP 7 < 7.4.0)

ibase_drop_db — Drops a database

### 说明

function ibase_drop_db(resource `$connection` = `null`): bool

This functions drops a database that was opened by either ibase_connect() or ibase_pconnect(). The database is closed and deleted from the server.

### 参数

`connection`
  An InterBase link identifier. If omitted, the last opened link is assumed.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ibase_connect() - Open a connection to a database
- ibase_pconnect() - Open a persistent connection to an InterBase database

# ibase_errcode

(PHP 5, PHP 7 < 7.4.0)

ibase_errcode — Return an error code

### 说明

function ibase_errcode(): int

Returns the error code that resulted from the most recent InterBase function call.

### 参数

此函数没有参数。

### 返回值

Returns the error code as an integer, or `false` if no error occurred.

### 参见

- ibase_errmsg() - Return error messages

# ibase_errmsg

(PHP 5, PHP 7 < 7.4.0)

ibase_errmsg — Return error messages

### 说明

function ibase_errmsg(): string

Returns the error message that resulted from the most recent InterBase function call.

### 参数

此函数没有参数。

### 返回值

Returns the error message as a string, or `false` if no error occurred.

### 参见

- ibase_errcode() - Return an error code

# ibase_execute

(PHP 5, PHP 7 < 7.4.0)

ibase_execute — Execute a previously prepared query

### 说明

function ibase_execute(resource `$query`, mixed `...$values`): resource

Execute a query prepared by ibase_prepare().

This is a lot more effective than using ibase_query() if you are repeating a same kind of query several times with only some parameters changing.

### 参数

`query`
  An InterBase query prepared by ibase_prepare().
`values`

### 返回值

If the query raises an error, returns `false`. If it is successful and there is a (possibly empty) result set (such as with a SELECT query), returns a result identifier. If the query was successful and there were no results, returns `true`.

> 注意: This function returns the number of rows affected by the query (if > 0 and applicable to the statement type). A query that succeeded, but did not affect any rows (e.g. an UPDATE of a non-existent record) will return `true`.

### 示例

示例 #1 ibase_execute() example

    <?php

    $dbh = ibase_connect($host, $username, $password);

    $updates = array(
        1 => 'Eric',
        5 => 'Filip',
        7 => 'Larry'
    );

    $query = ibase_prepare($dbh, "UPDATE FOO SET BAR = ? WHERE BAZ = ?");

    foreach ($updates as $baz => $bar) {
        ibase_execute($query, $bar, $baz);
    }

    ?>

### 参见

- ibase_query() - Execute a query on an InterBase database

# ibase_fetch_assoc

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_assoc — Fetch a result row from a query as an associative array

### 说明

function ibase_fetch_assoc(resource `$result`, int `$fetch_flag` = 0): array

Fetch a result row from a query as an associative array.

ibase_fetch_assoc() fetches one row of data from the `result`. If two or more columns of the result have the same field names, the last column will take precedence. To access the other column(s) of the same name, you either need to access the result with numeric indices by using ibase_fetch_row() or use alias names in your query.

### 参数

`result`
  The result handle.
`fetch_flag`
  `fetch_flag` is a combination of the constants `IBASE_TEXT` and `IBASE_UNIXTIME` ORed together. Passing `IBASE_TEXT` will cause this function to return BLOB contents instead of BLOB ids. Passing `IBASE_UNIXTIME` will cause this function to return date/time values as Unix timestamps instead of as formatted strings.

### 返回值

Returns an associative array that corresponds to the fetched row. Subsequent calls will return the next row in the result set, or `false` if there are no more rows.

### 参见

- ibase_fetch_row() - Fetch a row from an InterBase database
- ibase_fetch_object() - Get an object from a InterBase database

# ibase_fetch_object

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_object — Get an object from a InterBase database

### 说明

function ibase_fetch_object(resource `$result_id`, int `$fetch_flag` = 0): object

Fetches a row as a pseudo-object from a given result identifier.

Subsequent calls to ibase_fetch_object() return the next row in the result set.

### 参数

`result_id`
  An InterBase result identifier obtained either by ibase_query() or ibase_execute().
`fetch_flag`
  `fetch_flag` is a combination of the constants `IBASE_TEXT` and `IBASE_UNIXTIME` ORed together. Passing `IBASE_TEXT` will cause this function to return BLOB contents instead of BLOB ids. Passing `IBASE_UNIXTIME` will cause this function to return date/time values as Unix timestamps instead of as formatted strings.

### 返回值

Returns an object with the next row information, or `false` if there are no more rows.

### 示例

示例 #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);
    ?>

### 参见

- ibase_fetch_row() - Fetch a row from an InterBase database
- ibase_fetch_assoc() - Fetch a result row from a query as an associative array

# ibase_fetch_row

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_row — Fetch a row from an InterBase database

### 说明

function ibase_fetch_row(resource `$result_identifier`, int `$fetch_flag` = 0): array

ibase_fetch_row() fetches one row of data from the given result set.

Subsequent calls to ibase_fetch_row() return the next row in the result set, or `false` if there are no more rows.

### 参数

`result_identifier`
  An InterBase result identifier.
`fetch_flag`
  `fetch_flag` is a combination of the constants `IBASE_TEXT` and `IBASE_UNIXTIME` ORed together. Passing `IBASE_TEXT` will cause this function to return BLOB contents instead of BLOB ids. Passing `IBASE_UNIXTIME` will cause this function to return date/time values as Unix timestamps instead of as formatted strings.

### 返回值

Returns an array that corresponds to the fetched row, or `false` if there are no more rows. Each result column is stored in an array offset, starting at offset 0.

### 参见

- ibase_fetch_assoc() - Fetch a result row from a query as an associative array
- ibase_fetch_object() - Get an object from a InterBase database

# ibase_field_info

(PHP 5, PHP 7 < 7.4.0)

ibase_field_info — Get information about a field

### 说明

function ibase_field_info(resource `$result`, int `$field_number`): array

Returns an array with information about a field after a select query has been run.

### 参数

`result`
  An InterBase result identifier.
`field_number`
  Field offset.

### 返回值

Returns an array with the following keys: `name`, `alias`, `relation`, `length` and `type`.

### 示例

示例 #1 ibase_field_info() example

    <?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";
    }
    ?>

### 参见

- ibase_num_fields() - Get the number of fields in a result set

# ibase_free_event_handler

(PHP 5, PHP 7 < 7.4.0)

ibase_free_event_handler — Cancels a registered event handler

### 说明

function ibase_free_event_handler(resource `$event`): bool

This function causes the registered event handler specified by `event` to be cancelled. The callback function will no longer be called for the events it was registered to handle.

### 参数

`event`
  An event resource, created by ibase_set_event_handler().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ibase_set_event_handler() - Register a callback function to be called when events are posted

# ibase_free_query

(PHP 5, PHP 7 < 7.4.0)

ibase_free_query — Free memory allocated by a prepared query

### 说明

function ibase_free_query(resource `$query`): bool

Frees a prepared query.

### 参数

`query`
  A query prepared with ibase_prepare().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# ibase_free_result

(PHP 5, PHP 7 < 7.4.0)

ibase_free_result — Free a result set

### 说明

function ibase_free_result(resource `$result_identifier`): bool

Frees a result set.

### 参数

`result_identifier`
  A result set created by ibase_query() or ibase_execute().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# ibase_gen_id

(PHP 5, PHP 7 < 7.4.0)

ibase_gen_id — Increments the named generator and returns its new value

### 说明

function ibase_gen_id(string `$generator`, int `$increment` = 1, resource `$link_identifier` = `null`): mixed
警告

本函数还未编写文档，仅有参数列表。

### 返回值

Returns new generator value as integer, or as string if the value is too big.

# ibase_maintain_db

(PHP 5, PHP 7 < 7.4.0)

ibase_maintain_db — Execute a maintenance command on the database server

### 说明

function ibase_maintain_db(
resource `$service_handle`,
string `$db`,
int `$action`,
int `$argument` = 0
): bool
警告

本函数还未编写文档，仅有参数列表。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# ibase_modify_user

(PHP 5, PHP 7 < 7.4.0)

ibase_modify_user — Modify a user to a security database

### 说明

function ibase_modify_user(
resource `$service_handle`,
string `$user_name`,
string `$password`,
string `$first_name` = ?,
string `$middle_name` = ?,
string `$last_name` = ?
): bool

### 参数

`service_handle`
  The handle on the database server service.
`user_name`
  The login name of the database user to modify.
`password`
  The user's new password.
`first_name`
  The user's new first name.
`middle_name`
  The user's new middle name.
`last_name`
  The user's new last name.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ibase_add_user() - Add a user to a security database
- ibase_delete_user() - Delete a user from a security database

# ibase_name_result

(PHP 5, PHP 7 < 7.4.0)

ibase_name_result — Assigns a name to a result set

### 说明

function ibase_name_result(resource `$result`, string `$name`): bool

This function assigns a name to a result set. This name can be used later in UPDATE|DELETE ... WHERE CURRENT OF `name` statements.

### 参数

`result`
  An InterBase result set.
`name`
  The name to be assigned.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 ibase_name_result() example

    <?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);
    }
    ?>

### 参见

- ibase_prepare() - Prepare a query for later binding of parameter placeholders and execution
- ibase_execute() - Execute a previously prepared query

# ibase_num_fields

(PHP 5, PHP 7 < 7.4.0)

ibase_num_fields — Get the number of fields in a result set

### 说明

function ibase_num_fields(resource `$result_id`): int

Get the number of fields in a result set.

### 参数

`result_id`
  An InterBase result identifier.

### 返回值

Returns the number of fields as an integer.

### 示例

示例 #1 ibase_num_fields() example

    <?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";
    }
    ?>

### 参见

- ibase_field_info() - Get information about a field

# ibase_num_params

(PHP 5, PHP 7 < 7.4.0)

ibase_num_params — Return the number of parameters in a prepared query

### 说明

function ibase_num_params(resource `$query`): int

This function returns the number of parameters in the prepared query specified by `query`. This is the number of binding arguments that must be present when calling ibase_execute().

### 参数

`query`
  The prepared query handle.

### 返回值

Returns the number of parameters as an integer.

### 参见

- ibase_prepare() - Prepare a query for later binding of parameter placeholders and execution
- ibase_param_info() - Return information about a parameter in a prepared query

# ibase_param_info

(PHP 5, PHP 7 < 7.4.0)

ibase_param_info — Return information about a parameter in a prepared query

### 说明

function ibase_param_info(resource `$query`, int `$param_number`): array

Returns an array with information about a parameter after a query has been prepared.

### 参数

`query`
  An InterBase prepared query handle.
`param_number`
  Parameter offset.

### 返回值

Returns an array with the following keys: `name`, `alias`, `relation`, `length` and `type`.

### 参见

- ibase_field_info() - Get information about a field
- ibase_num_params() - Return the number of parameters in a prepared query

# ibase_pconnect

(PHP 5, PHP 7 < 7.4.0)

ibase_pconnect — Open a persistent connection to an InterBase database

### 说明

function ibase_pconnect(
string `$database` = ?,
string `$username` = ?,
string `$password` = ?,
string `$charset` = ?,
int `$buffers` = ?,
int `$dialect` = ?,
string `$role` = ?,
int `$sync` = ?
): resource

Opens a persistent connection to an InterBase database.

ibase_pconnect() acts very much like ibase_connect() with two major differences.

First, when connecting, the function will first try to find a (persistent) link that's already opened with the same parameters. If one is found, an identifier for it will be returned instead of opening a new connection.

Second, the connection to the InterBase server will not be closed when the execution of the script ends. Instead, the link will remain open for future use (ibase_close() will not close links established by ibase_pconnect()). This type of link is therefore called 'persistent'.

### 参数

`database`
  The `database` argument has to be a valid path to database file on the server it resides on. If the server is not local, it must be prefixed with either 'hostname:' (TCP/IP), '//hostname/' (NetBEUI) or 'hostname@' (IPX/SPX), depending on the connection protocol used.
`username`
  The user name. Can be set with the `ibase.default_user` php.ini directive.
`password`
  The password for `username`. Can be set with the `ibase.default_password` php.ini directive.
`charset`
  `charset` is the default character set for a database.
`buffers`
  `buffers` is the number of database buffers to allocate for the server-side cache. If 0 or omitted, server chooses its own default.
`dialect`
  `dialect` selects the default SQL dialect for any statement executed within a connection, and it defaults to the highest one supported by client libraries. Functional only with InterBase 6 and up.
`role`
  Functional only with InterBase 5 and up.
`sync`

### 返回值

Returns an InterBase link identifier on success, or `false` on error.

### 参见

- ibase_close() - Close a connection to an InterBase database
- ibase_connect() - Open a connection to a database

# ibase_prepare

(PHP 5, PHP 7 < 7.4.0)

ibase_prepare — Prepare a query for later binding of parameter placeholders and execution

### 说明

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

Prepare a query for later binding of parameter placeholders and execution (via ibase_execute()).

### 参数

`query`
  An InterBase query.
`link_identifier`
  An InterBase link identifier returned from ibase_connect(). If omitted, the last opened link is assumed.
`trans`
  An InterBase transaction handle the query should be associated with. If omitted, the default transaction of the connection is assumed.

### 返回值

Returns a prepared query handle, or `false` on error.

# ibase_query

(PHP 5, PHP 7 < 7.4.0)

ibase_query — Execute a query on an InterBase database

### 说明

function ibase_query(resource `$link_identifier` = ?, string `$query`, int `$bind_args` = ?): resource

Performs a query on an InterBase database.

### 参数

`link_identifier`
  An InterBase link identifier. If omitted, the last opened link is assumed.
`query`
  An InterBase query.
`bind_args`

### 返回值

If the query raises an error, returns `false`. If it is successful and there is a (possibly empty) result set (such as with a SELECT query), returns a result identifier. If the query was successful and there were no results, returns `true`.

> 注意: In PHP 5.0.0 and up, this function will return the number of rows affected by the query for INSERT, UPDATE and DELETE statements. In order to retain backward compatibility, it will return `true` for these statements if the query succeeded without affecting any rows.

### 错误／异常

If you get some error like "arithmetic exception, numeric overflow, or string truncation. Cannot transliterate character between character sets" (this occurs when you try use some character with accents) when using this and after ibase_query() you must set the character set (i.e. ISO8859_1 or your current character set).

### 示例

示例 #1 ibase_query() example

    <?php

    $host = 'localhost:/path/to/your.gdb';

    $dbh = ibase_connect($host, $username, $password);
    $stmt = 'SELECT * FROM tblname';

    $sth = ibase_query($dbh, $stmt) or die(ibase_errmsg());

    ?>

### 参见

- ibase_errmsg() - Return error messages
- ibase_fetch_row() - Fetch a row from an InterBase database
- ibase_fetch_object() - Get an object from a InterBase database
- ibase_free_result() - Free a result set

# ibase_restore

(PHP 5, PHP 7 < 7.4.0)

ibase_restore — Initiates a restore task in the service manager and returns immediately

### 说明

function ibase_restore(
resource `$service_handle`,
string `$source_file`,
string `$dest_db`,
int `$options` = 0,
bool `$verbose` = `false`
): mixed

This function passes the arguments to the (remote) database server. There it starts a new restore process. Therefore you won't get any responses.

### 参数

`service_handle`
  A previously opened connection to the database server.
`source_file`
  The absolute path on the server where the backup file is located.
`dest_db`
  The path to create the new database on the server. You can also use database alias.
`options`

  Additional options to pass to the database server for restore. The `options` parameter can be a combination of the following constants: `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`. Read the section about 预定义常量 for further information.

`verbose`
  Since the restore process is done on the database server, you don't have any chance to get its output. This argument is useless.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

Since the restore process is done on the (remote) server, this function just passes the arguments to it. While the arguments are legal, you won't get `false`.

### 示例

示例 #1 ibase_restore() example

    <?php

    // Attach to database server by ip address and port
    $service = ibase_service_attach ('10.1.11.200/3050', 'sysdba', 'masterkey');

    // Start the restore process on database server
    // Restore employee backup to the new emps.fdb database
    // Don't use any special arguments
    ibase_restore($service, '/srv/backup/employees.fbk', '/srv/firebird/emps.fdb');

    // Free the attached connection
    ibase_service_detach ($service);
    ?>

示例 #2 ibase_restore() example with arguments

    <?php

    // Attach to database server by name and default port
    $service = ibase_service_attach ('fb-server.contoso.local', 'sysdba', 'masterkey');

    // Start the restore process on database server
    // Restore to employee database using alias.
    // Restore without indixes. Replace existing database.
    ibase_restore($service, '/srv/backup/employees.fbk', 'employees.fdb', IBASE_RES_DEACTIVATE_IDX | IBASE_RES_REPLACE);

    // Free the attached connection
    ibase_service_detach ($service);
    ?>

### 参见

- ibase_backup() - Initiates a backup task in the service manager and returns immediately

# ibase_rollback

(PHP 5, PHP 7 < 7.4.0)

ibase_rollback — Roll back a transaction

### 说明

function ibase_rollback(resource `$link_or_trans_identifier` = `null`): bool

Rolls back a transaction.

### 参数

`link_or_trans_identifier`
  If called without an argument, this function rolls back the default transaction of the default link. If the argument is a connection identifier, the default transaction of the corresponding connection will be rolled back. If the argument is a transaction identifier, the corresponding transaction will be rolled back.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# ibase_rollback_ret

(PHP 5, PHP 7 < 7.4.0)

ibase_rollback_ret — Roll back a transaction without closing it

### 说明

function ibase_rollback_ret(resource `$link_or_trans_identifier` = `null`): bool

Rolls back a transaction without closing it.

### 参数

`link_or_trans_identifier`
  If called without an argument, this function rolls back the default transaction of the default link. If the argument is a connection identifier, the default transaction of the corresponding connection will be rolled back. If the argument is a transaction identifier, the corresponding transaction will be rolled back. The transaction context will be retained, so statements executed from within this transaction will not be invalidated.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# ibase_server_info

(PHP 5, PHP 7 < 7.4.0)

ibase_server_info — Request information about a database server

### 说明

function ibase_server_info(resource `$service_handle`, int `$action`): string

### 参数

`service_handle`
  A previously created connection to the database server.
`action`
  A valid constant.

### 返回值

Returns mixed types depending on context.

### 示例

示例 #1 ibase_service_attach() example

    <?php
        // Attach to the remote Firebird server
        if (($service = ibase_service_attach('10.1.1.254/3050', 'sysdba', 'masterkey')) != FALSE) {

            // Successfully attached.

            // Output the info
            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";

            // Detach from server (disconnect)
            ibase_service_detach($service);

        }
        else {
            // Output message on error
            $conn_error = ibase_errmsg();
            die($conn_error);
        }
    ?>

以上示例会输出：

    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 — Connect to the service manager

### 说明

function ibase_service_attach(string `$host`, string `$dba_username`, string `$dba_password`): resource|false

### 参数

`host`
  The name or ip address of the database host. You can define the port by adding '/' and port number. If no port is specified, port 3050 will be used.
`dba_username`
  The name of any valid user.
`dba_password`
  The user's password.

### 返回值

Returns a Interbase / Firebird link identifier on success 或者在失败时返回 `false`.

### 示例

示例 #1 ibase_service_attach() example

    <?php
        // Attach to the remote Firebird server by ip address
        if (($service = ibase_service_attach('10.1.1.199', 'sysdba', 'masterkey')) != FALSE) {

            // Successfully attached.
            // Fetch server version (something like 'LI-V3.0.4.33054 Firebird 3.0')
            $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

            // Fetch server implementation (something like 'Firebird/Linux/AMD/Intel/x64')
            $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

            // Detach from server (disconnect)
            ibase_service_detach($service);

            // Output the info
            echo "Server version: " . $server_version . "<br/>";
            echo "Server implementation: " . $server_implementation;
        }
        else {
            // Output message on error
            $conn_error = ibase_errmsg();
            die($conn_error);
        }

    ?>

示例 #2 ibase_service_attach() example using `hostname/port` syntax

    <?php
        // Attach to the remote Firebird server by name. Use Port 3050.
        if (($service = ibase_service_attach('FB-SRV-01.contoso.local/3050', 'sysdba', 'masterkey')) != FALSE) {

            // Successfully attached.
            // Fetch server version (something like 'LI-V3.0.4.33054 Firebird 3.0')
            $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

            // Fetch server implementation (something like 'Firebird/Linux/AMD/Intel/x64')
            $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

            // Detach from server (disconnect)
            ibase_service_detach($service);

            // Output the info
            echo "Server version: " . $server_version . "<br/>";
            echo "Server implementation: " . $server_implementation;
        }
        else {
            // Output message on error
            $conn_error = ibase_errmsg();
            die($conn_error);
        }

    ?>

### 参见

- ibase_service_detach() - Disconnect from the service manager

# ibase_service_detach

(PHP 5, PHP 7 < 7.4.0)

ibase_service_detach — Disconnect from the service manager

### 说明

function ibase_service_detach(resource `$service_handle`): bool

### 参数

`service_handle`
  A previously created connection to the database server.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 ibase_service_detach() example

    <?php
        // Attach to the remote Firebird server by ip address
        if (($service = ibase_service_attach('10.1.1.199', 'sysdba', 'masterkey')) != FALSE) {

            // Successfully attached.
            // Fetch server version (something like 'LI-V3.0.4.33054 Firebird 3.0')
            $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

            // Fetch server implementation (something like 'Firebird/Linux/AMD/Intel/x64')
            $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

            // Detach from server (disconnect)
            if(ibase_service_detach($service) == FALSE) {
                echo "Error on service detach.";
            }
            else {
                echo "Successfully detached from service.";
            }

        }
        else {
            // Output message on error
            $conn_error = ibase_errmsg();
            die($conn_error);
        }

    ?>

# ibase_set_event_handler

(PHP 5, PHP 7 < 7.4.0)

ibase_set_event_handler — Register a callback function to be called when events are posted

### 说明

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

This function registers a PHP user function as event handler for the specified events.

### 参数

`event_handler`
  The callback is called with the event name and the link resource as arguments whenever one of the specified events is posted by the database. The callback must return `false` if the event handler should be canceled. Any other return value is ignored. This function accepts up to 15 event arguments.
`event_name`
  An event name.
`event_names`
  At most 15 events allowed.

### 返回值

The return value is an event resource. This resource can be used to free the event handler using ibase_free_event_handler().

### 示例

示例 #1 ibase_set_event_handler() example

    <?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");
    ?>

### 参见

- ibase_free_event_handler() - Cancels a registered event handler
- ibase_wait_event() - Wait for an event to be posted by the database

# ibase_trans

(PHP 5, PHP 7 < 7.4.0)

ibase_trans — Begin a transaction

### 说明

function ibase_trans(int `$trans_args` = ?, resource `$link_identifier` = ?): resource
function ibase_trans(resource `$link_identifier` = ?): resource

Begins a transaction.

> 注意: The first call to ibase_trans() will not return the default transaction of a connection. All transactions started by ibase_trans() will be rolled back at the end of the script if they were not committed or rolled back by either ibase_commit() or ibase_rollback().

> 注意: This function will accept multiple `trans_args` and `link_identifier` arguments. This allows transactions over multiple database connections, which are committed using a 2-phase commit algorithm. This means you can rely on the updates to either succeed in every database, or fail in every database. It does NOT mean you can use tables from different databases in the same query! If you use transactions over multiple databases, you will have to specify both the `link_id` and `transaction_id` in calls to ibase_query() and ibase_prepare().

### 参数

`trans_args`
  `trans_args` can be a combination of `IBASE_READ`, `IBASE_WRITE`, `IBASE_COMMITTED`, `IBASE_CONSISTENCY`, `IBASE_CONCURRENCY`, `IBASE_REC_VERSION`, `IBASE_REC_NO_VERSION`, `IBASE_WAIT` and `IBASE_NOWAIT`.
`link_identifier`
  An InterBase link identifier. If omitted, the last opened link is assumed.

### 返回值

Returns a transaction handle, or `false` on error.

# ibase_wait_event

(PHP 5, PHP 7 < 7.4.0)

ibase_wait_event — Wait for an event to be posted by the database

### 说明

function ibase_wait_event(string `$event_name`, string `...$event_names`): string
function ibase_wait_event(resource `$connection`, string `$event_name`, string `...$event_names`): string

This function suspends execution of the script until one of the specified events is posted by the database. The name of the event that was posted is returned. This function accepts up to 15 event arguments.

### 参数

`event_name`
  The event name.
`event_names`

### 返回值

Returns the name of the event that was posted.

### 参见

- ibase_set_event_handler() - Register a callback function to be called when events are posted
- ibase_free_event_handler() - Cancels a registered event handler

## 目录

- fbird_add_user — 别名 ibase_add_user
- fbird_affected_rows — 别名 ibase_affected_rows
- fbird_backup — 别名 ibase_backup
- fbird_blob_add — 别名 ibase_blob_add
- fbird_blob_cancel — Cancel creating blob
- fbird_blob_close — 别名 ibase_blob_close
- fbird_blob_create — 别名 ibase_blob_create
- fbird_blob_echo — 别名 ibase_blob_echo
- fbird_blob_get — 别名 ibase_blob_get
- fbird_blob_import — 别名 ibase_blob_import
- fbird_blob_info — 别名 ibase_blob_info
- fbird_blob_open — 别名 ibase_blob_open
- fbird_close — 别名 ibase_close
- fbird_commit — 别名 ibase_commit
- fbird_commit_ret — 别名 ibase_commit_ret
- fbird_connect — 别名 ibase_connect
- fbird_db_info — 别名 ibase_db_info
- fbird_delete_user — 别名 ibase_delete_user
- fbird_drop_db — 别名 ibase_drop_db
- fbird_errcode — 别名 ibase_errcode
- fbird_errmsg — 别名 ibase_errmsg
- fbird_execute — 别名 ibase_execute
- fbird_fetch_assoc — 别名 ibase_fetch_assoc
- fbird_fetch_object — 别名 ibase_fetch_object
- fbird_fetch_row — 别名 ibase_fetch_row
- fbird_field_info — 别名 ibase_field_info
- fbird_free_event_handler — 别名 ibase_free_event_handler
- fbird_free_query — 别名 ibase_free_query
- fbird_free_result — 别名 ibase_free_result
- fbird_gen_id — 别名 ibase_gen_id
- fbird_maintain_db — 别名 ibase_maintain_db
- fbird_modify_user — 别名 ibase_modify_user
- fbird_name_result — 别名 ibase_name_result
- fbird_num_fields — 别名 ibase_num_fields
- fbird_num_params — 别名 ibase_num_params
- fbird_param_info — 别名 ibase_param_info
- fbird_pconnect — 别名 ibase_pconnect
- fbird_prepare — 别名 ibase_prepare
- fbird_query — 别名 ibase_query
- fbird_restore — 别名 ibase_restore
- fbird_rollback — 别名 ibase_rollback
- fbird_rollback_ret — 别名 ibase_rollback_ret
- fbird_server_info — 别名 ibase_server_info
- fbird_service_attach — 别名 ibase_service_attach
- fbird_service_detach — 别名 ibase_service_detach
- fbird_set_event_handler — 别名 ibase_set_event_handler
- fbird_trans — 别名 ibase_trans
- fbird_wait_event — 别名 ibase_wait_event
- ibase_add_user — Add a user to a security database
- ibase_affected_rows — Return the number of rows that were affected by the previous query
- ibase_backup — Initiates a backup task in the service manager and returns immediately
- ibase_blob_add — Add data into a newly created blob
- ibase_blob_cancel — Cancel creating blob
- ibase_blob_close — Close blob
- ibase_blob_create — Create a new blob for adding data
- ibase_blob_echo — Output blob contents to browser
- ibase_blob_get — Get len bytes data from open blob
- ibase_blob_import — Create blob, copy file in it, and close it
- ibase_blob_info — Return blob length and other useful info
- ibase_blob_open — Open blob for retrieving data parts
- ibase_close — Close a connection to an InterBase database
- ibase_commit — Commit a transaction
- ibase_commit_ret — Commit a transaction without closing it
- ibase_connect — Open a connection to a database
- ibase_db_info — Request statistics about a database
- ibase_delete_user — Delete a user from a security database
- ibase_drop_db — Drops a database
- ibase_errcode — Return an error code
- ibase_errmsg — Return error messages
- ibase_execute — Execute a previously prepared query
- ibase_fetch_assoc — Fetch a result row from a query as an associative array
- ibase_fetch_object — Get an object from a InterBase database
- ibase_fetch_row — Fetch a row from an InterBase database
- ibase_field_info — Get information about a field
- ibase_free_event_handler — Cancels a registered event handler
- ibase_free_query — Free memory allocated by a prepared query
- ibase_free_result — Free a result set
- ibase_gen_id — Increments the named generator and returns its new value
- ibase_maintain_db — Execute a maintenance command on the database server
- ibase_modify_user — Modify a user to a security database
- ibase_name_result — Assigns a name to a result set
- ibase_num_fields — Get the number of fields in a result set
- ibase_num_params — Return the number of parameters in a prepared query
- ibase_param_info — Return information about a parameter in a prepared query
- ibase_pconnect — Open a persistent connection to an InterBase database
- ibase_prepare — Prepare a query for later binding of parameter placeholders and execution
- ibase_query — Execute a query on an InterBase database
- ibase_restore — Initiates a restore task in the service manager and returns immediately
- ibase_rollback — Roll back a transaction
- ibase_rollback_ret — Roll back a transaction without closing it
- ibase_server_info — Request information about a database server
- ibase_service_attach — Connect to the service manager
- ibase_service_detach — Disconnect from the service manager
- ibase_set_event_handler — Register a callback function to be called when events are posted
- ibase_trans — Begin a transaction
- ibase_wait_event — Wait for an event to be posted by the database

- 安装/配置
  - 安装
  - 运行时配置
- 预定义常量
- Firebird/InterBase 函数
  - fbird_add_user — 别名 ibase_add_user
  - fbird_affected_rows — 别名 ibase_affected_rows
  - fbird_backup — 别名 ibase_backup
  - fbird_blob_add — 别名 ibase_blob_add
  - fbird_blob_cancel — Cancel creating blob
  - fbird_blob_close — 别名 ibase_blob_close
  - fbird_blob_create — 别名 ibase_blob_create
  - fbird_blob_echo — 别名 ibase_blob_echo
  - fbird_blob_get — 别名 ibase_blob_get
  - fbird_blob_import — 别名 ibase_blob_import
  - fbird_blob_info — 别名 ibase_blob_info
  - fbird_blob_open — 别名 ibase_blob_open
  - fbird_close — 别名 ibase_close
  - fbird_commit — 别名 ibase_commit
  - fbird_commit_ret — 别名 ibase_commit_ret
  - fbird_connect — 别名 ibase_connect
  - fbird_db_info — 别名 ibase_db_info
  - fbird_delete_user — 别名 ibase_delete_user
  - fbird_drop_db — 别名 ibase_drop_db
  - fbird_errcode — 别名 ibase_errcode
  - fbird_errmsg — 别名 ibase_errmsg
  - fbird_execute — 别名 ibase_execute
  - fbird_fetch_assoc — 别名 ibase_fetch_assoc
  - fbird_fetch_object — 别名 ibase_fetch_object
  - fbird_fetch_row — 别名 ibase_fetch_row
  - fbird_field_info — 别名 ibase_field_info
  - fbird_free_event_handler — 别名 ibase_free_event_handler
  - fbird_free_query — 别名 ibase_free_query
  - fbird_free_result — 别名 ibase_free_result
  - fbird_gen_id — 别名 ibase_gen_id
  - fbird_maintain_db — 别名 ibase_maintain_db
  - fbird_modify_user — 别名 ibase_modify_user
  - fbird_name_result — 别名 ibase_name_result
  - fbird_num_fields — 别名 ibase_num_fields
  - fbird_num_params — 别名 ibase_num_params
  - fbird_param_info — 别名 ibase_param_info
  - fbird_pconnect — 别名 ibase_pconnect
  - fbird_prepare — 别名 ibase_prepare
  - fbird_query — 别名 ibase_query
  - fbird_restore — 别名 ibase_restore
  - fbird_rollback — 别名 ibase_rollback
  - fbird_rollback_ret — 别名 ibase_rollback_ret
  - fbird_server_info — 别名 ibase_server_info
  - fbird_service_attach — 别名 ibase_service_attach
  - fbird_service_detach — 别名 ibase_service_detach
  - fbird_set_event_handler — 别名 ibase_set_event_handler
  - fbird_trans — 别名 ibase_trans
  - fbird_wait_event — 别名 ibase_wait_event
  - ibase_add_user — Add a user to a security database
  - ibase_affected_rows — Return the number of rows that were affected by the previous query
  - ibase_backup — Initiates a backup task in the service manager and returns immediately
  - ibase_blob_add — Add data into a newly created blob
  - ibase_blob_cancel — Cancel creating blob
  - ibase_blob_close — Close blob
  - ibase_blob_create — Create a new blob for adding data
  - ibase_blob_echo — Output blob contents to browser
  - ibase_blob_get — Get len bytes data from open blob
  - ibase_blob_import — Create blob, copy file in it, and close it
  - ibase_blob_info — Return blob length and other useful info
  - ibase_blob_open — Open blob for retrieving data parts
  - ibase_close — Close a connection to an InterBase database
  - ibase_commit — Commit a transaction
  - ibase_commit_ret — Commit a transaction without closing it
  - ibase_connect — Open a connection to a database
  - ibase_db_info — Request statistics about a database
  - ibase_delete_user — Delete a user from a security database
  - ibase_drop_db — Drops a database
  - ibase_errcode — Return an error code
  - ibase_errmsg — Return error messages
  - ibase_execute — Execute a previously prepared query
  - ibase_fetch_assoc — Fetch a result row from a query as an associative array
  - ibase_fetch_object — Get an object from a InterBase database
  - ibase_fetch_row — Fetch a row from an InterBase database
  - ibase_field_info — Get information about a field
  - ibase_free_event_handler — Cancels a registered event handler
  - ibase_free_query — Free memory allocated by a prepared query
  - ibase_free_result — Free a result set
  - ibase_gen_id — Increments the named generator and returns its new value
  - ibase_maintain_db — Execute a maintenance command on the database server
  - ibase_modify_user — Modify a user to a security database
  - ibase_name_result — Assigns a name to a result set
  - ibase_num_fields — Get the number of fields in a result set
  - ibase_num_params — Return the number of parameters in a prepared query
  - ibase_param_info — Return information about a parameter in a prepared query
  - ibase_pconnect — Open a persistent connection to an InterBase database
  - ibase_prepare — Prepare a query for later binding of parameter placeholders and execution
  - ibase_query — Execute a query on an InterBase database
  - ibase_restore — Initiates a restore task in the service manager and returns immediately
  - ibase_rollback — Roll back a transaction
  - ibase_rollback_ret — Roll back a transaction without closing it
  - ibase_server_info — Request information about a database server
  - ibase_service_attach — Connect to the service manager
  - ibase_service_detach — Disconnect from the service manager
  - ibase_set_event_handler — Register a callback function to be called when events are posted
  - ibase_trans — Begin a transaction
  - ibase_wait_event — Wait for an event to be posted by the database

# IBM DB2, Cloudscape and Apache Derby

# 简介

These functions enable you to access IBM DB2 Universal Database, IBM Cloudscape, and Apache Derby databases using the DB2 Call Level Interface (DB2 CLI).

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置
- 资源类型

## 需求

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).

## 安装

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 PECL 扩展安装 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.

> 注意: 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.

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

ibm_db2 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
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.

这是配置指令的简短说明。

`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.

## 资源类型

The ibm_db2 extension returns connection resources, statement resources, and result set resources.

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`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 函数

# db2_autocommit

(PECL ibm_db2 >= 1.0.0)

db2_autocommit — Returns or sets the AUTOCOMMIT state for a database connection

### 说明

function db2_autocommit(resource `$connection`, int `$value` = ?): int|bool

Sets or gets the AUTOCOMMIT behavior of the specified connection resource.

### 参数

`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.

### 返回值

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. 成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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.";
    }
    ?>

以上示例会输出：

    0 -- AUTOCOMMIT is off.

示例 #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.";
    }
    ?>

以上示例会输出：

    Turning AUTOCOMMIT on succeeded.
    1 -- AUTOCOMMIT is on.

### 参见

- 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

### 说明

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().

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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";
        }
    }
    ?>

以上示例会输出：

    Pook, cat, 3.2
    Rickety Ride, goat, 9.7
    Peaches, dog, 12.3

示例 #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";
        }
    }
    ?>

以上示例会输出：

    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

示例 #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);
    ?>

### 参见

- 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

### 说明

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".

### 参数

`connection`
  Specifies an active DB2 client connection.

### 返回值

Returns an object on a successful call, 或者在失败时返回 `false`

### 示例

示例 #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);

    ?>

以上示例会输出：

    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)

### 参见

- 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

### 说明

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.

### 参数

`connection`
  Specifies an active DB2 client connection.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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.";
    }
    ?>

以上示例会输出：

    Connection was successfully closed.

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 参见

- 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

### 说明

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.

### 参数

`connection`
  A valid database connection resource variable as returned from db2_connect() or db2_pconnect().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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.

### 参数

`connection`
  A connection resource associated with a connection that initially succeeded, but which over time became invalid.

### 返回值

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.

### 示例

示例 #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();
    }
    ?>

以上示例会输出：

    SQLSTATE value: 08001

### 参见

- 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

### 说明

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.

### 参数

`connection`
  A connection resource associated with a connection that initially succeeded, but which over time became invalid.

### 返回值

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.

### 示例

示例 #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();
    }
    ?>

以上示例会输出：

    [IBM][CLI Driver] SQL1013N  The database alias name
    or database name "BADNAME" could not be found.  SQLSTATE=42705
     SQLCODE=-1013

### 参见

- 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

### 说明

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.

### 参数

`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;

  > 注意:

  > 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.

    > 注意: 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".

    > 注意: `i5_libl` calls qsys2/qcmdexc('cmd',cmdlen), which is only available in i5/OS V5R4 and later.

### 返回值

Returns a connection handle resource if the connection attempt is successful. If the connection attempt fails, db2_connect() returns `false`.

### 示例

示例 #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.";
    }
    ?>

以上示例会输出：

    Connection succeeded.

示例 #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.";
    }
    ?>

以上示例会输出：

    Connection succeeded.

示例 #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.";
    }
    ?>

以上示例会输出：

    Connection succeeded.
    Autocommit is off.

示例 #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);
    ?>

以上示例会输出：

    ANIMALS
    NAMES
    PICTURES

示例 #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";
    }
    ?>

以上示例会输出：

    Explicit trusted connection succeeded.
    User has been switched.

### 参见

- 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

### 说明

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.

### 参数

`stmt`
  A valid statement resource.

### 返回值

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.

### 参见

- 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

### 说明

function db2_escape_string(string `$string_literal`): string

Prepends backslashes to special characters in the string argument.

### 参数

`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`.

### 返回值

Returns `string_literal` with the special characters noted above prepended with backslashes.

### 示例

示例 #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] = "Intersting 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";
        }
    }
    ?>

以上示例会输出：

    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: Intersting characters: \Z , \0 .
    db2_escape_string: Nothing to quote
    db2_escape_string: 200676
    db2_escape_string:

### 参见

- db2_prepare() - Prepares an SQL statement to be executed

# db2_exec

(PECL ibm_db2 >= 1.0.0)

db2_exec — Executes an SQL statement directly

### 说明

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.

### 参数

`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().

### 返回值

Returns a statement resource if the SQL statement was issued successfully, or `false` if the database failed to execute the SQL statement.

### 示例

示例 #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... ";
        }
    }
    ?>

以上示例会输出：

    Successfully created the table.
    Insert... Insert... Insert... Insert... Insert... Insert... Insert...

示例 #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";
        }
    }
    ?>

以上示例会输出：

    Bubbles
    Gizmo
    Pook
    Rickety Ride

示例 #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);

    ?>

以上示例会输出：

    1000     Kathy Smith     416-555-1358
    1001     Kathy Smith     905-555-7258

示例 #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);

    ?>

以上示例会输出：

    1001     Kathy Smith     905-555-7258     5002     Shipped

示例 #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);

    ?>

以上示例会输出：

    <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>

### 参见

- 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

### 说明

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().

### 参数

`stmt`
  A prepared statement returned from db2_prepare().
`parameters`
  An array of input parameters matching any parameter markers contained in the prepared statement.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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.";
        }
    }
    ?>

以上示例会输出：

    Successfully added new pet.

示例 #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!";
    ?>

以上示例会输出：

    I have 7 pets!

示例 #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);

    ?>

以上示例会输出：

    1000     Kathy Smith     416-555-1358
    1001     Kathy Smith     905-555-7258

示例 #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);

    ?>

以上示例会输出：

    1001     Kathy Smith     905-555-7258     5002     Shipped

示例 #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);

    ?>

以上示例会输出：

    <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>

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 示例

示例 #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]);
    }
    ?>

以上示例会输出：

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

示例 #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;
    }
    ?>

以上示例会输出：

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 示例

示例 #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']);
    }
    ?>

以上示例会输出：

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

示例 #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;
    }
    ?>

以上示例会输出：

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

### 参见

- 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

### 说明

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().

### 参数

`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.

### 返回值

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.

### 示例

示例 #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]);
    }
    ?>

以上示例会输出：

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

示例 #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;
    }
    ?>

以上示例会输出：

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 示例

示例 #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);
    }
    ?>

以上示例会输出：

    Come here, Pook, my little cat!

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

Returns `true` if the requested row exists in the result set. Returns `false` if the requested row does not exist in the result set.

### 示例

示例 #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";
    }
    ?>

以上示例会输出：

    cat Pook
    gold fish Bubbles
    budgerigar Gizmo
    goat Rickety Ride

示例 #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);
    ?>

以上示例会输出：

    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

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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`.

### 参见

- 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

### 说明

function db2_field_name(resource `$stmt`, int|string `$column`): string|false

Returns the name of the specified column in the result set.

### 参数

`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.

### 返回值

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`.

### 参见

- 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

### 说明

function db2_field_num(resource `$stmt`, int|string `$column`): int|false

Returns the position of the named column in a result set.

### 参数

`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.

### 返回值

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`.

### 参见

- 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

### 说明

function db2_field_precision(resource `$stmt`, int|string `$column`): int|false

Returns the precision of the indicated column in a result set.

### 参数

`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.

### 返回值

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`.

### 参见

- 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

### 说明

function db2_field_scale(resource `$stmt`, int|string `$column`): int|false

Returns the scale of the indicated column in a result set.

### 参数

`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.

### 返回值

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`.

### 参见

- 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

### 说明

function db2_field_type(resource `$stmt`, int|string `$column`): string|false

Returns the data type of the indicated column in a result set.

### 参数

`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.

### 返回值

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`.

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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`.

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 参见

- 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

### 说明

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.

### 参数

`stmt`
  A valid statement resource.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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.

### 参数

`stmt`
  A valid statement resource.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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.

### 参数

`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().

  > 注意: 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.

    > 注意: 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.

    > 注意: 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.

    > 注意: 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.

    > 注意: 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 | -

### 返回值

Returns the current setting of the connection attribute provided on success 或者在失败时返回 `false`.

### 示例

示例 #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";
    ?>

以上示例会输出：

    Client attributes passed through connection string:
    db2inst1
    account
    myapp
    workstation
    Client attributes passed post-connection:
    db2inst1
    account
    myapp
    workstation

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

Returns the auto generated ID of last insert query that successfully executed on this connection.

### 示例

示例 #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.";
    }
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`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.

### 返回值

Returns the amount of data the user specifies. Returns `false` if the data cannot be retrieved.

### 示例

示例 #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();
    }

    ?>

以上示例会输出：

    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.

### 参见

- 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

### 说明

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.

### 参数

`stmt`
  A prepared statement returned from db2_exec() or db2_execute().

### 返回值

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.

### 示例

示例 #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);
    }
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`stmt`
  A valid statement resource containing a result set.

### 返回值

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.

### 示例

示例 #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.";
    ?>

以上示例会输出：

    There are 4 columns in the result set.

### 参见

- 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

### 说明

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`.

> 注意: 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.

### 参数

`stmt`
  A valid `stmt` resource containing a result set.

### 返回值

Returns the number of rows affected by the last SQL statement issued by the specified statement handle, 或者在失败时返回 `false`

# db2_pclose

(PECL ibm_db2 >= 1.8.0)

db2_pclose — Closes a persistent database connection

### 说明

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.

> 注意: 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.

### 参数

`connection`
  Specifies an active DB2 client connection.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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.";
    }
    ?>

以上示例会输出：

    Connection was successfully closed.

### 参见

- 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

### 说明

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 持久数据库连接.

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.

### 参数

`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;

  > 注意:

  > 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.

  小技巧

  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.

    > 注意: 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.

    > 注意: 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".

    > 注意: i5_libl calls qsys2/qcmdexc('cmd',cmdlen), which is only available in i5/OS V5R4 and later.

### 返回值

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`.

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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.";
    }
    ?>

以上示例会输出：

    Persistent connection succeeded.
    Second persistent connection succeeded.

示例 #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";
    }
    ?>

以上示例会输出：

    Explicit trusted connection succeeded.
    User has been switched.

### 参见

- 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

### 说明

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().

### 参数

`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().

### 返回值

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().

### 示例

示例 #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);
        }
    }
    ?>

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 参见

- 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

### 说明

function db2_procedures(
resource `$connection`,
?string `$qualifier`,
string `$schema`,
string `$procedure`
): resource

Returns a result set listing the stored procedures registered in a database.

### 参数

`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.

### 返回值

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.

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 示例

示例 #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";
    }
    ?>

以上示例会输出：

    cat Pook
    gold fish Bubbles
    budgerigar Gizmo
    goat Rickety Ride

### 参见

- 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

### 说明

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.

### 参数

`connection`
  A valid database connection resource variable as returned from db2_connect() or db2_pconnect().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    }
    ?>

以上示例会输出：

    7
    0
    7

### 参见

- 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

### 说明

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.

### 参数

`connection`
  Specifies an active DB2 client connection.

### 返回值

Returns an object on a successful call, 或者在失败时返回 `false`

### 示例

示例 #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);
    }
    ?>

以上示例会输出：

    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)

### 参见

- 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

### 说明

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.

### 参数

`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().

  > 注意: 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.

    > 注意: 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.

    > 注意: 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.

    > 注意: 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.

    > 注意: 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 | -

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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';
    }
    ?>

以上示例会输出：

    Options Set Successfully

示例 #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';
    }
    ?>

以上示例会输出：

    Options Set Successfully

示例 #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';
    }
    ?>

以上示例会输出：

    Could Not Set Options

示例 #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';
    }
    ?>

以上示例会输出：

    Could Not Set Options

示例 #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';
    }
    ?>

以上示例会输出：

    Could Not Set Options

示例 #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';
    }
    ?>

以上示例会输出：

    Could Not Set Options

示例 #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));

    ?>

以上示例会输出：

    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
    )

示例 #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]}";
        }
      }
    ?>

以上示例会输出：

    first2 last2

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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`.

### 参见

- 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

### 说明

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.

### 参数

`stmt`
  A valid statement resource.

### 返回值

Returns a string containing an SQLSTATE value.

### 参见

- 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

### 说明

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().

### 参数

`stmt`
  A valid statement resource.

### 返回值

Returns a string containing the error message and SQLCODE value for the last error that occurred issuing an SQL statement.

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 参见

- 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

## 目录

- 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

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
  - 资源类型
- 预定义常量
- IBM DB2 函数
  - 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.

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置

## 需求

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.

> 注意: 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.

## 安装

## Installing the MongoDB PHP Extension with PIE

> 注意: PHP 扩展安装器 (PIE) 是一个新的工具，将取代 PECL。 我们建议使用 PIE 来安装扩展。在 » https://github.com/php/pie 了解更多。

To install the MongoDB extension using PIE, run the following command:

    pie install mongodb/mongodb-extension

## Installing the MongoDB PHP Extension with PECL

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » 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.

> 注意: 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.

> 注意: 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.

> 注意: Additional DLL dependencies for Windows Users
> 为了使此扩展生效， DLL 文件必须能在 Windows 系统的 PATH 指示的路径下找到。如何操作的信息，请参见题为“如何在 Windows 中将 PHP 目录加到 PATH 中”的FAQ。虽然将 DLL 文件从 PHP 文件夹复制到 Windows 系统目录也行，但不建议这样做。 此扩展需要下列文件在 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.

> 注意: 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

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

mongodb 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
mongodb.debug | "" | `INI_ALL` |

这是配置指令的简短说明。

`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.

  > 注意: 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.

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`MONGODB_VERSION` (string)
  x.y.z style version number of the extension
`MONGODB_STABILITY` (string)
  Current stability (alpha/beta/stable)

# Tutorials

## 目录

- 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

## 目录

- 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

> 注意: On Unix platforms, the extension is sensitive to scripts that use the fork() system call without also calling exec(). Users are advised not to re-use MongoDB\Driver\Manager instances in a forked child process.

## 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.

> 注意: 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

警告

BSON documents can technically contain duplicate keys because documents are stored as a list of key-value pairs; however, applications should refrain from generating documents with duplicate keys as server and driver behavior may be undefined. Since PHP objects and arrays cannot have duplicate keys, data could also be lost when decoding a BSON document with duplicate keys.

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].

  > 注意: 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

## 目录

- 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 boundry 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 扩展类

## 目录

- 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)

## 简介

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.

## 类摘要

final class MongoDB\Driver\Manager {
/* 方法 */
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
}

## 示例

示例 #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);

    ?>

以上示例的输出类似于：

    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

### 说明

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.

> 注意: 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.

### 参数

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  A monitoring event subscriber to register with this Manager.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `subscriber` is a MongoDB\Driver\Monitoring\LogSubscriber, since loggers can only be registered globally.

### 参见

- 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

### 说明

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.

> 注意: 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.

> 注意: 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.

> 注意: On Unix platforms, the extension is sensitive to scripts that use the fork() system call without also calling exec(). Users are advised not to re-use MongoDB\Driver\Manager instances in a forked child process.

### 参数

`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. 注意: 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. 注意: 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`. 警告 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`. 警告 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`. 警告 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. 注意: 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`. 注意: 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. 注意: 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 | The Manager used to route data key queries to a separate MongoDB cluster. By default, the current Manager and cluster is used.
  keyVaultNamespace | string | A fully qualified namespace (e.g. `"databaseName.collectionName"`) denoting the collection that contains all data keys used for encryption and decryption. This option is required.
  kmsProviders | array | A document containing the configuration for one or more KMS providers, which are used to encrypt data keys. Supported providers include `"aws"`, `"azure"`, `"gcp"`, `"kmip"`, and `"local"` and at least one must be specified. If an empty document is specified for `"aws"`, `"azure"`, or `"gcp"`, the driver will attempt to configure the provider using » Automatic Credentials. The format for `"aws"` is as follows:
      aws: {
          accessKeyId: <string>,
          secretAccessKey: <string>,
          sessionToken: <optional string>
      }
  The format for `"azure"` is as follows:
      azure: {
          tenantId: <string>,
          clientId: <string>,
          clientSecret: <string>,
          identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"
      }
  The format for `"gcp"` is as follows:
      gcp: {
          email: <string>,
          privateKey: <base64 string>|<MongoDB\BSON\Binary>,
          endpoint: <optional string> // Defaults to "oauth2.googleapis.com"
      }
  The format for `"kmip"` is as follows:
      kmip: {
          endpoint: <string>
      }
  The format for `"local"` is as follows:
      local: {
          // 96-byte master key used to encrypt/decrypt data keys
          key: <base64 string>|<MongoDB\BSON\Binary>
      }
  tlsOptions | array | A document containing the TLS configuration for one or more KMS providers. Supported providers include `"aws"`, `"azure"`, `"gcp"`, and `"kmip"`. All providers support the following options:
      <provider>: {
          tlsCaFile: <optional string>,
          tlsCertificateKeyFile: <optional string>,
          tlsCertificateKeyFilePassword: <optional string>,
          tlsDisableOCSPEndpointCheck: <optional bool>
      }
  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`. 注意: 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. 注意: 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`. 注意: 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.

  > 注意: 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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\RuntimeException if the `uri` format is invalid

### 更新日志

版本 | 说明
--- | ---
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/"`.

### 示例

示例 #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",
        ]
    );
    ?>

### 参见

- 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

### 说明

final public function MongoDB\Driver\Manager::createClientEncryption(array `$options`): MongoDB\Driver\ClientEncryption

Constructs a new MongoDB\Driver\ClientEncryption object with the specified options.

### 参数

`options`

  options
  Option | Type | Description
  --- | --- | ---
  keyVaultClient | MongoDB\Driver\Manager | The Manager used to route data key queries to a separate MongoDB cluster. By default, the current Manager and cluster is used.
  keyVaultNamespace | string | A fully qualified namespace (e.g. `"databaseName.collectionName"`) denoting the collection that contains all data keys used for encryption and decryption. This option is required.
  kmsProviders | array | A document containing the configuration for one or more KMS providers, which are used to encrypt data keys. Supported providers include `"aws"`, `"azure"`, `"gcp"`, `"kmip"`, and `"local"` and at least one must be specified. If an empty document is specified for `"aws"`, `"azure"`, or `"gcp"`, the driver will attempt to configure the provider using » Automatic Credentials. The format for `"aws"` is as follows:
      aws: {
          accessKeyId: <string>,
          secretAccessKey: <string>,
          sessionToken: <optional string>
      }
  The format for `"azure"` is as follows:
      azure: {
          tenantId: <string>,
          clientId: <string>,
          clientSecret: <string>,
          identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"
      }
  The format for `"gcp"` is as follows:
      gcp: {
          email: <string>,
          privateKey: <base64 string>|<MongoDB\BSON\Binary>,
          endpoint: <optional string> // Defaults to "oauth2.googleapis.com"
      }
  The format for `"kmip"` is as follows:
      kmip: {
          endpoint: <string>
      }
  The format for `"local"` is as follows:
      local: {
          // 96-byte master key used to encrypt/decrypt data keys
          key: <base64 string>|<MongoDB\BSON\Binary>
      }
  tlsOptions | array | A document containing the TLS configuration for one or more KMS providers. Supported providers include `"aws"`, `"azure"`, `"gcp"`, and `"kmip"`. All providers support the following options:
      <provider>: {
          tlsCaFile: <optional string>,
          tlsCertificateKeyFile: <optional string>,
          tlsCertificateKeyFilePassword: <optional string>,
          tlsDisableOCSPEndpointCheck: <optional bool>
      }

### 返回值

Returns a new MongoDB\Driver\ClientEncryption instance.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\RuntimeException if the extension was compiled without libmongocrypt support

### 更新日志

版本 | 说明
--- | ---
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"`.

### 参见

- 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

### 说明

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.

### 参数

`namespace` (string)
  A fully qualified namespace (e.g. `"databaseName.collectionName"`).
`bulk` (MongoDB\Driver\BulkWrite)
  The write(s) to execute.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  session | MongoDB\Driver\Session | A session to associate with the operation.
  writeConcern | MongoDB\Driver\WriteConcern | A write concern to apply to the operation.

### 返回值

Returns MongoDB\Driver\WriteResult on success.

### 错误／异常

- 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.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used in combination with an unacknowledged write concern.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\BulkWriteException on any write failure (e.g. write error, failure to apply a write concern)
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### 更新日志

版本 | 说明
--- | ---
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 paramater 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.

### 示例

示例 #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());
    }
    ?>

以上示例的输出类似于：

    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)

### 参见

- 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

### 说明

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.

### 参数

`bulk` (MongoDB\Driver\BulkWriteCommand)
  The write(s) to execute.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  session | MongoDB\Driver\Session | A session to associate with the operation.
  writeConcern | MongoDB\Driver\WriteConcern | A write concern to apply to the operation.

### 返回值

Returns MongoDB\Driver\BulkWriteCommandResult on success.

### 错误／异常

- 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.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used in combination with an unacknowledged write concern.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\BulkWriteCommandException on any write failure (e.g. command failure, write or write concern error)
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### 示例

示例 #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());

    ?>

以上示例会输出：

    Inserted 3 document(s)
    Updated  1 document(s)

示例 #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());

    ?>

以上示例的输出类似于：

    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)

### 参见

- 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

### 说明

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.

### 参数

`db` (string)
  The name of the database on which to execute the command.
`command` (MongoDB\Driver\Command)
  The command to execute.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | A read concern to apply to the operation. This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version.
  readPreference | MongoDB\Driver\ReadPreference | A read preference to use for selecting a server for the operation.
  session | MongoDB\Driver\Session | A session to associate with the operation.
  writeConcern | MongoDB\Driver\WriteConcern | A write concern to apply to the operation.

  警告

  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().

### 返回值

Returns MongoDB\Driver\Cursor on success.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used with an associated transaction in combination with a `"readConcern"` or `"writeConcern"` option.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used in combination with an unacknowledged write concern.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command, issuing a write command to a secondary).

### 更新日志

版本 | 说明
--- | ---
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 paramater will still accept a MongoDB\Driver\ReadPreference object.

### 示例

示例 #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);

    ?>

以上示例会输出：

    array(1) {
      ["ok"]=>
      float(1)
    }

示例 #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);
    }

    ?>

以上示例会输出：

    object(stdClass)#6 (2) {
      ["_id"]=>
      string(3) "bar"
      ["sum"]=>
      int(10)
    }
    object(stdClass)#7 (2) {
      ["_id"]=>
      string(3) "foo"
      ["sum"]=>
      int(2)
    }

示例 #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.

### 注释

> 注意: 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.

> 注意: 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().

### 参见

- 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

### 说明

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.

### 参数

`namespace` (string)
  A fully qualified namespace (e.g. `"databaseName.collectionName"`).
`query` (MongoDB\Driver\Query)
  The query to execute.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  readPreference | MongoDB\Driver\ReadPreference | A read preference to use for selecting a server for the operation.
  session | MongoDB\Driver\Session | A session to associate with the operation.

### 返回值

Returns MongoDB\Driver\Cursor on success.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid query operators).

### 更新日志

版本 | 说明
--- | ---
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 paramater will still accept a MongoDB\Driver\ReadPreference object.

### 示例

示例 #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);
    }

    ?>

以上示例会输出：

    object(stdClass)#6 (1) {
      ["x"]=>
      int(3)
    }
    object(stdClass)#7 (1) {
      ["x"]=>
      int(2)
    }

示例 #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.

### 参见

- 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

### 说明

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.

### 参数

`db` (string)
  The name of the database on which to execute the command.
`command` (MongoDB\Driver\Command)
  The command to execute.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | A read concern to apply to the operation. This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version.
  readPreference | MongoDB\Driver\ReadPreference | A read preference to use for selecting a server for the operation.
  session | MongoDB\Driver\Session | A session to associate with the operation.

  警告

  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().

### 返回值

Returns MongoDB\Driver\Cursor on success.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used with an associated transaction in combination with a `"readConcern"` or `"writeConcern"` option.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command).

### 参见

- 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

### 说明

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.

### 参数

`db` (string)
  The name of the database on which to execute the command.
`command` (MongoDB\Driver\Command)
  The command to execute.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | A read concern to apply to the operation. This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version.
  session | MongoDB\Driver\Session | A session to associate with the operation.
  writeConcern | MongoDB\Driver\WriteConcern | A write concern to apply to the operation.

  警告

  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().

### 返回值

Returns MongoDB\Driver\Cursor on success.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used with an associated transaction in combination with a `"readConcern"` or `"writeConcern"` option.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used in combination with an unacknowledged write concern.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command).

### 更新日志

版本 | 说明
--- | ---
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.

### 参见

- 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

### 说明

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.

> 注意: 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.

### 参数

`db` (string)
  The name of the database on which to execute the command.
`command` (MongoDB\Driver\Command)
  The command to execute.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  session | MongoDB\Driver\Session | A session to associate with the operation.
  writeConcern | MongoDB\Driver\WriteConcern | A write concern to apply to the operation.

  警告

  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().

### 返回值

Returns MongoDB\Driver\Cursor on success.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used with an associated transaction in combination with a `"readConcern"` or `"writeConcern"` option.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used in combination with an unacknowledged write concern.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command).

### 更新日志

版本 | 说明
--- | ---
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.

### 参见

- 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

### 说明

final public function MongoDB\Driver\Manager::getEncryptedFieldsMap(): array|object|null

Returns the `encryptedFieldsMap` auto encryption option for the Manager, if specified.

### 参数

此函数没有参数。

### 返回值

The `encryptedFieldsMap` auto encryption option for the Manager, or `null` if it was not specified.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

The MongoDB\Driver\ReadConcern for the Manager.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例的输出类似于：

    object(MongoDB\Driver\ReadConcern)#2 (0) {
    }
    object(MongoDB\Driver\ReadConcern)#1 (1) {
      ["level"]=>
      string(5) "local"
    }

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

The MongoDB\Driver\ReadPreference for the Manager.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例的输出类似于：

    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) {
        }
      }
    }

### 参见

- 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

### 说明

final public function MongoDB\Driver\Manager::getServers(): array

Returns an array of MongoDB\Driver\Server instances to which this manager is connected.

> 注意: 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.

### 参数

此函数没有参数。

### 返回值

Returns an array of MongoDB\Driver\Server instances to which this manager is connected.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例的输出类似于：

    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)
      }
    }

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

The MongoDB\Driver\WriteConcern for the Manager.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例的输出类似于：

    object(MongoDB\Driver\WriteConcern)#2 (0) {
    }
    object(MongoDB\Driver\WriteConcern)#1 (2) {
      ["w"]=>
      string(8) "majority"
      ["wtimeout"]=>
      int(2000)
    }

### 参见

- 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

### 说明

final public function MongoDB\Driver\Manager::removeSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Unregisters a monitoring event subscriber with this Manager.

> 注意: If `subscriber` is not already registered with this Manager, this function is a no-op.

### 参数

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  A monitoring event subscriber to unregister with this Manager.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

> 注意: 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.

### 参数

`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.

### 返回值

Returns a MongoDB\Driver\Server matching the read preference.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\RuntimeException if a server matching the read preference could not be found.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 1.11.0 | The `readPreference` is now optional. If `null` or omitted, the primary server will be selected by default.

### 参见

- 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

### 说明

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.

> 注意: A MongoDB\Driver\Session can only be used with the MongoDB\Driver\Manager from which it was created.

### 参数

`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 | The maximum amount of time in milliseconds to allow a single `commitTransaction` command to run. If specified, `maxCommitTimeMS` must be a signed 32-bit integer greater than or equal to zero.
  readConcern | MongoDB\Driver\ReadConcern | A read concern to apply to the operation. This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version.
  readPreference | MongoDB\Driver\ReadPreference | A read preference to use for selecting a server for the operation.
  writeConcern | MongoDB\Driver\WriteConcern | A write concern to apply to the operation.
  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`

### 返回值

Returns a MongoDB\Driver\Session.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- 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).

### 更新日志

版本 | 说明
--- | ---
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.

### 参见

- MongoDB\Driver\Session
- » Causal Consistency in the MongoDB manual

## 目录

- 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)

## 简介

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.

## 类摘要

final class MongoDB\Driver\Command {
/* 方法 */
final public function __construct(array|object `$document`, ?array `$commandOptions` = `null`)
}

## 示例

示例 #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;
    }

    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`document`
  The complete command document, which will be sent to the server.
`commandOptions`

  > 注意: 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).

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 1.4.0 | Added a second `commandOptions` argument, which supports the `"maxAwaitTimeMS"` option.

### 示例

示例 #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);

    ?>

以上示例的输出类似于：

    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)
    }

示例 #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);

    ?>

以上示例的输出类似于：

operation exceeded time limit

### 参见

- MongoDB\Driver\Manager::executeCommand() - Execute a database command
- MongoDB\Driver\Cursor

## 目录

- MongoDB\Driver\Command::__construct — Create a new Command

# The MongoDB\Driver\Query class

(mongodb >=1.0.0)

## 简介

The MongoDB\Driver\Query class is a value object that represents a database query.

## 类摘要

final class MongoDB\Driver\Query {
/* 方法 */
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

### 说明

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().

### 参数

`filter` (array|object)
  The » query predicate. An empty predicate will match all documents in the collection.

  > 注意: When evaluating query criteria, MongoDB compares types and values according to its own » comparison rules for BSON types, which differs from PHP's comparison and type juggling rules. When matching a special BSON type the query criteria should use the respective BSON class (e.g. use MongoDB\BSON\ObjectId to match an » ObjectId).

`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 | » Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. When specifying collation, the `"locale"` field is mandatory; all other collation fields are optional. For descriptions of the fields, see » Collation Document. If the collation is unspecified but the collection has a default collation, the operation uses the collation specified for the collection. If no collation is specified for the collection or for the operation, MongoDB uses the simple binary comparison used in prior versions for string comparisons. This option is available in MongoDB 3.4+ and will result in an exception at execution time if specified for an older server version.
  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 | Map of parameter names and values. Values must be constant or closed expressions that do not reference document fields. Parameters can then be accessed as variables in an aggregate expression context (e.g. `$$var`). This option is available in MongoDB 5.0+ and will result in an exception at execution time if specified for an older server version.
  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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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);
    }

    ?>

### 参见

- MongoDB\Driver\Manager::executeQuery() - Execute a database query
- MongoDB\Driver\Cursor

## 目录

- MongoDB\Driver\Query::__construct — Create a new Query

# The MongoDB\Driver\BulkWrite class

(mongodb >=1.0.0)

## 简介

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.

## 类摘要

final class MongoDB\Driver\BulkWrite implements Countable {
/* 方法 */
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
}

## 示例

示例 #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.

示例 #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());

    ?>

以上示例会输出：

    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 fullfilled, 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]);
    /* ... */

    ?>

以上示例会输出：

    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)

## 参见

- 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

### 说明

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().

### 参数

`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 | Map of parameter names and values. Values must be constant or closed expressions that do not reference document fields. Parameters can then be accessed as variables in an aggregate expression context (e.g. `$$var`). This option is available in MongoDB 5.0+ and will result in an exception at execution time if specified for an older server version.
  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`

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 1.14.0 | Added the `"comment"` and `"let"` options.
PECL mongodb 1.1.0 | Added the `"bypassDocumentValidation"` option.

### 示例

示例 #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());

    ?>

以上示例会输出：

    Inserted 2 document(s)
    Updated  1 document(s)
    Upserted 1 document(s)
    Deleted  1 document(s)

### 参见

- 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

### 说明

public function MongoDB\Driver\BulkWrite::count(): int

Returns the number of write operations added to the MongoDB\Driver\BulkWrite object.

### 参数

此函数没有参数。

### 返回值

Returns number of write operations added to the MongoDB\Driver\BulkWrite object.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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));

    ?>

以上示例会输出：

    int(4)

# MongoDB\Driver\BulkWrite::delete

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::delete — Add a delete operation to the bulk

### 说明

public function MongoDB\Driver\BulkWrite::delete(array|object `$filter`, ?array `$deleteOptions` = `null`): void

Adds a delete operation to the MongoDB\Driver\BulkWrite.

### 参数

`filter` (array|object)
  The » query predicate. An empty predicate will match all documents in the collection.

  > 注意: When evaluating query criteria, MongoDB compares types and values according to its own » comparison rules for BSON types, which differs from PHP's comparison and type juggling rules. When matching a special BSON type the query criteria should use the respective BSON class (e.g. use MongoDB\BSON\ObjectId to match an » ObjectId).

`deleteOptions`

  deleteOptions
  Option | Type | Description | Default
  --- | --- | --- | ---
  collation | array|object | » Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. When specifying collation, the `"locale"` field is mandatory; all other collation fields are optional. For descriptions of the fields, see » Collation Document. If the collation is unspecified but the collection has a default collation, the operation uses the collation specified for the collection. If no collation is specified for the collection or for the operation, MongoDB uses the simple binary comparison used in prior versions for string comparisons. This option is available in MongoDB 3.4+ and will result in an exception at execution time if specified for an older server version.
  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`

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 1.8.0 | Added the `"hint"` option.
PECL mongodb 1.2.0 | Added the `"collation"` option.

### 示例

示例 #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);

    ?>

### 参见

- 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

### 说明

public function MongoDB\Driver\BulkWrite::insert(array|object `$document`): mixed

Adds an insert operation to the MongoDB\Driver\BulkWrite.

### 参数

`document` (array|object)
  A document to insert.

### 返回值

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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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);

    ?>

以上示例的输出类似于：

    object(MongoDB\BSON\ObjectId)#3 (1) {
      ["oid"]=>
      string(24) "67f58058d1a0aa2fd80d55d0"
    }
    string(9) "custom-id"
    object(MongoDB\BSON\ObjectId)#4 (1) {
      ["oid"]=>
      string(24) "0123456789abcdef01234567"
    }

### 参见

- 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

### 说明

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.

### 参数

`filter` (array|object)
  The » query predicate. An empty predicate will match all documents in the collection.

  > 注意: When evaluating query criteria, MongoDB compares types and values according to its own » comparison rules for BSON types, which differs from PHP's comparison and type juggling rules. When matching a special BSON type the query criteria should use the respective BSON class (e.g. use MongoDB\BSON\ObjectId to match an » ObjectId).

`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 | » Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. When specifying collation, the `"locale"` field is mandatory; all other collation fields are optional. For descriptions of the fields, see » Collation Document. If the collation is unspecified but the collection has a default collation, the operation uses the collation specified for the collection. If no collation is specified for the collection or for the operation, MongoDB uses the simple binary comparison used in prior versions for string comparisons. This option is available in MongoDB 3.4+ and will result in an exception at execution time if specified for an older server version.
  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`

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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);

    ?>

### 参见

- MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations
- MongoDB\Driver\WriteResult

## 目录

- 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)

## 简介

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.

## 类摘要

final class MongoDB\Driver\BulkWriteCommand implements Countable {
/* 方法 */
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
}

## 示例

示例 #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());

    ?>

以上示例会输出：

    Inserted 3 document(s)
    Updated  1 document(s)

示例 #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());

    ?>

以上示例的输出类似于：

    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)

## 参见

- 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

### 说明

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().

### 参数

`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 | Map of parameter names and values. Values must be constant or closed expressions that do not reference document fields. Parameters can then be accessed as variables in an aggregate expression context (e.g. `$$var`). This option is available in MongoDB 5.0+ and will result in an exception at execution time if specified for an older server version.
  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`

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例会输出：

    Inserted 3 document(s)
    Updated  1 document(s)

### 参见

- 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

### 说明

public function MongoDB\Driver\BulkWriteCommand::count(): int

Returns the number of write operations added to the MongoDB\Driver\BulkWriteCommand object.

### 参数

此函数没有参数。

### 返回值

Returns number of write operations added to the MongoDB\Driver\BulkWriteCommand object.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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));

    ?>

以上示例会输出：

    int(4)

# MongoDB\Driver\BulkWriteCommand::deleteMany

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::deleteMany — Add a deleteMany operation

### 说明

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.

### 参数

`namespace` (string)
  A fully qualified namespace (e.g. `"databaseName.collectionName"`).
`filter` (array|object)
  The » query predicate. An empty predicate will match all documents in the collection.

  > 注意: When evaluating query criteria, MongoDB compares types and values according to its own » comparison rules for BSON types, which differs from PHP's comparison and type juggling rules. When matching a special BSON type the query criteria should use the respective BSON class (e.g. use MongoDB\BSON\ObjectId to match an » ObjectId).

`options`

  options
  Option | Type | Description | Default
  --- | --- | --- | ---
  collation | array|object | » Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. When specifying collation, the `"locale"` field is mandatory; all other collation fields are optional. For descriptions of the fields, see » Collation Document. If the collation is unspecified but the collection has a default collation, the operation uses the collation specified for the collection. If no collation is specified for the collection or for the operation, MongoDB uses the simple binary comparison used in prior versions for string comparisons. This option is available in MongoDB 3.4+ and will result in an exception at execution time if specified for an older server version.
  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.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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);

    ?>

### 参见

- 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

### 说明

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.

### 参数

`namespace` (string)
  A fully qualified namespace (e.g. `"databaseName.collectionName"`).
`filter` (array|object)
  The » query predicate. An empty predicate will match all documents in the collection.

  > 注意: When evaluating query criteria, MongoDB compares types and values according to its own » comparison rules for BSON types, which differs from PHP's comparison and type juggling rules. When matching a special BSON type the query criteria should use the respective BSON class (e.g. use MongoDB\BSON\ObjectId to match an » ObjectId).

`options`

  options
  Option | Type | Description | Default
  --- | --- | --- | ---
  collation | array|object | » Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. When specifying collation, the `"locale"` field is mandatory; all other collation fields are optional. For descriptions of the fields, see » Collation Document. If the collation is unspecified but the collection has a default collation, the operation uses the collation specified for the collection. If no collation is specified for the collection or for the operation, MongoDB uses the simple binary comparison used in prior versions for string comparisons. This option is available in MongoDB 3.4+ and will result in an exception at execution time if specified for an older server version.
  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.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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);

    ?>

### 参见

- 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

### 说明

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`.

### 参数

`namespace` (string)
  A fully qualified namespace (e.g. `"databaseName.collectionName"`).
`document` (array|object)
  A document to insert.

### 返回值

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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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);

    ?>

以上示例的输出类似于：

    object(MongoDB\BSON\ObjectId)#3 (1) {
      ["oid"]=>
      string(24) "67f58058d1a0aa2fd80d55d0"
    }
    string(9) "custom-id"
    object(MongoDB\BSON\ObjectId)#4 (1) {
      ["oid"]=>
      string(24) "0123456789abcdef01234567"
    }

### 参见

- 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

### 说明

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.

### 参数

`namespace` (string)
  A fully qualified namespace (e.g. `"databaseName.collectionName"`).
`filter` (array|object)
  The » query predicate. An empty predicate will match all documents in the collection.

  > 注意: When evaluating query criteria, MongoDB compares types and values according to its own » comparison rules for BSON types, which differs from PHP's comparison and type juggling rules. When matching a special BSON type the query criteria should use the respective BSON class (e.g. use MongoDB\BSON\ObjectId to match an » ObjectId).

`replacement` (array|object)
  A replacement document.
`options`

  options
  Option | Type | Description | Default
  --- | --- | --- | ---
  collation | array|object | » Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. When specifying collation, the `"locale"` field is mandatory; all other collation fields are optional. For descriptions of the fields, see » Collation Document. If the collation is unspecified but the collection has a default collation, the operation uses the collation specified for the collection. If no collation is specified for the collection or for the operation, MongoDB uses the simple binary comparison used in prior versions for string comparisons. This option is available in MongoDB 3.4+ and will result in an exception at execution time if specified for an older server version.
  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`

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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);

    ?>

### 参见

- 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

### 说明

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.

### 参数

`namespace` (string)
  A fully qualified namespace (e.g. `"databaseName.collectionName"`).
`filter` (array|object)
  The » query predicate. An empty predicate will match all documents in the collection.

  > 注意: When evaluating query criteria, MongoDB compares types and values according to its own » comparison rules for BSON types, which differs from PHP's comparison and type juggling rules. When matching a special BSON type the query criteria should use the respective BSON class (e.g. use MongoDB\BSON\ObjectId to match an » ObjectId).

`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 | » Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. When specifying collation, the `"locale"` field is mandatory; all other collation fields are optional. For descriptions of the fields, see » Collation Document. If the collation is unspecified but the collection has a default collation, the operation uses the collation specified for the collection. If no collation is specified for the collection or for the operation, MongoDB uses the simple binary comparison used in prior versions for string comparisons. This option is available in MongoDB 3.4+ and will result in an exception at execution time if specified for an older server version.
  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`

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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);

    ?>

### 参见

- 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

### 说明

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.

### 参数

`namespace` (string)
  A fully qualified namespace (e.g. `"databaseName.collectionName"`).
`filter` (array|object)
  The » query predicate. An empty predicate will match all documents in the collection.

  > 注意: When evaluating query criteria, MongoDB compares types and values according to its own » comparison rules for BSON types, which differs from PHP's comparison and type juggling rules. When matching a special BSON type the query criteria should use the respective BSON class (e.g. use MongoDB\BSON\ObjectId to match an » ObjectId).

`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 | » Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. When specifying collation, the `"locale"` field is mandatory; all other collation fields are optional. For descriptions of the fields, see » Collation Document. If the collation is unspecified but the collection has a default collation, the operation uses the collation specified for the collection. If no collation is specified for the collection or for the operation, MongoDB uses the simple binary comparison used in prior versions for string comparisons. This option is available in MongoDB 3.4+ and will result in an exception at execution time if specified for an older server version.
  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`

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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);

    ?>

### 参见

- 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

## 目录

- 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)

## 简介

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.

## 类摘要

final class MongoDB\Driver\Session {
/* 常量 */
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;
/* 方法 */
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
}

## 预定义常量

`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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\RuntimeException if the transaction could not be aborted (e.g. a transaction was not started).

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

`operationTime`
  The operation time is a logical timestamp. Typically, this value will be obtained by calling MongoDB\Driver\Session::getOperationTime() on another session object.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- 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 commited (e.g. a transaction was not started).

### 参见

- 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)

### 说明

final private function MongoDB\Driver\Session::__construct()

MongoDB\Driver\Session objects are returned by MongoDB\Driver\Manager::startSession() and cannot be constructed directly.

### 参数

此函数没有参数。

### 参见

- 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

### 说明

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.

> 注意: Sessions are also closed during garbage collection. It should not be necessary to call this method under normal circumstances.

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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`.

### 参数

此函数没有参数。

### 返回值

Returns the cluster time for this session, or `null` if the session has no cluster time.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the logical session ID for this session.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Session::getOperationTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::getOperationTime — Returns the operation time for this session

### 说明

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`

### 参数

此函数没有参数。

### 返回值

Returns the operation time for this session, or `null` if the session has no operation time.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the MongoDB\Driver\Server to which this session is pinned, or `null` if the session is not pinned to any server.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Session::getTransactionOptions

(mongodb >=1.7.0)

MongoDB\Driver\Session::getTransactionOptions — Returns options for the currently running transaction

### 说明

final public function MongoDB\Driver\Session::getTransactionOptions(): ?array

Returns options for the currently running transaction.

### 参数

此函数没有参数。

### 返回值

Returns a array containing current transaction options, or `null` if no transaction is running.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\Driver\Session::getTransactionState(): string

Returns the transaction state for this session.

### 参数

此函数没有参数。

### 返回值

Returns the current transaction state for this session.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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).

### 参数

此函数没有参数。

### 返回值

Returns whether the session has been marked as dirty.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Session::isInTransaction

(mongodb >=1.6.0)

MongoDB\Driver\Session::isInTransaction — Returns whether a multi-document transaction is in progress

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns `true` if a transaction is currently in progress for this session, and `false` otherwise.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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().

### 参数

`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 | The maximum amount of time in milliseconds to allow a single `commitTransaction` command to run. If specified, `maxCommitTimeMS` must be a signed 32-bit integer greater than or equal to zero.
  readConcern | MongoDB\Driver\ReadConcern | A read concern to apply to the operation. This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version.
  readPreference | MongoDB\Driver\ReadPreference | A read preference to use for selecting a server for the operation.
  writeConcern | MongoDB\Driver\WriteConcern | A write concern to apply to the operation.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- 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).

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 1.6.0 | The `"maxCommitTimeMS"` option was added.

### 参见

- 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

## 目录

- 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)

## 简介

The MongoDB\Driver\ClientEncryption class handles creation of data keys for client-side encryption, as well as manually encrypting and decrypting values.

## 类摘要

final class MongoDB\Driver\ClientEncryption {
/* 常量 */
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;
/* 方法 */
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
}

## 预定义常量

`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`.

  > 注意: 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`.

## 更新日志

版本 | 说明
--- | ---
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`.

## 参见

- MongoDB\Driver\Manager::createClientEncryption()

# MongoDB\Driver\ClientEncryption::addKeyAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::addKeyAltName — Adds an alternate name to a key document

### 说明

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`.

### 参数

`keyId`
  A MongoDB\BSON\Binary instance with subtype 4 (UUID) identifying the key document.
`keyAltName`
  Alternate name to add to the key document.

### 返回值

Returns the previous version of the key document, or `null` if no document matched.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### 参见

- 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

### 说明

final public function MongoDB\Driver\ClientEncryption::__construct(array `$options`)

Constructs a new MongoDB\Driver\ClientEncryption object with the specified options.

### 参数

`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 | A fully qualified namespace (e.g. `"databaseName.collectionName"`) denoting the collection that contains all data keys used for encryption and decryption. This option is required.
  kmsProviders | array | A document containing the configuration for one or more KMS providers, which are used to encrypt data keys. Supported providers include `"aws"`, `"azure"`, `"gcp"`, `"kmip"`, and `"local"` and at least one must be specified. If an empty document is specified for `"aws"`, `"azure"`, or `"gcp"`, the driver will attempt to configure the provider using » Automatic Credentials. The format for `"aws"` is as follows:
      aws: {
          accessKeyId: <string>,
          secretAccessKey: <string>,
          sessionToken: <optional string>
      }
  The format for `"azure"` is as follows:
      azure: {
          tenantId: <string>,
          clientId: <string>,
          clientSecret: <string>,
          identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"
      }
  The format for `"gcp"` is as follows:
      gcp: {
          email: <string>,
          privateKey: <base64 string>|<MongoDB\BSON\Binary>,
          endpoint: <optional string> // Defaults to "oauth2.googleapis.com"
      }
  The format for `"kmip"` is as follows:
      kmip: {
          endpoint: <string>
      }
  The format for `"local"` is as follows:
      local: {
          // 96-byte master key used to encrypt/decrypt data keys
          key: <base64 string>|<MongoDB\BSON\Binary>
      }
  tlsOptions | array | A document containing the TLS configuration for one or more KMS providers. Supported providers include `"aws"`, `"azure"`, `"gcp"`, and `"kmip"`. All providers support the following options:
      <provider>: {
          tlsCaFile: <optional string>,
          tlsCertificateKeyFile: <optional string>,
          tlsCertificateKeyFilePassword: <optional string>,
          tlsDisableOCSPEndpointCheck: <optional bool>
      }

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\RuntimeException if the extension was compiled without libmongocrypt support

### 更新日志

版本 | 说明
--- | ---
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.

### 参见

- 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

### 说明

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.

### 参数

`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 options
  Option | Type | Description
  --- | --- | ---
  region | string | Required.
  key | string | Required. The Amazon Resource Name (ARN) to the AWS customer master key (CMK).
  endpoint | string | Optional. An alternate host identifier to send KMS requests to. May include port number.
  `"azure"` provider options
  Option | Type | Description
  --- | --- | ---
  keyVaultEndpoint | string | Required. Host with optional port (e.g. "example.vault.azure.net").
  keyName | string | Required.
  keyVersion | string | Optional. A specific version of the named key. Defaults to using the key's primary version.
  `"gcp"` provider options
  Option | Type | Description
  --- | --- | ---
  projectId | string | Required.
  location | string | Required.
  keyRing | string | Required.
  keyName | string | Required.
  keyVersion | string | Optional. A specific version of the named key. Defaults to using the key's primary version.
  endpoint | string | Optional. Host with optional port. Defaults to "cloudkms.googleapis.com".
  `"kmip"` provider options
  Option | Type | Description
  --- | --- | ---
  keyId | string | Optional. Unique identifier to a 96-byte KMIP secret data managed object. If unspecified, the driver creates a random 96-byte KMIP secret data managed object.
  endpoint | string | Optional. Host with optional port.
  delegated | bool | Optional. If true, this key should be decrypted by the KMIP server.
  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.

### 返回值

Returns the identifier of the new key as a MongoDB\BSON\Binary object with subtype 4 (UUID).

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### 更新日志

版本 | 说明
--- | ---
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

### 说明

final public function MongoDB\Driver\ClientEncryption::decrypt(MongoDB\BSON\Binary `$value`): mixed

Decrypts the value.

### 参数

`value`
  A MongoDB\BSON\Binary instance with subtype 6 containing the encrypted value.

### 返回值

Returns the decrypted value as it was passed to MongoDB\Driver\ClientEncryption::encrypt().

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\EncryptionException if an error occurs while decrypting the value

### 参见

- MongoDB\Driver\ClientEncryption::encrypt() - Encrypt a value

# MongoDB\Driver\ClientEncryption::deleteKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::deleteKey — Deletes a key document

### 说明

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.

### 参数

`keyId`
  A MongoDB\BSON\Binary instance with subtype 4 (UUID) identifying the key document.

### 返回值

Returns the result of the internal `deleteOne` operation on the key vault collection.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

# MongoDB\Driver\ClientEncryption::encrypt

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::encrypt — Encrypt a value

### 说明

final public function MongoDB\Driver\ClientEncryption::encrypt(mixed `$value`, ?array `$options` = `null`): MongoDB\BSON\Binary

Encrypts the value.

### 参数

`value`
  The value to be encrypted. Any value that can be inserted into MongoDB can be encrypted using this method.
`options`

  Encryption options
  Option | Type | Description
  --- | --- | ---
  algorithm | string | The encryption algorithm to be used. This option is required. Specify one of the following ClientEncryption constants: `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.

### 返回值

Returns the encrypted value as MongoDB\BSON\Binary object with subtype 6.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\EncryptionException if an error occurs while encrypting the value

### 更新日志

版本 | 说明
--- | ---
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.

### 参见

- 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

### 说明

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`.

> 注意: The extension does not yet support range queries for Decimal128 BSON field types.

### 参数

`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`

  Encryption options
  Option | Type | Description
  --- | --- | ---
  algorithm | string | The encryption algorithm to be used. This option is required. Specify one of the following ClientEncryption constants: `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.

### 返回值

Returns the encrypted expression as an object.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\EncryptionException if an error occurs while encrypting the expression

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 1.20.0 | Added the `"trimFactor"` range option. The `"sparsity"` range option is now optional.

### 参见

- 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

### 说明

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`.

### 参数

`keyId`
  A MongoDB\BSON\Binary instance with subtype 4 (UUID) identifying the key document.

### 返回值

Returns the key document, or `null` if no document matched.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- 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

### 说明

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`.

### 参数

`keyAltName`
  Alternate name for the key document.

### 返回值

Returns the key document, or `null` if no document matched.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### 参见

- 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

### 说明

final public function MongoDB\Driver\ClientEncryption::getKeys(): MongoDB\Driver\Cursor

Finds all key documents in the key vault collection.

### 参数

此函数没有参数。

### 返回值

Returns MongoDB\Driver\Cursor on success.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- 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

### 说明

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`.

### 参数

`keyId`
  A MongoDB\BSON\Binary instance with subtype 4 (UUID) identifying the key document.
`keyAltName`
  Alternate name to remove from the key document.

### 返回值

Returns the previous version of the key document, or `null` if no document matched.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### 参见

- 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

### 说明

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.

### 参数

`filter` (array|object)
  The » query predicate. An empty predicate will match all documents in the collection.

  > 注意: When evaluating query criteria, MongoDB compares types and values according to its own » comparison rules for BSON types, which differs from PHP's comparison and type juggling rules. When matching a special BSON type the query criteria should use the respective BSON class (e.g. use MongoDB\BSON\ObjectId to match an » ObjectId).

`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 options
  Option | Type | Description
  --- | --- | ---
  region | string | Required.
  key | string | Required. The Amazon Resource Name (ARN) to the AWS customer master key (CMK).
  endpoint | string | Optional. An alternate host identifier to send KMS requests to. May include port number.
  `"azure"` provider options
  Option | Type | Description
  --- | --- | ---
  keyVaultEndpoint | string | Required. Host with optional port (e.g. "example.vault.azure.net").
  keyName | string | Required.
  keyVersion | string | Optional. A specific version of the named key. Defaults to using the key's primary version.
  `"gcp"` provider options
  Option | Type | Description
  --- | --- | ---
  projectId | string | Required.
  location | string | Required.
  keyRing | string | Required.
  keyName | string | Required.
  keyVersion | string | Optional. A specific version of the named key. Defaults to using the key's primary version.
  endpoint | string | Optional. Host with optional port. Defaults to "cloudkms.googleapis.com".
  `"kmip"` provider options
  Option | Type | Description
  --- | --- | ---
  keyId | string | Optional. Unique identifier to a 96-byte KMIP secret data managed object. If unspecified, the driver creates a random 96-byte KMIP secret data managed object.
  endpoint | string | Optional. Host with optional port.
  delegated | bool | Optional. If true, this key should be decrypted by the KMIP server.

### 返回值

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`.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- 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.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 1.20.0 | Added `"delegated"` to the KMIP provider masterKey options.

## 目录

- 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)

## 简介

## 类摘要

final class MongoDB\Driver\ServerApi implements MongoDB\BSON\Serializable, Serializable {
/* 常量 */
const string MongoDB\Driver\ServerAPI::V1 = "1";
/* 方法 */
final public function bsonSerialize(): stdClass
final public function __construct(string `$version`, ?bool `$strict` = `null`, ?bool `$deprecationErrors` = `null`)
}

## 预定义常量

`MongoDB\Driver\ServerApi::V1`
  Server API version 1.

## 示例

示例 #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";

    ?>

以上示例会输出：

    4.9.0-alpha7-49-gb968ca0

示例 #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";

    ?>

以上示例会输出：

    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

### 说明

final public function MongoDB\Driver\ServerApi::bsonSerialize(): stdClass

### 参数

此函数没有参数。

### 返回值

Returns an object for serializing the ServerApi as BSON.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

`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.

## 目录

- 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)

## 简介

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.

## 类摘要

final class MongoDB\Driver\WriteConcern implements MongoDB\BSON\Serializable, Serializable {
/* 常量 */
const string MAJORITY = "majority";
/* 属性 */
public readonly string|int|null $w;
public readonly ?bool $j;
public readonly int $wtimeout;
/* 方法 */
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
}

## 属性

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.

## 预定义常量

`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.

## 更新日志

版本 | 说明
--- | ---
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

### 说明

final public function MongoDB\Driver\WriteConcern::bsonSerialize(): stdClass

### 参数

此函数没有参数。

### 返回值

Returns an object for serializing the WriteConcern as BSON.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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();

    ?>

以上示例的输出类似于：

    object(stdClass)#2 (1) {
      ["w"]=>
      string(8) "majority"
    }

    { "w" : "majority" }

示例 #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();

    ?>

以上示例的输出类似于：

    object(stdClass)#2 (3) {
      ["w"]=>
      int(2)
      ["j"]=>
      bool(true)
      ["wtimeout"]=>
      int(1000)
    }

    { "w" : 2, "j" : true, "wtimeout" : 1000 }

### 参见

- 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

### 说明

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.

### 参数

`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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- 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.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 1.7.0 | The `wTimeout` parameter now accepts 64-bit values.

### 示例

示例 #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);

    ?>

### 参见

- » Write Concern reference

# MongoDB\Driver\WriteConcern::getJournal

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getJournal — Returns the WriteConcern's "journal" option

### 说明

final public function MongoDB\Driver\WriteConcern::getJournal(): ?bool

### 参数

此函数没有参数。

### 返回值

Returns the WriteConcern's "journal" option.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例会输出：

    NULL
    bool(true)
    bool(false)

### 参见

- » Write Concern reference

# MongoDB\Driver\WriteConcern::getW

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getW — Returns the WriteConcern's "w" option

### 说明

final public function MongoDB\Driver\WriteConcern::getW(): string|int|null

### 参数

此函数没有参数。

### 返回值

Returns the WriteConcern's "w" option.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例会输出：

    int(1)
    string(8) "majority"

### 参见

- » Write Concern reference

# MongoDB\Driver\WriteConcern::getWtimeout

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getWtimeout — Returns the WriteConcern's "wtimeout" option

### 说明

final public function MongoDB\Driver\WriteConcern::getWtimeout(): int

### 参数

此函数没有参数。

### 返回值

Returns the WriteConcern's "wtimeout" option.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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());

    ?>

以上示例会输出：

    int(0)
    int(3000)

### 参见

- » Write Concern reference

# MongoDB\Driver\WriteConcern::isDefault

(mongodb >=1.3.0)

MongoDB\Driver\WriteConcern::isDefault — Checks if this is the default write concern

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns `true` if this is the default write concern and `false` otherwise.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例会输出：

    bool(false)
    bool(false)
    bool(true)

### 参见

- MongoDB\Driver\Manager::getWriteConcern() - Return the WriteConcern for the Manager
- » Modify Default Write Concern in the MongoDB manual
- » Write Concern reference

## 目录

- 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)

## 简介

## 类摘要

final class MongoDB\Driver\ReadPreference implements MongoDB\BSON\Serializable, Serializable {
/* 属性 */
public readonly string $mode;
public readonly ?array $tags;
public readonly int $maxStalenessSeconds;
public readonly ?object $hedge;
/* 常量 */
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;
/* 方法 */
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
}

## 属性

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.
  警告

  This property is deprecated as hedged reads are deprecated in MongoDB 8.0.

## 预定义常量

`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.

## 更新日志

版本 | 说明
--- | ---
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

### 说明

final public function MongoDB\Driver\ReadPreference::bsonSerialize(): stdClass

### 参数

此函数没有参数。

### 返回值

Returns an object for serializing the ReadPreference as BSON.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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();

    ?>

以上示例的输出类似于：

    object(stdClass)#2 (1) {
      ["mode"]=>
      string(7) "primary"
    }

    { "mode" : "primary" }

示例 #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();

    ?>

以上示例的输出类似于：

    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" }, {  } ] }

示例 #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();

    ?>

以上示例的输出类似于：

    object(stdClass)#2 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["maxStalenessSeconds"]=>
      int(120)
    }

    { "mode" : "secondary", "maxStalenessSeconds" : 120 }

### 参见

- 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

### 说明

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.

### 参数

`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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- 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.

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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]]));

    ?>

以上示例会输出：

    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)
      }
    }

### 参见

- » Read Preference reference

# MongoDB\Driver\ReadPreference::getHedge

(mongodb >=1.8.0)

MongoDB\Driver\ReadPreference::getHedge — Returns the ReadPreference's "hedge" option

### 说明

final public function MongoDB\Driver\ReadPreference::getHedge(): ?object

### 参数

此函数没有参数。

### 返回值

Returns the ReadPreference's "hedge" option.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- » Read Preference reference

# MongoDB\Driver\ReadPreference::getMaxStalenessSeconds

(mongodb >=1.2.0)

MongoDB\Driver\ReadPreference::getMaxStalenessSeconds — Returns the ReadPreference's "maxStalenessSeconds" option

### 说明

final public function MongoDB\Driver\ReadPreference::getMaxStalenessSeconds(): int

### 参数

此函数没有参数。

### 返回值

Returns the ReadPreference's "maxStalenessSeconds" option. If no max staleness has been specified, `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS` will be returned.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例会输出：

    int(-1)
    int(-1)
    int(90)
    int(1000)

### 参见

- » Read Preference reference

# MongoDB\Driver\ReadPreference::getMode

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::getMode — Returns the ReadPreference's "mode" option

警告

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.

### 说明

final public function MongoDB\Driver\ReadPreference::getMode(): int

### 参数

此函数没有参数。

### 返回值

Returns the ReadPreference's "mode" option.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此方法已被移除。

### 示例

示例 #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());

    ?>

以上示例会输出：

    int(1)
    int(5)
    int(2)
    int(6)
    int(10)

### 参见

- 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

### 说明

final public function MongoDB\Driver\ReadPreference::getModeString(): string

### 参数

此函数没有参数。

### 返回值

Returns the ReadPreference's "mode" option as a string.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例会输出：

    string(7) "primary"
    string(16) "primaryPreferred"
    string(9) "secondary"
    string(18) "secondaryPreferred"
    string(7) "nearest"

### 参见

- 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

### 说明

final public function MongoDB\Driver\ReadPreference::getTagSets(): array

### 参数

此函数没有参数。

### 返回值

Returns the ReadPreference's "tagSets" option.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例会输出：

    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) {
      }
    }

### 参见

- » Read Preference reference

## 目录

- 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)

## 简介

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.

## 类摘要

final class MongoDB\Driver\ReadConcern implements MongoDB\BSON\Serializable, Serializable {
/* 属性 */
public readonly ?string $level;
/* 常量 */
const string AVAILABLE = "available";
const string LINEARIZABLE = "linearizable";
const string LOCAL = "local";
const string MAJORITY = "majority";
const string SNAPSHOT = "snapshot";
/* 方法 */
final public function bsonSerialize(): stdClass
final public function __construct(?string `$level` = `null`)
final public function getLevel(): ?string
final public function isDefault(): bool
}

## 属性

level
  The read concern level. `null` if no level was specified.

## 预定义常量

`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.
  小技巧

  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"`.

## 更新日志

版本 | 说明
--- | ---
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.

## 参见

- » Read Concern reference

# MongoDB\Driver\ReadConcern::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\ReadConcern::bsonSerialize — Returns an object for BSON serialization

### 说明

final public function MongoDB\Driver\ReadConcern::bsonSerialize(): stdClass

### 参数

此函数没有参数。

### 返回值

Returns an object for serializing the ReadConcern as BSON.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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();

    ?>

以上示例的输出类似于：

    object(stdClass)#2 (0) {
    }

    { }

示例 #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();

    ?>

以上示例的输出类似于：

    object(stdClass)#2 (1) {
      ["level"]=>
      string(5) "local"
    }

    { "level" : "local" }

### 参见

- 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

### 说明

final public function MongoDB\Driver\ReadConcern::__construct(?string `$level` = `null`)

Constructs a new MongoDB\Driver\ReadConcern, which is an immutable value object.

### 参数

`level`
  The » read concern level. You may use, but are not limited to, one of the class constants.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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);

    ?>

### 参见

- » Read Concern reference

# MongoDB\Driver\ReadConcern::getLevel

(mongodb >=1.0.0)

MongoDB\Driver\ReadConcern::getLevel — Returns the ReadConcern's "level" option

### 说明

final public function MongoDB\Driver\ReadConcern::getLevel(): ?string

### 参数

此函数没有参数。

### 返回值

Returns the ReadConcern's "level" option.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例会输出：

    NULL
    string(5) "local"
    string(8) "majority"

### 参见

- » Read Concern reference

# MongoDB\Driver\ReadConcern::isDefault

(mongodb >=1.3.0)

MongoDB\Driver\ReadConcern::isDefault — Checks if this is the default read concern

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns `true` if this is the default read concern and `false` otherwise.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例会输出：

    bool(true)
    bool(false)
    bool(false)
    bool(true)

### 参见

- MongoDB\Driver\Manager::getReadConcern() - Return the ReadConcern for the Manager
- » Read Concern reference

## 目录

- 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)

## 简介

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.

## 类摘要

final class MongoDB\Driver\Cursor implements MongoDB\Driver\CursorInterface {
/* 方法 */
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
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 1.9.0 | Implements Iterator.
PECL mongodb 1.6.0 | Implements MongoDB\Driver\CursorInterface, which extends Traversable.

## 示例

示例 #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);
    }

    ?>

以上示例的输出类似于：

    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
    )

示例 #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.

> 注意: 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.

## 错误／异常

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.
- Throws MongoDB\Driver\Exception\UnexpectedValueException if the input did not contain exactly one BSON document. Possible reasons include, but are not limited to, invalid BSON, extra data (after reading one BSON document), or an unexpected » libbson error.

# MongoDB\Driver\Cursor::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::__construct — Create a new Cursor (not used)

### 说明

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.

### 参数

此函数没有参数。

### 参见

- 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

### 说明

public function MongoDB\Driver\Cursor::current(): array|object|null

### 参数

此函数没有参数。

### 返回值

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.

### 参见

- Iterator::current() - 返回当前元素

# MongoDB\Driver\Cursor::getId

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::getId — Returns the ID for this cursor

### 说明

final public function MongoDB\Driver\Cursor::getId(): MongoDB\BSON\Int64

Returns the ID for this cursor, which uniquely identifies the cursor on the server.

### 参数

此函数没有参数。

### 返回值

Returns the ID for this cursor. The ID will be returned as a MongoDB\BSON\Int64 object.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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));

    ?>

以上示例的输出类似于：

    object(MongoDB\BSON\Int64)#5 (1) {
      ["integer"]=>
      string(11) "94810124093"
    }

### 参见

- MongoDB\BSON\Int64

# MongoDB\Driver\Cursor::getServer

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::getServer — Returns the server associated with this cursor

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the MongoDB\Driver\Server associated with this cursor.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例的输出类似于：

    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)
    }

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns `true` if there are definitely no additional results available on the cursor, and `false` otherwise.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例会输出：

    bool(false)
    bool(false)
    bool(false)
    bool(true)

### 参见

- » 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

### 说明

public function MongoDB\Driver\Cursor::key(): int

### 参数

此函数没有参数。

### 返回值

The current result's numeric index within the cursor.

### 参见

- Iterator::key() - 返回当前元素的键

# MongoDB\Driver\Cursor::next

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::next — Advances the cursor to the next result

### 说明

public function MongoDB\Driver\Cursor::next(): void

### 参数

此函数没有参数。

### 返回值

Moves the current position to the next element in the cursor.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.

### 参见

- Iterator::next() - 向前移动到下一个元素

# MongoDB\Driver\Cursor::rewind

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::rewind — Rewind the cursor to the first result

### 说明

public function MongoDB\Driver\Cursor::rewind(): void

If the cursor has advanced beyond its first position, it can no longer be rewound.

### 参数

此函数没有参数。

### 返回值

`null`.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\LogicException if this method is called after the cursor has advanced beyond its first position.

### 参见

- Iterator::rewind() - 返回到迭代器的第一个元素

# MongoDB\Driver\Cursor::setTypeMap

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::setTypeMap — Sets a type map to use for BSON unserialization

### 说明

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.

### 参数

`typeMap` (array)
  Type map configuration.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

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.

### 示例

示例 #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);
    }

    ?>

以上示例的输出类似于：

    array(2) {
      ["_id"]=>
      object(MongoDB\BSON\ObjectId)#6 (1) {
        ["oid"]=>
        string(24) "56424fb76118fd3267180741"
      }
      ["x"]=>
      int(1)
    }

### 参见

- Persisting Data

# MongoDB\Driver\Cursor::toArray

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::toArray — Returns an array containing all results for this cursor

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns an array containing all results for this cursor.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例的输出类似于：

    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)
      }
    }

### 参见

- 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

### 说明

public function MongoDB\Driver\Cursor::valid(): bool

### 参数

此函数没有参数。

### 返回值

`true` if the current cursor position is valid, `false` otherwise.

### 参见

- Iterator::valid() - 检查当前位置是否有效

## 目录

- 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)

## 简介

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().

警告

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.

## 类摘要

final class MongoDB\Driver\CursorId implements Serializable, Stringable {
/* 方法 */
final private function __construct()
final public function __toString(): string
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此类已被移除。
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)

### 说明

final private function MongoDB\Driver\CursorId::__construct()

MongoDB\Driver\CursorId objects are returned from MongoDB\Driver\Cursor::getId() and cannot be constructed directly.

### 参数

此函数没有参数。

### 参见

- 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

### 说明

final public function MongoDB\Driver\CursorId::__toString(): string

Returns the string representation of the cursor ID.

### 参数

此函数没有参数。

### 返回值

Returns the string representation of the cursor ID.

### 示例

示例 #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());

    ?>

以上示例的输出类似于：

    string(11) "98061641158"

### 参见

- MongoDB\Driver\Cursor::getId() - Returns the ID for this cursor

## 目录

- 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)

## 简介

This interface is implemented by MongoDB\Driver\Cursor to be used as a parameter, return, or property type in userland classes.

## 类摘要

class MongoDB\Driver\CursorInterface implements Iterator {
/* 方法 */
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
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | This interface now extends Iterator. Return types previously declared as tentative are now enforced.
PECL mongodb 1.15.0 | 在 PHP 8.0 及更高版本中，方法的返回类型被声明为暂定（tentative）， 这会导致在实现该接口但未声明相应返回类型的代码中触发弃用提示。 可以添加 `#[ReturnTypeWillChange]` 属性来消除该弃用提示。

# MongoDB\Driver\CursorInterface::getId

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::getId — Returns the ID for this cursor

### 说明

abstract public function MongoDB\Driver\CursorInterface::getId(): MongoDB\BSON\Int64

Returns the ID for this cursor, which uniquely identifies the cursor on the server.

### 参数

此函数没有参数。

### 返回值

Returns the ID for this cursor.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
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.

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the MongoDB\Driver\Server associated with this cursor.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns `true` if additional results are not available, and `false` otherwise.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

`typeMap` (array)
  Type map configuration.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns an array containing all results for this cursor.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

## 目录

- 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)

## 简介

## 类摘要

final class MongoDB\Driver\Server {
/* 常量 */
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;
/* 方法 */
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
}

## 预定义常量

`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().

## 更新日志

版本 | 说明
--- | ---
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)

### 说明

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().

### 参数

此函数没有参数。

### 参见

- 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

### 说明

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.

### 参数

`namespace` (string)
  A fully qualified namespace (e.g. `"databaseName.collectionName"`).
`bulk` (MongoDB\Driver\BulkWrite)
  The write(s) to execute.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  session | MongoDB\Driver\Session | A session to associate with the operation.
  writeConcern | MongoDB\Driver\WriteConcern | A write concern to apply to the operation.

### 返回值

Returns MongoDB\Driver\WriteResult on success.

### 错误／异常

- 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.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used in combination with an unacknowledged write concern.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\BulkWriteException on any write failure (e.g. write error, failure to apply a write concern)
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### 更新日志

版本 | 说明
--- | ---
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 paramater 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.

### 注释

> 注意: It is the caller's responsibility to ensure that the server is capable of executing the write operation. For example, executing a write operation on a secondary (excluding its "local" database) will fail.

### 参见

- 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

### 说明

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.

### 参数

`bulk` (MongoDB\Driver\BulkWriteCommand)
  The write(s) to execute.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  session | MongoDB\Driver\Session | A session to associate with the operation.
  writeConcern | MongoDB\Driver\WriteConcern | A write concern to apply to the operation.

### 返回值

Returns MongoDB\Driver\BulkWriteCommandResult on success.

### 错误／异常

- 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.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used in combination with an unacknowledged write concern.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\BulkWriteCommandException on any write failure (e.g. command failure, write or write concern error)
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### 参见

- 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

### 说明

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.

> 注意: The `"readPreference"` option does not control the server to which the driver issues the operation; it will always be executed on this server object. Instead, it may be used when issuing the operation to a secondary (from a replica set connection, not standalone) or mongos node to ensure that the driver sets the wire protocol accordingly or adds the read preference to the operation, respectively.

### 参数

`db` (string)
  The name of the database on which to execute the command.
`command` (MongoDB\Driver\Command)
  The command to execute.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | A read concern to apply to the operation. This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version.
  readPreference | MongoDB\Driver\ReadPreference | A read preference to use for selecting a server for the operation.
  session | MongoDB\Driver\Session | A session to associate with the operation.
  writeConcern | MongoDB\Driver\WriteConcern | A write concern to apply to the operation.

  警告

  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().

### 返回值

Returns MongoDB\Driver\Cursor on success.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used with an associated transaction in combination with a `"readConcern"` or `"writeConcern"` option.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used in combination with an unacknowledged write concern.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command, issuing a write command to a secondary).

### 更新日志

版本 | 说明
--- | ---
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 paramater will still accept a MongoDB\Driver\ReadPreference object.

### 注释

> 注意: It is the caller's responsibility to ensure that the server is capable of executing the write operation. For example, executing a write operation on a secondary (excluding its "local" database) will fail.

### 参见

- 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

### 说明

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.

> 注意: The `"readPreference"` option does not control the server to which the driver issues the operation; it will always be executed on this server object. Instead, it may be used when issuing the operation to a secondary (from a replica set connection, not standalone) or mongos node to ensure that the driver sets the wire protocol accordingly or adds the read preference to the operation, respectively.

### 参数

`namespace` (string)
  A fully qualified namespace (e.g. `"databaseName.collectionName"`).
`query` (MongoDB\Driver\Query)
  The query to execute.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  readPreference | MongoDB\Driver\ReadPreference | A read preference to use for selecting a server for the operation.
  session | MongoDB\Driver\Session | A session to associate with the operation.

### 返回值

Returns MongoDB\Driver\Cursor on success.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid query operators).

### 更新日志

版本 | 说明
--- | ---
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 paramater will still accept a MongoDB\Driver\ReadPreference object.

### 参见

- 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

### 说明

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.

> 注意: The `"readPreference"` option does not control the server to which the driver issues the operation; it will always be executed on this server object. Instead, it may be used when issuing the operation to a secondary (from a replica set connection, not standalone) or mongos node to ensure that the driver sets the wire protocol accordingly or adds the read preference to the operation, respectively.

### 参数

`db` (string)
  The name of the database on which to execute the command.
`command` (MongoDB\Driver\Command)
  The command to execute.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | A read concern to apply to the operation. This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version.
  readPreference | MongoDB\Driver\ReadPreference | A read preference to use for selecting a server for the operation.
  session | MongoDB\Driver\Session | A session to associate with the operation.

  警告

  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().

### 返回值

Returns MongoDB\Driver\Cursor on success.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used with an associated transaction in combination with a `"readConcern"` or `"writeConcern"` option.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command).

### 参见

- 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

### 说明

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.

### 参数

`db` (string)
  The name of the database on which to execute the command.
`command` (MongoDB\Driver\Command)
  The command to execute.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | A read concern to apply to the operation. This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version.
  session | MongoDB\Driver\Session | A session to associate with the operation.
  writeConcern | MongoDB\Driver\WriteConcern | A write concern to apply to the operation.

  警告

  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().

### 返回值

Returns MongoDB\Driver\Cursor on success.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used with an associated transaction in combination with a `"readConcern"` or `"writeConcern"` option.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used in combination with an unacknowledged write concern.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command).

### 更新日志

版本 | 说明
--- | ---
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.

### 注释

> 注意: It is the caller's responsibility to ensure that the server is capable of executing the write operation. For example, executing a write operation on a secondary (excluding its "local" database) will fail.

### 参见

- 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

### 说明

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.

> 注意: 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.

### 参数

`db` (string)
  The name of the database on which to execute the command.
`command` (MongoDB\Driver\Command)
  The command to execute.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  session | MongoDB\Driver\Session | A session to associate with the operation.
  writeConcern | MongoDB\Driver\WriteConcern | A write concern to apply to the operation.

  警告

  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().

### 返回值

Returns MongoDB\Driver\Cursor on success.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used with an associated transaction in combination with a `"readConcern"` or `"writeConcern"` option.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"session"` option is used in combination with an unacknowledged write concern.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
- Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command).

### 更新日志

版本 | 说明
--- | ---
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.

### 注释

> 注意: It is the caller's responsibility to ensure that the server is capable of executing the write operation. For example, executing a write operation on a secondary (excluding its "local" database) will fail.

### 参见

- 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

### 说明

final public function MongoDB\Driver\Server::getHost(): string

Returns the hostname of this server.

### 参数

此函数没有参数。

### 返回值

Returns the hostname of this server.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #1 MongoDB\Driver\Server::getHost() example

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");
    $server = $manager->selectServer();

    var_dump($server->getHost());

    ?>

以上示例会输出：

    string(9) "localhost"

### 参见

- 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

### 说明

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.

> 注意: 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.

### 参数

此函数没有参数。

### 返回值

Returns an array of information describing this server.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例的输出类似于：

    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"
      }
    }

### 更新日志

版本 | 说明
--- | ---
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.

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

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).

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
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`.

### 示例

示例 #1 MongoDB\Driver\Server::getLatency() example

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");
    $server = $manager->selectServer();

    var_dump($server->getLatency());

    ?>

以上示例的输出类似于：

    int(592)

### 参见

- 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

### 说明

final public function MongoDB\Driver\Server::getPort(): int

Returns the port on which this server is listening.

### 参数

此函数没有参数。

### 返回值

Returns the port on which this server is listening.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #1 MongoDB\Driver\Server::getPort() example

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");
    $server = $manager->selectServer();

    var_dump($server->getPort());

    ?>

以上示例会输出：

    int(27017)

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns a MongoDB\Driver\ServerDescription for this server.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Server::getTags

(mongodb >=1.0.0)

MongoDB\Driver\Server::getTags — Returns an array of tags describing this server in a replica set

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns an array of tags used to describe this server in a replica set.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns an int denoting the type of this server.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\Driver\Server::isArbiter(): bool

Returns whether this server is an » arbiter member of a replica set.

### 参数

此函数没有参数。

### 返回值

Returns `true` if this server is an arbiter member of a replica set, and `false` otherwise.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\Driver\Server::isHidden(): bool

Returns whether this server is a » hidden member of a replica set.

### 参数

此函数没有参数。

### 返回值

Returns `true` if this server is a hidden member of a replica set, and `false` otherwise.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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`).

### 参数

此函数没有参数。

### 返回值

Returns `true` if this server is a passive member of a replica set, and `false` otherwise.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\Driver\Server::isPrimary(): bool

Returns whether this server is a » primary member of a replica set.

### 参数

此函数没有参数。

### 返回值

Returns `true` if this server is a primary member of a replica set, and `false` otherwise.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\Driver\Server::isSecondary(): bool

Returns whether this server is a » secondary member of a replica set.

### 参数

此函数没有参数。

### 返回值

Returns `true` if this server is a secondary member of a replica set, and `false` otherwise.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server

## 目录

- 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)

## 简介

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.

## 类摘要

final class MongoDB\Driver\ServerDescription {
/* 常量 */
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";
/* 方法 */
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
}

## 预定义常量

`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

### 说明

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.

> 注意: 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.

### 参数

此函数没有参数。

### 返回值

Returns an array of information describing this server.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\Driver\ServerDescription::getHost(): string

Returns the hostname of this server.

### 参数

此函数没有参数。

### 返回值

Returns the hostname of this server.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\Driver\ServerDescription::getLastUpdateTime(): int

Returns the server's last update time in microseconds.

> 注意: 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().

### 参数

此函数没有参数。

### 返回值

Returns the server's last update time in microseconds.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\ServerDescription::getPort

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getPort — Returns the port on which this server is listening

### 说明

final public function MongoDB\Driver\ServerDescription::getPort(): int

Returns the port on which this server is listening.

### 参数

此函数没有参数。

### 返回值

Returns the port on which this server is listening.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the server's round trip time in milliseconds.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns a string denoting the type of this server.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- MongoDB\Driver\Server::getType() - Returns an integer denoting the type of this server

## 目录

- 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)

## 简介

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.

## 类摘要

final class MongoDB\Driver\TopologyDescription {
/* 常量 */
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";
/* 方法 */
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
}

## 预定义常量

`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

### 说明

final public function MongoDB\Driver\TopologyDescription::getServers(): array

Returns an array of MongoDB\Driver\ServerDescription objects corresponding to the known servers in the topology.

### 参数

此函数没有参数。

### 返回值

Returns an array of MongoDB\Driver\ServerDescription objects corresponding to the known servers in the topology.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\TopologyDescription::getType

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::getType — Returns a string denoting the type of this topology

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns a string denoting the type of this topology.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\TopologyDescription::hasReadableServer

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::hasReadableServer — Returns whether the topology has a readable server

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns whether the topology has a readable server or, if `readPreference` is specified, a server matching the specified read preference.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\TopologyDescription::hasWritableServer

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::hasWritableServer — Returns whether the topology has a writable server

### 说明

final public function MongoDB\Driver\TopologyDescription::hasWritableServer(): bool

Returns whether the topology has a writable server.

### 参数

此函数没有参数。

### 返回值

Returns whether the topology has a writable server.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

## 目录

- 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)

## 简介

The MongoDB\Driver\WriteConcernError class encapsulates information about a write concern error and may be returned by MongoDB\Driver\WriteResult::getWriteConcernError().

## 类摘要

final class MongoDB\Driver\WriteConcernError {
/* 属性 */
public readonly string $message;
public readonly int $code;
public readonly ?object $info;
/* 方法 */
final public function getCode(): int
final public function getInfo(): ?object
final public function getMessage(): string
}

## 属性

message
  The error message.
code
  The error code.
info
  Additional information for the error, or `null` if not available.

## 更新日志

版本 | 说明
--- | ---
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

### 说明

final public function MongoDB\Driver\WriteConcernError::getCode(): int

### 参数

此函数没有参数。

### 返回值

Returns the WriteConcernError's error code.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());
    }

    ?>

以上示例的输出类似于：

    int(64)

### 参见

- » Write Concern reference

# MongoDB\Driver\WriteConcernError::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getInfo — Returns metadata document for the WriteConcernError

### 说明

final public function MongoDB\Driver\WriteConcernError::getInfo(): ?object

### 参数

此函数没有参数。

### 返回值

Returns the metadata document for the WriteConcernError, or `null` if no metadata is available.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());
    }

    ?>

以上示例的输出类似于：

    object(stdClass)#1 (1) {
      ["wtimeout"]=>
      bool(true)
    }

### 参见

- » Write Concern reference

# MongoDB\Driver\WriteConcernError::getMessage

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getMessage — Returns the WriteConcernError's error message

### 说明

final public function MongoDB\Driver\WriteConcernError::getMessage(): string

### 参数

此函数没有参数。

### 返回值

Returns the WriteConcernError's error message.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());
    }

    ?>

以上示例的输出类似于：

    string(33) "waiting for replication timed out"

### 参见

- » Write Concern reference

## 目录

- 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)

## 简介

The MongoDB\Driver\WriteError class encapsulates information about a write error and may be returned as an array element from MongoDB\Driver\WriteResult::getWriteErrors().

## 类摘要

final class MongoDB\Driver\WriteError {
/* 属性 */
public readonly string $message;
public readonly int $code;
public readonly int $index;
public readonly ?object $info;
/* 方法 */
final public function getCode(): int
final public function getIndex(): int
final public function getInfo(): ?object
final public function getMessage(): string
}

## 属性

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.

## 更新日志

版本 | 说明
--- | ---
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

### 说明

final public function MongoDB\Driver\WriteError::getCode(): int

### 参数

此函数没有参数。

### 返回值

Returns the WriteError's error code.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());
    }

    ?>

以上示例的输出类似于：

    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

### 说明

final public function MongoDB\Driver\WriteError::getIndex(): int

### 参数

此函数没有参数。

### 返回值

Returns the index of the write operation (from MongoDB\Driver\BulkWrite) corresponding to this WriteError.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());
    }

    ?>

以上示例的输出类似于：

    int(1)

### 参见

- MongoDB\Driver\BulkWrite

# MongoDB\Driver\WriteError::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getInfo — Returns metadata document for the WriteError

### 说明

final public function MongoDB\Driver\WriteError::getInfo(): ?object

### 参数

此函数没有参数。

### 返回值

Returns the metadata document for the WriteError, or `null` if no metadata is available.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\WriteError::getMessage

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getMessage — Returns the WriteError's error message

### 说明

final public function MongoDB\Driver\WriteError::getMessage(): string

### 参数

此函数没有参数。

### 返回值

Returns the WriteError's error message.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());
    }

    ?>

以上示例的输出类似于：

    string(70) "E11000 duplicate key error index: db.collection.$_id_ dup key: { : 1 }"

## 目录

- 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)

## 简介

The MongoDB\Driver\WriteResult class encapsulates information about an executed MongoDB\Driver\BulkWrite and may be returned by MongoDB\Driver\Manager::executeBulkWrite().

## 类摘要

final class MongoDB\Driver\WriteResult {
/* 属性 */
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;
/* 方法 */
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
}

## 属性

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.

## 更新日志

版本 | 说明
--- | ---
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

### 说明

final public function MongoDB\Driver\WriteResult::getDeletedCount(): int

### 参数

此函数没有参数。

### 返回值

Returns the number of documents deleted.

### 错误／异常

- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 当针对未确认写入调用此方法时，现在会抛出异常，而不是返回 `null`。

### 示例

示例 #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());

    ?>

以上示例会输出：

    int(1)

### 参见

- 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)

### 说明

final public function MongoDB\Driver\WriteResult::getInsertedCount(): int

### 参数

此函数没有参数。

### 返回值

Returns the number of documents inserted (excluding upserts).

### 错误／异常

- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 当针对未确认写入调用此方法时，现在会抛出异常，而不是返回 `null`。

### 示例

示例 #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());

    ?>

以上示例会输出：

    int(1)

### 参见

- 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

### 说明

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().

### 参数

此函数没有参数。

### 返回值

Returns the number of documents selected for update.

### 错误／异常

- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 当针对未确认写入调用此方法时，现在会抛出异常，而不是返回 `null`。

### 示例

示例 #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());

    ?>

以上示例会输出：

    int(1)

### 参见

- 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

### 说明

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().

### 参数

此函数没有参数。

### 返回值

Returns the number of existing documents updated.

### 错误／异常

- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 当针对未确认写入调用此方法时，现在会抛出异常，而不是返回 `null`。

### 示例

示例 #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());

    ?>

以上示例会输出：

    int(1)

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the MongoDB\Driver\Server associated with this write result.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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);

    ?>

以上示例会输出：

    bool(true)

### 参见

- MongoDB\Driver\Server

# MongoDB\Driver\WriteResult::getUpsertedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getUpsertedCount — Returns the number of documents inserted by an upsert

### 说明

final public function MongoDB\Driver\WriteResult::getUpsertedCount(): int

### 参数

此函数没有参数。

### 返回值

Returns the number of documents inserted by an upsert.

### 错误／异常

- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 当针对未确认写入调用此方法时，现在会抛出异常，而不是返回 `null`。

### 示例

示例 #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());

    ?>

以上示例会输出：

    int(2)

### 参见

- 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

### 说明

final public function MongoDB\Driver\WriteResult::getUpsertedIds(): array

### 参数

此函数没有参数。

### 返回值

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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例的输出类似于：

    array(2) {
      [2]=>
      object(MongoDB\BSON\ObjectId)#4 (1) {
        ["oid"]=>
        string(24) "580e62a224f2302f191b880b"
      }
      [3]=>
      object(MongoDB\BSON\ObjectId)#5 (1) {
        ["oid"]=>
        string(24) "580e62a224f2302f191b880c"
      }
    }

### 参见

- 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

### 说明

final public function MongoDB\Driver\WriteResult::getWriteConcernError(): ?MongoDB\Driver\WriteConcernError

### 参数

此函数没有参数。

### 返回值

Returns a MongoDB\Driver\WriteConcernError if a write concern error was encountered during the write operation, and `null` otherwise.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());
    }

    ?>

以上示例的输出类似于：

    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)
      }
    }

### 参见

- MongoDB\Driver\WriteConcern
- » Write Concern reference

# MongoDB\Driver\WriteResult::getWriteErrors

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getWriteErrors — Returns any write errors that occurred

### 说明

final public function MongoDB\Driver\WriteResult::getWriteErrors(): array

### 参数

此函数没有参数。

### 返回值

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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());
    }

    ?>

以上示例的输出类似于：

    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
      }
    }

示例 #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());
    }

    ?>

以上示例的输出类似于：

    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
      }
    }

### 参见

- MongoDB\Driver\WriteError

# MongoDB\Driver\WriteResult::isAcknowledged

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::isAcknowledged — Returns whether the write was acknowledged

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns `true` if the write was acknowledged, and `false` otherwise.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例会输出：

    bool(true)

示例 #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());

    ?>

以上示例会输出：

    bool(false)

### 参见

- MongoDB\Driver\WriteConcern
- » Write Concern reference

## 目录

- 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)

## 简介

The MongoDB\Driver\BulkWriteCommandResult class encapsulates information about an executed MongoDB\Driver\BulkWriteCommand and is returned by MongoDB\Driver\Manager::executeBulkWriteCommand().

## 类摘要

final class MongoDB\Driver\BulkWriteCommandResult {
/* 方法 */
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

### 说明

final public function MongoDB\Driver\BulkWriteCommandResult::getDeletedCount(): int

### 参数

此函数没有参数。

### 返回值

Returns the total number of documents deleted by all operations.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.

### 示例

示例 #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());

    ?>

以上示例会输出：

    int(3)

### 参见

- 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

### 说明

final public function MongoDB\Driver\BulkWriteCommandResult::getDeleteResults(): ?MongoDB\BSON\Document

### 参数

此函数没有参数。

### 返回值

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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.

### 示例

示例 #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());

    ?>

以上示例的输出类似于：

    object(stdClass)#7 (1) {
      ["4"]=>
      object(stdClass)#6 (1) {
        ["deletedCount"]=>
        object(MongoDB\BSON\Int64)#5 (1) {
          ["integer"]=>
          string(1) "3"
        }
      }
    }

### 参见

- 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

### 说明

final public function MongoDB\Driver\BulkWriteCommandResult::getInsertedCount(): int

### 参数

此函数没有参数。

### 返回值

Returns the total number of documents inserted (excluding upserts) by all operations.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.

### 示例

示例 #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());

    ?>

以上示例会输出：

    int(1)

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.

### 示例

示例 #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());

    ?>

以上示例的输出类似于：

    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"
        }
      }
    }

### 参见

- 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

### 说明

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().

### 参数

此函数没有参数。

### 返回值

Returns the total number of documents selected for update by all operations.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.

### 示例

示例 #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());

    ?>

以上示例会输出：

    int(1)

### 参见

- 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

### 说明

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().

### 参数

此函数没有参数。

### 返回值

Returns the total number of existing documents updated by all operations.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.

### 示例

示例 #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());

    ?>

以上示例会输出：

    int(1)

### 参见

- 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

### 说明

final public function MongoDB\Driver\BulkWriteCommandResult::getUpdateResults(): ?MongoDB\BSON\Document

### 参数

此函数没有参数。

### 返回值

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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.

### 示例

示例 #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());

    ?>

以上示例的输出类似于：

    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"
        }
      }
    }

### 参见

- 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

### 说明

final public function MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount(): int

### 参数

此函数没有参数。

### 返回值

Returns the total number of documents upserted by all operations.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.

### 示例

示例 #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());

    ?>

以上示例会输出：

    int(2)

### 参见

- 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

### 说明

final public function MongoDB\Driver\BulkWriteCommandResult::isAcknowledged(): bool

If the write is acknowledged, other fields will be available on the MongoDB\Driver\BulkWriteCommandResult object.

### 参数

此函数没有参数。

### 返回值

Returns `true` if the write was acknowledged, and `false` otherwise.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例会输出：

    bool(true)

示例 #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());

    ?>

以上示例会输出：

    bool(false)

### 参见

- MongoDB\Driver\WriteConcern
- » Write Concern reference

## 目录

- 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

## 目录

- 函数
- 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

# 函数

# MongoDB\BSON\fromJSON

(mongodb >=1.0.0)

MongoDB\BSON\fromJSON — Returns the BSON representation of a JSON value

警告

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.

### 说明

function MongoDB\BSON\fromJSON(string `$json`): string

Converts an » extended JSON string to its BSON representation.

### 参数

`json` (string)
  JSON value to be converted.

### 返回值

The serialized BSON document as a binary string.

### 错误／异常

- Throws MongoDB\Driver\Exception\UnexpectedValueException if the JSON value cannot be converted to BSON (e.g. due to a syntax error).

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此函数已被移除。

### 示例

示例 #1 MongoDB\BSON\fromJSON() example

    <?php

    $json = '{ "_id": { "$oid": "563143b280d2387c91807965" } }';
    $bson = MongoDB\BSON\fromJSON($json);
    $value = MongoDB\BSON\toPHP($bson);
    var_dump($value);

    ?>

以上示例会输出：

    object(stdClass)#2 (1) {
      ["_id"]=>
      object(MongoDB\BSON\ObjectId)#1 (1) {
        ["oid"]=>
        string(24) "563143b280d2387c91807965"
      }
    }

### 参见

- 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

警告

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.

### 说明

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.

### 参数

`value` (array|object)
  PHP value to be serialized.

### 返回值

The serialized BSON document as a binary string.

### 错误／异常

- 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.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此函数已被移除。

### 示例

示例 #1 MongoDB\BSON\fromPHP() example

    <?php

    $bson = MongoDB\BSON\fromPHP(['foo' => 1]);
    echo bin2hex($bson), "\n";

    ?>

以上示例会输出：

    0e00000010666f6f000100000000

### 参见

- 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

警告

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.

### 说明

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).

### 参数

`bson` (string)
  BSON value to be converted.

### 返回值

The converted JSON value.

### 错误／异常

- Throws MongoDB\Driver\Exception\UnexpectedValueException if the input did not contain exactly one BSON document. Possible reasons include, but are not limited to, invalid BSON, extra data (after reading one BSON document), or an unexpected » libbson error.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此函数已被移除。

### 示例

示例 #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";
    }

    ?>

以上示例会输出：

    { "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 } }

### 参见

- 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

警告

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.

### 说明

function MongoDB\BSON\toJSON(string `$bson`): string

Converts a BSON string to its » Legacy Extended JSON representation.

> 注意: 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.

警告

» 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().

### 参数

`bson` (string)
  BSON value to be converted.

### 返回值

The converted JSON value.

### 错误／异常

- Throws MongoDB\Driver\Exception\UnexpectedValueException if the input did not contain exactly one BSON document. Possible reasons include, but are not limited to, invalid BSON, extra data (after reading one BSON document), or an unexpected » libbson error.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此函数已被移除。

### 示例

示例 #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";
    }

    ?>

以上示例会输出：

    { "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 } }

### 参见

- 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

警告

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.

### 说明

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` paramater may be used to control the PHP types used for converting BSON arrays and documents (both root and embedded).

警告

BSON documents can technically contain duplicate keys because documents are stored as a list of key-value pairs; however, applications should refrain from generating documents with duplicate keys as server and driver behavior may be undefined. Since PHP objects and arrays cannot have duplicate keys, data could also be lost when decoding a BSON document with duplicate keys.

### 参数

`bson` (string)
  BSON value to be unserialized.
`typeMap` (array)
  Type map configuration.

### 返回值

The unserialized PHP value.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException if a class in the type map cannot be instantiated or does not implement MongoDB\BSON\Unserializable.
- Throws MongoDB\Driver\Exception\UnexpectedValueException if the input did not contain exactly one BSON document. Possible reasons include, but are not limited to, invalid BSON, extra data (after reading one BSON document), or an unexpected » libbson error.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此函数已被移除。
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.

### 示例

示例 #1 MongoDB\BSON\toPHP() example

    <?php

    $bson = hex2bin('0e00000010666f6f000100000000');
    $value = MongoDB\BSON\toPHP($bson);
    var_dump($value);

    ?>

以上示例会输出：

    object(stdClass)#1 (1) {
      ["foo"]=>
      int(1)
    }

### 参见

- 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

警告

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.

### 说明

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.

### 参数

`bson` (string)
  BSON value to be converted.

### 返回值

The converted JSON value.

### 错误／异常

- Throws MongoDB\Driver\Exception\UnexpectedValueException if the input did not contain exactly one BSON document. Possible reasons include, but are not limited to, invalid BSON, extra data (after reading one BSON document), or an unexpected » libbson error.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此函数已被移除。

### 示例

示例 #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";
    }

    ?>

以上示例会输出：

    { "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 } }

### 参见

- 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

## 目录

- 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)

## 简介

Represents a BSON document. This class is used when reading data as raw BSON and cannot be modified.

## 类摘要

final class MongoDB\BSON\Document implements MongoDB\BSON\Type, ArrayAccess, IteratorAggregate {
/* 方法 */
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
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此类不再实现 Serializable 接口。
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)

### 说明

final private function MongoDB\BSON\Document::__construct()

MongoDB\BSON\Document objects are created through static factory methods and cannot be instantiated directly.

### 参数

此函数没有参数。

### 参见

- 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

### 说明

final static public function MongoDB\BSON\Document::fromBSON(string `$bson`): MongoDB\BSON\Document

### 参数

`bson` (string)
  A string containing a document in BSON format.

### 返回值

Returns a new MongoDB\BSON\Document instance.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\UnexpectedValueException if `bson` is an invalid BSON string or contains more than a single document.

### 参见

- 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

### 说明

final static public function MongoDB\BSON\Document::fromJSON(string `$json`): MongoDB\BSON\Document

Converts an » extended JSON string to its BSON representation.

### 参数

`json` (string)
  JSON value to be converted.

### 返回值

Returns a new MongoDB\BSON\Document instance.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\UnexpectedValueException if the JSON value cannot be converted to a BSON document (e.g. due to a syntax error).

### 参见

- 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

### 说明

final static public function MongoDB\BSON\Document::fromPHP(object|array `$value`): MongoDB\BSON\Document

### 参数

`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.

### 返回值

Returns a new MongoDB\BSON\Document instance.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\BSON\Document::get(string `$key`): mixed

### 参数

`key` (string)
  The key to retrieve from the document.

### 返回值

Returns the value associated with the given key. If the key is not present in the document, an exception is thrown.

> 注意: 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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\RuntimeException if the key is not present in the document.

### 参见

- 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

### 说明

final public function MongoDB\BSON\Document::getIterator(): MongoDB\BSON\Iterator

### 参数

此函数没有参数。

### 返回值

Returns a MongoDB\BSON\Iterator instance that can be used to iterate over all keys in the document.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\UnexpectedValueException if the BSON iterator could not be initialized.

### 参见

- » BSON Types

# MongoDB\BSON\Document::has

(mongodb >=1.16.0)

MongoDB\BSON\Document::has — Returns whether a key is present in the document

### 说明

final public function MongoDB\BSON\Document::has(string `$key`): bool

### 参数

`key` (string)
  The key to look for in the document.

### 返回值

Returns `true` if the key is present in the document and `false` otherwise.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\BSON\Document::offsetExists(mixed `$key`): bool

### 参数

`key`
  The key to look for in the document.

### 返回值

Returns `true` if the key is present in the document and `false` otherwise.

### 参见

- ArrayAccess::offsetExists() - 检查一个偏移位置是否存在
- 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

### 说明

final public function MongoDB\BSON\Document::offsetGet(mixed `$key`): mixed

### 参数

`key`
  The key to retrieve from the document.

### 返回值

Returns the value associated with the given key. If the key is not present in the document, an exception is thrown.

> 注意: 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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\RuntimeException if the key is not present in the document.

### 参见

- ArrayAccess::offsetGet() - 获取一个偏移位置的值
- 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

### 说明

final public function MongoDB\BSON\Document::offsetSet(mixed `$key`, mixed `$value`): void

Sets the value at the specified `key` to `value`.

### 参数

`key`
  The index being set.
`value`
  The new value for the `key`.

### 返回值

没有返回值。

### 错误／异常

- Always throws a MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\Document::offsetUnset

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetUnset — Implementation of ArrayAccess

### 说明

final public function MongoDB\BSON\Document::offsetUnset(mixed `$key`): void

Unsets the value at the specified index.

### 参数

`key`
  The index being unset.

### 返回值

没有返回值。

### 错误／异常

- 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

### 说明

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).

### 参数

此函数没有参数。

### 返回值

Returns a string containing the » Canonical Extended JSON representation of the BSON document.

### 示例

示例 #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";
    }

    ?>

以上示例会输出：

    { "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 } }

### 参见

- 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

### 说明

final public function MongoDB\BSON\Document::toPHP(?array `$typeMap` = `null`): array|object

Unserializes the BSON document to its PHP representation. The `typeMap` paramater may be used to control the PHP types used for converting BSON arrays and documents (both root and embedded).

警告

BSON documents can technically contain duplicate keys because documents are stored as a list of key-value pairs; however, applications should refrain from generating documents with duplicate keys as server and driver behavior may be undefined. Since PHP objects and arrays cannot have duplicate keys, data could also be lost when decoding a BSON document with duplicate keys.

### 参数

`typeMap` (array)
  Type map configuration.

### 返回值

The decoded PHP value.

> 注意: 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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException if a class in the type map cannot be instantiated or does not implement MongoDB\BSON\Unserializable.

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns a string containing the » Relaxed Extended JSON representation of the BSON document.

### 示例

示例 #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";
    }

    ?>

以上示例会输出：

    { "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 } }

### 参见

- 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

### 说明

final public function MongoDB\BSON\Document::__toString(): string

### 参数

此函数没有参数。

### 返回值

Returns the string representation of this document as BSON.

### 参见

- » BSON Types

## 目录

- 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)

## 简介

Represents a BSON array. This class is used when reading data as raw BSON and cannot be modified.

## 类摘要

final class MongoDB\BSON\PackedArray implements MongoDB\BSON\Type, ArrayAccess, IteratorAggregate {
/* 方法 */
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
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此类不再实现 Serializable 接口。
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)

### 说明

final private function MongoDB\BSON\PackedArray::__construct()

MongoDB\BSON\PackedArray objects are created through static factory methods and cannot be instantiated directly.

### 参数

此函数没有参数。

### 参见

- 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

### 说明

final static public function MongoDB\BSON\PackedArray::fromJSON(string `$json`): MongoDB\BSON\PackedArray

Converts an » extended JSON string to its BSON representation.

### 参数

`json` (string)
  JSON value to be converted.

### 返回值

Returns a new MongoDB\BSON\PackedArray instance.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\UnexpectedValueException if the JSON value cannot be converted to a BSON array (e.g. due to a syntax error).

### 示例

示例 #1 MongoDB\BSON\PackedArray::fromJSON() example

    <?php

    $json = '[ "foo", { "$numberInt" : "123" }, { "$numberLong" : "4294967295" }, { "$oid" : "56315a7c6118fd1b920270b1" } ]';
    $packedArray = MongoDB\BSON\PackedArray::fromJSON($json);
    var_dump($packedArray);

    ?>

以上示例会输出：

    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"
        }
      }
    }

### 参见

- 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

### 说明

final static public function MongoDB\BSON\PackedArray::fromPHP(array `$value`): MongoDB\BSON\PackedArray

### 参数

`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`).

### 返回值

Returns a new MongoDB\BSON\PackedArray instance.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if the given array is not a list (i.e. has sequential numeric keys starting with `0`).

### 参见

- » BSON Types

# MongoDB\BSON\PackedArray::get

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::get — Returns the value of an index in the array

### 说明

final public function MongoDB\BSON\PackedArray::get(int `$key`): mixed

### 参数

`key` (int)
  The index to retrieve from the array.

### 返回值

Returns the value associated with the given index. If the index is not present in the array, an exception is thrown.

> 注意: 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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\RuntimeException if the index is not present in the array.

### 参见

- 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

### 说明

final public function MongoDB\BSON\PackedArray::getIterator(): MongoDB\BSON\Iterator

### 参数

此函数没有参数。

### 返回值

Returns a MongoDB\BSON\Iterator instance that can be used to iterate over all indexes in the array.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\UnexpectedValueException if the BSON iterator could not be initialized.

### 参见

- » BSON Types

# MongoDB\BSON\PackedArray::has

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::has — Returns whether a index is present in the array

### 说明

final public function MongoDB\BSON\PackedArray::has(int `$index`): bool

### 参数

`index` (int)
  The index to look for in the array.

### 返回值

Returns `true` if the index is present in the array and `false` otherwise.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\BSON\PackedArray::offsetExists(mixed `$key`): bool

### 参数

`key`
  The index to look for in the array.

### 返回值

Returns `true` if the index is present in the array and `false` otherwise.

### 参见

- ArrayAccess::offsetExists() - 检查一个偏移位置是否存在
- 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

### 说明

final public function MongoDB\BSON\PackedArray::offsetGet(mixed `$key`): mixed

### 参数

`key`
  The index to retrieve from the array. Only int is supported.

### 返回值

Returns the value associated with the given index. If the index is not present in the array, an exception is thrown.

> 注意: 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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\RuntimeException if the index is not present in the array.

### 参见

- ArrayAccess::offsetGet() - 获取一个偏移位置的值
- 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

### 说明

final public function MongoDB\BSON\PackedArray::offsetSet(mixed `$key`, mixed `$value`): void

Sets the value at the specified `key` to `value`.

### 参数

`key`
  The index being set.
`value`
  The new value for the `key`.

### 返回值

没有返回值。

### 错误／异常

- Always throws a MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\PackedArray::offsetUnset

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetUnset — Implementation of ArrayAccess

### 说明

final public function MongoDB\BSON\PackedArray::offsetUnset(mixed `$key`): void

Unsets the value at the specified index.

### 参数

`key`
  The index being unset.

### 返回值

没有返回值。

### 错误／异常

- 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

### 说明

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).

### 参数

此函数没有参数。

### 返回值

Returns a string containing the » Canonical Extended JSON representation of the BSON array.

### 示例

示例 #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";

    ?>

以上示例会输出：

    [ "foo", { "$numberInt" : "123" }, { "$numberLong" : "4294967295" }, { "$oid" : "56315a7c6118fd1b920270b1" } ]

### 参见

- 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

### 说明

final public function MongoDB\BSON\PackedArray::toPHP(?array `$typeMap` = `null`): array|object

### 参数

`typeMap` (array)
  Type map configuration.

### 返回值

The decoded PHP value.

> 注意: 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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException if a class in the type map cannot be instantiated or does not implement MongoDB\BSON\Unserializable.

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns a string containing the » Relaxed Extended JSON representation of the BSON array.

### 示例

示例 #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";

    ?>

以上示例会输出：

    [ "foo", 123, 4294967295, { "$oid" : "56315a7c6118fd1b920270b1" } ]

### 参见

- 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

### 说明

final public function MongoDB\BSON\PackedArray::__toString(): string

### 参数

此函数没有参数。

### 返回值

Returns the string representation of this array as BSON.

### 参见

- » BSON Types

## 目录

- 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)

## 简介

Iterator used to iterate a BSON document or array.

## 类摘要

final class MongoDB\BSON\Iterator implements Iterator {
/* 方法 */
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)

### 说明

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.

### 参数

此函数没有参数。

### 参见

- 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

### 说明

public function MongoDB\BSON\Iterator::current(): mixed

### 参数

此函数没有参数。

### 返回值

Returns the value of the current element.

> 注意: 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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\LogicException if the iterator is not valid.

### 参见

- Iterator::current() - 返回当前元素

# MongoDB\BSON\Iterator::key

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::key — Returns the key of the current element

### 说明

public function MongoDB\BSON\Iterator::key(): string|int

### 参数

此函数没有参数。

### 返回值

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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\LogicException if the iterator is not valid.

### 参见

- Iterator::key() - 返回当前元素的键

# MongoDB\BSON\Iterator::next

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::next — Advances the iterator to next element

### 说明

public function MongoDB\BSON\Iterator::next(): void

### 参数

此函数没有参数。

### 参见

- Iterator::next() - 向前移动到下一个元素

# MongoDB\BSON\Iterator::rewind

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::rewind — Rewinds the Iterator to the first element

### 说明

public function MongoDB\BSON\Iterator::rewind(): void

### 参数

此函数没有参数。

### 参见

- Iterator::rewind() - 返回到迭代器的第一个元素

# MongoDB\BSON\Iterator::valid

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::valid — Checks if current position is valid

### 说明

public function MongoDB\BSON\Iterator::valid(): bool

### 参数

此函数没有参数。

### 返回值

Returns `true` if the current iterator position is valid, `false` otherwise.

### 参见

- Iterator::valid() - 检查当前位置是否有效

## 目录

- 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)

## 简介

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.

## 类摘要

final class MongoDB\BSON\Binary implements MongoDB\BSON\BinaryInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* 常量 */
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;
/* 方法 */
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
}

## 预定义常量

`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.

## 更新日志

版本 | 说明
--- | ---
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 | 此类不再实现 Serializable 接口。
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

### 说明

final public function MongoDB\BSON\Binary::__construct(string `$data`, int `$type` = MongoDB\BSON\Binary::TYPE_GENERIC)

### 参数

`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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- 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.

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #1 MongoDB\BSON\Binary::__construct() example

    <?php

    $binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
    var_dump($binary);

    ?>

以上示例会输出：

    object(MongoDB\BSON\Binary)#1 (2) {
      ["data"]=>
      string(3) "foo"
      ["type"]=>
      int(0)
    }

### 参见

- » 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

### 说明

final public static function MongoDB\BSON\Binary::fromVector(array `$vector`, MongoDB\BSON\VectorType `$vectorType`): MongoDB\BSON\Binary

### 参数

`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.

### 返回值

Returns a new Binary with subtype `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\BSON\Binary::getData(): string

### 参数

此函数没有参数。

### 返回值

Returns the Binary's data.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #1 MongoDB\BSON\Binary::getData() example

    <?php

    $binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
    var_dump($binary->getData());

    ?>

以上示例会输出：

    string(3) "foo"

### 参见

- » BSON Types

# MongoDB\BSON\Binary::getType

(mongodb >=1.0.0)

MongoDB\BSON\Binary::getType — Returns the Binary's type

### 说明

final public function MongoDB\BSON\Binary::getType(): int

### 参数

此函数没有参数。

### 返回值

Returns the Binary's type.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #1 MongoDB\BSON\Binary::getType() example

    <?php

    $binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
    var_dump($binary->getType());

    ?>

以上示例会输出：

    int(0)

### 参见

- » 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

### 说明

final public function MongoDB\BSON\Binary::getVectorType(): MongoDB\BSON\VectorType

### 参数

此函数没有参数。

### 返回值

Returns the data type of the Binary vector.

### 错误／异常

- Throws MongoDB\Driver\Exception\LogicException if the subtype is not `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- » 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

### 说明

final public function MongoDB\BSON\Binary::jsonSerialize(): mixed

### 参数

此函数没有参数。

### 返回值

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Binary.

> 注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- JsonSerializable::jsonSerialize() - 指定需要被序列化成 JSON 的数据
- json_encode() - 对变量进行 JSON 编码
- 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`

### 说明

final public function MongoDB\BSON\Binary::toArray(): array

### 参数

此函数没有参数。

### 返回值

Returns an array containing the vector data.

### 错误／异常

- Throws MongoDB\Driver\Exception\LogicException if the subtype is not `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\BSON\Binary::__toString(): string

此方法是该方法的别名： MongoDB\BSON\Binary::getData().

### 参数

此函数没有参数。

### 返回值

Returns the Binary's data.

### 示例

示例 #1 MongoDB\BSON\Binary::__toString() example

    <?php

    var_dump((string) new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC));

    ?>

以上示例会输出：

    string(3) "foo"

### 参见

- MongoDB\BSON\Binary::getData() - Returns the Binary's data
- » BSON Types

## 目录

- 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)

## 简介

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`.

## 注解摘要

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)

## 简介

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….

> 注意: MongoDB\BSON\Decimal128 is only compatible with MongoDB 3.4+. Attempting to use the BSON type with an earlier version of MongoDB will result in an error.

## 类摘要

final class MongoDB\BSON\Decimal128 implements MongoDB\BSON\Decimal128Interface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* 方法 */
final public function __construct(string `$value`)
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此类不再实现 Serializable 接口。
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

### 说明

final public function MongoDB\BSON\Decimal128::__construct(string `$value`)

> 注意: MongoDB\BSON\Decimal128 is only compatible with MongoDB 3.4+. Attempting to use the BSON type with an earlier version of MongoDB will result in an error.

### 参数

`value` (string)
  A decimal string.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `value` is not a valid decimal string.

### 示例

示例 #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));

    ?>

以上示例的输出类似于：

    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"
    }

### 参见

- » 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

### 说明

final public function MongoDB\BSON\Decimal128::jsonSerialize(): mixed

### 参数

此函数没有参数。

### 返回值

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Decimal128.

> 注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- JsonSerializable::jsonSerialize() - 指定需要被序列化成 JSON 的数据
- json_encode() - 对变量进行 JSON 编码
- 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

### 说明

final public function MongoDB\BSON\Decimal128::__toString(): string

### 参数

此函数没有参数。

### 返回值

Returns the string representation of this Decimal128.

### 示例

示例 #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));

    ?>

以上示例的输出类似于：

    string(9) "1234.5678"
    string(3) "NaN"
    string(8) "Infinity"

### 参见

- » Decimal128 floating-point format
- » BSON Types

## 目录

- 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)

## 简介

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.

> 注意: This BSON type is mainly used when executing database commands that take a Javascript function as a parameter, such as » mapReduce.

## 类摘要

final class MongoDB\BSON\Javascript implements MongoDB\BSON\JavascriptInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* 方法 */
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
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此类不再实现 Serializable 接口。
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

### 说明

final public function MongoDB\BSON\Javascript::__construct(string `$code`, array|object|null `$scope` = `null`)

### 参数

`code` (string)
  Javascript code.
`scope` (array|object)
  Javascript scope.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `code` contains null bytes.

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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);

    ?>

以上示例会输出：

    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"
      }
    }

### 参见

- » BSON Types

# MongoDB\BSON\Javascript::getCode

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::getCode — Returns the Javascript's code

### 说明

final public function MongoDB\BSON\Javascript::getCode(): string

### 参数

此函数没有参数。

### 返回值

Returns the Javascript's code.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #1 MongoDB\BSON\Javascript::getCode() example

    <?php

    $js = new MongoDB\BSON\Javascript('function foo(bar) { return bar; }');
    var_dump($js->getCode());

    ?>

以上示例会输出：

    string(33) "function foo(bar) { return bar; }"

### 参见

- » BSON Types

# MongoDB\BSON\Javascript::getScope

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::getScope — Returns the Javascript's scope document

### 说明

final public function MongoDB\BSON\Javascript::getScope(): ?object

### 参数

此函数没有参数。

### 返回值

Returns the Javascript's scope document, or `null` if the is no scope.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例会输出：

    NULL
    object(stdClass)#1 (1) {
      ["foo"]=>
      int(42)
    }

### 参见

- » BSON Types

# MongoDB\BSON\Javascript::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::jsonSerialize — Returns a representation that can be converted to JSON

### 说明

final public function MongoDB\BSON\Javascript::jsonSerialize(): mixed

### 参数

此函数没有参数。

### 返回值

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Javascript.

> 注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- JsonSerializable::jsonSerialize() - 指定需要被序列化成 JSON 的数据
- json_encode() - 对变量进行 JSON 编码
- 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

### 说明

final public function MongoDB\BSON\Javascript::__toString(): string

此方法是该方法的别名： MongoDB\BSON\Javascript::getCode().

### 参数

此函数没有参数。

### 返回值

Returns the Javascript's code.

### 示例

示例 #1 MongoDB\BSON\Javascript::__toString() example

    <?php

    var_dump((string) new MongoDB\BSON\Javascript('function foo(bar) { return bar; }'));

    ?>

以上示例会输出：

    string(33) "function foo(bar) { return bar; }"

### 参见

- MongoDB\BSON\Javascript::getCode() - Returns the Javascript's code
- » BSON Types

## 目录

- 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)

## 简介

Special BSON type which compares higher than all other possible BSON element values.

> 注意: This is an internal MongoDB type used for indexing and sharding.

## 类摘要

final class MongoDB\BSON\MaxKey implements MongoDB\BSON\MaxKeyInterface, MongoDB\BSON\Type, JsonSerializable {
/* 方法 */
final public function __construct()
final public function jsonSerialize(): mixed
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此类不再实现 Serializable 接口。
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

### 说明

final public function MongoDB\BSON\MaxKey::__construct()

### 参数

此函数没有参数。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #1 MongoDB\BSON\MaxKey::__construct() example

    <?php

    var_dump(new MongoDB\BSON\MaxKey());

    ?>

以上示例会输出：

    object(MongoDB\BSON\MaxKey)#1 (0) {
    }

### 参见

- » BSON Types

# MongoDB\BSON\MaxKey::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\MaxKey::jsonSerialize — Returns a representation that can be converted to JSON

### 说明

final public function MongoDB\BSON\MaxKey::jsonSerialize(): mixed

### 参数

此函数没有参数。

### 返回值

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\MaxKey.

> 注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- JsonSerializable::jsonSerialize() - 指定需要被序列化成 JSON 的数据
- json_encode() - 对变量进行 JSON 编码
- 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\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)

## 简介

Special BSON type which compares lower than all other possible BSON element values.

> 注意: This is an internal MongoDB type used for indexing and sharding.

## 类摘要

final class MongoDB\BSON\MinKey implements MongoDB\BSON\MinKeyInterface, MongoDB\BSON\Type, JsonSerializable {
/* 方法 */
final public function __construct()
final public function jsonSerialize(): mixed
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此类不再实现 Serializable 接口。
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

### 说明

final public function MongoDB\BSON\MinKey::__construct()

### 参数

此函数没有参数。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #1 MongoDB\BSON\MinKey::__construct() example

    <?php

    var_dump(new MongoDB\BSON\MinKey());

    ?>

以上示例会输出：

    object(MongoDB\BSON\MinKey)#1 (0) {
    }

### 参见

- » BSON Types

# MongoDB\BSON\MinKey::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\MinKey::jsonSerialize — Returns a representation that can be converted to JSON

### 说明

final public function MongoDB\BSON\MinKey::jsonSerialize(): mixed

### 参数

此函数没有参数。

### 返回值

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\MinKey.

> 注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- JsonSerializable::jsonSerialize() - 指定需要被序列化成 JSON 的数据
- json_encode() - 对变量进行 JSON 编码
- 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\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)

## 简介

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.

## 类摘要

final class MongoDB\BSON\ObjectId implements MongoDB\BSON\ObjectIdInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* 方法 */
final public function __construct(?string `$id` = `null`)
final public function getTimestamp(): int
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此类不再实现 Serializable 接口。
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

### 说明

final public function MongoDB\BSON\ObjectId::__construct(?string `$id` = `null`)

### 参数

`id` (string)
  A 24-character hexadecimal string. If not provided, the extension will generate an ObjectId.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `id` is not a 24-character hexadecimal string.

### 示例

示例 #1 MongoDB\BSON\ObjectId::__construct() example

    <?php

    var_dump(new MongoDB\BSON\ObjectId());

    var_dump(new MongoDB\BSON\ObjectId('000000000000000000000001'));

    ?>

以上示例的输出类似于：

    object(MongoDB\BSON\ObjectId)#1 (1) {
      ["oid"]=>
      string(24) "56732d3dda14d81214634921"
    }
    object(MongoDB\BSON\ObjectId)#1 (1) {
      ["oid"]=>
      string(24) "000000000000000000000001"
    }

### 参见

- » ObjectId Reference
- » BSON Types: ObjectId

# MongoDB\BSON\ObjectId::getTimestamp

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::getTimestamp — Returns the timestamp component of this ObjectId

### 说明

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.

> 注意: Because PHP's integer type is signed, some values returned by this method may appear as negative integers on 32-bit platforms. The `"%u"` formatter of sprintf() may be used to obtain a string representation of the unsigned decimal value.

### 参数

此函数没有参数。

### 返回值

Returns the timestamp component of this ObjectId.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #1 MongoDB\BSON\ObjectId::getTimestamp() example

    <?php

    var_dump((new MongoDB\BSON\ObjectId())->getTimestamp());

    var_dump((new MongoDB\BSON\ObjectId('0000002a0000000000000000'))->getTimestamp());

    ?>

以上示例的输出类似于：

    integer(1484854719)
    integer(42)

### 参见

- » 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

### 说明

final public function MongoDB\BSON\ObjectId::jsonSerialize(): mixed

### 参数

此函数没有参数。

### 返回值

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\ObjectId.

> 注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- JsonSerializable::jsonSerialize() - 指定需要被序列化成 JSON 的数据
- json_encode() - 对变量进行 JSON 编码
- 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 hexidecimal representation of this ObjectId

### 说明

final public function MongoDB\BSON\ObjectId::__toString(): string

### 参数

此函数没有参数。

### 返回值

Returns the hexidecimal representation of this ObjectId.

### 示例

示例 #1 MongoDB\BSON\ObjectId::__toString() example

    <?php

    var_dump((string) new MongoDB\BSON\ObjectId());
    var_dump((string) new MongoDB\BSON\ObjectId('000000000000000000000001'));

    ?>

以上示例的输出类似于：

    string(24) "56731b49da14d8747d701211"
    string(24) "000000000000000000000001"

### 参见

- » ObjectId Reference
- » BSON Types: ObjectId

## 目录

- 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 hexidecimal representation of this ObjectId

# The MongoDB\BSON\Regex class

(mongodb >=1.0.0)

## 简介

BSON type for a regular expression pattern and optional » flags.

> 注意: This BSON type is mainly used when querying the database. Alternatively, the » $regex query operator may be used.

## 类摘要

final class MongoDB\BSON\Regex implements MongoDB\BSON\RegexInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* 方法 */
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
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此类不再实现 Serializable 接口。
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

### 说明

final public function MongoDB\BSON\Regex::__construct(string `$pattern`, string `$flags` = "")

### 参数

`pattern` (string)
  The regular expression pattern.

  > 注意: The pattern should not be wrapped with delimiter characters.

`flags` (string)
  The » regular expression flags. Characters in this argument will be sorted alphabetically.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `pattern` or `flags` contain null bytes.

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #1 MongoDB\BSON\Regex::__construct() example

    <?php

    $regex = new MongoDB\BSON\Regex('^foo', 'i');
    var_dump($regex);

    ?>

以上示例会输出：

    object(MongoDB\BSON\Regex)#1 (2) {
      ["pattern"]=>
      string(4) "^foo"
      ["flags"]=>
      string(1) "i"
    }

### 参见

- » BSON Types
- » Supported regular expression flags

# MongoDB\BSON\Regex::getFlags

(mongodb >=1.0.0)

MongoDB\BSON\Regex::getFlags — Returns the Regex's flags

### 说明

final public function MongoDB\BSON\Regex::getFlags(): string

### 参数

此函数没有参数。

### 返回值

Returns the Regex's flags.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #1 MongoDB\BSON\Regex::getFlags() example

    <?php

    $regex = new MongoDB\BSON\Regex('regex', 'i');
    var_dump($regex->getFlags());

    ?>

以上示例的输出类似于：

    string(1) "i"

### 参见

- » BSON Types
- » Supported regular expression flags

# MongoDB\BSON\Regex::getPattern

(mongodb >=1.0.0)

MongoDB\BSON\Regex::getPattern — Returns the Regex's pattern

### 说明

final public function MongoDB\BSON\Regex::getPattern(): string

### 参数

此函数没有参数。

### 返回值

Returns the Regex's pattern.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #1 MongoDB\BSON\Regex::getPattern() example

    <?php

    $regex = new MongoDB\BSON\Regex('regex', 'i');
    var_dump($regex->getPattern());

    ?>

以上示例的输出类似于：

    string(5) "regex"

### 参见

- » BSON Types

# MongoDB\BSON\Regex::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Regex::jsonSerialize — Returns a representation that can be converted to JSON

### 说明

final public function MongoDB\BSON\Regex::jsonSerialize(): mixed

### 参数

此函数没有参数。

### 返回值

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Regex.

> 注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- JsonSerializable::jsonSerialize() - 指定需要被序列化成 JSON 的数据
- json_encode() - 对变量进行 JSON 编码
- 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

### 说明

final public function MongoDB\BSON\Regex::__toString(): string

### 参数

此函数没有参数。

### 返回值

Returns the string representation of this Regex.

### 示例

示例 #1 MongoDB\BSON\Regex::__toString() example

    <?php

    $regex = new MongoDB\BSON\Regex('regex', 'i');
    var_dump((string) $regex);

    ?>

以上示例会输出：

    string(8) "/regex/i"

### 参见

- » BSON Types

## 目录

- 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)

## 简介

Represents a » BSON timestamp, The value consists of a 4-byte timestamp (i.e. seconds since the epoch) and a 4-byte increment.

> 注意: 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).

## 类摘要

final class MongoDB\BSON\Timestamp implements MongoDB\BSON\TimestampInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* 方法 */
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
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此类不再实现 Serializable 接口。
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

### 说明

final public function MongoDB\BSON\Timestamp::__construct(int `$increment`, int `$timestamp`)

### 参数

`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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #1 MongoDB\BSON\Timestamp::__construct() example

    <?php

    $timestamp = new MongoDB\BSON\Timestamp(1234, 5678);

    ?>

以上示例会输出：

    object(MongoDB\BSON\Timestamp)#1 (2) {
      ["increment"]=>
      int(1234)
      ["timestamp"]=>
      int(5678)
    }

### 参见

- » BSON Types: Timestamps

# MongoDB\BSON\Timestamp::getIncrement

(mongodb >=1.3.0)

MongoDB\BSON\Timestamp::getIncrement — Returns the increment component of this Timestamp

### 说明

final public function MongoDB\BSON\Timestamp::getIncrement(): int

The increment component of a Timestamp is its least significant 32 bits, whichs 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.

> 注意: Because PHP's integer type is signed, some values returned by this method may appear as negative integers on 32-bit platforms. The `"%u"` formatter of sprintf() may be used to obtain a string representation of the unsigned decimal value.

### 参数

此函数没有参数。

### 返回值

Returns the increment component of this Timestamp.

警告

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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- » BSON Types: Timestamps

# MongoDB\BSON\Timestamp::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\Timestamp::getTimestamp — Returns the timestamp component of this Timestamp

### 说明

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.

> 注意: Because PHP's integer type is signed, some values returned by this method may appear as negative integers on 32-bit platforms. The `"%u"` formatter of sprintf() may be used to obtain a string representation of the unsigned decimal value.

### 参数

此函数没有参数。

### 返回值

Returns the timestamp component of this Timestamp.

警告

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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- » BSON Types: Timestamps

# MongoDB\BSON\Timestamp::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Timestamp::jsonSerialize — Returns a representation that can be converted to JSON

### 说明

final public function MongoDB\BSON\Timestamp::jsonSerialize(): mixed

### 参数

此函数没有参数。

### 返回值

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Timestamp.

> 注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- JsonSerializable::jsonSerialize() - 指定需要被序列化成 JSON 的数据
- json_encode() - 对变量进行 JSON 编码
- 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

### 说明

final public function MongoDB\BSON\Timestamp::__toString(): string

### 参数

此函数没有参数。

### 返回值

Returns the string representation of this Timestamp.

### 示例

示例 #1 MongoDB\BSON\Timestamp::__toString() example

    <?php

    $timestamp = new MongoDB\BSON\Timestamp(1234, 5678);
    var_dump((string) $timestamp);

    ?>

以上示例的输出类似于：

    string(11) "[1234:5678]"

### 参见

- » BSON Types: Timestamps

## 目录

- 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)

## 简介

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.

## 类摘要

final class MongoDB\BSON\UTCDateTime implements MongoDB\BSON\UTCDateTimeInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* 方法 */
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
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此类不再实现 Serializable 接口。
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

### 说明

final public function MongoDB\BSON\UTCDateTime::__construct(int|MongoDB\BSON\Int64|DateTimeInterface|null `$milliseconds` = `null`)

### 参数

`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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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));

    ?>

以上示例的输出类似于：

    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"
    }

### 参见

- » BSON Types: Date

# MongoDB\BSON\UTCDateTime::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\UTCDateTime::jsonSerialize — Returns a representation that can be converted to JSON

### 说明

final public function MongoDB\BSON\UTCDateTime::jsonSerialize(): mixed

### 参数

此函数没有参数。

### 返回值

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\UTCDateTime.

> 注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- JsonSerializable::jsonSerialize() - 指定需要被序列化成 JSON 的数据
- json_encode() - 对变量进行 JSON 编码
- 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

### 说明

final public function MongoDB\BSON\UTCDateTime::toDateTime(): DateTime

### 参数

此函数没有参数。

### 返回值

Returns the DateTime representation of this UTCDateTime. The returned DateTime will use the UTC time zone.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例的输出类似于：

    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"
    }

### 参见

- 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

### 说明

final public function MongoDB\BSON\UTCDateTime::toDateTimeImmutable(): DateTimeImmutable

### 参数

此函数没有参数。

### 返回值

Returns the DateTimeImmutable representation of this UTCDateTime. The returned DateTimeImmutable will use the UTC time zone.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 示例

示例 #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());

    ?>

以上示例的输出类似于：

    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"
    }

### 参见

- 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

### 说明

final public function MongoDB\BSON\UTCDateTime::__toString(): string

### 参数

此函数没有参数。

### 返回值

Returns the string representation of this UTCDateTime.

### 示例

示例 #1 MongoDB\BSON\UTCDateTime::__toString() example

    <?php

    $utcdatetime = new MongoDB\BSON\UTCDateTime(1416445411987);
    var_dump((string) $utcdatetime);

    ?>

以上示例会输出：

    string(13) "1416445411987"

### 参见

- » BSON Types: Date

## 目录

- 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)

## 简介

Abstract base interface that should not be implemented directly.

## 接口摘要

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)

## 简介

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.

> 注意: 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.

## 接口摘要

class MongoDB\BSON\Persistable implements MongoDB\BSON\Unserializable, MongoDB\BSON\Serializable {
/* 方法 */
abstract public function bsonSerialize(): array|stdClass|MongoDB\BSON\Document
/* 继承的方法 */
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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

An array, stdClass, or MongoDB\BSON\Document to be serialized as a BSON document.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 之前声明为暂定的返回类型现在已被强制执行。
PECL mongodb 1.17.0 | This method may now also return MongoDB\BSON\Document instances in addition to array and stdClass.

### 参见

- 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

## 目录

- MongoDB\BSON\Persistable::bsonSerialize — Provides an array or document to serialize as BSON

# The MongoDB\BSON\Serializable interface

(mongodb >=1.0.0)

## 简介

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.

## 接口摘要

class MongoDB\BSON\Serializable implements MongoDB\BSON\Type {
/* 方法 */
abstract public function bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 之前声明为暂定的返回类型现在已被强制执行。
PECL mongodb 1.15.0 | 在 PHP 8.0 及更高版本中，方法的返回类型被声明为暂定（tentative）， 这会导致在实现该接口但未声明相应返回类型的代码中触发弃用提示。 可以添加 `#[ReturnTypeWillChange]` 属性来消除该弃用提示。

# MongoDB\BSON\Serializable::bsonSerialize

(mongodb >=1.0.0)

MongoDB\BSON\Serializable::bsonSerialize — Provides an array or document to serialize as BSON

### 说明

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.

### 参数

此函数没有参数。

### 返回值

An array, stdClass, MongoDB\BSON\Document, or MongoDB\BSON\PackedArray to be serialized as a BSON array or document.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 之前声明为暂定的返回类型现在已被强制执行。
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.

### 示例

示例 #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";

    ?>

以上示例的输出类似于：

    { "_id" : { "$oid" : "56cccdcada14d8755a58c591" }, "foo" : "bar" }

示例 #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";

    ?>

以上示例会输出：

    { "0" : 1, "1" : 2, "2" : 3 }

示例 #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";

    ?>

以上示例会输出：

    { "document" : { "foo" : "bar" } }

示例 #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";

    ?>

以上示例会输出：

    { "array" : [ 1, 2, 3 ] }

### 参见

- MongoDB\BSON\Unserializable::bsonUnserialize() - Constructs the object from a BSON array or document
- MongoDB\BSON\Persistable
- Persisting Data

## 目录

- MongoDB\BSON\Serializable::bsonSerialize — Provides an array or document to serialize as BSON

# The MongoDB\BSON\Unserializable interface

(mongodb >=1.0.0)

## 简介

Classes that implement this interface may be specified in a type map for unserializing BSON arrays and documents (both root and embedded).

## 接口摘要

class MongoDB\BSON\Unserializable {
/* 方法 */
abstract public function bsonUnserialize(array `$data`): void
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 之前声明为暂定的返回类型现在已被强制执行。
PECL mongodb 1.15.0 | 在 PHP 8.0 及更高版本中，方法的返回类型被声明为暂定（tentative）， 这会导致在实现该接口但未声明相应返回类型的代码中触发弃用提示。 可以添加 `#[ReturnTypeWillChange]` 属性来消除该弃用提示。

# MongoDB\BSON\Unserializable::bsonUnserialize

(mongodb >=1.0.0)

MongoDB\BSON\Unserializable::bsonUnserialize — Constructs the object from a BSON array or document

### 说明

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.

> 注意: This method acts as the constructor of the object. The __construct() method will not be called after this method.

### 参数

`data` (array)
  Properties within the BSON array or document.

### 返回值

The return value from this method is ignored.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 之前声明为暂定的返回类型现在已被强制执行。

### 示例

示例 #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']));

    ?>

以上示例会输出：

    object(MyDocument)#1 (1) {
      ["data":"MyDocument":private]=>
      array(1) {
        ["foo"]=>
        string(3) "bar"
      }
    }

### 参见

- MongoDB\BSON\Serializable::bsonSerialize() - Provides an array or document to serialize as BSON
- MongoDB\BSON\Persistable
- Persisting Data

## 目录

- MongoDB\BSON\Unserializable::bsonUnserialize — Constructs the object from a BSON array or document

# The MongoDB\BSON\BinaryInterface interface

(mongodb >=1.3.0)

## 简介

This interface is implemented by MongoDB\BSON\Binary to be used as a parameter, return, or property type in userland classes.

## 类摘要

class MongoDB\BSON\BinaryInterface {
/* 方法 */
abstract public function getData(): string
abstract public function getType(): int
abstract public function __toString(): string
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 之前声明为暂定的返回类型现在已被强制执行。
PECL mongodb 1.15.0 | 在 PHP 8.0 及更高版本中，方法的返回类型被声明为暂定（tentative）， 这会导致在实现该接口但未声明相应返回类型的代码中触发弃用提示。 可以添加 `#[ReturnTypeWillChange]` 属性来消除该弃用提示。

# MongoDB\BSON\BinaryInterface::getData

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::getData — Returns the BinaryInterface's data

### 说明

abstract public function MongoDB\BSON\BinaryInterface::getData(): string

### 参数

此函数没有参数。

### 返回值

Returns the BinaryInterface's data.

### 参见

- 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

### 说明

abstract public function MongoDB\BSON\BinaryInterface::getType(): int

### 参数

此函数没有参数。

### 返回值

Returns the BinaryInterface's type.

### 参见

- 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

### 说明

abstract public function MongoDB\BSON\BinaryInterface::__toString(): string

此方法是该方法的别名： MongoDB\BSON\BinaryInterface::getData().

### 参数

此函数没有参数。

### 返回值

Returns the BinaryInterface's data.

### 参见

- MongoDB\BSON\BinaryInterface::getData() - Returns the BinaryInterface's data
- MongoDB\BSON\Binary::__toString() - Returns the Binary's data

## 目录

- 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)

## 简介

This interface is implemented by MongoDB\BSON\Decimal128 to be used as a parameter, return, or property type in userland classes.

## 类摘要

class MongoDB\BSON\Decimal128Interface {
/* 方法 */
abstract public function __toString(): string
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 之前声明为暂定的返回类型现在已被强制执行。
PECL mongodb 1.15.0 | 在 PHP 8.0 及更高版本中，方法的返回类型被声明为暂定（tentative）， 这会导致在实现该接口但未声明相应返回类型的代码中触发弃用提示。 可以添加 `#[ReturnTypeWillChange]` 属性来消除该弃用提示。

# MongoDB\BSON\Decimal128Interface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\Decimal128Interface::__toString — Returns the string representation of this Decimal128Interface

### 说明

abstract public function MongoDB\BSON\Decimal128Interface::__toString(): string

### 参数

此函数没有参数。

### 返回值

Returns the string representation of this Decimal128Interface.

### 参见

- MongoDB\BSON\Decimal128::__toString() - Returns the string representation of this Decimal128

## 目录

- MongoDB\BSON\Decimal128Interface::__toString — Returns the string representation of this Decimal128Interface

# The MongoDB\BSON\JavascriptInterface interface

(mongodb >=1.3.0)

## 简介

This interface is implemented by MongoDB\BSON\Javascript to be used as a parameter, return, or property type in userland classes.

## 类摘要

class MongoDB\BSON\JavascriptInterface {
/* 方法 */
abstract public function getCode(): string
abstract public function getScope(): ?object
abstract public function __toString(): string
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 之前声明为暂定的返回类型现在已被强制执行。
PECL mongodb 1.15.0 | 在 PHP 8.0 及更高版本中，方法的返回类型被声明为暂定（tentative）， 这会导致在实现该接口但未声明相应返回类型的代码中触发弃用提示。 可以添加 `#[ReturnTypeWillChange]` 属性来消除该弃用提示。

# MongoDB\BSON\JavascriptInterface::getCode

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::getCode — Returns the JavascriptInterface's code

### 说明

abstract public function MongoDB\BSON\JavascriptInterface::getCode(): string

### 参数

此函数没有参数。

### 返回值

Returns the JavascriptInterface's code.

### 参见

- 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

### 说明

abstract public function MongoDB\BSON\JavascriptInterface::getScope(): ?object

### 参数

此函数没有参数。

### 返回值

Returns the JavascriptInterface's scope document.

### 参见

- 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

### 说明

abstract public function MongoDB\BSON\JavascriptInterface::__toString(): string

此方法是该方法的别名： MongoDB\BSON\JavascriptInterface::getCode().

### 参数

此函数没有参数。

### 返回值

Returns the JavascriptInterface's code.

### 参见

- MongoDB\BSON\JavascriptInterface::getCode() - Returns the JavascriptInterface's code
- MongoDB\BSON\Javascript::__toString() - Returns the Javascript's code

## 目录

- 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)

## 简介

This interface is implemented by MongoDB\BSON\MaxKey to be used as a parameter, return, or property type in userland classes.

## 类摘要

class MongoDB\BSON\MaxKeyInterface {
}

This interface has no methods.

# The MongoDB\BSON\MinKeyInterface interface

(mongodb >=1.3.0)

## 简介

This interface is implemented by MongoDB\BSON\MinKey to be used as a parameter, return, or property type in userland classes.

## 类摘要

class MongoDB\BSON\MinKeyInterface {
}

This interface has no methods.

# The MongoDB\BSON\ObjectIdInterface interface

(mongodb >=1.3.0)

## 简介

This interface is implemented by MongoDB\BSON\ObjectId to be used as a parameter, return, or property type in userland classes.

## 类摘要

class MongoDB\BSON\ObjectIdInterface {
/* 方法 */
abstract public function getTimestamp(): int
abstract public function __toString(): string
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 之前声明为暂定的返回类型现在已被强制执行。
PECL mongodb 1.15.0 | 在 PHP 8.0 及更高版本中，方法的返回类型被声明为暂定（tentative）， 这会导致在实现该接口但未声明相应返回类型的代码中触发弃用提示。 可以添加 `#[ReturnTypeWillChange]` 属性来消除该弃用提示。

# MongoDB\BSON\ObjectIdInterface::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\ObjectIdInterface::getTimestamp — Returns the timestamp component of this ObjectIdInterface

### 说明

abstract public function MongoDB\BSON\ObjectIdInterface::getTimestamp(): int

### 参数

此函数没有参数。

### 返回值

Returns the timestamp component of this ObjectIdInterface.

### 参见

- 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 hexidecimal representation of this ObjectIdInterface

### 说明

abstract public function MongoDB\BSON\ObjectIdInterface::__toString(): string

### 参数

此函数没有参数。

### 返回值

Returns the hexidecimal representation of this ObjectIdInterface.

### 参见

- MongoDB\BSON\ObjectId::__toString() - Returns the hexidecimal representation of this ObjectId

## 目录

- MongoDB\BSON\ObjectIdInterface::getTimestamp — Returns the timestamp component of this ObjectIdInterface
- MongoDB\BSON\ObjectIdInterface::__toString — Returns the hexidecimal representation of this ObjectIdInterface

# The MongoDB\BSON\RegexInterface interface

(mongodb >=1.3.0)

## 简介

This interface is implemented by MongoDB\BSON\Regex to be used as a parameter, return, or property type in userland classes.

## 类摘要

class MongoDB\BSON\RegexInterface {
/* 方法 */
abstract public function getFlags(): string
abstract public function getPattern(): string
abstract public function __toString(): string
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 之前声明为暂定的返回类型现在已被强制执行。
PECL mongodb 1.15.0 | 在 PHP 8.0 及更高版本中，方法的返回类型被声明为暂定（tentative）， 这会导致在实现该接口但未声明相应返回类型的代码中触发弃用提示。 可以添加 `#[ReturnTypeWillChange]` 属性来消除该弃用提示。

# MongoDB\BSON\RegexInterface::getFlags

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::getFlags — Returns the RegexInterface's flags

### 说明

abstract public function MongoDB\BSON\RegexInterface::getFlags(): string

### 参数

此函数没有参数。

### 返回值

Returns the RegexInterface's flags.

### 参见

- 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

### 说明

abstract public function MongoDB\BSON\RegexInterface::getPattern(): string

### 参数

此函数没有参数。

### 返回值

Returns the RegexInterface's pattern.

### 参见

- 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

### 说明

abstract public function MongoDB\BSON\RegexInterface::__toString(): string

### 参数

此函数没有参数。

### 返回值

Returns the string representation of this RegexInterface.

### 参见

- MongoDB\BSON\Regex::__toString() - Returns the string representation of this Regex

## 目录

- 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)

## 简介

This interface is implemented by MongoDB\BSON\Timestamp to be used as a parameter, return, or property type in userland classes.

## 类摘要

class MongoDB\BSON\TimestampInterface {
/* 方法 */
abstract public function getIncrement(): int
abstract public function getTimestamp(): int
abstract public function __toString(): string
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 之前声明为暂定的返回类型现在已被强制执行。
PECL mongodb 1.15.0 | 在 PHP 8.0 及更高版本中，方法的返回类型被声明为暂定（tentative）， 这会导致在实现该接口但未声明相应返回类型的代码中触发弃用提示。 可以添加 `#[ReturnTypeWillChange]` 属性来消除该弃用提示。

# MongoDB\BSON\TimestampInterface::getIncrement

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::getIncrement — Returns the increment component of this TimestampInterface

### 说明

abstract public function MongoDB\BSON\TimestampInterface::getIncrement(): int

### 参数

此函数没有参数。

### 返回值

Returns the increment component of this TimestampInterface.

警告

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.

### 参见

- 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

### 说明

abstract public function MongoDB\BSON\TimestampInterface::getTimestamp(): int

### 参数

此函数没有参数。

### 返回值

Returns the timestamp component of this TimestampInterface.

警告

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.

### 参见

- 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

### 说明

abstract public function MongoDB\BSON\TimestampInterface::__toString(): string

### 参数

此函数没有参数。

### 返回值

Returns the string representation of this TimestampInterface.

### 参见

- MongoDB\BSON\Timestamp::__toString() - Returns the string representation of this Timestamp

## 目录

- 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)

## 简介

This interface is implemented by MongoDB\BSON\UTCDateTime to be used as a parameter, return, or property type in userland classes.

## 类摘要

class MongoDB\BSON\UTCDateTimeInterface {
/* 方法 */
abstract public function toDateTime(): DateTime
abstract public function toDateTimeImmutable(): DateTimeImmutable
abstract public function __toString(): string
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 之前声明为暂定的返回类型现在已被强制执行。
PECL mongodb 1.15.0 | 在 PHP 8.0 及更高版本中，方法的返回类型被声明为暂定（tentative）， 这会导致在实现该接口但未声明相应返回类型的代码中触发弃用提示。 可以添加 `#[ReturnTypeWillChange]` 属性来消除该弃用提示。

# MongoDB\BSON\UTCDateTimeInterface::toDateTime

(mongodb >=1.3.0)

MongoDB\BSON\UTCDateTimeInterface::toDateTime — Returns the DateTime representation of this UTCDateTimeInterface

### 说明

abstract public function MongoDB\BSON\UTCDateTimeInterface::toDateTime(): DateTime

### 参数

此函数没有参数。

### 返回值

Returns the DateTime representation of this UTCDateTimeInterface. The returned DateTime should use the UTC time zone.

### 参见

- 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

### 说明

abstract public function MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable(): DateTimeImmutable

### 参数

此函数没有参数。

### 返回值

Returns the DateTimeImmutable representation of this UTCDateTimeInterface. The returned DateTimeImmutable will use the UTC time zone.

### 参见

- 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

### 说明

abstract public function MongoDB\BSON\UTCDateTimeInterface::__toString(): string

### 参数

此函数没有参数。

### 返回值

Returns the string representation of this UTCDateTimeInterface.

### 参见

- MongoDB\BSON\UTCDateTime::__toString() - Returns the string representation of this UTCDateTime

## 目录

- 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)

## 简介

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.

## 类摘要

final class MongoDB\BSON\DBPointer implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* 方法 */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此类不再实现 Serializable 接口。
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)

### 说明

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.

### 参数

此函数没有参数。

### 参见

- » BSON Types

# MongoDB\BSON\DBPointer::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::jsonSerialize — Returns a representation that can be converted to JSON

### 说明

final public function MongoDB\BSON\DBPointer::jsonSerialize(): mixed

### 参数

此函数没有参数。

### 返回值

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\DBPointer.

> 注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- JsonSerializable::jsonSerialize() - 指定需要被序列化成 JSON 的数据
- json_encode() - 对变量进行 JSON 编码
- 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

### 说明

final public function MongoDB\BSON\DBPointer::__toString(): string

### 参数

此函数没有参数。

### 返回值

Returns an empty string.

### 参见

- » BSON Types

## 目录

- 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)

## 简介

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.

## 类摘要

final class MongoDB\BSON\Int64 implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* 方法 */
final public function __construct(int|string `$value`)
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此类不再实现 Serializable 接口。
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

### 说明

final public function MongoDB\BSON\Int64::__construct(int|string `$value`)

Creates a new MongoDB\BSON\Int64 instance for the given integer value.

### 参数

`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.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 1.16.0 | This method was made public to support creating Int64 instances when working with raw BSON.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if string `value` cannot be parsed as a 64-bit integer.

### 参见

- » BSON Types

# MongoDB\BSON\Int64::jsonSerialize

(mongodb >=1.5.0)

MongoDB\BSON\Int64::jsonSerialize — Returns a representation that can be converted to JSON

### 说明

final public function MongoDB\BSON\Int64::jsonSerialize(): mixed

### 参数

此函数没有参数。

### 返回值

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Int64.

> 注意: 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.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- JsonSerializable::jsonSerialize() - 指定需要被序列化成 JSON 的数据
- json_encode() - 对变量进行 JSON 编码
- 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

### 说明

final public function MongoDB\BSON\Int64::__toString(): string

### 参数

此函数没有参数。

### 返回值

Returns the string representation of this Int64.

### 示例

示例 #1 MongoDB\BSON\Int64::__toString() example

    <?php

    $int64 = new MongoDB\BSON\Int64('9223372036854775807');

    var_dump((string) $int64);

    ?>

以上示例的输出类似于：

    string(19) "9223372036854775807"

### 参见

- » BSON Types

## 目录

- 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)

## 简介

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.

## 类摘要

final class MongoDB\BSON\Symbol implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* 方法 */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此类不再实现 Serializable 接口。
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)

### 说明

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.

### 参数

此函数没有参数。

### 参见

- » BSON Types

# MongoDB\BSON\Symbol::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::jsonSerialize — Returns a representation that can be converted to JSON

### 说明

final public function MongoDB\BSON\Symbol::jsonSerialize(): mixed

### 参数

此函数没有参数。

### 返回值

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Symbol.

> 注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- JsonSerializable::jsonSerialize() - 指定需要被序列化成 JSON 的数据
- json_encode() - 对变量进行 JSON 编码
- 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

### 说明

final public function MongoDB\BSON\Symbol::__toString(): string

### 参数

此函数没有参数。

### 返回值

Returns the string representation of this Symbol.

### 参见

- » BSON Types

## 目录

- 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)

## 简介

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.

## 类摘要

final class MongoDB\BSON\Undefined implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* 方法 */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此类不再实现 Serializable 接口。
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)

### 说明

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.

### 参数

此函数没有参数。

### 参见

- » BSON Types

# MongoDB\BSON\Undefined::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::jsonSerialize — Returns a representation that can be converted to JSON

### 说明

final public function MongoDB\BSON\Undefined::jsonSerialize(): mixed

### 参数

此函数没有参数。

### 返回值

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Undefined.

> 注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- JsonSerializable::jsonSerialize() - 指定需要被序列化成 JSON 的数据
- json_encode() - 对变量进行 JSON 编码
- 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

### 说明

final public function MongoDB\BSON\Undefined::__toString(): string

### 参数

此函数没有参数。

### 返回值

Returns an empty string.

### 参见

- » BSON Types

## 目录

- 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

## 目录

- 函数
- 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

# 函数

# MongoDB\Driver\Monitoring\addSubscriber

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\addSubscriber — Registers a monitoring event subscriber globally

### 说明

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.

> 注意: 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.

### 参数

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  A monitoring event subscriber to register globally.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

function MongoDB\Driver\Monitoring\removeSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Unregisters a monitoring event subscriber globally.

> 注意: If `subscriber` is not already registered globally, this function is a no-op.

### 参数

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  A monitoring event subscriber to unregister globally.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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)

## 目录

- 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)

## 简介

The MongoDB\Driver\Monitoring\CommandFailedEvent class encapsulates information about a failed command.

## 类摘要

final class MongoDB\Driver\Monitoring\CommandFailedEvent {
/* 属性 */
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;
/* 方法 */
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
}

## 属性

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.

## 更新日志

版本 | 说明
--- | ---
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

### 说明

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName(): string

Returns the command name (e.g. `"find"`, `"aggregate"`).

### 参数

此函数没有参数。

### 返回值

Returns the command name.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName(): string

### 参数

此函数没有参数。

### 返回值

Returns the database on which the command was executed.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the command's duration in microseconds.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getError(): Exception

### 参数

此函数没有参数。

### 返回值

Returns the Exception associated with the failed command.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getHost(): string

### 参数

此函数没有参数。

### 返回值

Returns the hostname of the server on which the command was executed.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId — Returns the command's operation ID

### 说明

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.

> 注意: 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.

### 参数

此函数没有参数。

### 返回值

Returns the command's operation ID.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getPort(): int

### 参数

此函数没有参数。

### 返回值

Returns the port of the server on which the command was executed.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getReply

(mongodb >=1.5.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getReply — Returns the command reply document

### 说明

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).

### 参数

此函数没有参数。

### 返回值

Returns the command reply document as a stdClass object.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the command's request ID.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

警告

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.

### 说明

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getServer(): MongoDB\Driver\Server

Returns the MongoDB\Driver\Server on which the command was executed.

### 参数

此函数没有参数。

### 返回值

Returns the MongoDB\Driver\Server on which the command was executed.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此方法已被移除。

### 参见

- 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

### 说明

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+.

### 参数

此函数没有参数。

### 返回值

Returns the server connection ID, or `null` if it is not available.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId — Returns the load balancer service ID for the command

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the load balancer service ID, or `null` if the driver is not connected to a load balancer.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

## 目录

- 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)

## 简介

The MongoDB\Driver\Monitoring\CommandStartedEvent class encapsulates information about a started command.

## 类摘要

final class MongoDB\Driver\Monitoring\CommandStartedEvent {
/* 属性 */
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;
/* 方法 */
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
}

## 属性

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.

## 更新日志

版本 | 说明
--- | ---
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

### 说明

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).

### 参数

此函数没有参数。

### 返回值

Returns the command document as a stdClass object.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- Application Performance Monitoring (APM)
- Persisting Data

# MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName — Returns the command name

### 说明

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName(): string

Returns the command name (e.g. `"find"`, `"aggregate"`).

### 参数

此函数没有参数。

### 返回值

Returns the command name.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName(): string

### 参数

此函数没有参数。

### 返回值

Returns the database on which the command was executed.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getHost(): string

### 参数

此函数没有参数。

### 返回值

Returns the hostname of the server on which the command was executed.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId — Returns the command's operation ID

### 说明

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.

> 注意: 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.

### 参数

此函数没有参数。

### 返回值

Returns the command's operation ID.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getPort(): int

### 参数

此函数没有参数。

### 返回值

Returns the port of the server on which the command was executed.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId — Returns the command's request ID

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the command's request ID.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

警告

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.

### 说明

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getServer(): MongoDB\Driver\Server

Returns the MongoDB\Driver\Server on which the command was executed.

### 参数

此函数没有参数。

### 返回值

Returns the MongoDB\Driver\Server on which the command was executed.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此方法已被移除。

### 参见

- 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

### 说明

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+.

### 参数

此函数没有参数。

### 返回值

Returns the server connection ID, or `null` if it is not available.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId — Returns the load balancer service ID for the command

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the load balancer service ID, or `null` if the driver is not connected to a load balancer.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

## 目录

- 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)

## 简介

The MongoDB\Driver\Monitoring\CommandSucceededEvent class encapsulates information about a successful command.

## 类摘要

final class MongoDB\Driver\Monitoring\CommandSucceededEvent {
/* 属性 */
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;
/* 方法 */
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
}

## 属性

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.

## 更新日志

版本 | 说明
--- | ---
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

### 说明

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName(): string

Returns the command name (e.g. `"find"`, `"aggregate"`).

### 参数

此函数没有参数。

### 返回值

Returns the command name.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName(): string

### 参数

此函数没有参数。

### 返回值

Returns the database on which the command was executed.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the command's duration in microseconds.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost(): string

### 参数

此函数没有参数。

### 返回值

Returns the hostname of the server on which the command was executed.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId — Returns the command's operation ID

### 说明

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.

> 注意: 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.

### 参数

此函数没有参数。

### 返回值

Returns the command's operation ID.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort(): int

### 参数

此函数没有参数。

### 返回值

Returns the port of the server on which the command was executed.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply — Returns the command reply document

### 说明

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).

### 参数

此函数没有参数。

### 返回值

Returns the command reply document as a stdClass object.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the command's request ID.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

警告

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.

### 说明

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer(): MongoDB\Driver\Server

Returns the MongoDB\Driver\Server on which the command was executed.

### 参数

此函数没有参数。

### 返回值

Returns the MongoDB\Driver\Server on which the command was executed.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此方法已被移除。

### 参见

- 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

### 说明

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+.

### 参数

此函数没有参数。

### 返回值

Returns the server connection ID, or `null` if it is not available.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId — Returns the load balancer service ID for the command

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the load balancer service ID, or `null` if the driver is not connected to a load balancer.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

## 目录

- 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)

## 简介

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.

## 类摘要

final class MongoDB\Driver\Monitoring\ServerChangedEvent {
/* 属性 */
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;
/* 方法 */
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
}

## 属性

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.

## 更新日志

版本 | 说明
--- | ---
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

### 说明

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getHost(): string

### 参数

此函数没有参数。

### 返回值

Returns the hostname of the server.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription — Returns the new description for the server

### 说明

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription(): MongoDB\Driver\ServerDescription

### 参数

此函数没有参数。

### 返回值

Returns the new MongoDB\Driver\ServerDescription for the server.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getPort — Returns the port on which this server is listening

### 说明

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getPort(): int

### 参数

此函数没有参数。

### 返回值

Returns the port on which this server is listening.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription — Returns the previous description for the server

### 说明

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription(): MongoDB\Driver\ServerDescription

### 参数

此函数没有参数。

### 返回值

Returns the previous MongoDB\Driver\ServerDescription for the server.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId — Returns the topology ID associated with this server

### 说明

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### 参数

此函数没有参数。

### 返回值

Returns the topology ID.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

## 目录

- 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)

## 简介

The MongoDB\Driver\Monitoring\ServerClosedEvent class encapsulates information about a closed server. This corresponds to an existing server being removed from the topology.

## 类摘要

final class MongoDB\Driver\Monitoring\ServerClosedEvent {
/* 属性 */
public readonly string $host;
public readonly int $port;
public readonly MongoDB\BSON\ObjectId $topologyId;
/* 方法 */
final public function getHost(): string
final public function getPort(): int
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## 属性

host
  The hostname of the server.
port
  The port of the server.
topologyId
  The topology ID.

## 更新日志

版本 | 说明
--- | ---
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

### 说明

final public function MongoDB\Driver\Monitoring\ServerClosedEvent::getHost(): string

### 参数

此函数没有参数。

### 返回值

Returns the hostname of the server.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerClosedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getPort — Returns the port on which this server is listening

### 说明

final public function MongoDB\Driver\Monitoring\ServerClosedEvent::getPort(): int

### 参数

此函数没有参数。

### 返回值

Returns the port on which this server is listening.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId — Returns the topology ID associated with this server

### 说明

final public function MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### 参数

此函数没有参数。

### 返回值

Returns the topology ID.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

## 目录

- 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)

## 简介

The MongoDB\Driver\Monitoring\ServerOpeningEvent class encapsulates information about an opened server. This corresponds to a new server being added to the topology.

## 类摘要

final class MongoDB\Driver\Monitoring\ServerOpeningEvent {
/* 属性 */
public readonly string $host;
public readonly int $port;
public readonly MongoDB\BSON\ObjectId $topologyId;
/* 方法 */
final public function getHost(): string
final public function getPort(): int
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## 属性

host
  The hostname of the server.
port
  The port of the server.
topologyId
  The topology ID.

## 更新日志

版本 | 说明
--- | ---
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

### 说明

final public function MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost(): string

### 参数

此函数没有参数。

### 返回值

Returns the hostname of the server.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort — Returns the port on which this server is listening

### 说明

final public function MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort(): int

### 参数

此函数没有参数。

### 返回值

Returns the port on which this server is listening.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId — Returns the topology ID associated with this server

### 说明

final public function MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId(): MongoDB\BSON\ObjectId

### 参数

此函数没有参数。

### 返回值

Returns the topology ID.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

## 目录

- 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)

## 简介

The MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent class encapsulates information about a failed server heartbeat (i.e. » hello command issued through » server monitoring).

## 类摘要

final class MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent {
/* 属性 */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
public readonly int $duration;
public readonly Exception $error;
/* 方法 */
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
}

## 属性

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.

## 更新日志

版本 | 说明
--- | ---
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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the heartbeat's duration in microseconds.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError — Returns the Exception associated with the failed heartbeat

### 说明

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError(): Exception

### 参数

此函数没有参数。

### 返回值

Returns the Exception associated with the failed heartbeat.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost — Returns the hostname of the server

### 说明

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost(): string

### 参数

此函数没有参数。

### 返回值

Returns the hostname of the server.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort — Returns the port on which this server is listening

### 说明

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort(): int

### 参数

此函数没有参数。

### 返回值

Returns the port on which this server is listening.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited — Returns whether the heartbeat used a streaming protocol

### 说明

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`.

### 参数

此函数没有参数。

### 返回值

Returns `false`.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

## 目录

- 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)

## 简介

The MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent class encapsulates information about a started server heartbeat (i.e. » hello command issued through » server monitoring).

## 类摘要

final class MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent {
/* 属性 */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
/* 方法 */
final public function getHost(): string
final public function getPort(): int
final public function isAwaited(): bool
}

## 属性

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`.

## 更新日志

版本 | 说明
--- | ---
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

### 说明

final public function MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost(): string

### 参数

此函数没有参数。

### 返回值

Returns the hostname of the server.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort — Returns the port on which this server is listening

### 说明

final public function MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort(): int

### 参数

此函数没有参数。

### 返回值

Returns the port on which this server is listening.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited — Returns whether the heartbeat used a streaming protocol

### 说明

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`.

### 参数

此函数没有参数。

### 返回值

Returns `false`.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

## 目录

- 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)

## 简介

The MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent class encapsulates information about a successful server heartbeat (i.e. » hello command issued through » server monitoring).

## 类摘要

final class MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent {
/* 属性 */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
public readonly int $duration;
public readonly object $reply;
/* 方法 */
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
}

## 属性

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.

## 更新日志

版本 | 说明
--- | ---
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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the heartbeat's duration in microseconds.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost — Returns the hostname of the server

### 说明

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost(): string

### 参数

此函数没有参数。

### 返回值

Returns the hostname of the server.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort — Returns the port on which this server is listening

### 说明

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort(): int

### 参数

此函数没有参数。

### 返回值

Returns the port on which this server is listening.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply — Returns the heartbeat reply document

### 说明

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).

### 参数

此函数没有参数。

### 返回值

Returns the heartbeat reply document as a stdClass object.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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`.

### 参数

此函数没有参数。

### 返回值

Returns `false`.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

## 目录

- 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)

## 简介

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.

## 类摘要

final class MongoDB\Driver\Monitoring\TopologyChangedEvent {
/* 属性 */
public readonly MongoDB\BSON\ObjectId $topologyId;
public readonly MongoDB\Driver\TopologyDescription $newDescription;
public readonly MongoDB\Driver\TopologyDescription $previousDescription;
/* 方法 */
final public function getNewDescription(): MongoDB\Driver\TopologyDescription
final public function getPreviousDescription(): MongoDB\Driver\TopologyDescription
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## 属性

topologyId
  The topology ID.
newDescription
  The new topology description.
previousDescription
  The previous topology description.

## 更新日志

版本 | 说明
--- | ---
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

### 说明

final public function MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription(): MongoDB\Driver\TopologyDescription

### 参数

此函数没有参数。

### 返回值

Returns the new MongoDB\Driver\TopologyDescription for the topology.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription — Returns the previous description for the topology

### 说明

final public function MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription(): MongoDB\Driver\TopologyDescription

### 参数

此函数没有参数。

### 返回值

Returns the previous MongoDB\Driver\TopologyDescription for the topology.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId — Returns the topology ID

### 说明

final public function MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### 参数

此函数没有参数。

### 返回值

Returns the topology ID.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

## 目录

- 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)

## 简介

The MongoDB\Driver\Monitoring\TopologyClosedEvent class encapsulates information about a closed topology.

> 注意: 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).

## 类摘要

final class MongoDB\Driver\Monitoring\TopologyClosedEvent {
/* 属性 */
public readonly MongoDB\BSON\ObjectId $topologyId;
/* 方法 */
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## 属性

topologyId
  The topology ID.

## 更新日志

版本 | 说明
--- | ---
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

### 说明

final public function MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### 参数

此函数没有参数。

### 返回值

Returns the topology ID.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

## 目录

- MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId — Returns the topology ID

# The MongoDB\Driver\Monitoring\TopologyOpeningEvent class

(mongodb >=1.13.0)

## 简介

The MongoDB\Driver\Monitoring\TopologyOpeningEvent class encapsulates information about an opened topology.

> 注意: 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.

## 类摘要

final class MongoDB\Driver\Monitoring\TopologyOpeningEvent {
/* 属性 */
public readonly MongoDB\BSON\ObjectId $topologyId;
/* 方法 */
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## 属性

topologyId
  The topology ID.

## 更新日志

版本 | 说明
--- | ---
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

### 说明

final public function MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId(): MongoDB\BSON\ObjectId

### 参数

此函数没有参数。

### 返回值

Returns the topology ID.

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

## 目录

- MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId — Returns the topology ID

# The MongoDB\Driver\Monitoring\CommandSubscriber interface

(mongodb >=1.3.0)

## 简介

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.

## 接口摘要

class MongoDB\Driver\Monitoring\CommandSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* 方法 */
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
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 之前声明为暂定的返回类型现在已被强制执行。
PECL mongodb 1.15.0 | 在 PHP 8.0 及更高版本中，方法的返回类型被声明为暂定（tentative）， 这会导致在实现该接口但未声明相应返回类型的代码中触发弃用提示。 可以添加 `#[ReturnTypeWillChange]` 属性来消除该弃用提示。

# MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed — Notification method for a failed command

### 说明

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.

### 参数

`event` (MongoDB\Driver\Monitoring\CommandFailedEvent)
  An event object encapsulating information about the failed command.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

`event` (MongoDB\Driver\Monitoring\CommandStartedEvent)
  An event object encapsulating information about the started command.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

`event` (MongoDB\Driver\Monitoring\CommandSucceededEvent)
  An event object encapsulating information about the successful command.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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)

## 目录

- 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)

## 简介

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.

## 接口摘要

class MongoDB\Driver\Monitoring\LogSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* 常量 */
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;
/* 方法 */
abstract public function log(int `$level`, string `$domain`, string `$message`): void
}

## 预定义常量

`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

### 说明

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.

### 参数

`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.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally

## 目录

- MongoDB\Driver\Monitoring\LogSubscriber::log — Notification method for a log message

# The MongoDB\Driver\Monitoring\SDAMSubscriber interface

(mongodb >=1.13.0)

## 简介

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.

## 接口摘要

class MongoDB\Driver\Monitoring\SDAMSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* 方法 */
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
}

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 之前声明为暂定的返回类型现在已被强制执行。
PECL mongodb 1.15.0 | 在 PHP 8.0 及更高版本中，方法的返回类型被声明为暂定（tentative）， 这会导致在实现该接口但未声明相应返回类型的代码中触发弃用提示。 可以添加 `#[ReturnTypeWillChange]` 属性来消除该弃用提示。

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged — Notification method for a server description change

### 说明

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.

### 参数

`event` (MongoDB\Driver\Monitoring\ServerChangedEvent)
  An event object encapsulating information about the changed server description.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

`event` (MongoDB\Driver\Monitoring\ServerClosedEvent)
  An event object encapsulating information about the closed server.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

`event` (MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent)
  An event object encapsulating information about the failed server heartbeat.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

`event` (MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent)
  An event object encapsulating information about the started server heartbeat.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

`event` (MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent)
  An event object encapsulating information about the successful server heartbeat.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

`event` (MongoDB\Driver\Monitoring\ServerOpeningEvent)
  An event object encapsulating information about the opened server.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

### 参数

`event` (MongoDB\Driver\Monitoring\TopologyChangedEvent)
  An event object encapsulating information about the changed topology description.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

> 注意: 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).

### 参数

`event` (MongoDB\Driver\Monitoring\TopologyClosedEvent)
  An event object encapsulating information about the closed topology.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

### 说明

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.

> 注意: 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.

### 参数

`event` (MongoDB\Driver\Monitoring\TopologyOpeningEvent)
  An event object encapsulating information about the opened topology.

### 返回值

没有返回值。

### 错误／异常

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参见

- 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

## 目录

- 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)

## 简介

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.

## 接口摘要

class MongoDB\Driver\Monitoring\Subscriber {
}

This interface has no methods. Its only purpose is to be the base interface for all event subscribers.

# Exception 类

## 目录

- 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)

## 简介

Thrown when the driver fails to authenticate with the server.

## 类摘要

class MongoDB\Driver\Exception\AuthenticationException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* 继承的属性 */
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;
/* 继承的方法 */
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)

## 简介

Thrown when a bulk write operation fails.

## 类摘要

class MongoDB\Driver\Exception\BulkWriteException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* 属性 */
public readonly MongoDB\Driver\WriteResult $writeResult;
/* 继承的属性 */
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;
/* 方法 */
final public function getWriteResult(): MongoDB\Driver\WriteResult
/* 继承的方法 */
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
}

## 属性

writeResult
  The MongoDB\Driver\WriteResult associated with the failed write operation.

## 更新日志

版本 | 说明
--- | ---
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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

The MongoDB\Driver\WriteResult for the failed write operation.

### 示例

示例 #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);
        }
    }

    ?>

以上示例的输出类似于：

    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
      }
    }

### 参见

- MongoDB\Driver\WriteResult
- MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations

## 目录

- MongoDB\Driver\Exception\BulkWriteException::getWriteResult — Returns the WriteResult for the failed write operation

# The MongoDB\Driver\Exception\BulkWriteCommandException class

(mongodb >=2.1.0)

## 简介

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.

## 类摘要

class MongoDB\Driver\Exception\BulkWriteCommandException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* 属性 */
private ?MongoDB\BSON\Document $errorReply;
private ?MongoDB\Driver\BulkWriteCommandResult $partialResult;
private array $writeConcernErrors;
private array $writeErrors;
/* 继承的属性 */
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;
/* 方法 */
final public function getErrorReply(): ?MongoDB\BSON\Document
final public function getPartialResult(): ?MongoDB\Driver\BulkWriteCommandResult
final public function getWriteConcernErrors(): array
final public function getWriteErrors(): array
/* 继承的方法 */
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
}

## 属性

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

### 说明

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply(): ?MongoDB\BSON\Document

### 参数

此函数没有参数。

### 返回值

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.

### 示例

示例 #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());
    }

    ?>

以上示例的输出类似于：

    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"
      }
    }

### 参见

- 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

### 说明

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult(): ?MongoDB\Driver\BulkWriteCommandResult

### 参数

此函数没有参数。

### 返回值

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).

### 示例

示例 #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());

    ?>

以上示例会输出：

    int(1)

示例 #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());

    ?>

以上示例会输出：

    NULL

### 参见

- 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

### 说明

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors(): array

### 参数

此函数没有参数。

### 返回值

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.

### 示例

示例 #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());
    }

    ?>

以上示例的输出类似于：

    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"
          }
        }
      }
    }

### 参见

- 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

### 说明

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors(): array

### 参数

此函数没有参数。

### 返回值

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.

### 示例

示例 #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());
    }

    ?>

以上示例的输出类似于：

    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) {
        }
      }
    }

### 参见

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command
- MongoDB\Driver\WriteError

## 目录

- 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)

## 简介

Thrown when a command fails.

## 类摘要

class MongoDB\Driver\Exception\CommandException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* 属性 */
public readonly object $resultDocument;
/* 继承的属性 */
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;
/* 方法 */
final public function getResultDocument(): object
/* 继承的方法 */
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
}

## 属性

resultDocument
  The result document associated with the failed command.

## 更新日志

版本 | 说明
--- | ---
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

### 说明

final public function MongoDB\Driver\Exception\CommandException::getResultDocument(): object

Returns the result document for the failed command.

### 参数

此函数没有参数。

### 返回值

The result document for the failed command.

### 参见

- MongoDB\Driver\Manager::executeCommand() - Execute a database command

## 目录

- MongoDB\Driver\Exception\CommandException::getResultDocument — Returns the result document for the failed command

# The MongoDB\Driver\Exception\ConnectionException class

(mongodb >= 1.0.0)

## 简介

Base class for exceptions thrown when the driver fails to establish a database connection.

## 类摘要

class MongoDB\Driver\Exception\ConnectionException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* 继承的属性 */
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;
/* 继承的方法 */
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)

## 简介

Thrown when the driver fails to establish a database connection within a specified time limit (connectTimeoutMS) or server selection fails (serverSelectionTimeoutMS).

## 类摘要

final class MongoDB\Driver\Exception\ConnectionTimeoutException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* 继承的属性 */
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;
/* 继承的方法 */
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)

## 简介

Base class for exceptions thrown during client-side encryption.

## 类摘要

class MongoDB\Driver\Exception\EncryptionException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* 继承的属性 */
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;
/* 继承的方法 */
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)

## 简介

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).

## 类摘要

class MongoDB\Driver\Exception\Exception {
}

# The MongoDB\Driver\Exception\ExecutionTimeoutException class

(mongodb >= 1.0.0)

## 简介

Thrown when a query or command fails to complete within a specified time limit (e.g. » maxTimeMS).

## 类摘要

final class MongoDB\Driver\Exception\ExecutionTimeoutException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* 继承的属性 */
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;
/* 继承的方法 */
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
}

## 更新日志

版本 | 说明
--- | ---
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)

## 简介

Thrown when a driver method is given invalid arguments (e.g. invalid option types).

## 类摘要

class MongoDB\Driver\Exception\InvalidArgumentException extends InvalidArgumentException implements MongoDB\Driver\Exception\Exception {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?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 MongoDB\Driver\Exception\LogicException class

(mongodb >= 1.0.0)

## 简介

Thrown when the driver is incorrectly used (e.g. rewinding a cursor).

## 类摘要

class MongoDB\Driver\Exception\LogicException extends LogicException implements MongoDB\Driver\Exception\Exception {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?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 MongoDB\Driver\Exception\RuntimeException class

(mongodb >= 1.0.0)

## 简介

Thrown when the driver encounters a runtime error (e.g. internal error from » libmongoc).

## 类摘要

class MongoDB\Driver\Exception\RuntimeException extends RuntimeException implements MongoDB\Driver\Exception\Exception {
/* 属性 */
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;
/* 方法 */
final public function 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
}

## 属性

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.

## 更新日志

版本 | 说明
--- | ---
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

### 说明

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`.

### 参数

`errorLabel`
  The name of the `errorLabel` to test for.

### 返回值

Whether the given `errorLabel` is associated with this exception.

### 参见

- MongoDB\Driver\Session::commitTransaction() - Commits a transaction
- » MongoDB documentation on transactions

## 目录

- 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)

## 简介

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.

## 类摘要

class MongoDB\Driver\Exception\ServerException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* 继承的属性 */
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;
/* 继承的方法 */
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)

警告

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.

## 简介

Thrown when the driver fails to establish an SSL connection with the server.

## 类摘要

final class MongoDB\Driver\Exception\SSLConnectionException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* 继承的属性 */
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;
/* 继承的方法 */
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)

## 简介

Thrown when the driver encounters an unexpected value (e.g. during BSON serialization or deserialization).

## 类摘要

class MongoDB\Driver\Exception\UnexpectedValueException extends UnexpectedValueException implements MongoDB\Driver\Exception\Exception {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?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 MongoDB\Driver\Exception\WriteException class

(mongodb >= 1.0.0)

警告

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.

## 简介

Base class for exceptions thrown by a failed write operation. The exception encapsulates a MongoDB\Driver\WriteResult object.

## 类摘要

abstract class MongoDB\Driver\Exception\WriteException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* 属性 */
protected MongoDB\Driver\WriteResult $writeResult;
/* 继承的属性 */
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;
/* 方法 */
final public function getWriteResult(): MongoDB\Driver\WriteResult
/* 继承的方法 */
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
}

## 属性

writeResult
  The MongoDB\Driver\WriteResult associated with the failed write operation.

## 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 此类已被移除。
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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

The MongoDB\Driver\WriteResult for the failed write operation.

### 示例

示例 #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);
        }
    }

    ?>

以上示例的输出类似于：

    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
      }
    }

### 参见

- MongoDB\Driver\WriteResult
- MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations

## 目录

- 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

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
- 预定义常量
- 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 扩展类
  - 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
  - 函数
  - 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
  - 函数
  - 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 类
  - 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

# MySQL Drivers and Plugins

PHP offers several MySQL drivers and plugins for accessing and handling MySQL.

The differences and functionality of the MySQL extensions are described within the overview of this section.

The extensions listed support the MySQL protocol. Examples of compatible database servers are » MariaDB Server, » MySQL Server, » Percona Server for MySQL, and » TiDB.

# Overview of the MySQL PHP drivers

# Introduction

There are several PHP APIs for accessing the MySQL database. Users can choose between the mysqli or PDO_MySQL extensions.

This guide explains the terminology used to describe each API, information about choosing which API to use, and also information to help choose which MySQL library to use with the API.

# Terminology overview

This section provides an introduction to the options available to you when developing a PHP application that needs to interact with a MySQL database.

What is an API?

An Application Programming Interface, or API, defines the classes, methods, functions and variables that your application will need to call in order to carry out its desired task. In the case of PHP applications that need to communicate with databases the necessary APIs are usually exposed via PHP extensions.

APIs can be procedural or object-oriented. With a procedural API you call functions to carry out tasks, with the object-oriented API you instantiate classes and then call methods on the resulting objects. Of the two, the latter is usually the preferred interface, as it is more modern and leads to better organized code.

When writing PHP applications that need to connect to the MySQL server there are several API options available. This document discusses what is available and how to select the best solution for your application.

What is a Connector?

In the MySQL documentation, the term connector refers to a piece of software that allows your application to connect to the MySQL database server. MySQL provides connectors for a variety of languages, including PHP.

If your PHP application needs to communicate with a database server you will need to write PHP code to perform such activities as connecting to the database server, querying the database and other database-related functions. Software is required to provide the API that your PHP application will use, and also handle the communication between your application and the database server, possibly using other intermediate libraries where necessary. This software is known generically as a connector, as it allows your application to connect to a database server.

What is a Driver?

A driver is a piece of software designed to communicate with a specific type of database server. The driver may also call a library, such as the MySQL Client Library or the MySQL Native Driver. These libraries implement the low-level protocol used to communicate with the MySQL database server.

By way of an example, the PHP Data Objects (PDO) database abstraction layer may use one of several database-specific drivers. One of the drivers it has available is the PDO MYSQL driver, which allows it to interface with the MySQL server.

Sometimes people use the terms connector and driver interchangeably, this can be confusing. In the MySQL-related documentation the term driver is reserved for software that provides the database-specific part of a connector package.

What is an Extension?

In the PHP documentation, you will come across another term - extension. The PHP code consists of a core, with optional extensions to the core functionality. PHP's MySQL-related extension, `mysqli`, is implemented using the PHP extension framework.

An extension typically exposes an API to the PHP programmer, to allow its facilities to be used programmatically. However, some extensions which use the PHP extension framework do not expose an API to the PHP programmer.

The PDO MySQL driver extension, for example, does not expose an API to the PHP programmer, but provides an interface to the PDO layer above it.

The terms API and extension should not be taken to mean the same thing, as an extension may not necessarily expose an API to the programmer.

# Choosing an API

PHP offers different APIs to connect to MySQL. Below we show the APIs provided by the mysqli and PDO extensions. Each code snippet creates a connection to a MySQL server running on "example.com" using the username "user" and the password "password". And a query is run to greet the user.

示例 #1 Comparing the 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']);

示例 #2 Comparing prepared statements

    <?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']);

Feature comparison

The overall performance of both extensions is considered to be about the same. Although the performance of the extension contributes only a fraction of the total run time of a PHP web request. Often, the impact is as low as 0.1%.

| ext/mysqli | PDO_MySQL
--- | --- | ---
PHP version introduced | 5.0 | 5.1
Included with PHP 7.x and 8.x | Yes | Yes
Development status | Active | Active
Lifecycle | Active | Active
Recommended for new projects | Yes | Yes
OOP Interface | Yes | Yes
Procedural Interface | Yes | No
API supports non-blocking, asynchronous queries with mysqlnd | Yes | No
Persistent Connections | Yes | Yes
API supports Charsets | Yes | Yes
API supports server-side Prepared Statements | Yes | Yes
API supports client-side Prepared Statements | No | Yes
API supports Stored Procedures | Yes | Yes
API supports Multiple Statements | Yes | Most
API supports Transactions | Yes | Yes
Transactions can be controlled with SQL | Yes | Yes
Supports all MySQL 5.1+ functionality | Yes | Most

# Choosing a library

The mysqli and PDO_MySQL PHP extensions are lightweight wrappers on top of a C client library. The extensions can either use the mysqlnd library or the `libmysqlclient` library. Choosing a library is a compile time decision.

The mysqlnd library is part of the PHP distribution. It offers features like lazy connections and query caching, features that are not available with libmysqlclient, so using the built-in mysqlnd library is highly recommended. See the mysqlnd documentation for additional details, and a listing of features and functionality that it offers.

示例 #1 Configure commands for using mysqlnd or libmysqlclient

    // Recommended, compiles with mysqlnd
    $ ./configure --with-mysqli=mysqlnd --with-pdo-mysql=mysqlnd

    // Alternatively recommended, compiles with mysqlnd
    $ ./configure --with-mysqli --with-pdo-mysql

    // Not recommended, compiles with libmysqlclient
    $ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-mysql=/path/to/mysql_config

Library feature comparison

It is recommended to use the mysqlnd library instead of the MySQL Client Server library (libmysqlclient). Both libraries are supported and constantly being improved.

| MySQL native driver (mysqlnd) | MySQL client server library (`libmysqlclient`)
--- | --- | ---
Part of the PHP distribution | Yes | No
PHP version introduced | 5.3.0 | N/A
License | PHP License 3.01 | Dual-License
Development status | Active | Active
Lifecycle | No end announced | No end announced
Compile default (for all MySQL extensions) | Yes | No
Compression protocol support | Yes | Yes
SSL support | Yes | Yes
Named pipe support | Yes | Yes
Non-blocking, asynchronous queries | Yes | No
Performance statistics | Yes | No
LOAD LOCAL INFILE respects the open_basedir directive | Yes | No
Uses PHP's native memory management system (e.g., follows PHP memory limits) | Yes | No
Return numeric column as double (COM_QUERY) | Yes | No
Return numeric column as string (COM_QUERY) | Yes | Yes
Plugin API | Yes | Limited
Automatic reconnect | No | Optional

# Concepts

## 目录

- Buffered and Unbuffered queries
- Character sets

These concepts are specific to the MySQL drivers for PHP.

## Buffered and Unbuffered queries

Queries are using the buffered mode by default. This means that query results are immediately transferred from the MySQL Server to PHP and then are kept in the memory of the PHP process. This allows additional operations like counting the number of rows, and moving (seeking) the current result pointer. It also allows issuing further queries on the same connection while working on the result set. The downside of the buffered mode is that larger result sets might require quite a lot memory. The memory will be kept occupied till all references to the result set are unset or the result set was explicitly freed, which will automatically happen during request end at the latest. The terminology "store result" is also used for buffered mode, as the whole result set is stored at once.

> 注意: When using libmysqlclient as library PHP's memory limit won't count the memory used for result sets unless the data is fetched into PHP variables. With mysqlnd the memory accounted for will include the full result set.

Unbuffered MySQL queries execute the query and then wait for the data from the MySQL server to be fetched. This uses less memory on the PHP-side, but can increase the load on the server. Unless the full result set was fetched from the server no further queries can be sent over the same connection. Unbuffered queries can also be referred to as "use result". Once all rows in the result set are fetched, the result set is gone and it cannot be iterated again.

Following these characteristics, unbuffered queries should be used only when a large result set is expected that will be processed sequentially. Unbuffered queries contain a number of pitfalls that makes it more difficult to use them, e.g. the number of rows in the result set is unknown until the last row is fetched. Buffered queries are the easier and more flexible way to process result sets.

Because buffered queries are the default, the examples below will demonstrate how to execute unbuffered queries with each API.

示例 #1 Unbuffered query example: 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;
    }
    ?>

示例 #2 Unbuffered query example: 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;
    }
    ?>

## Character sets

Ideally a proper character set will be set at the server level, and doing this is described within the » Character Set Configuration section of the MySQL Server manual. Alternatively, each MySQL API offers a method to set the character set at runtime.

警告

# The character set and character escaping

The character set should be understood and defined, as it has an affect on every action, and includes security implications. For example, the escaping mechanism (e.g., mysqli_real_escape_string() for mysqli and PDO::quote() for PDO_MySQL) will adhere to this setting. It is important to realize that these functions will not use the character set that is defined with a query, so for example the following will not have an effect on them:

示例 #1 Problems with setting the character set with SQL

    <?php

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    // Will NOT affect $mysqli->real_escape_string();
    $mysqli->query("SET NAMES utf8mb4");

    // Will NOT affect $mysqli->real_escape_string();
    $mysqli->query("SET CHARACTER SET utf8mb4");

    // But, this will affect $mysqli->real_escape_string();
    $mysqli->set_charset('utf8mb4');

    // But, this will NOT affect it (UTF-8 vs utf8mb4) -- don't use dashes here
    $mysqli->set_charset('UTF-8');
    ?>

Below are examples that demonstrate how to properly alter the character set at runtime using each API.

> 注意: Possible UTF-8 confusion
> Because character set names in MySQL do not contain dashes, the string "utf8" is valid in MySQL to set the character set to UTF-8 (up to 3 byte UTF-8 Unicode Encoding). The string "UTF-8" is not valid, as using "UTF-8" will fail to change the character set and will throw an error.

示例 #2 Setting the character set example: mysqli

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    echo 'Initial character set: ' . $mysqli->character_set_name() . "\n";

    if (!$mysqli->set_charset('utf8mb4')) {
        printf("Error loading character set utf8mb4: %s\n", $mysqli->error);
        exit;
    }

    echo 'Your current character set is: ' . $mysqli->character_set_name() . "\n";
    ?>

示例 #3 Setting the character set example: pdo_mysql

    <?php
    $pdo = new PDO("mysql:host=localhost;dbname=world;charset=utf8mb4", 'my_user', 'my_pass');
    ?>

- Terminology overview
- Choosing an API
- Choosing a library
- Concepts
  - Buffered and Unbuffered queries
  - Character sets

# MySQL增强版扩展

# 简介

`mysqli` 扩展允许访问 MySQL 4.1 及以上版本提供的功能。关于 MySQL 数据库服务器的更多信息请参阅 » http://www.mysql.com/。

可在 概述 中找到从 PHP 中使用 MySQL 的软件概述。

MySQL 的文档请查看 » http://dev.mysql.com/doc/。

本文档中的部分内容摘自 Oracle Corporation 许可的 MySQL 手册。

示例使用免费提供的 » world 或 » sakila 数据库。

# 概述

这一部分对在PHP应用开发过程中需要和Mysql数据库交互时可用的选择进行一个简单介绍。

什么是API?

一个应用程序接口（Application Programming Interface的缩写），定义了类，方法，函数，变量等等一切 你的应用程序中为了完成特定任务而需要调用的内容。在PHP应用程序需要和数据库进行交互的时候所需要的API 通常是通过PHP扩展暴露出来（给终端PHP程序员调用）。

API可以是面向过程的，也可以是面向对象的。对于面向过程的API，我们通过调用函数来完成任务，而对于面向对象的API， 我们实例化类，并在实例化后得到的对象上调用方法。对于这两种接口而言，后者通常是首选的，因为它更加现代化，并且 给我们带来了良好的代码结构。

当构建一个需要连接到MySQL服务端的PHP应用的时候，有好几种API可供选择。此文档就是讨论这些可用的API并讨论如何为 你的应用选择一个最佳的解决方案。

什么是连接器?

在MySQL文档中，术语connector解释为“一段允许你的应用连接到MySQL数据库服务器的软件代码”。 MySQL提供了很多语言的连接器，其中包括PHP的。

在你的 PHP 应用需要和一个数据库服务器交互的时候，你需要书写 PHP 代码去完成连接数据库服务器，查询数据库以及其他数据库相关功能 等一系列活动。你的 PHP 应用将会使用提供这些 API 的软件，或者在需要的时候使用一些中间库，来处理你的应用和数据库服务器之间的交互。 这种软件通常被认为是连接器，它允许你的引用连接到数据库服务器。

什么是驱动?

驱动是一段设计用来于一种特定类型的数据库服务器进行交互的软件代码。驱动可能会调用一些库，比如MySQL客户端库或者MySQL Native驱动库。 这些库实现了用于和MySQL数据库服务器进行交互的底层协议。

通过一个例子PDO(PHP Database Object的缩写)数据库抽象层可以 使用多种特定数据库的驱动。其中一种驱动就是PDO MYSQL驱动，它就是与MySQL服务器之间的接口。

有时大家会不加区分的使用连接器和驱动这两个术语。在MySQL相关文档中driver术语被作为一个连接器包 中提供特定数据库部分的软件代码。

什么是扩展?

在 PHP 文档中，会遇到另外一个术语——extension。PHP 代码是由核心，一些可选扩展组成了核心功能。PHP 的 MySQL 相关扩展，比如 mysqli 扩展和 PDO MySQL 驱动都是使用 PHP 扩展框架实现的。

扩展一个典型的作用就是暴露一个API给PHP程序员，允许扩展自己的功能可以被程序员使用。当然，也有一部分基于PHP扩展框架 开发的扩展不会给PHP程序员暴露API接口。

比如说PDO MySQL驱动扩展，就没有向PHP程序员暴露API接口，但是向它上层的PDO层提供了一个接口。

术语API和扩展描述的不是同一类事物，因为扩展可能并不需要暴露一个API接口给程序员。

PHP中提供的用于MySQL的主要API是什么？

当考虑连接到 MySQL 数据库服务器的时候，有两种主要的 API 可供选择：

- PHP的mysqli扩展

- PHP数据对象(PDO)

三者都有各自的优缺点。下面的讨论就是为了对每种API的关键方面给出一个简短的介绍。

什么是PHP的mysqli扩展?

`mysqli`扩展，我们有时称之为MySQL增强扩展，可以用于使用 MySQL4.1.3或更新版本中新的高级特性。`mysqli`扩展在PHP 5及以后版本中包含。

`mysqli`扩展有一系列的优势，相对于`mysql`扩展的提升主要有：

- 面向对象接口

- prepared语句支持（译注：关于prepare请参阅mysql相关文档）

- 多语句执行支持

- 事务支持

- 增强的调试能力

在提供了面向对象接口的同时也提供了一个面向过程的接口。

`mysqli`扩展是使用PHP扩展框架构建的，它的源代码在PHP源码目录下的ext/mysqli中。

对于`mysqli`扩展的更多信息，请参阅MySQLi。

什么是PDO?

PHP数据对象，是PHP应用中的一个数据库抽象层规范。PDO提供了一个统一的API接口可以使得你的PHP应用不去关心具体要 连接的数据库服务器系统类型。也就是说，如果你使用PDO的API，可以在任何需要的时候无缝切换数据库服务器，比如从Firebird 到MySQL，仅仅需要修改很少的PHP代码。

其他数据库抽象层的例子包括Java应用中的JDBC以及Perl中的DBI。

当然，PDO也有它自己的先进性，比如一个干净的，简单的，可移植的API，它最主要的缺点是会限制让你不能使用 后期MySQL服务端提供所有的数据库高级特性。比如，PDO不允许使用MySQL支持的多语句执行。

PDO是基于PHP扩展框架实现的，它的源码在PHP源码目录的ext/pdo下。

PDO的更多信息，请参阅PDO。

什么是PDO的MySQL驱动器?

PDO的MySQL驱动并不是一套API，至少从PHP程序员的角度来看是这样的。实际上，PDO的MySQL驱动处于PDO自己的下层， 提供了特定的Mysql功能。程序员直接调用PDO的API，而PDO使用了PDO的MySQL驱动完成与MySQL服务器端的交互。

PDO的MySQL驱动是众多PDO驱动中的一个。其他可用的PDO驱动包括Firebird，PostgreSQL等等。

PDO的MySQL驱动是基于PHP扩展框架实现的。它的源码在PHP源码目录下的ext/pdo_mysql。 它没有向PHP程序员暴露API。

PDO的MySQL扩展的更多信息请参阅MySQL PDO Driver。

什么是 PHP MySQL Native Driver？

为了与 MySQL 数据库服务端进行交互，`mysqli` 和 PDO MySQL 驱动都使用了实现了必要的协议的底层库。以前，可用的库只有 MySQL Client 库，也称为 `libmysqlclient`。

然而，`libmysqlclient` 提供的接口没有针对与 PHP 的应用交互进行优化，因为 `libmysqlclient` 早期是为 C 应用程序设计的。基于这个原因，开发 MySQL Native Driver、`mysqlnd` 作为 `libmysqlclient` 的 PHP 应用替代方案。

`mysqli` 扩展和 PDO MySQL 驱动都可以各自配置使用 `libmysqlclient` 或者 `mysqlnd`。`mysqlnd` 作为专门设计用于 PHP 系统的库，它在内存和速度上都比 `libmysqlclient` 有很大提升。强烈建议使用这些改进。

MySQL Native Driver 是使用 PHP 扩展框架实现的。源代码位于 ext/mysqlnd。它没有向 PHP 程序员露出接口。

特性比较

下表比较了 PHP 连接到 MySQL 主要方法的功能：

PHP 的 MySQL API 选项比较
| PHP mysqli 扩展 | PDO（使用 PDO MySQL Driver 和 MySQL Native Driver）
--- | --- | ---
引入的 PHP 版本 | 5.0 | 5.0
MySQL 开发状态 | 积极开发 | 积极开发
API 的字符集支持 | 是 | 是
API 的服务端预处理语句支持 | 是 | 是
API 的客户端预处理语句支持 | 否 | 是
API 的存储过程支持 | 是 | 是
API 的多语句支持 | 是 | 大多数
是否支持所有 MySQL 4.1 以上功能 | 是 | 大多数

# 快速入门指南

## 目录

- 面向过程和面向对象，两种接口
- Connections
- Executing statements
- Prepared Statements
- Stored Procedures
- Multiple Statements
- API support for transactions
- Metadata

本快速入门指南将有助于选择和熟悉 PHP MySQL API。

此快速入门概述了 mysqli 扩展。为 API 的所有主要方面提供了代码示例。 Database concepts are explained to the degree needed for presenting concepts specific to MySQL.

要求：熟悉 PHP 编程语言、SQL 语言、MySQL 服务器基础知识。

## 面向过程和面向对象，两种接口

mysqli 扩展具有双重接口。支持面向过程和面向对象，两种编程范式。

从旧的 mysql 扩展迁移的用户可能更喜欢过程接口。过程接口类似于旧的 mysql 扩展。在许多情况下，函数名称仅在前缀上有所不同。一些 mysqli 函数将连接句柄作为第一个参数，而匹配的旧 mysql 接口函数将其作为可选的最后一个参数。

示例 #1 从旧的 mysql 扩展轻松迁移

    <?php
    $mysqli = mysqli_connect("example.com", "user", "password", "database");
    $result = mysqli_query($mysqli, "SELECT 'Please do not use the deprecated mysql extension for new development. ' 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 'Use the mysqli extension instead.' AS _msg FROM DUAL", $mysql);
    $row = mysql_fetch_assoc($result);
    echo $row['_msg'];

以上示例会输出：

    Please do not use the deprecated mysql extension for new development. Use the mysqli extension instead.

面向对象接口

除了经典的过程式接口，用户还可以选择使用面向对象接口。文档是使用面向对象的接口组织的。面向对象的接口按用途分组进行展示函数，使其更容易上手。参考部分提供了两种语法变体的示例。

这两个接口之间没有显着的性能差异。用户可以根据个人喜好进行选择。

示例 #2 面向对象和面向过程接口

    <?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'];

以上示例会输出：

    A world full of choices to please everybody.

面向对象的接口用于快速入门，因为参考部分是以这种方式组织的。

混合风格

可以随时在样式之间切换。出于代码清晰度和编码风格的原因，这两种风格不建议混合使用。

示例 #3 糟糕的编码风格

    <?php

    $mysqli = new mysqli("example.com", "user", "password", "database");

    $result = mysqli_query($mysqli, "SELECT 'Possible but bad style.' AS _msg FROM DUAL");

    if ($row = $result->fetch_assoc()) {
        echo $row['_msg'];
    }

以上示例会输出：

    Possible but bad style.

参见

- mysqli::__construct()
- mysqli::query()
- mysqli_result::fetch_assoc()
- $mysqli::connect_errno
- $mysqli::connect_error
- $mysqli::errno
- $mysqli::error
- MySQLi 扩展的函数概述

## Connections

The MySQL server supports the use of different transport layers for connections. Connections use TCP/IP, Unix domain sockets or Windows named pipes.

The hostname `localhost` has a special meaning. It is bound to the use of Unix domain sockets. To open a TCP/IP connection to the localhost, `127.0.0.1` must be used instead of the hostname `localhost`.

示例 #1 Special meaning of 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";

以上示例会输出：

    Localhost via UNIX socket
    127.0.0.1 via TCP/IP

Connection parameter defaults

Depending on the connection function used, assorted parameters can be omitted. If a parameter is not provided, then the extension attempts to use the default values that are set in the PHP configuration file.

示例 #2 Setting defaults

    mysqli.default_host=192.168.2.27
    mysqli.default_user=root
    mysqli.default_pw=""
    mysqli.default_port=3306
    mysqli.default_socket=/tmp/mysql.sock

The resulting parameter values are then passed to the client library that is used by the extension. If the client library detects empty or unset parameters, then it may default to the library built-in values.

Built-in connection library defaults

If the host value is unset or empty, then the client library will default to a Unix socket connection on `localhost`. If socket is unset or empty, and a Unix socket connection is requested, then a connection to the default socket on `/tmp/mysql.sock` is attempted.

On Windows systems, the host name `.` is interpreted by the client library as an attempt to open a Windows named pipe based connection. In this case the socket parameter is interpreted as the pipe name. If not given or empty, then the socket (pipe name) defaults to `\\.\pipe\MySQL`.

If neither a Unix domain socket based not a Windows named pipe based connection is to be established and the port parameter value is unset, the library will default to port `3306`.

The mysqlnd library and the MySQL Client Library (libmysqlclient) implement the same logic for determining defaults.

Connection options

Connection options are available to, for example, set init commands which are executed upon connect, or for requesting use of a certain charset. Connection options must be set before a network connection is established.

For setting a connection option, the connect operation has to be performed in three steps: creating a connection handle with mysqli_init() or mysqli::__construct(), setting the requested options using mysqli::options(), and establishing the network connection with mysqli::real_connect().

Connection pooling

The mysqli extension supports persistent database connections, which are a special kind of pooled connections. By default, every database connection opened by a script is either explicitly closed by the user during runtime or released automatically at the end of the script. A persistent connection is not. Instead it is put into a pool for later reuse, if a connection to the same server using the same username, password, socket, port and default database is opened. Reuse saves connection overhead.

Every PHP process is using its own mysqli connection pool. Depending on the web server deployment model, a PHP process may serve one or multiple requests. Therefore, a pooled connection may be used by one or more scripts subsequently.

Persistent connection

If an unused persistent connection for a given combination of host, username, password, socket, port and default database cannot be found in the connection pool, then mysqli opens a new connection. The use of persistent connections can be enabled and disabled using the PHP directive mysqli.allow_persistent. The total number of connections opened by a script can be limited with mysqli.max_links. The maximum number of persistent connections per PHP process can be restricted with mysqli.max_persistent. Please note that the web server may spawn many PHP processes.

A common complain about persistent connections is that their state is not reset before reuse. For example, open and unfinished transactions are not automatically rolled back. But also, authorization changes which happened in the time between putting the connection into the pool and reusing it are not reflected. This may be seen as an unwanted side-effect. On the contrary, the name `persistent` may be understood as a promise that the state is persisted.

The mysqli extension supports both interpretations of a persistent connection: state persisted, and state reset before reuse. The default is reset. Before a persistent connection is reused, the mysqli extension implicitly calls mysqli::change_user() to reset the state. The persistent connection appears to the user as if it was just opened. No artifacts from previous usages are visible.

The mysqli::change_user() call is an expensive operation. For best performance, users may want to recompile the extension with the compile flag `MYSQLI_NO_CHANGE_USER_ON_PCONNECT` being set.

It is left to the user to choose between safe behavior and best performance. Both are valid optimization goals. For ease of use, the safe behavior has been made the default at the expense of maximum performance.

See also

- mysqli::__construct()
- mysqli_init()
- mysqli::options()
- mysqli::real_connect()
- mysqli::change_user()
- $mysqli::host_info
- MySQLi Configuration Options
- Persistent Database Connections

## Executing statements

Statements can be executed with the mysqli::query(), mysqli::real_query() and mysqli::multi_query(). The mysqli::query() function is the most common, and combines the executing statement with a buffered fetch of its result set, if any, in one call. Calling mysqli::query() is identical to calling mysqli::real_query() followed by mysqli::store_result().

示例 #1 Executing queries

    <?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)");

Buffered result sets

After statement execution, results can be either retrieved all at once or read row by row from the server. Client-side result set buffering allows the server to free resources associated with the statement's results as early as possible. Generally speaking, clients are slow consuming result sets. Therefore, it is recommended to use buffered result sets. mysqli::query() combines statement execution and result set buffering.

PHP applications can navigate freely through buffered results. Navigation is fast because the result sets are held in client memory. Please, keep in mind that it is often easier to scale by client than it is to scale the server.

示例 #2 Navigation through buffered results

    <?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 "Reverse order...\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 "Result set order...\n";
    foreach ($result as $row) {
        echo " id = " . $row['id'] . "\n";
    }

以上示例会输出：

    Reverse order...
     id = 3
     id = 2
     id = 1
    Result set order...
     id = 1
     id = 2
     id = 3

Unbuffered result sets

If client memory is a short resource and freeing server resources as early as possible to keep server load low is not needed, unbuffered results can be used. Scrolling through unbuffered results is not possible before all rows have been read.

示例 #3 Navigation through unbuffered results

    <?php

    $mysqli->real_query("SELECT id FROM test ORDER BY id ASC");
    $result = $mysqli->use_result();

    echo "Result set order...\n";
    foreach ($result as $row) {
        echo " id = " . $row['id'] . "\n";
    }

Result set values data types

The mysqli::query(), mysqli::real_query() and mysqli::multi_query() functions are used to execute non-prepared statements. At the level of the MySQL Client Server Protocol, the command `COM_QUERY` and the text protocol are used for statement execution. With the text protocol, the MySQL server converts all data of a result sets into strings before sending. This conversion is done regardless of the SQL result set column data type. The mysql client libraries receive all column values as strings. No further client-side casting is done to convert columns back to their native types. Instead, all values are provided as PHP strings.

示例 #4 Text protocol returns strings by default

    <?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']));

以上示例会输出：

    id = 1 (string)
    label = a (string)

It is possible to convert integer and float columns back to PHP numbers by setting the `MYSQLI_OPT_INT_AND_FLOAT_NATIVE` connection option, if using the mysqlnd library. If set, the mysqlnd library will check the result set meta data column types and convert numeric SQL columns to PHP numbers, if the PHP data type value range allows for it. This way, for example, SQL INT columns are returned as integers.

示例 #5 Native data types with mysqlnd and connection option

    <?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']));

以上示例会输出：

    id = 1 (integer)
    label = a (string)

See also

- mysqli::__construct()
- mysqli::options()
- mysqli::real_connect()
- mysqli::query()
- mysqli::multi_query()
- mysqli::use_result()
- mysqli::store_result()

## Prepared Statements

The MySQL database supports prepared statements. A prepared statement or a parameterized statement is used to execute the same statement repeatedly with high efficiency and protect against SQL injections.

Basic workflow

The prepared statement execution consists of two stages: prepare and execute. At the prepare stage a statement template is sent to the database server. The server performs a syntax check and initializes server internal resources for later use.

The MySQL server supports using anonymous, positional placeholder with `?`.

Prepare is followed by execute. During execute the client binds parameter values and sends them to the server. The server executes the statement with the bound values using the previously created internal resources.

示例 #1 Prepared statement

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Non-prepared statement */
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");

    /* Prepared statement, stage 1: prepare */
    $stmt = $mysqli->prepare("INSERT INTO test(id, label) VALUES (?, ?)");

    /* Prepared statement, stage 2: bind and execute */
    $id = 1;
    $label = 'PHP';
    $stmt->bind_param("is", $id, $label); // "is" means that $id is bound as an integer and $label as a string

    $stmt->execute();

Repeated execution

A prepared statement can be executed repeatedly. Upon every execution the current value of the bound variable is evaluated and sent to the server. The statement is not parsed again. The statement template is not transferred to the server again.

示例 #2 INSERT prepared once, executed multiple times

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Non-prepared statement */
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");

    /* Prepared statement, stage 1: prepare */
    $stmt = $mysqli->prepare("INSERT INTO test(id, label) VALUES (?, ?)");

    /* Prepared statement, stage 2: bind and execute */
    $stmt->bind_param("is", $id, $label); // "is" means that $id is bound as an integer and $label as a string

    $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));

以上示例会输出：

    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++"
      }
    }

Every prepared statement occupies server resources. Statements should be closed explicitly immediately after use. If not done explicitly, the statement will be closed when the statement handle is freed by PHP.

Using a prepared statement is not always the most efficient way of executing a statement. A prepared statement executed only once causes more client-server round-trips than a non-prepared statement. This is why the `SELECT` is not run as a prepared statement above.

Also, consider the use of the MySQL multi-INSERT SQL syntax for INSERTs. For the example, multi-INSERT requires fewer round-trips between the server and client than the prepared statement shown above.

示例 #3 Less round trips using 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();

Result set values data types

The MySQL Client Server Protocol defines a different data transfer protocol for prepared statements and non-prepared statements. Prepared statements are using the so called binary protocol. The MySQL server sends result set data "as is" in binary format. Results are not serialized into strings before sending. Client libraries receive binary data and try to convert the values into appropriate PHP data types. For example, results from an SQL `INT` column will be provided as PHP integer variables.

示例 #4 Native datatypes

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Non-prepared statement */
    $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']));

以上示例会输出：

    id = 1 (integer)
    label = PHP (string)

This behavior differs from non-prepared statements. By default, non-prepared statements return all results as strings. This default can be changed using a connection option. If the connection option is used, there are no differences.

Fetching results using bound variables

Results from prepared statements can either be retrieved by binding output variables, or by requesting a mysqli_result object.

Output variables must be bound after statement execution. One variable must be bound for every column of the statements result set.

示例 #5 Output variable binding

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Non-prepared statement */
    $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));
    }

以上示例会输出：

    id = 1 (integer), label = PHP (string)

Prepared statements return unbuffered result sets by default. The results of the statement are not implicitly fetched and transferred from the server to the client for client-side buffering. The result set takes server resources until all results have been fetched by the client. Thus it is recommended to consume results timely. If a client fails to fetch all results or the client closes the statement before having fetched all data, the data has to be fetched implicitly by `mysqli`.

It is also possible to buffer the results of a prepared statement using mysqli_stmt::store_result().

Fetching results using mysqli_result interface

Instead of using bound results, results can also be retrieved through the mysqli_result interface. mysqli_stmt::get_result() returns a buffered result set.

示例 #6 Using mysqli_result to fetch results

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Non-prepared statement */
    $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));

以上示例会输出：

    array(1) {
      [0]=>
      array(2) {
        ["id"]=>
        int(1)
        ["label"]=>
        string(3) "PHP"
      }
    }

Using the mysqli_result interface offers the additional benefit of flexible client-side result set navigation.

示例 #7 Buffered result set for flexible read out

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Non-prepared statement */
    $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());
    }

以上示例会输出：

    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"
    }

Escaping and SQL injection

Bound variables are sent to the server separately from the query and thus cannot interfere with it. The server uses these values directly at the point of execution, after the statement template is parsed. Bound parameters do not need to be escaped as they are never substituted into the query string directly. A hint must be provided to the server for the type of bound variable, to create an appropriate conversion. See the mysqli_stmt::bind_param() function for more information.

Such a separation sometimes considered as the only security feature to prevent SQL injection, but the same degree of security can be achieved with non-prepared statements, if all the values are formatted correctly. It should be noted that correct formatting is not the same as escaping and involves more logic than simple escaping. Thus, prepared statements are simply a more convenient and less error-prone approach to this element of database security.

Client-side prepared statement emulation

The API does not include emulation for client-side prepared statement emulation.

See also

- mysqli::__construct()
- mysqli::query()
- mysqli::prepare()
- mysqli_stmt::prepare()
- mysqli_stmt::execute()
- mysqli_stmt::bind_param()
- mysqli_stmt::bind_result()

## Stored Procedures

The MySQL database supports stored procedures. A stored procedure is a subroutine stored in the database catalog. Applications can call and execute the stored procedure. The `CALL` SQL statement is used to execute a stored procedure.

Parameter

Stored procedures can have `IN`, `INOUT` and `OUT` parameters, depending on the MySQL version. The mysqli interface has no special notion for the different kinds of parameters.

IN parameter

Input parameters are provided with the `CALL` statement. Please, make sure values are escaped correctly.

示例 #1 Calling a stored procedure

    <?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());

以上示例会输出：

    array(1) {
      ["id"]=>
      string(1) "1"
    }

INOUT/OUT parameter

The values of `INOUT`/`OUT` parameters are accessed using session variables.

示例 #2 Using session variables

    <?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'];

以上示例会输出：

    Hi!

Application and framework developers may be able to provide a more convenient API using a mix of session variables and databased catalog inspection. However, please note the possible performance impact of a custom solution based on catalog inspection.

Handling result sets

Stored procedures can return result sets. Result sets returned from a stored procedure cannot be fetched correctly using mysqli::query(). The mysqli::query() function combines statement execution and fetching the first result set into a buffered result set, if any. However, there are additional stored procedure result sets hidden from the user which cause mysqli::query() to fail returning the user expected result sets.

Result sets returned from a stored procedure are fetched using mysqli::real_query() or mysqli::multi_query(). Both functions allow fetching any number of result sets returned by a statement, such as `CALL`. Failing to fetch all result sets returned by a stored procedure causes an error.

示例 #3 Fetching results from stored procedures

    <?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());

以上示例会输出：

    ---
    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"
      }
    }

Use of prepared statements

No special handling is required when using the prepared statement interface for fetching results from the same stored procedure as above. The prepared statement and non-prepared statement interfaces are similar. Please note, that not every MYSQL server version may support preparing the `CALL` SQL statement.

示例 #4 Stored Procedures and Prepared Statements

    <?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());

以上示例会输出：

    ---
    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)
      }
    }

Of course, use of the bind API for fetching is supported as well.

示例 #5 Stored Procedures and Prepared Statements using 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());

以上示例会输出：

    id = 1
    id = 2
    id = 3
    id = 2
    id = 3
    id = 4

See also

- mysqli::query()
- mysqli::multi_query()
- mysqli::next_result()
- mysqli::more_results()

## Multiple Statements

MySQL optionally allows having multiple statements in one statement string, but it requires special handling.

Multiple statements or multi queries must be executed with mysqli::multi_query(). The individual statements of the statement string are separated by semicolon. Then, all result sets returned by the executed statements must be fetched.

The MySQL server allows having statements that do return result sets and statements that do not return result sets in one multiple statement.

示例 #1 Multiple Statements

    <?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());

以上示例会输出：

    array(1) {
      [0]=>
      array(1) {
        ["_num"]=>
        string(1) "0"
      }
    }
    array(1) {
      [0]=>
      array(1) {
        ["_num"]=>
        string(1) "1"
      }
    }

Security considerations

The API functions mysqli::query() and mysqli::real_query() do not set a connection flag necessary for activating multi queries in the server. An extra API call is used for multiple statements to reduce the damage of accidental SQL injection attacks. An attacker may try to add statements such as `; DROP DATABASE mysql` or `; SELECT SLEEP(999)`. If the attacker succeeds in adding SQL to the statement string but mysqli::multi_query() is not used, the server will not execute the injected and malicious SQL statement.

示例 #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");
    ?>

以上示例会输出：

    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

Prepared statements

Use of the multiple statement with prepared statements is not supported.

See also

- mysqli::query()
- mysqli::multi_query()
- mysqli::next_result()
- mysqli::more_results()

## API support for transactions

The MySQL server supports transactions depending on the storage engine used. Since MySQL 5.5, the default storage engine is InnoDB. InnoDB has full ACID transaction support.

Transactions can either be controlled using SQL or API calls. It is recommended to use API calls for enabling and disabling the `autocommit` mode and for committing and rolling back transactions.

示例 #1 Setting `autocommit` mode with SQL and through the API

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Recommended: using API to control transactional settings */
    $mysqli->autocommit(false);

    /* Won't be monitored and recognized by the replication and the load balancing plugin */
    $mysqli->query('SET AUTOCOMMIT = 0');

Optional feature packages, such as the replication and load balancing plugin, can easily monitor API calls. The replication plugin offers transaction aware load balancing, if transactions are controlled with API calls. Transaction aware load balancing is not available if SQL statements are used for setting `autocommit` mode, committing or rolling back a transaction.

示例 #2 Commit and 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();

Please note, that the MySQL server cannot roll back all statements. Some statements cause an implicit commit.

See also

- mysqli::autocommit()
- mysqli::begin_transaction()
- mysqli::commit()
- mysqli::rollback()

## Metadata

A MySQL result set contains metadata. The metadata describes the columns found in the result set. All metadata sent by MySQL is accessible through the `mysqli` interface. The extension performs no or negligible changes to the information it receives. Differences between MySQL server versions are not aligned.

Meta data is access through the mysqli_result interface.

示例 #1 Accessing result set meta data

    <?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());

以上示例会输出：

    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)
      }
    }

Prepared statements

Meta data of result sets created using prepared statements are accessed the same way. A suitable mysqli_result handle is returned by mysqli_stmt::result_metadata().

示例 #2 Prepared statements metadata

    <?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());

See also

- mysqli::query()
- mysqli_result::fetch_fields()

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置

## 需求

为了使这些函数可用，必须编译支持 mysqli 扩展的 PHP。

MySQL 8

当运行 PHP 7.1.16 之前的版本或者 PHP 7.2.4 之前的 PHP 7.2 版本时，需要将 MySQL 8 服务器的默认密码插件设置为 mysql_native_password。否则在未使用 caching_sha2_password 时，也会看到类似这样的错误 The server requested authentication method unknown to the client [caching_sha2_password]。

这是因为 MySQL 8 默认使用 caching_sha2_password，这是旧版 PHP (mysqlnd) 版本无法识别的插件。然而，可以在 my.cnf 中设置 `default_authentication_plugin=mysql_native_password` 来变更它。从 PHP 7.4.4 开始，完全支持 caching_sha2_password 插件。对于旧版本，mysql_xdevapi 扩展支持。

## 安装

在 PHP 5.0.0 中引入 `mysqli` 扩展。PHP 5.3.0 版本中引入 Mysql Native Driver。

## 在 Linux 上安装

常见的 Unix 发行版中包含可以安装的 PHP 的二进制版本。虽然这些二进制版本通常是在支持 MySQL 扩展的情况下编译的，但扩展库自身可能需要使用额外的包进行安装。因此需要检查选择的发行版附带包管理的可用性。

例如，在 Ubuntu 上，`php5-mysql` 包安装了 ext/mysql、ext/mysqli 和 pdo_mysql 三个 PHP 扩展。在 CentOS 上，`php-mysql` 包也安装了这三个 PHP 扩展。

或者，可以编译扩展本身。从源代码编译 PHP 允许指定要使用的 MySQL 扩展，以及为每个扩展选择客户端库。

Mysql Native Driver 是推荐的客户端库选项，可以提升性能并带来一些 MySQL Client Library 不支持访问的特性。参阅什么是 PHP 的 MySQL Native Driver？中对简要概述 Mysql Native Driver 的优势。

`/path/to/mysql_config` 表示 MySQL Server 自带的 mysql_config 程序的位置。

mysqli 编译时支持模型
PHP 版本 | 默认 | 配置选项: mysqlnd | 配置选项: `libmysqlclient` | 更新日志
--- | --- | --- | --- | ---
5.4.x 及以上 | mysqlnd | --with-mysqli | --with-mysqli=/path/to/mysql_config | 默认是 mysqlnd
5.3.x | libmysqlclient | --with-mysqli=mysqlnd | --with-mysqli=/path/to/mysql_config | 支持 mysqlnd
5.0.x, 5.1.x, 5.2.x | libmysqlclient | 不适用 | --with-mysqli=/path/to/mysql_config | 不支持 mysqlnd

请注意 MySQL 扩展和客户端库可以自由混合。比如，可以启用 MySQL 扩展使用 MySQL Client Library（libmysqlclient），同时配置 `mysqli` 扩展去使用 Mysql Native Driver。然而，扩展和客户端库的所有顺序都有可能。

## 在 Windows 系统上安装

在 Windows 上，必须在 php.ini 中启用 php_mysqli.dll DLL。

与启用任一 PHP 扩展（比如 php_mysqli.dll）一样，PHP 指令 extension_dir 应设置为 PHP 扩展所在目录。查看 Windows 手动安装说明。`extension_dir` 的示例值是 c:\php\ext。

> 注意:

> 如果启动 Web 服务器的时候发生了类似下面这样的错误：`"Unable to load dynamic library './php_mysqli.dll'"`，这是因为系统找不到 php_mysqli.dll。

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

MySQLi配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
mysqli.allow_local_infile | "0" | `INI_SYSTEM` | 在 PHP 7.2.16 和 7.3.3 之前，默认值为 "1"
mysqli.local_infile_directory |  | `INI_SYSTEM` | 自 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` | 自PHP 5.0.0起可用。
mysqli.default_pw | NULL | `INI_ALL` |
mysqli.reconnect | "0" | `INI_SYSTEM` | 自 PHP 8.2.0 起移除
mysqli.rollback_on_cached_plink | "0" | `INI_SYSTEM` |

关于前面出现的 INI_* 系列常量的详细定义，请参阅配置的修改一章。

这是配置指令的简短说明。

`mysqli.allow_local_infile` bool

  允许Mysql的Load Data语句访问PHP角度看的本地文件。

`mysqli.local_infile_directory` string

  限制加载 LOCAL DATA 文件为指定的目录。

`mysqli.allow_persistent` bool

  开启使用mysqli_connect()函数创建持久化连接的能力。

`mysqli.max_persistent` int

  可以创建的持久化连接的最大数量，设置为0表明不限制。

`mysqli.max_links` int

  每个进程中Mysql连接的最大数量。

`mysqli.default_port` int

  当没有指定其他端口号时使用的默认的用于连接数据库服务器的TCP端口号。如果没有设置默认值， 端口号将会按照顺序从环境变量`MYSQL_TCP_PORT`，/etc/services 文件中的`mysql-tcp`条目或编译期的`MYSQL_PORT`常量等位置获取。 Win32仅使用`MYSQL_PORT`常量。

`mysqli.default_socket` string

  当连接到本地数据库服务器时如果没有指定其他socket名称，使用的默认socket名称。

`mysqli.default_host` string

  当连接到数据库服务器时， 如果没有指定其他主机地址，使用的默认服务器主机。

`mysqli.default_user` string

  当连接到数据库服务器时，如果没有指定其他用户名，使用的默认用户名。

`mysqli.default_pw` string

  当连接到数据库服务器时，如果没有指定其他密码，使用的默认密码。

`mysqli.reconnect` int

  连接丢失时是否自动重新连接。

  > 注意: mysqlnd 驱动已此忽略此 php.ini 设置，并于 PHP 8.2.0 起移除。

`mysqli.rollback_on_cached_plink` bool

  If this option is enabled, closing a persistent connection will rollback any pending transactions of this connection before it is put back into the persistent connection pool. Otherwise, pending transactions will be rolled back only when the connection is reused, or when it is actually closed.

用户不能通过API调用或运行时配置来设置`MYSQL_OPT_READ_TIMEOUT`。 注意，如果可能这样做那么`libmysqlclient`和流对`MYSQL_OPT_READ_TIMEOUT` 的值将会有不同的解释。

# mysqli 扩展和持久化连接

持久化连接的目的在于重用客户端到服务器之间的连接， 而不是每次在需要的时候都重新建立一个连接。 由于持久化连接可以将已经建立的连接缓存起来，以备后续的使用， 所以省去了建立新的连接的开销， 因此可以带来性能上的提升。

不像 mysql 扩展，mysqli 没有提供一个特殊的方法用于打开持久化连接。 需要打开一个持久化连接时，你必须在 连接时在主机名前增加`p:`。

使用持久化连接也会存在一些风险， 因为在缓存中的连接可能处于一种不可预测的状态。 例如，如果客户端未能正常关闭连接， 可能在这个连接上残留了对库表的锁， 那么当这个连接被其他请求重用的时候，这个连接还是处于 有锁的状态。 所以，如果要很好的使用持久化连接，那么要求代码在和数据库进行交互的时候， 确保做好清理工作，保证被缓存的连接是一个干净的，没有残留的状态。

`mysqli` 扩展的持久化连接提供了内建的清理处理代码。 `mysqli` 所做的清理工作包括：

- 回滚处于活动状态的事务

- 关闭并且删除临时表

- 对表解锁

- 重置会话变量

- 关闭预编译 SQL 语句（在PHP中经常发生）

- 关闭处理程序

- 释放通过 GET_LOCK() 获得的锁

这确保了将连接返回到连接池的时候， 它处于一种“干净”的状态，可以被其他客户端进程所使用。

`mysqli` 扩展 通过自动调用 C-API 函数 `mysql_change_user()` 来完成这个清理工作。

自动清理的特性有优点也有缺点。 优点是程序员不再需要担心附加的清理代码， 因为它们会自动调用。 然而缺点就是 性能 可能会 慢一点， 因为每次从连接池返回一个连接都需要执行这些清理代码。

这个自动清理的代码可以通过在编译 php 时定义 `MYSQLI_NO_CHANGE_USER_ON_PCONNECT` 来关闭。

> 注意:

> `mysqli` 扩展在使用 MySQL Native Driver 或 Mysql Client Library（libmysql）时都支持持久化连接。

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`MYSQLI_READ_DEFAULT_GROUP` (int)

  从 my.cnf 或由 `MYSQLI_READ_DEFAULT_FILE` 指定的文件中读取命名区块（named group）的配置。

`MYSQLI_READ_DEFAULT_FILE` (int)

  从指定的选项文件中读取配置，而非从默认的 my.cnf。

`MYSQLI_OPT_CAN_HANDLE_EXPIRED_PASSWORDS` (int)
  向服务器表明客户端可以为过期密码处理沙盒模式。可与 mysqli_options() 一起使用。
`MYSQLI_OPT_LOAD_DATA_LOCAL_DIR` (int)
  如果启用，此选项将指定在 `LOAD DATA LOCAL` 语句中允许客户端指定 `LOCAL` 数据加载的目录。
`MYSQLI_OPT_CONNECT_TIMEOUT` (int)

  连接超时（秒）。

`MYSQLI_OPT_READ_TIMEOUT` (int)

  Command execution result timeout in seconds. Available as of PHP 7.2.0.

`MYSQLI_OPT_LOCAL_INFILE` (int)

  启用命令 `LOAD LOCAL INFILE`。

`MYSQLI_OPT_INT_AND_FLOAT_NATIVE` (int)

  Convert integer and float columns back to PHP numbers. Only valid for mysqlnd.

`MYSQLI_OPT_NET_CMD_BUFFER_SIZE` (int)

  The size of the internal command/network buffer. Only valid for mysqlnd.

`MYSQLI_OPT_NET_READ_BUFFER_SIZE` (int)

  Maximum read chunk size in bytes when reading the body of a MySQL command packet. Only valid for mysqlnd.

`MYSQLI_OPT_SSL_VERIFY_SERVER_CERT` (int)

`MYSQLI_INIT_COMMAND` (int)

  Command to execute when connecting to MySQL server. Will automatically be re-executed when reconnecting.

`MYSQLI_CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS` (int)
  向服务器表明客户端可以为过期密码处理沙盒模式。可与 mysqli_real_connect() 一起使用。
`MYSQLI_CLIENT_FOUND_ROWS` (int)
  返回匹配的行数，而不是受影响的行数。
`MYSQLI_CLIENT_SSL_VERIFY_SERVER_CERT` (int)
  验证服务器证书。
`MYSQLI_CLIENT_SSL` (int)

  Use SSL (encrypted protocol). This option should not be set by application programs; it is set internally in the MySQL client library.

`MYSQLI_CLIENT_COMPRESS` (int)

  使用压缩协议。

`MYSQLI_CLIENT_INTERACTIVE` (int)

  Allow `interactive_timeout` seconds (instead of `wait_timeout` seconds) of inactivity before closing the connection. The client's session `wait_timeout` variable will be set to the value of the session `interactive_timeout` variable.

`MYSQLI_CLIENT_IGNORE_SPACE` (int)

  Allow spaces after function names. Makes all functions names reserved words.

`MYSQLI_CLIENT_NO_SCHEMA` (int)

  Don't allow the `db_name.tbl_name.col_name` syntax.

`MYSQLI_CLIENT_MULTI_QUERIES`

  允许在单个 mysqli_query() 调用中进行多个以分号分隔的查询。

`MYSQLI_STORE_RESULT` (int)

  使用缓冲的结果集合。值为 `0`。

`MYSQLI_STORE_RESULT_COPY_DATA` (int)
  从 PHP 8.1 起，此常量不再有效。在 PHP 8.1 之前，此常量用于将结果从 `mysqlnd` 内部缓冲区复制到要获取的 PHP 变量中。默认情况下，`mysqlnd` 将使用引用逻辑来避免复制和重复保存在内存中的结果。对于某些结果集（例如，包含许多小行的结果集），复制方法可以减少总体内存使用量，因为保存结果的 PHP 变量可能会更早释放。仅适用于 `mysqlnd`。自 PHP 8.4.0 起弃用。
`MYSQLI_USE_RESULT` (int)

  使用无缓冲的结果集合。值为 `1`。

`MYSQLI_ASSOC` (int)

  列数据以字段名作为数组索引返回至数组中。

`MYSQLI_NUM` (int)

  Columns are returned into the array having an enumerated index.

`MYSQLI_BOTH` (int)

  Columns are returned into the array having both a numerical index and the fieldname as the associative index.

`MYSQLI_NOT_NULL_FLAG` (int)

  表示字段定义为 `NOT NULL`。

`MYSQLI_PRI_KEY_FLAG` (int)

  字段是主键索引的一部分。

`MYSQLI_UNIQUE_KEY_FLAG` (int)

  字段是唯一索引的一部分。

`MYSQLI_MULTIPLE_KEY_FLAG` (int)

  字段是普通索引的一部分。

`MYSQLI_BLOB_FLAG` (int)

  字段定义为 `BLOB`。

`MYSQLI_UNSIGNED_FLAG` (int)

  字段定义为 `UNSIGNED`。

`MYSQLI_ZEROFILL_FLAG` (int)

  字段定义为 `ZEROFILL`。

`MYSQLI_AUTO_INCREMENT_FLAG` (int)

  字段定义为 `AUTO_INCREMENT`。

`MYSQLI_TIMESTAMP_FLAG` (int)

  字段定义为 `TIMESTAMP`。

`MYSQLI_SET_FLAG` (int)

  字段定义为 `SET`。

`MYSQLI_NUM_FLAG` (int)

  字段定义为 `NUMERIC`。

`MYSQLI_PART_KEY_FLAG` (int)

  字段是多列索引的一部分。

`MYSQLI_GROUP_FLAG` (int)

  字段是 `GROUP BY` 的一部分。

`MYSQLI_NO_DEFAULT_VALUE_FLAG` (int)
  列的定义中没有 `DEFAULT` 子句。这不适用于 `NULL` 或 `AUTO_INCREMENT` 列，因为这些列的默认值有 `NULL` 默认值和隐式默认值。
`MYSQLI_TYPE_DECIMAL` (int)

  字段定义为 `DECIMAL`.

`MYSQLI_TYPE_NEWDECIMAL` (int)

  精度数学 `DECIMAL` 或 `NUMERIC` 字段。

`MYSQLI_TYPE_BIT` (int)

  字段定义为 `BIT`。

`MYSQLI_TYPE_TINY` (int)

  字段定义为 `TINYINT`。

`MYSQLI_TYPE_SHORT` (int)

  字段定义为 `SMALLINT`。

`MYSQLI_TYPE_LONG` (int)

  字段定义为 `INT`。

`MYSQLI_TYPE_FLOAT` (int)

  字段定义为 `FLOAT`。

`MYSQLI_TYPE_DOUBLE` (int)

  字段定义为 `DOUBLE`。

`MYSQLI_TYPE_NULL` (int)

  字段定义为 `DEFAULT NULL`。

`MYSQLI_TYPE_TIMESTAMP` (int)

  字段定义为 `TIMESTAMP`。

`MYSQLI_TYPE_LONGLONG` (int)

  字段定义为 `BIGINT`。

`MYSQLI_TYPE_INT24` (int)

  字段定义为 `MEDIUMINT`。

`MYSQLI_TYPE_DATE` (int)

  字段定义为 `DATE`。

`MYSQLI_TYPE_TIME` (int)

  字段定义为 `TIME`。

`MYSQLI_TYPE_DATETIME` (int)

  字段定义为 `DATETIME`。

`MYSQLI_TYPE_YEAR` (int)

  字段定义为 `YEAR`。

`MYSQLI_TYPE_NEWDATE` (int)

  字段定义为 `DATE`。

`MYSQLI_TYPE_INTERVAL` (int)

  `MYSQLI_TYPE_ENUM` 的别名。自 PHP 8.4.0 起移除。

`MYSQLI_TYPE_ENUM` (int)

  字段定义为 `ENUM`。

`MYSQLI_TYPE_SET` (int)

  字段定义为 `SET`。

`MYSQLI_TYPE_TINY_BLOB` (int)

  字段定义为 `TINYBLOB`。

`MYSQLI_TYPE_MEDIUM_BLOB` (int)

  字段定义为 `MEDIUMBLOB`。

`MYSQLI_TYPE_LONG_BLOB` (int)

  字段定义为 `LONGBLOB`。

`MYSQLI_TYPE_BLOB` (int)

  字段定义为 `BLOB`。

`MYSQLI_TYPE_VAR_STRING` (int)

  字段定义为 `VARCHAR`。

`MYSQLI_TYPE_STRING` (int)

  字段定义为 `CHAR` 或 `BINARY`。

`MYSQLI_TYPE_CHAR` (int)

  字段定义为 `TINYINT`。对于 `CHAR`，参阅 `MYSQLI_TYPE_STRING`。

`MYSQLI_TYPE_GEOMETRY` (int)

  字段定义为 `GEOMETRY`。

`MYSQLI_TYPE_JSON` (int)

  字段定义为 `JSON`。仅对 mysqlnd 和 MySQL 5.7.8 及更高版本有效。

`MYSQLI_TYPE_VECTOR` (int)

  定义该字段为 `VECTOR` 类型。

`MYSQLI_NEED_DATA` (int)

  More data available for bind variable.

`MYSQLI_ENUM_FLAG` (int)

  字段定义为 `ENUM`。

`MYSQLI_BINARY_FLAG` (int)

  字段定义为 `BINARY`。

`MYSQLI_CURSOR_TYPE_FOR_UPDATE` (int)

  自 PHP 8.4.0 起移除。

`MYSQLI_CURSOR_TYPE_NO_CURSOR` (int)

`MYSQLI_CURSOR_TYPE_READ_ONLY` (int)

`MYSQLI_CURSOR_TYPE_SCROLLABLE` (int)

  自 PHP 8.4.0 起移除。

`MYSQLI_STMT_ATTR_CURSOR_TYPE` (int)

`MYSQLI_STMT_ATTR_PREFETCH_ROWS` (int)

  自 PHP 8.4.0 起移除。

`MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH` (int)

`MYSQLI_SET_CHARSET_NAME` (int)

`MYSQLI_REPORT_INDEX` (int)

  如果在查询中没有使用索引或使用了坏索引，则会报告。

`MYSQLI_REPORT_ERROR` (int)

  报告来自 mysqli 函数调用的错误。

`MYSQLI_REPORT_STRICT` (int)

  抛出 `mysqli_sql_exception` 错误而不是警告。

`MYSQLI_REPORT_ALL` (int)

  启用所有选项（报告所有）。

`MYSQLI_REPORT_OFF` (int)

  关闭报告功能。

`MYSQLI_DEBUG_TRACE_ENABLED` (int)

  如果 mysqli_debug() 功能启用，设置为 1。

`MYSQLI_SERVER_PUBLIC_KEY` (int)

`MYSQLI_REFRESH_GRANT` (int)

  刷新授权表。自 PHP 8.4.0 起弃用。

`MYSQLI_REFRESH_LOG` (int)

  刷新日志，就像执行 `FLUSH LOGS` SQL 语句。自 PHP 8.4.0 起弃用。

`MYSQLI_REFRESH_TABLES` (int)

  刷新表缓存，就像执行 `FLUSH TABLES` SQL 语句。自 PHP 8.4.0 起弃用。

`MYSQLI_REFRESH_HOSTS` (int)

  刷新主机缓存，就像执行刷新 `FLUSH HOSTS` SQL 语句一样。自 PHP 8.4.0 起弃用。

`MYSQLI_REFRESH_REPLICA` (int)

  `MYSQLI_REFRESH_SLAVE` 常量的别名。自 PHP 8.1.0 起可用。自 PHP 8.4.0 起弃用。

`MYSQLI_REFRESH_STATUS` (int)

  重置状态变量，如执行 `FLUSH STATUS` SQL 语句。自 PHP 8.4.0 起弃用。

`MYSQLI_REFRESH_THREADS` (int)

  刷新线程缓存。自 PHP 8.4.0 起弃用。

`MYSQLI_REFRESH_SLAVE` (int)

  在从复制服务器上：重置主服务器信息，并重新启动从服务器。就像执行 `RESET SLAVE` SQL 语句一样。自 PHP 8.4.0 起弃用。

`MYSQLI_REFRESH_MASTER` (int)

  在主复制服务器上：删除二进制日志索引中列出的二进制日志文件，并截断索引文件。就像执行 `RESET MASTER` SQL 语句一样。自 PHP 8.4.0 起弃用。

`MYSQLI_REFRESH_BACKUP_LOG` (int)
  关闭并重新打开备份日志文件。自 PHP 8.4.0 起弃用。
`MYSQLI_TRANS_COR_AND_CHAIN` (int)

  追加“AND CHAIN”到 mysqli_commit() 或 mysqli_rollback()。

`MYSQLI_TRANS_COR_AND_NO_CHAIN` (int)

  追加“AND NO CHAIN”到 mysqli_commit() 或 mysqli_rollback()。

`MYSQLI_TRANS_COR_RELEASE` (int)

  追加“RELEASE”到 mysqli_commit() 或 mysqli_rollback()。

`MYSQLI_TRANS_COR_NO_RELEASE` (int)

  追加“NO RELEASE”到 mysqli_commit() 或 mysqli_rollback()。

`MYSQLI_TRANS_START_READ_ONLY` (int)

  使用 mysqli_begin_transaction() 作为“START TRANSACTION READ ONLY”启动事务。

`MYSQLI_TRANS_START_READ_WRITE` (int)

  使用 mysqli_begin_transaction() 作为“START TRANSACTION READ WRITE”启动事务。

`MYSQLI_TRANS_START_WITH_CONSISTENT_SNAPSHOT` (int)

  “START TRANSACTION WITH CONSISTENT SNAPSHOT” 启动事务。

`MYSQLI_CLIENT_SSL_DONT_VERIFY_SERVER_CERT` (int)

  需要 MySQL 5.6.5 及其以上版本。

`MYSQLI_IS_MARIADB` (bool)

  mysqli 扩展是否针对 MariaDB 客户端库编译。自 PHP 8.1.2 起有效。

`MYSQLI_ASYNC` (int)
  查询是异步执行，不会立即返回结果集。仅适用于 `mysqlnd`。
`MYSQLI_ON_UPDATE_NOW_FLAG` (int)
  如果更新了某个字段，将获取当前时间值。

# Notes

Some implementation notes:

1. Support was added for `MYSQL_TYPE_GEOMETRY` to the MySQLi extension in PHP 5.3.

2. Note there are different internal implementations within `libmysqlclient` and `mysqlnd` for handling columns of type `MYSQL_TYPE_GEOMETRY`. Generally speaking, `mysqlnd` will allocate significantly less memory. For example, if there is a `POINT` column in a result set, `libmysqlclient` may pre-allocate up to 4GB of RAM although less than 50 bytes are needed for holding a `POINT` column in memory. Memory allocation is much lower, less than 50 bytes, if using `mysqlnd`.

# MySQLi 扩展的函数概述

mysqli 方法的概述
mysqli 类
面向对象接口 | 面向过程接口 | 别名 (勿使用) | 描述
--- | --- | --- | ---
属性
$mysqli::affected_rows | mysqli_affected_rows() | N/A | 获取上次 Mysql 操作受影响的行数
$mysqli::client_info | mysqli_get_client_info() | N/A | 返回 Mysql 客户端版本信息，类型为 string
$mysqli::client_version | mysqli_get_client_version() | N/A | 返回 Mysql 客户端版本信息，类型为 integer
$mysqli::connect_errno | mysqli_connect_errno() | N/A | 返回最后一次连接数据库的错误代码
$mysqli::connect_error | mysqli_connect_error() | N/A | 返回最后一次连接数据库的错误描述，类型为字符串
$mysqli::errno | mysqli_errno() | N/A | 返回最近一次函数调用所产生的错误代码
$mysqli::error | mysqli_error() | N/A | 返回最近一次错误代码的描述，类型是字符串
$mysqli::field_count | mysqli_field_count() | N/A | 返回最近一次查询中，包含的列的数量
$mysqli::host_info | mysqli_get_host_info() | N/A | 返回字符串，表示数据库连接所使用的类型
$mysqli::protocol_version | mysqli_get_proto_info() | N/A | 返回使用的 MySQL 协议的版本信息
$mysqli::server_info | mysqli_get_server_info() | N/A | 返回 MySQL 服务器的版本
$mysqli::server_version | mysqli_get_server_version() | N/A | 返回 MySQL 服务器的版本，类型为 integer
$mysqli::info | mysqli_info() | N/A | 获取最近一次数据库查询的信息
$mysqli::insert_id | mysqli_insert_id() | N/A | 返回上次查询中所使用的自动生成的 ID
$mysqli::sqlstate | mysqli_sqlstate() | N/A | 返回上次 MySQL 操作的数据库状态错误（SQLSTATE error）
$mysqli::warning_count | mysqli_warning_count() | N/A | 根据数据库链接，返回最后一次数据库查询内警告的数量
Methods
mysqli::autocommit() | mysqli_autocommit() | N/A | 打开或关闭数据库的自动提交（auto-committing）功能
mysqli::change_user() | mysqli_change_user() | N/A | 更改指定数据库连接所使用的用户
mysqli::character_set_name() | mysqli_character_set_name() | N/A | 返回数据库连接的默认字符集
mysqli::close() | mysqli_close() | N/A | 关闭先前打开的数据库连接
mysqli::commit() | mysqli_commit() | N/A | 提交当前的数据库事务
mysqli::__construct() | mysqli_connect() | N/A | 打开新连接到 MySQL 服务器［注意：静态方法]
mysqli::debug() | mysqli_debug() | N/A | 执行调试操作
mysqli::dump_debug_info() | mysqli_dump_debug_info() | N/A | 将调试信息转储到日志中
mysqli::get_charset() | mysqli_get_charset() | N/A | 返回包含字符集信息的对象
mysqli::get_connection_stats() | mysqli_get_connection_stats() | N/A | 返回客户端连接的统计信息。仅可用于 mysqlnd。
mysqli::get_client_info() | mysqli_get_client_info() | N/A | 返回 MySQL 客户端版本的字符串信息
N/A | mysqli_get_client_stats() | N/A | 返回每个客户端进程的统计信息。 仅可用于 mysqlnd。
mysqli::get_server_info() | mysqli_get_server_info() | N/A | 返回 MySQLi 连接上的 MySQL 服务器的版本字符串
mysqli::get_warnings() | mysqli_get_warnings() | N/A | 文档暂缺
mysqli::init() | mysqli_init() | N/A | 初始化 MySQLi，返回对象，可供 mysqli_real_connect 使用。
mysqli::kill() | mysqli_kill() | N/A | 请求服务器杀死一个 MySQL 线程
mysqli::more_results() | mysqli_more_results() | N/A | 检查多语句查询内是否还有更多查询结果
mysqli::multi_query() | mysqli_multi_query() | N/A | 在数据库内执行多语句查询
mysqli::next_result() | mysqli_next_result() | N/A | 从 multi_query 中准备下一个结果集
mysqli::options() | mysqli_options() | mysqli_set_opt() | 设置选项
mysqli::ping() | mysqli_ping() | N/A | Ping 服务器链接，如果链接已经断开，尝试重连
mysqli::prepare() | mysqli_prepare() | N/A | 准备（prepare）需要执行的 SQL 语句
mysqli::query() | mysqli_query() | N/A | 在数据库内执行查询
mysqli::real_connect() | mysqli_real_connect() | N/A | 打开一个 MySQL 服务端的连接
mysqli::real_escape_string(), mysqli::escape_string() | mysqli_real_escape_string() | mysqli_escape_string() | 转义特殊字符，用于 SQL 语句，该转换会考虑连接中当前的字符集
mysqli::real_query() | mysqli_real_query() | N/A | 执行 SQL 查询
mysqli::refresh() | mysqli_refresh() | N/A | 刷新表或缓存，或重置复制（replication）服务器信息
mysqli::rollback() | mysqli_rollback() | N/A | 回滚当前事务
mysqli::select_db() | mysqli_select_db() | N/A | 为数据库查询设置默认数据库
mysqli::set_charset() | mysqli_set_charset() | N/A | 设置默认的客户端字符集
mysqli::ssl_set() | mysqli_ssl_set() | N/A | 使用 SSL 建立安全连接
mysqli::stat() | mysqli_stat() | N/A | 获取当前系统状态
mysqli::stmt_init() | mysqli_stmt_init() | N/A | 初始化语句并且返回供 mysqli_stmt_prepare 使用的对象
mysqli::store_result() | mysqli_store_result() | N/A | 传输最后一个查询的结果集
mysqli::thread_id() | mysqli_thread_id() | N/A | 返回当前连接的线程ID
mysqli::thread_safe() | mysqli_thread_safe() | N/A | 返回是否设定了线程安全
mysqli::use_result() | mysqli_use_result() | N/A | 初始化一个结果集的取回

mysqli_stmt 的方法概述
MySQL_STMT
面向对象接口 | 面向过程接口 | 别名 (勿使用) | 描述
--- | --- | --- | ---
属性
$mysqli_stmt::affected_rows | mysqli_stmt_affected_rows() | N/A | 返回受上次执行语句影响的总行数：修改、删除或插入
$mysqli_stmt::errno | mysqli_stmt_errno() | N/A | 返回最近一次语句调用的错误代码
$mysqli_stmt::error | mysqli_stmt_error() | N/A | 返回最后一条语句错误的字符串描述
$mysqli_stmt::field_count | mysqli_stmt_field_count() | N/A | 返回语句内的字段数量 - 文档暂缺
$mysqli_stmt::insert_id | mysqli_stmt_insert_id() | N/A | 获取上次 INSERT 操作生成的ID
$mysqli_stmt::num_rows | mysqli_stmt_num_rows() | N/A | 返回语句结果集中的行数
$mysqli_stmt::param_count | mysqli_stmt_param_count() | N/A | 返回语句中参数的数量
$mysqli_stmt::sqlstate | mysqli_stmt_sqlstate() | N/A | 返回上次执行 SQL 语句的 SQLSTATE 错误代码
方法
mysqli_stmt::attr_get() | mysqli_stmt_attr_get() | N/A | 用于获取语句属性的当前值
mysqli_stmt::attr_set() | mysqli_stmt_attr_set() | N/A | 用于修改 prepared 语句的行为
mysqli_stmt::bind_param() | mysqli_stmt_bind_param() | N/A | 绑定变量参数到 prepared 语句
mysqli_stmt::bind_result() | mysqli_stmt_bind_result() | N/A | 绑定变量参数到 prepared 语句，用于结果存储
mysqli_stmt::close() | mysqli_stmt_close() | N/A | 关闭 prepared 语句
mysqli_stmt::data_seek() | mysqli_stmt_data_seek() | N/A | 定位到结果集中的任意行
mysqli_stmt::execute() | mysqli_stmt_execute() | mysqli_execute() | 执行 prepared 查询
mysqli_stmt::fetch() | mysqli_stmt_fetch() | N/A | 获取 prepared 语句中的结果，到指定变量中
mysqli_stmt::free_result() | mysqli_stmt_free_result() | N/A | 释放给定语句处理存储的结果集所占内存
mysqli_stmt::get_result() | mysqli_stmt_get_result() | N/A | 获取 prepared 语句中的结果。 仅可用于 mysqlnd。
mysqli_stmt::get_warnings() | mysqli_stmt_get_warnings() | N/A | 暂无文档
mysqli_stmt::more_results() | mysqli_stmt_more_results() | N/A | 检查多语句查询中是否还有更多结果
mysqli_stmt::next_result() | mysqli_stmt_next_result() | N/A | 读取多语句查询中下一条结果
mysqli_stmt::num_rows() | mysqli_stmt_num_rows() | N/A | 参见 $mysqli_stmt::num_rows 中的属性
mysqli_stmt::prepare() | mysqli_stmt_prepare() | N/A | 准备执行 SQL 语句
mysqli_stmt::reset() | mysqli_stmt_reset() | N/A | 重置 prepare 语句
mysqli_stmt::result_metadata() | mysqli_stmt_result_metadata() | N/A | 返回 prepare 语句结果集内的元数据
mysqli_stmt::send_long_data() | mysqli_stmt_send_long_data() | N/A | 以块形式发送数据
mysqli_stmt::store_result() | mysqli_stmt_store_result() | N/A | 从 prepare 语句中传输储存结果集

mysqli_result 方法概述
mysqli_result
面向对象接口 | 面向过程接口 | 别名 (勿使用) | 描述
--- | --- | --- | ---
属性
$mysqli_result::current_field | mysqli_field_tell() | N/A | 获取当前字段在结果集指针中的开始位置
$mysqli_result::field_count | mysqli_num_fields() | N/A | 获取结果中字段数量
$mysqli_result::lengths | mysqli_fetch_lengths() | N/A | 返回结果集中当前行的列长度
$mysqli_result::num_rows | mysqli_num_rows() | N/A | 获取结果中行的数量
方法
mysqli_result::data_seek() | mysqli_data_seek() | N/A | 将结果中的结果指针调整到任意行
mysqli_result::fetch_all() | mysqli_fetch_all() | N/A | 抓取所有的结果行并且以关联数据，数值索引数组，或者两者皆有的方式返回结果集。 仅可用于 mysqlnd。
mysqli_result::fetch_array() | mysqli_fetch_array() | N/A | 以一个关联数组，数值索引数组，或者两者皆有的方式抓取一行结果
mysqli_result::fetch_assoc() | mysqli_fetch_assoc() | N/A | 以一个关联数组方式抓取一行结果
mysqli_result::fetch_column() | mysqli_fetch_column() | N/A | 从结果集的下一行中获取单个列
mysqli_result::fetch_field_direct() | mysqli_fetch_field_direct() | N/A | 抓取一个单字段的元数据
mysqli_result::fetch_field() | mysqli_fetch_field() | N/A | 返回结果集中的下一个字段
mysqli_result::fetch_fields() | mysqli_fetch_fields() | N/A | 返回一个代表结果集字段的对象数组
mysqli_result::fetch_object() | mysqli_fetch_object() | N/A | 以一个对象的方式返回一个结果集中的当前行
mysqli_result::fetch_row() | mysqli_fetch_row() | N/A | 以一个枚举数组方式返回一行结果
mysqli_result::field_seek() | mysqli_field_seek() | N/A | 设置结果指针到特定的字段开始位置
mysqli_result::free(), mysqli_result::close, mysqli_result::free_result | mysqli_free_result() | N/A | 释放与一个结果集相关的内存

mysqli_driver 的方法概述
MySQL_Driver
面向对象接口 | 面向过程接口 | 别名 (勿使用) | 描述
--- | --- | --- | ---
属性
$mysqli_driver::mysqli_report | mysqli_report() | N/A | 设置 mysqli 错误报告模式
方法
mysqli_driver::embedded_server_end() | mysqli_embedded_server_end() | N/A | 文档暂缺
mysqli_driver::embedded_server_start() | mysqli_embedded_server_start() | N/A | 文档暂缺

> 注意:

> 提供函数的别名，目的仅为向下兼容。不要在新项目中使用！

# mysqli 类

(PHP 5, PHP 7, PHP 8)

## 简介

代表 PHP 与 MySQL 数据库之间的连接。

## 类摘要

class mysqli {
/* 属性 */
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;
/* 方法 */
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 — Gets the number of affected rows in a previous MySQL operation

### 说明

面向对象风格

int|string $mysqli->affected_rows;

过程化风格

function mysqli_affected_rows(mysqli `$mysql`): int|string

Returns the number of rows affected by the last `INSERT`, `UPDATE`, `REPLACE` or `DELETE` query. Works like mysqli_num_rows() for `SELECT` statements.

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

An integer greater than zero indicates the number of rows affected or retrieved. Zero indicates that no records were updated for an `UPDATE` statement, no rows matched the `WHERE` clause in the query or that no query has yet been executed. `-1` indicates that the query returned an error or that mysqli_affected_rows() was called for an unbuffered `SELECT` query.

> 注意:

> If the number of affected rows is greater than the maximum int value (`PHP_INT_MAX`), the number of affected rows will be returned as a string.

### 示例

示例 #1 $mysqli->affected_rows example

面向对象风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Insert rows */
    $mysqli->query("CREATE TABLE Language SELECT * from CountryLanguage");
    printf("Affected rows (INSERT): %d\n", $mysqli->affected_rows);

    $mysqli->query("ALTER TABLE Language ADD Status int default 0");

    /* update rows */
    $mysqli->query("UPDATE Language SET Status=1 WHERE Percentage > 50");
    printf("Affected rows (UPDATE): %d\n", $mysqli->affected_rows);

    /* delete rows */
    $mysqli->query("DELETE FROM Language WHERE Percentage < 50");
    printf("Affected rows (DELETE): %d\n", $mysqli->affected_rows);

    /* select all rows */
    $result = $mysqli->query("SELECT CountryCode FROM Language");
    printf("Affected rows (SELECT): %d\n", $mysqli->affected_rows);

    /* Delete table Language */
    $mysqli->query("DROP TABLE Language");

过程化风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Insert rows */
    mysqli_query($link, "CREATE TABLE Language SELECT * from CountryLanguage");
    printf("Affected rows (INSERT): %d\n", mysqli_affected_rows($link));

    mysqli_query($link, "ALTER TABLE Language ADD Status int default 0");

    /* update rows */
    mysqli_query($link, "UPDATE Language SET Status=1 WHERE Percentage > 50");
    printf("Affected rows (UPDATE): %d\n", mysqli_affected_rows($link));

    /* delete rows */
    mysqli_query($link, "DELETE FROM Language WHERE Percentage < 50");
    printf("Affected rows (DELETE): %d\n", mysqli_affected_rows($link));

    /* select all rows */
    $result = mysqli_query($link, "SELECT CountryCode FROM Language");
    printf("Affected rows (SELECT): %d\n", mysqli_affected_rows($link));

    /* Delete table Language */
    mysqli_query($link, "DROP TABLE Language");

以上示例会输出：

    Affected rows (INSERT): 984
    Affected rows (UPDATE): 168
    Affected rows (DELETE): 815
    Affected rows (SELECT): 169

### 参见

- mysqli_num_rows() - Gets the number of rows in the result set
- mysqli_info() - 返回最近执行的 SQL 语句的信息

# mysqli::autocommit

# mysqli_autocommit

(PHP 5, PHP 7, PHP 8)

mysqli::autocommit -- mysqli_autocommit — 打开或关闭本次数据库连接的自动命令提交事务模式

### 说明

面向对象风格

public function mysqli::autocommit(bool `$enable`): bool

过程化风格

function mysqli_autocommit(mysqli `$mysql`, bool `$enable`): bool

打开或关闭本次数据库连接的自动命令提交事务模式。

如需要确认当前连接的自动事务提交状态，可执行这个 SQL 请求 `SELECT @@autocommit`。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`enable`

  是否开启自动提交。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 示例

示例 #1 mysqli::autocommit() 示例

面向对象风格

    <?php

    /* Tell mysqli to throw an exception if an error occurs */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* The table engine has to support transactions */
    $mysqli->query("CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Turn autocommit off */
    $mysqli->autocommit(false);

    $result = $mysqli->query("SELECT @@autocommit");
    $row = $result->fetch_row();
    printf("Autocommit is %s\n", $row[0]);

    try {
        /* Prepare insert statement */
        $stmt = $mysqli->prepare('INSERT INTO language(Code, Speakers) VALUES (?,?)');
        $stmt->bind_param('ss', $language_code, $native_speakers);

        /* Insert some values */
        $language_code = 'DE';
        $native_speakers = 50_123_456;
        $stmt->execute();
        $language_code = 'FR';
        $native_speakers = 40_546_321;
        $stmt->execute();

        /* Commit the data in the database. This doesn't set autocommit=true */
        $mysqli->commit();
        print "Committed 2 rows in the database\n";

        $result = $mysqli->query("SELECT @@autocommit");
        $row = $result->fetch_row();
        printf("Autocommit is %s\n", $row[0]);

        /* Try to insert more values */
        $language_code = 'PL';
        $native_speakers = 30_555_444;
        $stmt->execute();
        $language_code = 'DK';
        $native_speakers = 5_222_444;
        $stmt->execute();

        /* Setting autocommit=true will trigger a commit */
        $mysqli->autocommit(true);

        print "Committed 2 row in the database\n";
    } catch (mysqli_sql_exception $exception) {
        $mysqli->rollback();

        throw $exception;
    }

过程化风格

    <?php

    /* Tell mysqli to throw an exception if an error occurs */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* The table engine has to support transactions */
    mysqli_query($mysqli, "CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Turn autocommit off */
    mysqli_autocommit($mysqli, false);

    $result = mysqli_query($mysqli, "SELECT @@autocommit");
    $row = mysqli_fetch_row($result);
    printf("Autocommit is %s\n", $row[0]);

    try {
        /* Prepare insert statement */
        $stmt = mysqli_prepare($mysqli, 'INSERT INTO language(Code, Speakers) VALUES (?,?)');
        mysqli_stmt_bind_param($stmt, 'ss', $language_code, $native_speakers);

        /* Insert some values */
        $language_code = 'DE';
        $native_speakers = 50_123_456;
        mysqli_stmt_execute($stmt);
        $language_code = 'FR';
        $native_speakers = 40_546_321;
        mysqli_stmt_execute($stmt);

        /* Commit the data in the database. This doesn't set autocommit=true */
        mysqli_commit($mysqli);
        print "Committed 2 rows in the database\n";

        $result = mysqli_query($mysqli, "SELECT @@autocommit");
        $row = mysqli_fetch_row($result);
        printf("Autocommit is %s\n", $row[0]);

        /* Try to insert more values */
        $language_code = 'PL';
        $native_speakers = 30_555_444;
        mysqli_stmt_execute($stmt);
        $language_code = 'DK';
        $native_speakers = 5_222_444;
        mysqli_stmt_execute($stmt);

        /* Setting autocommit=true will trigger a commit */
        mysqli_autocommit($mysqli, true);

        print "Committed 2 row in the database\n";
    } catch (mysqli_sql_exception $exception) {
        mysqli_rollback($mysqli);

        throw $exception;
    }

以上示例会输出：

    Autocommit is 0
    Committed 2 rows in the database
    Autocommit is 0
    Committed 2 row in the database
    Autocommit is 0
    Committed 2 rows in the database
    Autocommit is 0
    Committed 2 row in the database

### 注释

> 注意:

> 此方法在不支持事务的表类型中不生效，如 MyISAM 或 ISAM。

### 参见

- mysqli_begin_transaction() - Starts a transaction
- mysqli_commit() - 提交当前事务
- mysqli_rollback() - 回滚当前事务

# mysqli::begin_transaction

# mysqli_begin_transaction

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::begin_transaction -- mysqli_begin_transaction — Starts a transaction

### 说明

面向对象风格

public function mysqli::begin_transaction(int `$flags` = 0, ?string `$name` = `null`): bool

过程化风格:

function mysqli_begin_transaction(mysqli `$mysql`, int `$flags` = 0, ?string `$name` = `null`): bool

Begins a transaction. Requires the InnoDB engine (it is enabled by default). For additional details about how MySQL transactions work, see » http://dev.mysql.com/doc/mysql/en/commit.html.

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`flags`

  Valid flags are:

  - `MYSQLI_TRANS_START_READ_ONLY`: Start the transaction as "START TRANSACTION READ ONLY". Requires MySQL 5.6 and above.

  - `MYSQLI_TRANS_START_READ_WRITE`: Start the transaction as "START TRANSACTION READ WRITE". Requires MySQL 5.6 and above.

  - `MYSQLI_TRANS_START_WITH_CONSISTENT_SNAPSHOT`: Start the transaction as "START TRANSACTION WITH CONSISTENT SNAPSHOT".

`name`

  Savepoint name for the transaction.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `name` is now nullable.

### 示例

示例 #1 mysqli::begin_transaction() example

面向对象风格

    <?php

    /* Tell mysqli to throw an exception if an error occurs */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* The table engine has to support transactions */
    $mysqli->query("CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Start transaction */
    $mysqli->begin_transaction();

    try {
        /* Insert some values */
        $mysqli->query("INSERT INTO language(Code, Speakers) VALUES ('DE', 42000123)");

        /* Try to insert invalid values */
        $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();

        /* If code reaches this point without errors then commit the data in the database */
        $mysqli->commit();
    } catch (mysqli_sql_exception $exception) {
        $mysqli->rollback();

        throw $exception;
    }

过程化风格

    <?php

    /* Tell mysqli to throw an exception if an error occurs */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* The table engine has to support transactions */
    mysqli_query($mysqli, "CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Start transaction */
    mysqli_begin_transaction($mysqli);

    try {
        /* Insert some values */
        mysqli_query($mysqli, "INSERT INTO language(Code, Speakers) VALUES ('DE', 42000123)");

        /* Try to insert invalid values */
        $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);

        /* If code reaches this point without errors then commit the data in the database */
        mysqli_commit($mysqli);
    } catch (mysqli_sql_exception $exception) {
        mysqli_rollback($mysqli);

        throw $exception;
    }

### 注释

> 注意:

> This function does not work with non transactional table types (like MyISAM or ISAM).

### 参见

- mysqli_autocommit() - 打开或关闭本次数据库连接的自动命令提交事务模式
- mysqli_commit() - 提交当前事务
- mysqli_rollback() - 回滚当前事务

# mysqli::change_user

# mysqli_change_user

(PHP 5, PHP 7, PHP 8)

mysqli::change_user -- mysqli_change_user — Changes the user of the database connection

### 说明

面向对象风格

public function mysqli::change_user(string `$username`, #[\SensitiveParameter] string `$password`, ?string `$database`): bool

过程化风格

function mysqli_change_user(
mysqli `$mysql`,
string `$username`,
#[\SensitiveParameter] string `$password`,
?string `$database`
): bool

Attempts to connect to the specified database using the provided credentials.

In comparison to mysqli::connect(), this method will not disconnect the current connection if the new connection cannot be opened.

In order to successfully change users a valid `username` and `password` parameters must be provided and that user must have sufficient permissions to access the desired database. If for any reason authorization fails, the current user authentication will remain.

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`username`

  The MySQL user name.

`password`

  The MySQL password.

`database`

  The database name. If `null` or an empty string is passed, the connection to the server will be opened with no default database.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 示例

示例 #1 Resetting the connection session

面向对象风格

    <?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("Default database: %s\n", $row[0]);

    $result = $mysqli->query("SELECT @a");
    $row = $result->fetch_row();
    if ($row[0] === null) {
        printf("Value of variable a is NULL\n");
    }

过程化风格

    <?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("Default database: %s\n", $row[0]);

    $result = mysqli_query($link, "SELECT @a");
    $row = mysqli_fetch_row($result);
    if ($row[0] === null) {
        printf("Value of variable a is NULL\n");
    }

以上示例会输出：

    Default database: world
    Value of variable a is NULL

示例 #2 If `database` is `null` the connection is opened without selecting any default database

面向对象风格

    <?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("Default database: %s\n", $row[0]);

以上示例会输出：

    Default database:

### 注释

> 注意:

> Using this command will always cause the current database connection to behave as if was a completely new database connection, regardless of if the operation was completed successfully. This reset includes performing a rollback on any active transactions, closing all temporary tables, and unlocking all locked tables.

### 参见

- mysqli_connect() - 别名 mysqli::__construct
- mysqli_select_db() - 选择用于数据库查询的默认数据库

# mysqli::character_set_name

# mysqli_character_set_name

(PHP 5, PHP 7, PHP 8)

mysqli::character_set_name -- mysqli_character_set_name — 返回当前数据库连接的字符编码

### 说明

面向对象风格

public function mysqli::character_set_name(): string

过程化风格

function mysqli_character_set_name(mysqli `$mysql`): string

返回当前数据库连接的字符编码。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

当前连接的字符编码

### 示例

示例 #1 mysqli::character_set_name() 示例

面向对象风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Set the default character set */
    $mysqli->set_charset('utf8mb4');

    /* Print current character set */
    $charset = $mysqli->character_set_name();
    printf("Current character set is %s\n", $charset);

过程化风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Set the default character set */
    mysqli_set_charset($mysqli, 'utf8mb4');

    /* Print current character set */
    $charset = mysqli_character_set_name($mysqli);
    printf("Current character set is %s\n", $charset);

以上示例会输出：

    Current character set is utf8mb4

### 参见

- mysqli_set_charset() - 设置客户端字符集
- mysqli_real_escape_string() - 根据当前连接的字符集，对于 SQL 语句中的特殊字符进行转义

# mysqli::close

# mysqli_close

(PHP 5, PHP 7, PHP 8)

mysqli::close -- mysqli_close — 关闭先前打开的数据库连接

### 说明

面向对象风格

public function mysqli::close(): true

过程化风格

function mysqli_close(mysqli `$mysql`): true

关闭先前打开的数据库连接。

当打开的非持久 MySQL 连接和结果集的对象销毁时会自动关闭。显式关闭打开的连接和释放结果集不是必需的。但是，如果脚本在获得结果后仍有大量工作要做，那么最好在脚本执行完所有数据库操作后立即关闭连接。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 此函数始终返回 `true`。之前失败时返回 `false`。

### 示例

示例 #1 mysqli::close() 示例

面向对象风格

    <?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");

    /* Close the connection as soon as it's no longer needed */
    $mysqli->close();

    foreach ($result as $row) {
        /* Processing of the data retrieved from the database */
    }

过程化风格

    <?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");

    /* Close the connection as soon as it's no longer needed */
    mysqli_close($mysqli);

    foreach ($result as $row) {
        /* Processing of the data retrieved from the database */
    }

### 注释

> 注意:

> mysqli_close() 不会关闭持久连接。更多详情，查看持久连接的相关手册页。

### 参见

- mysqli::__construct() - Open a new connection to the MySQL server
- mysqli_init() - 初始化 MySQLi 并返回用于 mysqli_real_connect() 的对象
- mysqli_real_connect() - 建立一个 MySQL 服务器连接
- mysqli_free_result() - Frees the memory associated with a result

# mysqli::commit

# mysqli_commit

(PHP 5, PHP 7, PHP 8)

mysqli::commit -- mysqli_commit — 提交当前事务

### 说明

面向对象风格

public function mysqli::commit(int `$flags` = 0, ?string `$name` = `null`): bool

过程化风格

function mysqli_commit(mysqli `$mysql`, int `$flags` = 0, ?string `$name` = `null`): bool

提交当前数据库连接的事务。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`flags`

  `MYSQLI_TRANS_COR_*` 常量的位掩码。

`name`

  如果提供，则执行 `COMMIT/*name*/`。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `name` 现在允许为 null。

### 示例

参阅 mysqli::begin_transaction() 示例。

### 注释

> 注意:

> 此方法在不支持事务的表类型中不生效，如 MyISAM 或 ISAM。

### 参见

- mysqli_autocommit() - 打开或关闭本次数据库连接的自动命令提交事务模式
- mysqli_begin_transaction() - Starts a transaction
- mysqli_rollback() - 回滚当前事务
- mysqli_savepoint() - 在当前事务中设置命名保存点

# mysqli::$connect_errno

# mysqli_connect_errno

(PHP 5, PHP 7, PHP 8)

mysqli::$connect_errno -- mysqli_connect_errno — Returns the error code from last connect call

### 说明

面向对象风格

int $mysqli->connect_errno;

过程化风格

function mysqli_connect_errno(): int

Returns the error code from the last connection attempt.

### 参数

此函数没有参数。

### 返回值

An error code for the last connection attempt, if it failed. Zero means no error occurred.

Returns the last connection error code regardless of the instance on which it is called.

### 示例

示例 #1 $mysqli->connect_errno example

面向对象风格

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);
    /* @ is used to suppress warnings */
    $mysqli = @new mysqli('localhost', 'fake_user', 'wrong_password', 'does_not_exist');
    if ($mysqli->connect_errno) {
        /* Use your preferred error logging method here */
        error_log('Connection error: ' . $mysqli->connect_errno);
    }

过程化风格

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);
    /* @ is used to suppress warnings */
    $link = @mysqli_connect('localhost', 'fake_user', 'wrong_password', 'does_not_exist');
    if (!$link) {
        /* Use your preferred error logging method here */
        error_log('Connection error: ' . mysqli_connect_errno());
    }

### 参见

- mysqli_connect() - 别名 mysqli::__construct
- mysqli_connect_error() - Returns a description of the last connection error
- mysqli_errno() - 返回最近函数调用的错误代码
- mysqli_error() - Returns a string description of the last error
- mysqli_sqlstate() - 返回上一次 MySQL 操作的 SQLSTATE 错误

# mysqli::$connect_error

# mysqli_connect_error

(PHP 5, PHP 7, PHP 8)

mysqli::$connect_error -- mysqli_connect_error — Returns a description of the last connection error

### 说明

面向对象风格

?string $mysqli->connect_error;

过程化风格

function mysqli_connect_error(): ?string

Returns the error message from the last connection attempt.

### 参数

此函数没有参数。

### 返回值

A string that describes the error. `null` is returned if no error occurred.

Returns the last connection error regardless of the instance on which it is called.

### 示例

示例 #1 $mysqli->connect_error example

面向对象风格

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);
    /* @ is used to suppress warnings */
    $mysqli = @new mysqli('localhost', 'fake_user', 'wrong_password', 'does_not_exist');
    if ($mysqli->connect_error) {
        /* Use your preferred error logging method here */
        error_log('Connection error: ' . $mysqli->connect_error);
    }

过程化风格

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);
    /* @ is used to suppress warnings */
    $link = @mysqli_connect('localhost', 'fake_user', 'wrong_password', 'does_not_exist');
    if (!$link) {
        /* Use your preferred error logging method here */
        error_log('Connection error: ' . mysqli_connect_error());
    }

### 参见

- mysqli_connect() - 别名 mysqli::__construct
- mysqli_connect_errno() - Returns the error code from last connect call
- mysqli_errno() - 返回最近函数调用的错误代码
- mysqli_error() - Returns a string description of the last error
- mysqli_sqlstate() - 返回上一次 MySQL 操作的 SQLSTATE 错误

# mysqli::__construct

# mysqli::connect

# mysqli_connect

(PHP 5, PHP 7, PHP 8)

mysqli::__construct -- mysqli::connect -- mysqli_connect — Open a new connection to the MySQL server

### 说明

面向对象风格

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

过程化风格

function mysqli_connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
): mysqli|false

Opens a connection to the MySQL Server.

### 参数

`hostname`

  Can be either a host name or an IP address. When passing `null`, the value is retrieved from mysqli.default_host. When possible, pipes will be used instead of the TCP/IP protocol. The TCP/IP protocol is used if a host name and port number are provided together e.g. `localhost:3308`.

  Prepending host by `p:` opens a persistent connection. mysqli_change_user() is automatically called on connections opened from the connection pool.

`username`

  The MySQL username or `null` to assume the username based on the mysqli.default_user ini option.

`password`

  The MySQL password or `null` to assume the password based on the mysqli.default_pw ini option.

`database`

  The default database to be used when performing queries or `null`.

`port`

  The port number to attempt to connect to the MySQL server or `null` to assume the port based on the mysqli.default_port ini option.

`socket`

  The socket or named pipe that should be used or `null` to assume the socket based on the mysqli.default_socket ini option.

  > 注意:

  > Specifying the `socket` parameter will not explicitly determine the type of connection to be used when connecting to the MySQL server. How the connection is made to the MySQL database is determined by the `hostname` parameter.

### 返回值

mysqli::__construct() always returns an object which represents the connection to a MySQL Server, regardless of it being successful or not.

mysqli_connect() returns an object which represents the connection to a MySQL Server, 或者在失败时返回 `false`.

mysqli::connect() returns `true` on success 或者在失败时返回 `false`. Prior to PHP 8.1.0, returns `null` on success.

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | mysqli::connect() now returns `true` instead of `null` on success.
7.4.0 | All parameters are now nullable.

### 示例

示例 #1 mysqli::__construct() example

面向对象风格

    <?php

    /* You should enable error reporting for mysqli before attempting to make a connection */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

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

    /* Set the desired charset after establishing a connection */
    $mysqli->set_charset('utf8mb4');

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

过程化风格

    <?php

    /* You should enable error reporting for mysqli before attempting to make a connection */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

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

    /* Set the desired charset after establishing a connection */
    mysqli_set_charset($mysqli, 'utf8mb4');

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

以上示例的输出类似于：

    Success... localhost via TCP/IP

示例 #2 Extending mysqli class

    <?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');

示例 #3 Manual error handling

If error reporting is disabled, the developer is responsible for checking and handling failures

面向对象风格

    <?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 connection error: ' . $mysqli->connect_error);
    }

    /* Set the desired charset after establishing a connection */
    $mysqli->set_charset('utf8mb4');
    if ($mysqli->errno) {
        throw new RuntimeException('mysqli error: ' . $mysqli->error);
    }

过程化风格

    <?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 connection error: ' . mysqli_connect_error());
    }

    /* Set the desired charset after establishing a connection */
    mysqli_set_charset($mysqli, 'utf8mb4');
    if (mysqli_errno($mysqli)) {
        throw new RuntimeException('mysqli error: ' . mysqli_error($mysqli));
    }

### 注释

> 注意: MySQLnd 总是使用服务器的默认字符集。此字符集在连接握手／认证时发送，并被 mysqlnd 使用。Libmysqlclient 使用 my.cnf 中的默认字符集或者由在调用 mysqli_init() 之后，mysqli_real_connect() 之前先调用 mysqli_options() 来指定。

> 注意:

> 面向对象风格 only: If the connection fails, an object is still returned. To check whether the connection failed, use either the mysqli_connect_error() function or the mysqli->connect_error property as in the preceding examples.

> 注意:

> If it is necessary to set options, such as the connection timeout, mysqli_real_connect() must be used instead.

> 注意:

> Calling the constructor with no parameters is the same as calling mysqli_init().

> 注意:

> Error "Can't create TCP/IP socket (10106)" usually means that the variables_order configure directive doesn't contain character `E`. On Windows, if the environment is not copied the `SYSTEMROOT` environment variable won't be available and PHP will have problems loading Winsock.

### 参见

- mysqli_real_connect() - 建立一个 MySQL 服务器连接
- mysqli_options() - 设置选项
- mysqli_connect_errno() - Returns the error code from last connect call
- mysqli_connect_error() - Returns a description of the last connection error
- mysqli_close() - 关闭先前打开的数据库连接

# mysqli::debug

# mysqli_debug

(PHP 5, PHP 7, PHP 8)

mysqli::debug -- mysqli_debug — Performs debugging operations

### 说明

面向对象风格

public function mysqli::debug(string `$options`): true

过程化风格

function mysqli_debug(string `$options`): true

Performs debugging operations using the Fred Fish debugging library.

### 参数

`options`

  A string representing the debugging operation to perform

  The debug control string is a sequence of colon separated fields as follows: ``

      <field_1>:<field_2>:<field_N>

  Each field consists of a mandatory flag character followed by an optional `,` and comma separated list of modifiers: `flag[,modifier,modifier,...,modifier]`

  Recognized Flag Characters
  `options` character | Description
  --- | ---
  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 | output to file
  T | `MYSQLND_DEBUG_DUMP_TIME`
  t | `MYSQLND_DEBUG_DUMP_TRACE`
  x | `MYSQLND_DEBUG_PROFILE_CALLS`

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | This function now always returns `true`. Previously it returned `false` on failure.

### 示例

示例 #1 Generating a Trace File

    <?php

    /* Create a trace file in '/tmp/client.trace' on the local (client) machine: */
    mysqli_debug("d:t:o,/tmp/client.trace");

    ?>

### 注释

> 注意:

> To use the mysqli_debug() function you must compile the MySQL client library to support debugging.

### 参见

- mysqli_dump_debug_info() - 将调试信息输出到日志
- mysqli_report() - 别名 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 — 将调试信息输出到日志

### 说明

面向对象风格

public function mysqli::dump_debug_info(): bool

过程化风格

function mysqli_dump_debug_info(mysqli `$mysql`): bool

这个函数设计用于超级权限用户执行将调试信息输出到连接相关的 MySQL Server 的日志中。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- mysqli_debug() - Performs debugging operations

# mysqli::$errno

# mysqli_errno

(PHP 5, PHP 7, PHP 8)

mysqli::$errno -- mysqli_errno — 返回最近函数调用的错误代码

### 说明

面向对象风格

int $mysqli->errno;

过程化风格

function mysqli_errno(mysqli `$mysql`): int

返回最近一次 mysqli 函数调用成功或者失败产生的错误代码。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

上次调用产生的错误代码（如果失败）, 0 代表没有错误发生。

### 示例

示例 #1 $mysqli->errno 示例

面向对象风格

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* 检查连接 */
    if ($mysqli->connect_errno) {
        printf("Connect failed: %s\n", $mysqli->connect_error);
        exit();
    }

    if (!$mysqli->query("SET a=1")) {
        printf("Errorcode: %d\n", $mysqli->errno);
    }

    /* 关闭连接 */
    $mysqli->close();
    ?>

过程化风格

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* 检查连接 */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    if (!mysqli_query($link, "SET a=1")) {
        printf("Errorcode: %d\n", mysqli_errno($link));
    }

    /* 关闭连接 */
    mysqli_close($link);
    ?>

以上示例会输出：

    Errorcode: 1193

### 参见

- mysqli_connect_errno() - Returns the error code from last connect call
- mysqli_connect_error() - Returns a description of the last connection error
- mysqli_error() - Returns a string description of the last error
- mysqli_sqlstate() - 返回上一次 MySQL 操作的 SQLSTATE 错误

# mysqli::$error

# mysqli_error

(PHP 5, PHP 7, PHP 8)

mysqli::$error -- mysqli_error — Returns a string description of the last error

### 说明

面向对象风格

string $mysqli->error;

过程化风格

function mysqli_error(mysqli `$mysql`): string

Returns the last error message for the most recent MySQLi function call that can succeed or fail.

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

A string that describes the error. An empty string if no error occurred.

### 示例

示例 #1 $mysqli->error example

面向对象风格

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* check connection */
    if ($mysqli->connect_errno) {
        printf("Connect failed: %s\n", $mysqli->connect_error);
        exit();
    }

    if (!$mysqli->query("SET a=1")) {
        printf("Error message: %s\n", $mysqli->error);
    }

    /* close connection */
    $mysqli->close();
    ?>

过程化风格

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    if (!mysqli_query($link, "SET a=1")) {
        printf("Error message: %s\n", mysqli_error($link));
    }

    /* close connection */
    mysqli_close($link);
    ?>

以上示例会输出：

    Error message: Unknown system variable 'a'

### 参见

- mysqli_connect_errno() - Returns the error code from last connect call
- mysqli_connect_error() - Returns a description of the last connection error
- mysqli_errno() - 返回最近函数调用的错误代码
- mysqli_sqlstate() - 返回上一次 MySQL 操作的 SQLSTATE 错误

# mysqli::$error_list

# mysqli_error_list

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

mysqli::$error_list -- mysqli_error_list — Returns a list of errors from the last command executed

### 说明

面向对象风格

array $mysqli->error_list;

过程化风格

function mysqli_error_list(mysqli `$mysql`): array

Returns an array of errors for the most recent MySQLi function call that can succeed or fail.

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

A list of errors, each as an associative array containing the errno, error, and sqlstate.

### 示例

示例 #1 $mysqli->error_list example

面向对象风格

    <?php
    $mysqli = new mysqli("localhost", "nobody", "");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    if (!$mysqli->query("SET a=1")) {
        print_r($mysqli->error_list);
    }

    /* close connection */
    $mysqli->close();
    ?>

过程化风格

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    if (!mysqli_query($link, "SET a=1")) {
        print_r(mysqli_error_list($link));
    }

    /* close connection */
    mysqli_close($link);
    ?>

以上示例会输出：

    Array
    (
        [0] => Array
            (
                [errno] => 1193
                [sqlstate] => HY000
                [error] => Unknown system variable 'a'
            )

    )

### 参见

- mysqli_connect_errno() - Returns the error code from last connect call
- mysqli_connect_error() - Returns a description of the last connection error
- mysqli_error() - Returns a string description of the last error
- mysqli_sqlstate() - 返回上一次 MySQL 操作的 SQLSTATE 错误

# mysqli::execute_query

# mysqli_execute_query

(PHP 8 >= 8.2.0)

mysqli::execute_query -- mysqli_execute_query — Prepares, binds parameters, and executes SQL statement

### 说明

面向对象风格

public function mysqli::execute_query(string `$query`, ?array `$params` = `null`): mysqli_result|bool

过程化风格

function mysqli_execute_query(mysqli `$mysql`, string `$query`, ?array `$params` = `null`): mysqli_result|bool

Prepares the SQL query, binds parameters, and executes it. The mysqli::execute_query() method is a shortcut for mysqli::prepare(), mysqli_stmt::bind_param(), mysqli_stmt::execute(), and mysqli_stmt::get_result().

The statement template can contain zero or more question mark (`?`) parameter markers⁠—also called placeholders. The parameter values must be provided as an array using `params` parameter.

A prepared statement is created under the hood but it's never exposed outside of the function. It's impossible to access properties of the statement as one would do with the mysqli_stmt object. Due to this limitation, the status information is copied to the mysqli object and is available using its methods, e.g. mysqli_affected_rows() or mysqli_error().

> 注意:

> In the case where a statement is passed to mysqli_execute_query() that is longer than `max_allowed_packet` of the server, the returned error codes are different depending on the operating system. The behavior is as follows:

> - On Linux returns an error code of 1153. The error message means got a packet bigger than `max_allowed_packet` bytes.

> - On Windows returns an error code 2006. This error message means server has gone away.

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`query`

  The query, as a string. It must consist of a single SQL statement.

  The SQL statement may contain zero or more parameter markers represented by question mark (`?`) characters at the appropriate positions.

  > 注意:

  > The markers are legal only in certain places in SQL statements. For example, they are permitted in the `VALUES()` list of an `INSERT` statement (to specify column values for a row), or in a comparison with a column in a `WHERE` clause to specify a comparison value. However, they are not permitted for identifiers (such as table or column names).

`params`

  An optional list array with as many elements as there are bound parameters in the SQL statement being executed. Each value is treated as a string.

### 返回值

Returns `false` on failure. For successful queries which produce a result set, such as `SELECT, SHOW, DESCRIBE` or `EXPLAIN`, returns a mysqli_result object. For other successful queries, returns `true`.

### 示例

示例 #1 mysqli::execute_query() example

面向对象风格

    <?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"]);
    }

过程化风格

    <?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"]);
    }

以上示例的输出类似于：

    Aachen (Nordrhein-Westfalen)
    Augsburg (Baijeri)
    Bergisch Gladbach (Nordrhein-Westfalen)
    Berlin (Berliini)
    Bielefeld (Nordrhein-Westfalen)

### 参见

- mysqli_prepare() - 预处理执行 SQL
- mysqli_stmt_execute() - Executes a prepared statement
- mysqli_stmt_bind_param() - Binds variables to a prepared statement as parameters
- mysqli_stmt_get_result() - Gets a result set from a prepared statement as a mysqli_result object

# mysqli::$field_count

# mysqli_field_count

(PHP 5, PHP 7, PHP 8)

mysqli::$field_count -- mysqli_field_count — Returns the number of columns for the most recent query

### 说明

面向对象风格

int $mysqli->field_count;

过程化风格

function mysqli_field_count(mysqli `$mysql`): int

Returns the number of columns for the most recent query on the connection represented by the `mysql` parameter. This function can be useful when using the mysqli_store_result() function to determine if the query should have produced a non-empty result set or not without knowing the nature of the query.

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

An integer representing the number of fields in a result set.

### 示例

示例 #1 $mysqli->field_count example

面向对象风格

    <?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) {
        /* this was a select/show or describe query */
        $result = $mysqli->store_result();

        /* process resultset */
        $row = $result->fetch_row();

        /* free resultset */
        $result->close();
    }

    /* close connection */
    $mysqli->close();
    ?>

过程化风格

    <?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)) {
        /* this was a select/show or describe query */
        $result = mysqli_store_result($link);

        /* process resultset */
        $row = mysqli_fetch_row($result);

        /* free resultset */
        mysqli_free_result($result);
    }

    /* close connection */
    mysqli_close($link);
    ?>

# mysqli::get_charset

# mysqli_get_charset

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli::get_charset -- mysqli_get_charset — Returns a character set object

### 说明

面向对象风格

public function mysqli::get_charset(): ?object

过程化风格

function mysqli_get_charset(mysqli `$mysql`): ?object

Returns a character set object providing several properties of the current active character set.

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

The function returns a character set object with the following properties:

`charset`

  Character set name

`collation`

  Collation name

`dir`

  Directory the character set description was fetched from or "" for built-in character sets

`min_length`

  Minimum character length in bytes

`max_length`

  Maximum character length in bytes

`number`

  Internal character set number

`state`

  As of PHP 8.2.0, it is always `1`

### 示例

示例 #1 mysqli::get_charset() example

面向对象风格

    <?php
      $db = mysqli_init();
      $db->real_connect("localhost","root","","test");
      $db->set_charset('latin1');
      var_dump($db->get_charset());
    ?>

过程化风格

    <?php
      $db = mysqli_init();
      mysqli_real_connect($db, "localhost","root","","test");
      mysqli_set_charset($db, 'latin1');
      var_dump(mysqli_get_charset($db));
    ?>

以上示例会输出：

    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(1)
    }

### 参见

- mysqli_character_set_name() - 返回当前数据库连接的字符编码
- mysqli_set_charset() - 设置客户端字符集

# 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 — 获取 MySQL 客户端信息

### 说明

面向对象风格

string $mysqli->client_info;
#[\Deprecated]
public function mysqli::get_client_info(): string

过程化风格

function mysqli_get_client_info(?mysqli `$mysql` = `null`): string

返回表示 MySQL 客户端库的版本信息的字符串。

### 参数

此函数没有参数。

### 返回值

表示 MySQL 客户端库的版本信息的字符串。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 弃用使用 `mysql` 参数调用 mysqli_get_client_info()。此函数从不需要参数，但错误的允许其作为可选参数。
8.1.0 | 弃用面向对象风格的 mysqli::get_client_info()。

### 示例

示例 #1 mysqli_get_client_info

    <?php

    /* 获取客户端版本新的时候，
       无需建立到数据库的连接 */

    printf("Client library version: %s\n", mysqli_get_client_info());
    ?>

### 参见

- mysqli_get_client_version() - 作为整数返回 MySQL 客户端的版本
- mysqli_get_server_info() - 返回 MySQL 服务器的版本号
- mysqli_get_server_version() - 作为一个整数返回MySQL服务器的版本

# mysqli::$client_version

# mysqli_get_client_version

(PHP 5, PHP 7, PHP 8)

mysqli::$client_version -- mysqli_get_client_version — 作为整数返回 MySQL 客户端的版本

### 说明

面向对象风格

int $mysqli->client_version;

过程化风格

function mysqli_get_client_version(): int

作为整数返回客户端版本号。

### 参数

此函数没有参数。

### 返回值

表示 MySQL 客户端库版本的数字，格式为 `main_version*10000 + minor_version *100 + sub_version`。例如：4.1.0 返回 40100。

这有助于快速确定客户端库的版本来辨别是否有某些特性存在。

### 示例

示例 #1 mysqli_get_client_version

    <?php

    /* We don't need a connection to determine
       the version of mysql client library */

    printf("Client library version: %d\n", mysqli_get_client_version());
    ?>

### 参见

- mysqli_get_client_info() - 获取 MySQL 客户端信息
- mysqli_get_server_info() - 返回 MySQL 服务器的版本号
- mysqli_get_server_version() - 作为一个整数返回MySQL服务器的版本

# 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 — 返回客户端连接的统计数据

### 说明

面向对象风格

public function mysqli::get_connection_stats(): array

过程化风格

function mysqli_get_connection_stats(mysqli `$mysql`): array

返回客户端连接的统计数据。

> 注意:

> 仅可用于 mysqlnd。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

返回数组，包含连接状态。

### 示例

示例 #1 A mysqli_get_connection_stats() 示例

    <?php
    $link = mysqli_connect();
    print_r(mysqli_get_connection_stats($link));
    ?>

以上示例的输出类似于：

    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
    )

### 参见

- 统计说明

# mysqli::$host_info

# mysqli_get_host_info

(PHP 5, PHP 7, PHP 8)

mysqli::$host_info -- mysqli_get_host_info — 返回表述使用的连接类型的字符串

### 说明

面向对象风格

string $mysqli->host_info;

过程化风格

function mysqli_get_host_info(mysqli `$mysql`): string

返回由 `mysql` 参数表示连接的字符串描述（包括服务器主机名）。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

表示服务器主机名和连接类型的字符串。

### 示例

示例 #1 $mysqli->host_info 示例

面向对象风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* print host information */
    printf("Host info: %s\n", $mysqli->host_info);

过程化风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* print host information */
    printf("Host info: %s\n", mysqli_get_host_info($link));

以上示例会输出：

    Host info: Localhost via UNIX socket

### 参见

- mysqli_get_proto_info() - 返回 MySQL 协议使用的版本号

# mysqli::$protocol_version

# mysqli_get_proto_info

(PHP 5, PHP 7, PHP 8)

mysqli::$protocol_version -- mysqli_get_proto_info — 返回 MySQL 协议使用的版本号

### 说明

面向对象风格

int $mysqli->protocol_version;

过程化风格

function mysqli_get_proto_info(mysqli `$mysql`): int

返回整数，表示由 `mysql` 参数表示的连接所使用的 MySQL 协议的版本号。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

返回表示协议版本号的整数。

### 示例

示例 #1 $mysqli->protocol_version 示例

面向对象风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password");

    /* print protocol version */
    printf("Protocol version: %d\n", $mysqli->protocol_version);

过程化风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password");

    /* print protocol version */
    printf("Protocol version: %d\n", mysqli_get_proto_info($link));

以上示例会输出：

    Protocol version: 10

### 参见

- mysqli_get_host_info() - 返回表述使用的连接类型的字符串

# 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 — 返回 MySQL 服务器的版本号

### 说明

面向对象风格

string $mysqli->server_info;
public function mysqli::get_server_info(): string

过程化风格

function mysqli_get_server_info(mysqli `$mysql`): string

返回字符串，表示 MySQLi 扩展连接的 MySQL 服务器的版本号。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

表示服务器版本的字符串。

### 示例

示例 #1 $mysqli->server_info 示例

面向对象风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password");

    /* print server version */
    printf("Server version: %s\n", $mysqli->server_info);

过程化风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password");

    /* print server version */
    printf("Server version: %s\n", mysqli_get_server_info($link));

以上示例的输出类似于：

    Server version: 8.0.21

### 参见

- mysqli_get_client_info() - 获取 MySQL 客户端信息
- mysqli_get_client_version() - 作为整数返回 MySQL 客户端的版本
- mysqli_get_server_version() - 作为一个整数返回MySQL服务器的版本

# mysqli::$server_version

# mysqli_get_server_version

(PHP 5, PHP 7, PHP 8)

mysqli::$server_version -- mysqli_get_server_version — 作为一个整数返回MySQL服务器的版本

### 说明

面向对象风格

int $mysqli->server_version;

过程化风格

function mysqli_get_server_version(mysqli `$mysql`): int

mysqli_get_server_version() 函数以整数的形式返回连接的 `mysql` 参数所表述的服务器的版本。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

一个整数表述的服务器版本。

版本号的格式是 `main_version * 10000 + minor_version * 100 + sub_version`（例如版本 4.1.0 是 40100）。

### 示例

示例 #1 $mysqli->server_version 示例

面向对象风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password");

    /* print server version */
    printf("Server version: %d\n", $mysqli->server_version);

过程化风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password");

    /* print server version */
    printf("Server version: %d\n", mysqli_get_server_version($link));

以上示例的输出类似于：

    Server version: 80021

### 参见

- mysqli_get_client_info() - 获取 MySQL 客户端信息
- mysqli_get_client_version() - 作为整数返回 MySQL 客户端的版本
- mysqli_get_server_info() - 返回 MySQL 服务器的版本号

# mysqli::get_warnings

# mysqli_get_warnings

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli::get_warnings -- mysqli_get_warnings — Get result of SHOW WARNINGS

### 说明

面向对象风格

public function mysqli::get_warnings(): mysqli_warning|false

过程化风格

function mysqli_get_warnings(mysqli `$mysql`): mysqli_warning|false

Returns a singly linked list comprised of mysqli_warning or `false` if there are no warnings. Each object in the list corresponds to a single line from the result of `SHOW WARNINGS`. Calling mysqli_warning::next() will refill the object with the values from the next row.

> 注意: To retrieve warning messages, it is recommended to use the SQL command `SHOW WARNINGS [limit row_count]` instead of this function.

警告

The linked list cannot be rewound or retrieved again.

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

Returns a singly linked list comprised of mysqli_warning or `false` if there are no warnings.

### 示例

示例 #1 Traversing the linked list to fetch all warnings

面向对象风格

    <?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("Error number: %s\n", $warning->errno);
                printf("Message: %s\n", $warning->message);
            } while ($warning->next());
        }
    }

过程化风格

    <?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("Error number: %s\n", $warning->errno);
                printf("Message: %s\n", $warning->message);
            } while ($warning->next());
        }
    }

以上示例会输出：

    Error number: 1365
    Message: Division by 0
    Error number: 1292
    Message: Truncated incorrect INTEGER value: 'NULL'

# mysqli::$info

# mysqli_info

(PHP 5, PHP 7, PHP 8)

mysqli::$info -- mysqli_info — 返回最近执行的 SQL 语句的信息

### 说明

面向对象风格

?string $mysqli->info;

过程化风格

function mysqli_info(mysqli `$mysql`): ?string

mysqli_info() 函数返回一个包含 最近执行的 SQL 语句信息的字符串。 下面有一些参考样例：

mysqli_info 可能的返回值
SQL 语句类型 | 返回结果字符串示例
--- | ---
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

> 注意:

> 如果所执行的 SQL 语句不是上面列出来的这几种类型的， mysqli_info() 函数会返回一个空字符串。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

最近执行的 SQL 语句的相关信息。

### 示例

示例 #1 $mysqli->info 示例

面向对象风格

    <?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);

过程化风格

    <?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));

以上示例会输出：

    Records: 150  Duplicates: 0  Warnings: 0

### 参见

- mysqli_affected_rows() - Gets the number of affected rows in a previous MySQL operation
- mysqli_warning_count() - Returns the number of warnings generated by the most recently executed query
- mysqli_num_rows() - Gets the number of rows in the result set

# mysqli::init

# mysqli_init

(PHP 5, PHP 7, PHP 8)

mysqli::init -- mysqli_init — 初始化 MySQLi 并返回用于 mysqli_real_connect() 的对象

### 说明

面向对象风格

#[\Deprecated]
public function mysqli::init(): ?bool

过程化风格

function mysqli_init(): mysqli|false

分配或者初始化适合 mysqli_options() 和 mysqli_real_connect() 的 MYSQL 对象。

> 注意:

> 在调用 mysqli_real_connect() 之前，对其它 mysqli 函数（mysqli_options() 和 mysqli_ssl_set() 除外）的后续调用都会失败。

### 参数

此函数没有参数。

### 返回值

mysqli::init() 成功时返回 `null`， 或者在失败时返回 `false`。mysqli_init() 成功时返回对象， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 弃用面向对象风格的 mysqli::init() 方法。用 parent::__construct() 替换对 parent::init() 的调用。

### 示例

参阅 mysqli_real_connect()。

### 参见

- mysqli_options() - 设置选项
- mysqli_close() - 关闭先前打开的数据库连接
- mysqli_real_connect() - 建立一个 MySQL 服务器连接
- mysqli_connect() - 别名 mysqli::__construct

# mysqli::$insert_id

# mysqli_insert_id

(PHP 5, PHP 7, PHP 8)

mysqli::$insert_id -- mysqli_insert_id — 返回上次查询为 AUTO_INCREMENT 列生成的值

### 说明

面向对象风格

int|string $mysqli->insert_id;

过程化风格

function mysqli_insert_id(mysqli `$mysql`): int|string

返回有 `AUTO_INCREMENT` 属性的表执行 `INSERT` 或 `UPDATE` 查询生成的 ID。对于多行 `INSERT` 语句，返回成功插入的第一个自动生成的值。

使用 `LAST_INSERT_ID()` MySQL 函数执行 `INSERT` 或 `UPDATE` 语句也会修改 mysqli_insert_id() 返回的值。如果使用 `LAST_INSERT_ID(expr)` 生成 `AUTO_INCREMENT` 的值，将返回最后 `expr` 的值而不是生成的 `AUTO_INCREMENT` 值。

如果之前的语句没有修改 `AUTO_INCREMENT` 的值，则返回 `0`。mysqli_insert_id() 必须在生成值的语句之后立即调用。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

上一个查询更新的 `AUTO_INCREMENT` 字段的值。如果连接上没有之前的查询或者查询没有更新 `AUTO_INCREMENT` 值。则返回 0。

只有使用当前连接发出的语句才会影响返回值。该值不受使用其它连接或客户端发出的语句的影响。

> 注意:

> 如果数字大于最大 int 值，将以字符串返回该值。

### 示例

示例 #1 $mysqli->insert_id 示例

面向对象风格

    <?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("New record has ID %d.\n", $mysqli->insert_id);

    /* 删除表 */
    $mysqli->query("DROP TABLE myCity");

过程化风格

    <?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("New record has ID %d.\n", mysqli_insert_id($link));

    /* 删除表 */
    mysqli_query($link, "DROP TABLE myCity");

以上示例会输出：

    New record has ID 1.

# mysqli::kill

# mysqli_kill

(PHP 5, PHP 7, PHP 8)

mysqli::kill -- mysqli_kill — 让服务器杀死一个 MySQL 线程

警告

此函数自 PHP 8.4.0 起弃用。强烈建议不要应用此函数。

### 说明

面向对象风格

#[\Deprecated]
public function mysqli::kill(int `$process_id`): bool

过程化风格

#[\Deprecated]
function mysqli_kill(mysqli `$mysql`, int `$process_id`): bool

本函数可以用来让服务器杀掉 `process_id` 参数指定的 MySQL 线程。必须通过调用 mysqli_thread_id() 函数来检索该值。

要停止正在运行的查询，应该使用 SQL 命令 `KILL QUERY processid`。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | mysqli::kill() 和 mysqli_kill() 都已弃用。使用 `KILL` SQL 命令代替。

### 示例

示例 #1 mysqli::kill() 示例

面向对象风格

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* 检查连接是否成功 */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    /* 获得连接对应的线程 ID */
    $thread_id = $mysqli->thread_id;

    /* 杀掉连接 */
    $mysqli->kill($thread_id);

    /* 下面的代码应该会发生错误 */
    if (!$mysqli->query("CREATE TABLE myCity LIKE City")) {
        printf("Error: %s\n", $mysqli->error);
        exit;
    }

    /* 关闭连接 */
    $mysqli->close();
    ?>

过程化风格

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* 检查连接是否成功 */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    /* 获得连接对应的线程 ID */
    $thread_id = mysqli_thread_id($link);

    /* 杀掉连接 */
    mysqli_kill($link, $thread_id);

    /* 下面的代码应该会发生错误 */
    if (!mysqli_query($link, "CREATE TABLE myCity LIKE City")) {
        printf("Error: %s\n", mysqli_error($link));
        exit;
    }

    /* 关闭连接 */
    mysqli_close($link);
    ?>

以上示例会输出：

    Error: MySQL server has gone away

### 参见

- mysqli_thread_id() - 返回当前连接的线程 ID

# mysqli::more_results

# mysqli_more_results

(PHP 5, PHP 7, PHP 8)

mysqli::more_results -- mysqli_more_results — 检查批量查询中是否还有查询结果

### 说明

面向对象风格

public function mysqli::more_results(): bool

过程化风格

function mysqli_more_results(mysqli `$mysql`): bool

检查上一次调用 mysqli_multi_query() 函数之后，是否还有更多的查询结果集。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

如果上一次调用 mysqli_multi_query() 函数之后， 还有更多的结果集（包含错误）可以读取，返回 `true`，否则返回 `false`。

### 示例

参见 mysqli_multi_query()。

### 参见

- mysqli_multi_query() - 在数据库上执行一个或多个查询
- mysqli_next_result() - 为读取 multi_query 执行之后的下一个结果集做准备
- mysqli_store_result() - 传输上次查询的结果集
- mysqli_use_result() - Initiate a result set retrieval

# mysqli::multi_query

# mysqli_multi_query

(PHP 5, PHP 7, PHP 8)

mysqli::multi_query -- mysqli_multi_query — 在数据库上执行一个或多个查询

### 说明

面向对象风格

public function mysqli::multi_query(string `$query`): bool

过程化风格

function mysqli_multi_query(mysqli `$mysql`, string `$query`): bool

执行一个或多个由分号分隔的查询。

警告

# Security warning: SQL injection

If the query contains any variable input then parameterized prepared statements should be used instead. Alternatively, the data must be properly formatted and all strings must be escaped using the mysqli_real_escape_string() function.

对数据库的单个调用中，查询是异步发送，但数据库会按顺序处理。 mysqli_multi_query() 在将控制返回给 PHP 之前等待第一个查询完成。MySQL 服务器将会按照顺序处理下一个查询。一旦下一个结果就绪，MySQL 将等待 PHP 的下一次 mysqli_next_result() 执行。

推荐使用 do-while 处理多个查询。在所有查询完成并将结果返回给 PHP 之前，连接一直处于繁忙状态。在处理完成所有查询之前，不能在同一连接上发出其它语句。要继续处理顺序中的下一个查询，请使用 mysqli_next_result()。如果下一个结果还没准备好，mysqli 就会等待 MySQL 服务器的响应。要检查是否有更多结果，使用 mysqli_more_results()。

对于产生查询结果集的查询，比如 `SELECT, SHOW, DESCRIBE` 或 `EXPLAIN`，mysqli_use_result() 或 mysqli_store_result() 可用于检索结果集。对于不产生结果集的查询（比如受影响的行数），可以使用相同函数查询。

小技巧

为存储过程执行 `CALL` 语句可以产生多个结果集。如果存储过程包含 `SELECT` 语句，结果集将按照执行过程中的顺序返回。通常，调用者不会知道过程将返回多少个结果集，必须准备好检索多个结果。该过程的最终结果是不包含结果集的 status 结果。status 表示过程是成功还是发生错误。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`query`

  包含要执行查询的字符串。多个查询必须用分号分隔。

### 返回值

如果第一个 SQL 语句就失败了，返回 `false`。要从其它语句中检索后续错误，必须先调用 mysqli_next_result()。

### 错误／异常

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.

### 示例

示例 #1 mysqli::multi_query() 示例

面向对象风格

    <?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";

    /* 批量执行查询 */
    $mysqli->multi_query($query);
    do {
        /* store the result set in PHP */
        if ($result = $mysqli->store_result()) {
            while ($row = $result->fetch_row()) {
                printf("%s\n", $row[0]);
            }
        }
        /* print divider */
        if ($mysqli->more_results()) {
            printf("-----------------\n");
        }
    } while ($mysqli->next_result());

过程化风格

    <?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";

    /* 批量执行查询 */
    mysqli_multi_query($link, $query);
    do {
        /* store the result set in PHP */
        if ($result = mysqli_store_result($link)) {
            while ($row = mysqli_fetch_row($result)) {
                printf("%s\n", $row[0]);
            }
        }
        /* print divider */
        if (mysqli_more_results($link)) {
            printf("-----------------\n");
        }
    } while (mysqli_next_result($link));

以上示例的输出类似于：

    my_user@localhost
    -----------------
    Amersfoort
    Maastricht
    Dordrecht
    Leiden
    Haarlemmermeer

### 参见

- mysqli_query() - 对数据库执行查询
- mysqli_use_result() - Initiate a result set retrieval
- mysqli_store_result() - 传输上次查询的结果集
- mysqli_next_result() - 为读取 multi_query 执行之后的下一个结果集做准备
- mysqli_more_results() - 检查批量查询中是否还有查询结果

# mysqli::next_result

# mysqli_next_result

(PHP 5, PHP 7, PHP 8)

mysqli::next_result -- mysqli_next_result — 为读取 multi_query 执行之后的下一个结果集做准备

### 说明

面向对象风格

public function mysqli::next_result(): bool

过程化风格

function mysqli_next_result(mysqli `$mysql`): bool

mysqli_multi_query() 函数执行之后，为读取下一个结果集做准备，然后可以使用 mysqli_store_result() 或 mysqli_use_result() 检索。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。如果下一条语句导致错误，也返回 `false`，这跟 mysqli_more_results() 不同。

### 错误／异常

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.

### 示例

参阅 mysqli_multi_query()。

### 参见

- mysqli_multi_query() - 在数据库上执行一个或多个查询
- mysqli_more_results() - 检查批量查询中是否还有查询结果
- mysqli_store_result() - 传输上次查询的结果集
- mysqli_use_result() - Initiate a result set retrieval

# mysqli::options

# mysqli_options

(PHP 5, PHP 7, PHP 8)

mysqli::options -- mysqli_options — 设置选项

### 说明

面向对象风格

public function mysqli::options(int `$option`, string|int `$value`): bool

过程化风格

function mysqli_options(mysqli `$mysql`, int `$option`, string|int `$value`): bool

用于设置连接的扩展选项，这些选项可以改变这个连接的行为。

如果要对多个选项进行设置，可以多次调用此函数来。

mysqli_options() 需要在 mysqli_init() 函数之后、 mysqli_real_connect() 函数之前调用。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`option`

  要进行设置的选项，可以是下列值中的某一项：

  有效的选项
  名称 | 描述
  --- | ---
  `MYSQLI_OPT_CONNECT_TIMEOUT` | 连接超时设置，以秒为单位
  `MYSQLI_OPT_READ_TIMEOUT` | 命令执行超时秒数，自 PHP 7.2.0 起可用。
  `MYSQLI_OPT_LOCAL_INFILE` | 启用或禁用 `LOAD LOCAL INFILE`
  `MYSQLI_OPT_LOAD_DATA_LOCAL_DIR` | 用于 `LOAD DATA LOCAL INFILE` 的目录。
  `MYSQLI_INIT_COMMAND` | 连接到 MySQL 服务器后要执行的命令
  `MYSQLI_SET_CHARSET_NAME` | 设置的默认字符集
  `MYSQLI_READ_DEFAULT_FILE` | 从指定的文件中读取选项，而不是使用 my.cnf 中的选项。mysqlnd 不支持。
  `MYSQLI_READ_DEFAULT_GROUP` | 从 my.cnf 或者 `MYSQL_READ_DEFAULT_FILE` 指定的文件中 读取指定的组中的选项。mysqlnd 不支持。
  `MYSQLI_SERVER_PUBLIC_KEY` | SHA-256 认证模式下，要使用的 RSA 公钥文件。
  `MYSQLI_OPT_NET_CMD_BUFFER_SIZE` | 内部命令/网络缓冲大小， 仅在 mysqlnd 驱动下有效。
  `MYSQLI_OPT_NET_READ_BUFFER_SIZE` | 以字节为单位，读取 MySQL 命令报文时候的块大小， 仅在 mysqlnd 驱动下有效。
  `MYSQLI_OPT_INT_AND_FLOAT_NATIVE` | 使用非预处理语句时，将整数和浮点数类型的列转换成 PHP 的数值类型。 仅在 mysqlnd 驱动下有效。
  `MYSQLI_OPT_SSL_VERIFY_SERVER_CERT` | 是否验证服务器证书。
  `MYSQLI_OPT_CAN_HANDLE_EXPIRED_PASSWORDS` | 客户端是否接受过期密码。
  `1` | 是否使用网络通信压缩。

`value`

  选项值。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 示例

参见 mysqli_real_connect()。

### 注释

> 注意: MySQLnd 总是使用服务器的默认字符集。此字符集在连接握手／认证时发送，并被 mysqlnd 使用。Libmysqlclient 使用 my.cnf 中的默认字符集或者由在调用 mysqli_init() 之后，mysqli_real_connect() 之前先调用 mysqli_options() 来指定。

### 参见

- mysqli_init() - 初始化 MySQLi 并返回用于 mysqli_real_connect() 的对象
- mysqli_real_connect() - 建立一个 MySQL 服务器连接

# mysqli::ping

# mysqli_ping

(PHP 5, PHP 7, PHP 8)

mysqli::ping -- mysqli_ping — ping 一个连接，或者如果连接处于断开状态，重新连接

警告

此函数自 PHP 8.4.0 起弃用。强烈建议不要应用此函数。

### 说明

面向对象风格

#[\Deprecated]
public function mysqli::ping(): bool

过程化风格

#[\Deprecated]
function mysqli_ping(mysqli `$mysql`): bool

检查到服务器的连接是否还正常。在启用 mysqli.reconnect 选项的前提下，如果连接已经断开，ping 操作会尝试重新建立连接。

> 注意: mysqlnd 驱动会忽略 php.ini 中的 mysqli.reconnect 选项，所以它不会自动重连。

客户端建立连接之后，长时间处于闲置状态，可以用此函数来检查服务器是否关闭了这个连接，如有必要，将会自动重新建立到服务器的连接。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | mysqli::ping() 和 mysqli_ping() 都已弃用。自 PHP 8.2.0 起，`reconnect` 功能已不可用，因此该函数已过时。

### 示例

示例 #1 mysqli::ping() 示例

面向对象风格

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* 检查连接 */
    if ($mysqli->connect_errno) {
        printf("Connect failed: %s\n", $mysqli->connect_error);
        exit();
    }

    /* 检查连接是否还活跃 */
    if ($mysqli->ping()) {
        printf ("Our connection is ok!\n");
    } else {
        printf ("Error: %s\n", $mysqli->error);
    }

    /* 关闭连接 */
    $mysqli->close();
    ?>

过程化风格

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* 检查连接 */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    /* 检查连接是否还活跃 */
    if (mysqli_ping($link)) {
        printf ("Our connection is ok!\n");
    } else {
        printf ("Error: %s\n", mysqli_error($link));
    }

    /* 关闭连接 */
    mysqli_close($link);
    ?>

以上示例会输出：

    Our connection is ok!

# mysqli::poll

# mysqli_poll

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::poll -- mysqli_poll — 轮询连接

### 说明

面向对象风格

public static function mysqli::poll(
?array `&$read`,
?array `&$error`,
array `&$reject`,
int `$seconds`,
int `$microseconds` = 0
): int|false

过程化风格

function mysqli_poll(
?array `&$read`,
?array `&$error`,
array `&$reject`,
int `$seconds`,
int `$microseconds` = 0
): int|false

轮询连接。此方法是 static 的。

> 注意:

> 仅可用于 mysqlnd。

### 参数

`read`

  要检测是否存在可以读取的结果集的连接的数组。

`error`

  发生错误的，例如：SQL 语句执行失败或者已经断开的 连接的数组。

`reject`

  没有可以读取的结果集的连接 的数组。

`seconds`

  秒为单位的最大等待时间，不可以为负数。

`microseconds`

  微秒为单位的最大等待时间，不可以为负数。

### 返回值

成功执行则返回存在可以读取结果集的连接数量， 否则 `false`。

### 错误／异常

当没有传递 `read` 和 `error` 参数时抛出 ValueError 异常。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | 现在，当没有传递 `read` 和 `error` 参数时抛出 ValueError 异常。

### 示例

示例 #1 mysqli_poll() 示例

    <?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 Error: %s", mysqli_error($link)));
            $processed++;
        }
    } while ($processed < count($all_links));
    ?>

以上示例会输出：

    Array
    (
        [0] => test
    )

### 参见

- mysqli_query() - 对数据库执行查询
- mysqli_reap_async_query() - 获取异步查询的结果

# mysqli::prepare

# mysqli_prepare

(PHP 5, PHP 7, PHP 8)

mysqli::prepare -- mysqli_prepare — 预处理执行 SQL

### 说明

面向对象风格

public function mysqli::prepare(string `$query`): mysqli_stmt|false

过程化风格

function mysqli_prepare(mysqli `$mysql`, string `$query`): mysqli_stmt|false

预处理 SQL 查询并返回 statement 句柄，用于对语句进行后续操作。查询仅仅支持单条 SQL 语句。

语句模板可以包含零或多个问号（`?`）参数标记，也称作占位符。在执行语句之前，必须使用 mysqli_stmt_bind_param() 将参数标记绑定到应用程序变量。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`query`

  string 格式的语句。必须由单个 SQL 语句组成。

  SQL 语句可能在适当的位置包含零个或多个由问号（`?`）字符表示的参数标记。

  > 注意:

  > SQL 语句中，仅允许在特定的位置出现问号参数占位符。例如，允许在 `INSERT` 语句中的 `VALUES()` 列表中使用，表示对应列的值，也可以在 `WHERE` 子句中使用参数来表示要进行比较的值。但不允许用于标识符（例如表名或列名）。

### 返回值

mysqli_prepare() 返回一个 statement 对象，如果发生错误则返回 `false`。

### 错误／异常

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.

### 示例

示例 #1 mysqli::prepare() 示例

面向对象风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $city = "Amersfoort";

    /* 创建预处理语句 */
    $stmt = $mysqli->prepare("SELECT District FROM City WHERE Name=?");

    /* 为标记绑定参数 */
    $stmt->bind_param("s", $city);

    /* 执行查询 */
    $stmt->execute();

    /* 绑定结果变量 */
    $stmt->bind_result($district);

    /* 获取值 */
    $stmt->fetch();

    printf("%s is in district %s\n", $city, $district);

过程化风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $city = "Amersfoort";

    /* 创建预处理语句 */
    $stmt = mysqli_prepare($link, "SELECT District FROM City WHERE Name=?");

    /* 为标记绑定参数 */
    mysqli_stmt_bind_param($stmt, "s", $city);

    /* 执行查询 */
    mysqli_stmt_execute($stmt);

    /* 绑定结果变量 */
    mysqli_stmt_bind_result($stmt, $district);

    /* 获取值 */
    mysqli_stmt_fetch($stmt);

    printf("%s is in district %s\n", $city, $district);

以上示例会输出：

    Amersfoort is in district Utrecht

### 参见

- mysqli_stmt_execute() - Executes a prepared statement
- mysqli_stmt_fetch() - Fetch results from a prepared statement into the bound variables
- mysqli_stmt_bind_param() - Binds variables to a prepared statement as parameters
- mysqli_stmt_bind_result() - Binds variables to a prepared statement for result storage
- mysqli_stmt_get_result() - Gets a result set from a prepared statement as a mysqli_result object
- mysqli_stmt_close() - Closes a prepared statement

# mysqli::query

# mysqli_query

(PHP 5, PHP 7, PHP 8)

mysqli::query -- mysqli_query — 对数据库执行查询

### 说明

面向对象风格

public function mysqli::query(string `$query`, int `$result_mode` = `MYSQLI_STORE_RESULT`): mysqli_result|bool

过程化风格

function mysqli_query(mysqli `$mysql`, string `$query`, int `$result_mode` = `MYSQLI_STORE_RESULT`): mysqli_result|bool

对数据库执行 `query`。

警告

# Security warning: SQL injection

If the query contains any variable input then parameterized prepared statements should be used instead. Alternatively, the data must be properly formatted and all strings must be escaped using the mysqli_real_escape_string() function.

对非 DML 查询（不是 INSERT、UPDATE 或 DELETE），此函数类似于调用 mysqli_real_query() 然后调用 mysqli_use_result() 或 mysqli_store_result()。

> 注意:

> 传递给 mysqli_query() 的语句长度比服务器的 `max_allowed_packet` 长的情况下，返回的错误码不同，具体取决于使用的是 MySQL Native Driver（`mysqlnd`）还是 MySQL Client Library（`libmysqlclient`）。行为如下：

> - Linux 上 `mysqlnd` 返回错误码 1153。错误消息表示为 got a packet bigger than `max_allowed_packet` bytes。

> - Windows 上 `mysqlnd` 返回错误码 2006。错误消息表示为 server has gone away。

> - `libmysqlclient` 在所有平台返回错误码 2006。错误消息表示为 server has gone away。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`query`

  查询字符串。

`result_mode`

  The result mode can be one of 3 constants indicating how the result will be returned from the MySQL server.

  `MYSQLI_STORE_RESULT`（默认）——返回带有缓冲结果集的 mysqli_result 对象。

  `MYSQLI_USE_RESULT` - returns a mysqli_result object with unbuffered result set. As long as there are pending records waiting to be fetched, the connection line will be busy and all subsequent calls will return error `Commands out of sync`. To avoid the error all records must be fetched from the server or the result set must be discarded by calling mysqli_free_result().

  `MYSQLI_ASYNC`（适用于 mysqlnd）——执行异步查询且并不立即返回结果。然后使用 mysqli_poll() 从此类查询中获取结果。与 `MYSQLI_STORE_RESULT` 或 `MYSQLI_USE_RESULT` 常量结合使用。

### 返回值

失败时返回 `false`。对于生成结果集的成功查询，比如 `SELECT, SHOW, DESCRIBE` 或 `EXPLAIN`，mysqli_query() 将返回 mysqli_result 对象。对其它成功查询，mysqli_query() 将返回 `true`。

### 错误／异常

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.

### 示例

示例 #1 mysqli::query() 示例

面向对象风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Create table doesn't return a resultset */
    $mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City");
    printf("Table myCity successfully created.\n");

    /* Select queries return a resultset */
    $result = $mysqli->query("SELECT Name FROM City LIMIT 10");
    printf("Select returned %d rows.\n", $result->num_rows);

    /* If we have to retrieve large amount of data we use MYSQLI_USE_RESULT */
    $result = $mysqli->query("SELECT * FROM City", MYSQLI_USE_RESULT);

    /* Note, that we can't execute any functions which interact with the
        server until all records have been fully retrieved or the result
        set was closed. All calls will return an 'out of sync' error */
    $mysqli->query("SET @a:='this will not work'");

过程化风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Create table doesn't return a resultset */
    mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City");
    printf("Table myCity successfully created.\n");

    /* Select queries return a resultset */
    $result = mysqli_query($link, "SELECT Name FROM City LIMIT 10");
    printf("Select returned %d rows.\n", mysqli_num_rows($result));

    /* If we have to retrieve large amount of data we use MYSQLI_USE_RESULT */
    $result = mysqli_query($link, "SELECT * FROM City", MYSQLI_USE_RESULT);

    /* Note, that we can't execute any functions which interact with the
        server until all records have been fully retrieved or the result
        set was closed. All calls will return an 'out of sync' error */
    mysqli_query($link, "SET @a:='this will not work'");

以上示例的输出类似于：

    Table myCity successfully created.
    Select returned 10 rows.

    Fatal error: Uncaught mysqli_sql_exception: Commands out of sync; you can't run this command now in...

### 参见

- mysqli_execute_query() - Prepares, binds parameters, and executes SQL statement
- mysqli_real_query() - 执行一个mysql查询
- mysqli_multi_query() - 在数据库上执行一个或多个查询
- mysqli_prepare() - 预处理执行 SQL
- mysqli_free_result() - Frees the memory associated with a result

# mysqli::real_connect

# mysqli_real_connect

(PHP 5, PHP 7, PHP 8)

mysqli::real_connect -- mysqli_real_connect — 建立一个 MySQL 服务器连接

### 说明

面向对象风格

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

过程化风格

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

建立与 MySQL 数据库服务器的连接，并可设置连接选项。

与 mysqli_connect() 的不同点：

- mysqli_real_connect() 需要一个有效的对象，该对象必须通过 mysqli_init() 创建。

- 可以使用 mysqli_options() 设置各种连接设置。

- 提供 `flags` 参数。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`hostname`

  可以使用域名、IP 地址。如果传递 `null`，值将从 mysqli.default_host 中检索。如果可能，将使用管道代替 TCP/IP 协议。如果同时提供主机名和端口号，则使用 TCP/IP 协议，例如 `localhost:3308`。

`username`

  MySQL 登录用户名，为 `null` 时则假设是基于 mysqli.default_user ini 选项的用户名。

`password`

  MySQL 密码，为 `null` 时则假设是基于 mysqli.default_pw ini 选项的密码。

`database`

  执行查询语句的默认数据库或为 `null`。

`port`

  MySQL 服务器的端口，为 `null` 时则假设是基于 mysqli.default_port ini 选项的端口。

`socket`

  指定使用的 socket 或者命名通道，为 `null` 时则假设是基于 mysqli.default_socket ini 选项的套接字。

  > 注意:

  > 指定 `socket` 参数并不能说明要采用何种方式连接数据库。 连接数据的方式由 `hostname` 设定。

`flags`

  这里可以设置连接参数：

  Supported flags
  Name | Description
  --- | ---
  `MYSQLI_CLIENT_COMPRESS` | 使用压缩协议
  `MYSQLI_CLIENT_FOUND_ROWS` | 返回语句匹配的行数，而不是影响的行数
  `MYSQLI_CLIENT_IGNORE_SPACE` | 允许函数名称后有空格，这将使所有的函数名称成为保留字。
  `MYSQLI_CLIENT_INTERACTIVE` | 在关闭连接之前允许等待 `interactive_timeout` 秒， 他替代 `wait_timeout` 设定。
  `MYSQLI_CLIENT_SSL` | 使用 SSL 加密
  `MYSQLI_CLIENT_SSL_DONT_VERIFY_SERVER_CERT` | 跟 `MYSQLI_CLIENT_SSL` 类似，但禁用对提供的 SSL 证书的验证。这仅适用于使用 MySQL Native Driver 和 MySQL 5.6 及其后续版本的安装。

  > 注意:

  > 从安全角度考虑，在 PHP 中不可以使用 `MULTI_STATEMENT`， 若要执行多查询语句，请使用 mysqli_multi_query()。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
7.4.0 | 所有的参数都可为 null。

### 示例

示例 #1 mysqli::real_connect() 示例

面向对象风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_init();

    $mysqli->options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0');
    $mysqli->options(MYSQLI_OPT_CONNECT_TIMEOUT, 5);

    $mysqli->real_connect('localhost', 'my_user', 'my_password', 'my_db', null, null, MYSQLI_CLIENT_COMPRESS|MYSQLI_CLIENT_FOUND_ROWS);

    echo 'Success... ' . $mysqli->host_info . "\n";

面向对象风格 when extending mysqli class

    <?php

    class foo_mysqli extends mysqli {
        public function __construct($host, $user, $pass, $db)
        {
            parent::__construct();

            parent::options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0');
            parent::options(MYSQLI_OPT_CONNECT_TIMEOUT, 5);

            parent::real_connect($host, $user, $pass, $db, null, null, MYSQLI_CLIENT_COMPRESS|MYSQLI_CLIENT_FOUND_ROWS);
        }
    }

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

    echo 'Success... ' . $db->host_info . "\n";

过程化风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_init();

    mysqli_options($link, MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0');
    mysqli_options($link, MYSQLI_OPT_CONNECT_TIMEOUT, 5);

    mysqli_real_connect($link, 'localhost', 'my_user', 'my_password', 'my_db', null, null, MYSQLI_CLIENT_COMPRESS|MYSQLI_CLIENT_FOUND_ROWS);

    echo 'Success... ' . mysqli_get_host_info($link) . "\n";

以上示例会输出：

    Success... MySQL host info: localhost via TCP/IP

### 注释

> 注意: MySQLnd 总是使用服务器的默认字符集。此字符集在连接握手／认证时发送，并被 mysqlnd 使用。Libmysqlclient 使用 my.cnf 中的默认字符集或者由在调用 mysqli_init() 之后，mysqli_real_connect() 之前先调用 mysqli_options() 来指定。

### 参见

- mysqli_connect() - 别名 mysqli::__construct
- mysqli_init() - 初始化 MySQLi 并返回用于 mysqli_real_connect() 的对象
- mysqli_options() - 设置选项
- mysqli_ssl_set() - 用于使用 SSL 建立安全连接
- mysqli_close() - 关闭先前打开的数据库连接

# mysqli::real_escape_string

# mysqli_real_escape_string

(PHP 5, PHP 7, PHP 8)

mysqli::real_escape_string -- mysqli_real_escape_string — 根据当前连接的字符集，对于 SQL 语句中的特殊字符进行转义

### 说明

面向对象风格

public function mysqli::real_escape_string(string `$string`): string

过程化风格

function mysqli_real_escape_string(mysqli `$mysql`, string `$string`): string

此函数用于创建可在 SQL 语句中使用的合法 SQL 字符串。考虑到连接的当前字符集，对指定的字符串进行编码以生成转义的 SQL 字符串。

警告

# 安全：默认字符集

字符集必须在服务器级别设置，或者使用 API 函数 mysqli_set_charset() 影响 mysqli_real_escape_string()。参阅字符集的概念（concepts）部分。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`string`

  需要进行转义的字符串。

  会被进行转义的字符包括：`NUL (ASCII 0)`、 `\n`、`\r`、`\`、 `'`、`"` 和 ``CTRL`+`Z``。

### 返回值

返回转义后的字符串。

### 示例

示例 #1 mysqli::real_escape_string() 示例

面向对象风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $city = "'s-Hertogenbosch";

    /* 对 $city 转义，此查询运行正常 */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'",
        $mysqli->real_escape_string($city));
    $result = $mysqli->query($query);
    printf("Select returned %d rows.\n", $result->num_rows);

    /* 未转义 $city，此查询运行失败 */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'", $city);
    $result = $mysqli->query($query);

过程化风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $city = "'s-Hertogenbosch";

    /* 对 $city 转义，此查询运行正常 */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'",
        mysqli_real_escape_string($mysqli, $city));
    $result = mysqli_query($mysqli, $query);
    printf("Select returned %d rows.\n", mysqli_num_rows($result));

    /* 未转义 $city，此查询运行失败 */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'", $city);
    $result = mysqli_query($mysqli, $query);

以上示例的输出类似于：

    Select returned 1 rows.

    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...

### 参见

- mysqli_set_charset() - 设置客户端字符集

# mysqli::real_query

# mysqli_real_query

(PHP 5, PHP 7, PHP 8)

mysqli::real_query -- mysqli_real_query — 执行一个mysql查询

### 说明

面向对象风格

public function mysqli::real_query(string `$query`): bool

过程化风格

function mysqli_real_query(mysqli `$mysql`, string `$query`): bool

对数据库执行单条查询，其结果可以使用 mysqli_store_result() 或 mysqli_use_result() 检索或存储。

警告

# Security warning: SQL injection

If the query contains any variable input then parameterized prepared statements should be used instead. Alternatively, the data must be properly formatted and all strings must be escaped using the mysqli_real_escape_string() function.

为了确定给定的查询是否应返回结果集，参阅 mysqli_field_count()。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`query`

  查询字符串。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 参见

- mysqli_query() - 对数据库执行查询
- mysqli_store_result() - 传输上次查询的结果集
- mysqli_use_result() - Initiate a result set retrieval

# 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 — 获取异步查询的结果

### 说明

面向对象风格

public function mysqli::reap_async_query(): mysqli_result|bool

过程化风格

function mysqli_reap_async_query(mysqli `$mysql`): mysqli_result|bool

获取异步查询的结果，

> 注意:

> 仅可用于 mysqlnd。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

失败时返回 `false`。对于生成结果集的成功查询，比如 `SELECT, SHOW, DESCRIBE` 或 `EXPLAIN`，mysqli_reap_async_query() 将返回 mysqli_result 对象。对其它成功查询，mysqli_reap_async_query() 将返回 `true`。

### 错误／异常

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.

### 参见

- mysqli_poll() - 轮询连接

# mysqli::refresh

# mysqli_refresh

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::refresh -- mysqli_refresh — 刷新

警告

此函数自 PHP 8.4.0 起弃用。强烈建议不要应用此函数。

### 说明

面向对象风格

#[\Deprecated]
public function mysqli::refresh(int `$flags`): bool

过程化风格

#[\Deprecated]
function mysqli_refresh(mysqli `$mysql`, int `$flags`): bool

刷新表或者缓存，或者重置复制服务器信息。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`flags`

  使用 MySQLi 常量文档记录的 MYSQLI_REFRESH_* 常量作为刷新选项。

  参见 MySQL 官方文档：» MySQL Refresh

### 返回值

刷新成功返回 `true`，否则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | mysqli::refresh() 和 mysqli_refresh() 都已弃用。使用 `FLUSH` SQL 命令代替。

### 参见

- mysqli_poll() - 轮询连接

# mysqli::release_savepoint

# mysqli_release_savepoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::release_savepoint -- mysqli_release_savepoint — 从当前事务的保存点中移除一个命名保存点

### 说明

面向对象风格

public function mysqli::release_savepoint(string `$name`): bool

过程化风格:

function mysqli_release_savepoint(mysqli `$mysql`, string `$name`): bool

此函数等同于执行 `$mysqli->query("RELEASE SAVEPOINT `$name`");`。此函数不会触发 commit 或者 rollback。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`name`

  保存点的标识符。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- mysqli_savepoint() - 在当前事务中设置命名保存点

# mysqli::rollback

# mysqli_rollback

(PHP 5, PHP 7, PHP 8)

mysqli::rollback -- mysqli_rollback — 回滚当前事务

### 说明

面向对象风格

public function mysqli::rollback(int `$flags` = 0, ?string `$name` = `null`): bool

过程化风格

function mysqli_rollback(mysqli `$mysql`, int `$flags` = 0, ?string `$name` = `null`): bool

回滚数据库的当前事务。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`flags`

  `MYSQLI_TRANS_COR_*` 常量的位掩码。

`name`

  如果提供，则执行 `ROLLBACK/*name*/`。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `name` 现在可以为 null。

### 示例

参阅 mysqli::begin_transaction() 示例。

### 注释

> 注意:

> 此函数不支持非事务表类型（如 MyISAM 或 ISAM）。

### 参见

- mysqli_begin_transaction() - Starts a transaction
- mysqli_commit() - 提交当前事务
- mysqli_autocommit() - 打开或关闭本次数据库连接的自动命令提交事务模式
- mysqli_release_savepoint() - 从当前事务的保存点中移除一个命名保存点

# mysqli::savepoint

# mysqli_savepoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::savepoint -- mysqli_savepoint — 在当前事务中设置命名保存点

### 说明

面向对象风格

public function mysqli::savepoint(string `$name`): bool

过程化风格:

function mysqli_savepoint(mysqli `$mysql`, string `$name`): bool

此函数等同于执行 `$mysqli->query("SAVEPOINT `$name`");`

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`name`

  保存点的标识符。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- mysqli_release_savepoint() - 从当前事务的保存点中移除一个命名保存点

# mysqli::select_db

# mysqli_select_db

(PHP 5, PHP 7, PHP 8)

mysqli::select_db -- mysqli_select_db — 选择用于数据库查询的默认数据库

### 说明

面向对象风格

public function mysqli::select_db(string `$database`): bool

过程化风格

function mysqli_select_db(mysqli `$mysql`, string `$database`): bool

选择默认数据库，用于在已连接的数据库中执行查询。

> 注意:

> 此函数只能用于更改连接的默认数据库。可以在 mysqli_connect() 中使用第 4 个参数选择默认数据库。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`database`

  数据库名称

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 示例

示例 #1 mysqli::select_db() 示例

面向对象风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    /* get the name of the current default database */
    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("Default database is %s.\n", $row[0]);

    /* change default database to "world" */
    $mysqli->select_db("world");

    /* get the name of the current default database */
    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("Default database is %s.\n", $row[0]);

过程化风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "test");

    /* get the name of the current default database */
    $result = mysqli_query($link, "SELECT DATABASE()");
    $row = mysqli_fetch_row($result);
    printf("Default database is %s.\n", $row[0]);

    /* change default database to "world" */
    mysqli_select_db($link, "world");

    /* get the name of the current default database */
    $result = mysqli_query($link, "SELECT DATABASE()");
    $row = mysqli_fetch_row($result);
    printf("Default database is %s.\n", $row[0]);

以上示例会输出：

    Default database is test.
    Default database is world.

### 参见

- mysqli_connect() - 别名 mysqli::__construct
- mysqli_real_connect() - 建立一个 MySQL 服务器连接

# mysqli::set_charset

# mysqli_set_charset

(PHP 5 >= 5.0.5, PHP 7, PHP 8)

mysqli::set_charset -- mysqli_set_charset — 设置客户端字符集

### 说明

面向对象风格

public function mysqli::set_charset(string `$charset`): bool

过程化风格

function mysqli_set_charset(mysqli `$mysql`, string `$charset`): bool

设置客户端与数据库间传输数据时所用的字符集。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`charset`

  所需的字符集。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 示例

示例 #1 mysqli::set_charset() 示例

面向对象风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    printf("Initial character set: %s\n", $mysqli->character_set_name());

    /* change character set to utf8mb4 */
    $mysqli->set_charset("utf8mb4");

    printf("Current character set: %s\n", $mysqli->character_set_name());

过程化风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect('localhost', 'my_user', 'my_password', 'test');

    printf("Initial character set: %s\n", mysqli_character_set_name($link));

    /* change character set to utf8mb4 */
    mysqli_set_charset($link, "utf8mb4");

    printf("Current character set: %s\n", mysqli_character_set_name($link));

以上示例的输出类似于：

    Initial character set: latin1
    Current character set: utf8mb4

### 注释

> 注意:

> 这是改变字符集的首选方法，不推荐使用 mysqli_query() 来设置（如 `SET NAMES utf8`）。有关详细信息，请参阅 MySQL 字符集概念部分。

### 参见

- mysqli_character_set_name() - 返回当前数据库连接的字符编码
- mysqli_real_escape_string() - 根据当前连接的字符集，对于 SQL 语句中的特殊字符进行转义
- MySQL 字符集概念
- » MySQL 支持的字符集列表

# mysqli::$sqlstate

# mysqli_sqlstate

(PHP 5, PHP 7, PHP 8)

mysqli::$sqlstate -- mysqli_sqlstate — 返回上一次 MySQL 操作的 SQLSTATE 错误

### 说明

面向对象风格

string $mysqli->sqlstate;

过程化风格

function mysqli_sqlstate(mysqli `$mysql`): string

返回包含 SQLSTATE 错误码的字符串，表示上次的错误。错误码由 5 个字符构成。`'00000'` 表示没有发生错误。错误码由 ANSI SQL 和 ODBC 定义。对可能的值列表，参见 » http://dev.mysql.com/doc/mysql/en/error-handling.html。

> 注意:

> 需要注意的是，并不是所有的 MySQL 错误都映射到了 SQLSTATE，未映射的错误消息使用 `HY000`（常规错误）表示。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

返回包含 SQLSTATE 错误码的字符串，表示上次的错误。 错误码由 5 个字符构成。`'00000'` 表示没有错误。

### 示例

示例 #1 $mysqli->sqlstate 示例

面向对象风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* City 表已经存在，所以会遇到一个错误 */
    try {
        $mysqli->query("CREATE TABLE City (ID INT, Name VARCHAR(30))");
    } catch (mysqli_sql_exception) {
        printf("Error - SQLSTATE %s.\n", $mysqli->sqlstate);
    }

过程化风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* City 表已经存在，所以会遇到一个错误 */
    try {
        mysqli_query($link, "CREATE TABLE City (ID INT, Name VARCHAR(30))");
    } catch (mysqli_sql_exception) {
        printf("Error - SQLSTATE %s.\n", mysqli_sqlstate($link));
    }

以上示例会输出：

    Error - SQLSTATE 42S01.

### 参见

- mysqli_errno() - 返回最近函数调用的错误代码
- mysqli_error() - Returns a string description of the last error

# mysqli::ssl_set

# mysqli_ssl_set

(PHP 5, PHP 7, PHP 8)

mysqli::ssl_set -- mysqli_ssl_set — 用于使用 SSL 建立安全连接

### 说明

面向对象风格

public function mysqli::ssl_set(
?string `$key`,
?string `$certificate`,
?string `$ca_certificate`,
?string `$ca_path`,
?string `$cipher_algos`
): true

过程化风格

function mysqli_ssl_set(
mysqli `$mysql`,
?string `$key`,
?string `$certificate`,
?string `$ca_certificate`,
?string `$ca_path`,
?string `$cipher_algos`
): true

用于使用 SSL 建立安全连接。必须在 mysqli_real_connect() 之前调用。除非启用 OpenSSL 支持，否则此函数不执行任何操作。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`key`

  密钥文件的路径

`certificate`

  证书文件的路径

`ca_certificate`

  签发机构的证书文件路径

`ca_path`

  指向一个目录的路径， 该目录下存放的是受信任的 CA 机构证书 PEM 格式的文件。

`cipher_algos`

  SSL 加密允许使用的算法清单

### 返回值

总是返回 `true`。如果 SSL 的设置有误，那么当尝试连接时，mysqli_real_connect() 将会返回错误。

### 参见

- mysqli_options() - 设置选项
- mysqli_real_connect() - 建立一个 MySQL 服务器连接

# mysqli::stat

# mysqli_stat

(PHP 5, PHP 7, PHP 8)

mysqli::stat -- mysqli_stat — 获取当前系统状态信息

### 说明

面向对象风格

public function mysqli::stat(): string|false

过程化风格

function mysqli_stat(mysqli `$mysql`): string|false

mysqli_stat() 返回字符串，其中包含类似于“mysqladmin status”命令提供的信息。包含以秒为单位的正常运行时间、运行中的线程数、问题数、重新加载数以及打开的表数量。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

描述服务器状态的字符串，发生错误则为 `false`。

### 示例

示例 #1 mysqli::stat() 示例

面向对象风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    printf("System status: %s\n", $mysqli->stat());

过程化风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    printf("System status: %s\n", mysqli_stat($link));

以上示例会输出：

    System status: 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

### 参见

- mysqli_get_server_info() - 返回 MySQL 服务器的版本号

# mysqli::stmt_init

# mysqli_stmt_init

(PHP 5, PHP 7, PHP 8)

mysqli::stmt_init -- mysqli_stmt_init — 初始化语句并返回用于 mysqli_stmt_prepare（调用）的对象

### 说明

面向对象风格

public function mysqli::stmt_init(): mysqli_stmt|false

过程化风格

function mysqli_stmt_init(mysqli `$mysql`): mysqli_stmt|false

分配并初始化适合 mysqli_stmt_prepare() 的语句对象。

> 注意:

> 在调用 mysqli_stmt_prepare() 之前，对其它 mysqli_stmt 函数的后续调用都会失败。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

返回对象。

### 参见

- mysqli_stmt_prepare() - Prepares an SQL statement for execution

# mysqli::store_result

# mysqli_store_result

(PHP 5, PHP 7, PHP 8)

mysqli::store_result -- mysqli_store_result — 传输上次查询的结果集

### 说明

面向对象风格

public function mysqli::store_result(int `$mode` = 0): mysqli_result|false

过程化风格

function mysqli_store_result(mysqli `$mysql`, int `$mode` = 0): mysqli_result|false

传输由 `mysql` 参数表示的连接上的上一次查询的结果集，可在 mysqli_data_seek() 函数中使用。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`mode`

  想要设置的选项。自 PHP 8.1 起，此参数无效。可以是下列中的某一值：

  有效选项
  名称 | 说明
  --- | ---
  `MYSQLI_STORE_RESULT_COPY_DATA` | 将结果从内部 mysqlnd 缓冲区复制到 PHP 变量中。默认 mysqlnd 采取引用策略来避免在内容中复制多份同样的结果集。例如，对于包含了很多小行的结果集，复制方法可以减少整体内存使用，因为保存结果的 PHP 变量可能会更早释放。（此选项适用于 mysqlnd 驱动）。

### 返回值

返回缓冲的结果对象，如果发生错误则返回 `false`。

> 注意:

> 如果查询没有返回结果集（例如，执行 INSERT 语句查询），mysqli_store_result() 会返回 `false`。如果读取结果集失败，也会返回 `false`。如果通过检查 mysqli_error() 是否返回非空字符串、mysqli_error() 或 mysqli_field_count() 是否返回了非零值来检查是否有错误。此函数在成功调用 mysqli_query() 后返回 `false` 的一个可能原因是结果集太大（无法分配内存）。如果 mysqli_field_count() 返回非零值，语句应该产生非空结果集。

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 现在弃用传递 `mode` 参数。该参数自 PHP 8.1.0 起不再有效。

### 示例

参阅 mysqli_multi_query()。

### 注释

> 注意:

> 执行查询之后，使用 mysqli_free_result() 函数来释放结果集所占用的内存，是一个很有用的实战经验。尤其是当使用 mysqli_store_result() 函数来转移数量较大的结果集的时候，释放结果集内存的操作尤为重要。

### 参见

- mysqli_real_query() - 执行一个mysql查询
- mysqli_use_result() - Initiate a result set retrieval

# mysqli::$thread_id

# mysqli_thread_id

(PHP 5, PHP 7, PHP 8)

mysqli::$thread_id -- mysqli_thread_id — 返回当前连接的线程 ID

### 说明

面向对象风格

int $mysqli->thread_id;

过程化风格

function mysqli_thread_id(mysqli `$mysql`): int

mysqli_thread_id() 函数返回当前连接的线程 ID，然后可以使用 mysqli_kill() 函数将其终止。如果连接中断且使用 mysqli_ping() 重新连接，线程 ID 会不同。所以，仅在需要时获取线程 ID。

> 注意:

> 线程 ID 是连接的基础上分配的。因此，如果连接断开然后重新建立，将分配新的线程 ID。

> 要终止正在查询的命令，可以使用 SQL 命令 `KILL QUERY processid`。

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

返回当前连接的线程 ID。

### 示例

示例 #1 $mysqli->thread_id 示例

面向对象风格

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* 检查连接 */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    /* 确定线程 ID */
    $thread_id = $mysqli->thread_id;

    /* 杀掉连接 */
    $mysqli->kill($thread_id);

    /* 这句代码应该会报错 */
    if (!$mysqli->query("CREATE TABLE myCity LIKE City")) {
        printf("Error: %s\n", $mysqli->error);
        exit;
    }

    /* 关闭连接 */
    $mysqli->close();
    ?>

过程化风格

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* 检查连接 */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    /* 确定线程 ID */
    $thread_id = mysqli_thread_id($link);

    /* 杀掉连接 */
    mysqli_kill($link, $thread_id);

    /* 这句代码应该会报错 */
    if (!mysqli_query($link, "CREATE TABLE myCity LIKE City")) {
        printf("Error: %s\n", mysqli_error($link));
        exit;
    }

    /* close connection */
    mysqli_close($link);
    ?>

以上示例会输出：

    Error: MySQL server has gone away

### 参见

- mysqli_kill() - 让服务器杀死一个 MySQL 线程

# mysqli::thread_safe

# mysqli_thread_safe

(PHP 5, PHP 7, PHP 8)

mysqli::thread_safe -- mysqli_thread_safe — 返回是否线程安全

### 说明

面向对象风格

public function mysqli::thread_safe(): bool

过程化风格

function mysqli_thread_safe(): bool

告知本数据库客户端库是否编译为线程安全的。

### 参数

此函数没有参数。

### 返回值

如果客户端线程安全为 `true`，否则为 `false`。

# mysqli::use_result

# mysqli_use_result

(PHP 5, PHP 7, PHP 8)

mysqli::use_result -- mysqli_use_result — Initiate a result set retrieval

### 说明

面向对象风格

public function mysqli::use_result(): mysqli_result|false

过程化风格

function mysqli_use_result(mysqli `$mysql`): mysqli_result|false

Used to initiate the retrieval of a result set from the last query executed using the mysqli_real_query() function on the database connection.

Either this or the mysqli_store_result() function must be called before the results of a query can be retrieved, and one or the other must be called to prevent the next query on that database connection from failing.

> 注意:

> The mysqli_use_result() function does not transfer the entire result set from the database and hence cannot be used functions such as mysqli_data_seek() to move to a particular row within the set. To use this functionality, the result set must be stored using mysqli_store_result(). One should not use mysqli_use_result() if a lot of processing on the client side is performed, since this will tie up the server and prevent other threads from updating any tables from which the data is being fetched.

### 参数

此函数没有参数。

### 返回值

Returns an unbuffered result object or `false` if an error occurred.

### 错误／异常

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.

### 示例

示例 #1 mysqli::use_result() example

面向对象风格

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    $query  = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* execute multi query */
    if ($mysqli->multi_query($query)) {
        do {
            /* store first result set */
            if ($result = $mysqli->use_result()) {
                while ($row = $result->fetch_row()) {
                    printf("%s\n", $row[0]);
                }
                $result->close();
            }
            /* print divider */
            if ($mysqli->more_results()) {
                printf("-----------------\n");
            }
        } while ($mysqli->next_result());
    }

    /* close connection */
    $mysqli->close();
    ?>

过程化风格

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    $query  = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* execute multi query */
    if (mysqli_multi_query($link, $query)) {
        do {
            /* store first result set */
            if ($result = mysqli_use_result($link)) {
                while ($row = mysqli_fetch_row($result)) {
                    printf("%s\n", $row[0]);
                }
                mysqli_free_result($result);
            }
            /* print divider */
            if (mysqli_more_results($link)) {
                printf("-----------------\n");
            }
        } while (mysqli_next_result($link));
    }

    /* close connection */
    mysqli_close($link);
    ?>

以上示例会输出：

    my_user@localhost
    -----------------
    Amersfoort
    Maastricht
    Dordrecht
    Leiden
    Haarlemmermeer

### 参见

- mysqli_real_query() - 执行一个mysql查询
- mysqli_store_result() - 传输上次查询的结果集

# mysqli::$warning_count

# mysqli_warning_count

(PHP 5, PHP 7, PHP 8)

mysqli::$warning_count -- mysqli_warning_count — Returns the number of warnings generated by the most recently executed query

### 说明

面向对象风格

int $mysqli->warning_count;

过程化风格

function mysqli_warning_count(mysqli `$mysql`): int

Returns the number of warnings generated by the most recently executed query.

> 注意: For retrieving warning messages the following SQL command can be used: `SHOW WARNINGS [limit row_count]`.

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。

### 返回值

Number of warnings or zero if there are no warnings.

### 示例

示例 #1 $mysqli->warning_count example

面向对象风格

    <?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]);
    }

过程化风格

    <?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]);
    }

以上示例会输出：

    Warning (1365): Division by 0

### 参见

- mysqli_errno() - 返回最近函数调用的错误代码
- mysqli_error() - Returns a string description of the last error
- mysqli_sqlstate() - 返回上一次 MySQL 操作的 SQLSTATE 错误

## 目录

- mysqli::$affected_rows — Gets the number of affected rows in a previous MySQL operation
- mysqli::autocommit — 打开或关闭本次数据库连接的自动命令提交事务模式
- mysqli::begin_transaction — Starts a transaction
- mysqli::change_user — Changes the user of the database connection
- mysqli::character_set_name — 返回当前数据库连接的字符编码
- mysqli::close — 关闭先前打开的数据库连接
- mysqli::commit — 提交当前事务
- mysqli::$connect_errno — Returns the error code from last connect call
- mysqli::$connect_error — Returns a description of the last connection error
- mysqli::__construct — Open a new connection to the MySQL server
- mysqli::debug — Performs debugging operations
- mysqli::dump_debug_info — 将调试信息输出到日志
- mysqli::$errno — 返回最近函数调用的错误代码
- mysqli::$error — Returns a string description of the last error
- mysqli::$error_list — Returns a list of errors from the last command executed
- mysqli::execute_query — Prepares, binds parameters, and executes SQL statement
- mysqli::$field_count — Returns the number of columns for the most recent query
- mysqli::get_charset — Returns a character set object
- mysqli::$client_info — 获取 MySQL 客户端信息
- mysqli::$client_version — 作为整数返回 MySQL 客户端的版本
- mysqli::get_connection_stats — 返回客户端连接的统计数据
- mysqli::$host_info — 返回表述使用的连接类型的字符串
- mysqli::$protocol_version — 返回 MySQL 协议使用的版本号
- mysqli::$server_info — 返回 MySQL 服务器的版本号
- mysqli::$server_version — 作为一个整数返回MySQL服务器的版本
- mysqli::get_warnings — Get result of SHOW WARNINGS
- mysqli::$info — 返回最近执行的 SQL 语句的信息
- mysqli::init — 初始化 MySQLi 并返回用于 mysqli_real_connect() 的对象
- mysqli::$insert_id — 返回上次查询为 AUTO_INCREMENT 列生成的值
- mysqli::kill — 让服务器杀死一个 MySQL 线程
- mysqli::more_results — 检查批量查询中是否还有查询结果
- mysqli::multi_query — 在数据库上执行一个或多个查询
- mysqli::next_result — 为读取 multi_query 执行之后的下一个结果集做准备
- mysqli::options — 设置选项
- mysqli::ping — ping 一个连接，或者如果连接处于断开状态，重新连接
- mysqli::poll — 轮询连接
- mysqli::prepare — 预处理执行 SQL
- mysqli::query — 对数据库执行查询
- mysqli::real_connect — 建立一个 MySQL 服务器连接
- mysqli::real_escape_string — 根据当前连接的字符集，对于 SQL 语句中的特殊字符进行转义
- mysqli::real_query — 执行一个mysql查询
- mysqli::reap_async_query — 获取异步查询的结果
- mysqli::refresh — 刷新
- mysqli::release_savepoint — 从当前事务的保存点中移除一个命名保存点
- mysqli::rollback — 回滚当前事务
- mysqli::savepoint — 在当前事务中设置命名保存点
- mysqli::select_db — 选择用于数据库查询的默认数据库
- mysqli::set_charset — 设置客户端字符集
- mysqli::$sqlstate — 返回上一次 MySQL 操作的 SQLSTATE 错误
- mysqli::ssl_set — 用于使用 SSL 建立安全连接
- mysqli::stat — 获取当前系统状态信息
- mysqli::stmt_init — 初始化语句并返回用于 mysqli_stmt_prepare（调用）的对象
- mysqli::store_result — 传输上次查询的结果集
- mysqli::$thread_id — 返回当前连接的线程 ID
- mysqli::thread_safe — 返回是否线程安全
- mysqli::use_result — Initiate a result set retrieval
- mysqli::$warning_count — Returns the number of warnings generated by the most recently executed query

# mysqli_stmt 类

(PHP 5, PHP 7, PHP 8)

## 简介

代表预处理的语句。

## 类摘要

class mysqli_stmt {
/* 属性 */
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;
/* 方法 */
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
}

## 属性

id

  存储语句 ID。

# mysqli_stmt::$affected_rows

# mysqli_stmt_affected_rows

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$affected_rows -- mysqli_stmt_affected_rows — Returns the total number of rows changed, deleted, inserted, or matched by the last statement executed

### 说明

面向对象风格

int|string $mysqli_stmt->affected_rows;

过程化风格

function mysqli_stmt_affected_rows(mysqli_stmt `$statement`): int|string

Returns the number of rows affected by `INSERT`, `UPDATE`, or `DELETE` query. Works like mysqli_stmt_num_rows() for `SELECT` statements.

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。

### 返回值

An integer greater than zero indicates the number of rows affected or retrieved. Zero indicates that no records were updated for an `UPDATE` statement, no rows matched the `WHERE` clause in the query or that no query has yet been executed. `-1` indicates that the query returned an error or that, for a `SELECT` query, mysqli_stmt_affected_rows() was called prior to calling mysqli_stmt_store_result().

> 注意:

> If the number of affected rows is greater than maximum PHP int value, the number of affected rows will be returned as a string value.

### 示例

示例 #1 mysqli_stmt_affected_rows() example

面向对象风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* create temp table */
    $mysqli->query("CREATE TEMPORARY TABLE myCountry LIKE Country");

    $query = "INSERT INTO myCountry SELECT * FROM Country WHERE Code LIKE ?";

    /* prepare statement */
    $stmt = $mysqli->prepare($query);

    /* Bind variable for placeholder */
    $code = 'A%';
    $stmt->bind_param("s", $code);

    /* execute statement */
    $stmt->execute();

    printf("Rows inserted: %d\n", $stmt->affected_rows);

过程化风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* create temp table */
    mysqli_query($link, "CREATE TEMPORARY TABLE myCountry LIKE Country");

    $query = "INSERT INTO myCountry SELECT * FROM Country WHERE Code LIKE ?";

    /* prepare statement */
    $stmt = mysqli_prepare($link, $query);

    /* Bind variable for placeholder */
    $code = 'A%';
    mysqli_stmt_bind_param($stmt, "s", $code);

    /* execute statement */
    mysqli_stmt_execute($stmt);

    printf("Rows inserted: %d\n", mysqli_stmt_affected_rows($stmt));

以上示例会输出：

    Rows inserted: 17

### 参见

- mysqli_stmt_num_rows() - Returns the number of rows fetched from the server
- mysqli_stmt_store_result() - Stores a result set in an internal buffer

# mysqli_stmt::attr_get

# mysqli_stmt_attr_get

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::attr_get -- mysqli_stmt_attr_get — Used to get the current value of a statement attribute

### 说明

面向对象风格

public function mysqli_stmt::attr_get(int `$attribute`): int

过程化风格

function mysqli_stmt_attr_get(mysqli_stmt `$statement`, int `$attribute`): int

Gets the current value of a statement attribute.

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。
`attribute`

  The attribute that you want to get.

### 返回值

Returns the value of the attribute.

# mysqli_stmt::attr_set

# mysqli_stmt_attr_set

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::attr_set -- mysqli_stmt_attr_set — Used to modify the behavior of a prepared statement

### 说明

面向对象风格

public function mysqli_stmt::attr_set(int `$attribute`, int `$value`): bool

过程化风格

function mysqli_stmt_attr_set(mysqli_stmt `$statement`, int `$attribute`, int `$value`): bool

Used to modify the behavior of a prepared statement. This function may be called multiple times to set several attributes.

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。
`attribute`

  The attribute that you want to set. It can have one of the following values:

  Attribute values
  Character | Description
  --- | ---
  MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH | Setting to `true` causes mysqli_stmt_store_result() to update the metadata `MYSQL_FIELD->max_length` value.
  MYSQLI_STMT_ATTR_CURSOR_TYPE | Type of cursor to open for statement when mysqli_stmt_execute() is invoked. `value` can be `MYSQLI_CURSOR_TYPE_NO_CURSOR` (the default) or `MYSQLI_CURSOR_TYPE_READ_ONLY`.
  MYSQLI_STMT_ATTR_PREFETCH_ROWS | Number of rows to fetch from server at a time when using a cursor. `value` can be in the range from 1 to the maximum value of unsigned long. The default is 1. Removed as of PHP 8.4.0.

  If you use the `MYSQLI_STMT_ATTR_CURSOR_TYPE` option with `MYSQLI_CURSOR_TYPE_READ_ONLY`, a cursor is opened for the statement when you invoke mysqli_stmt_execute(). If there is already an open cursor from a previous mysqli_stmt_execute() call, it closes the cursor before opening a new one. mysqli_stmt_reset() also closes any open cursor before preparing the statement for re-execution. mysqli_stmt_free_result() closes any open cursor.

  If you open a cursor for a prepared statement, mysqli_stmt_store_result() is unnecessary.

`value`

  The value to assign to the attribute.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 参见

- » 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 — Binds variables to a prepared statement as parameters

### 说明

面向对象风格

public function mysqli_stmt::bind_param(string `$types`, mixed `&$var`, mixed `&...$vars`): bool

过程化风格

function mysqli_stmt_bind_param(
mysqli_stmt `$statement`,
string `$types`,
mixed `&$var`,
mixed `&...$vars`
): bool

Bind variables for the parameter markers in the SQL statement prepared by mysqli_prepare() or mysqli_stmt_prepare().

> 注意:

> If data size of a variable exceeds max. allowed packet size (max_allowed_packet), you have to specify `b` in `types` and use mysqli_stmt_send_long_data() to send the data in packets.

> 注意:

> Care must be taken when using mysqli_stmt_bind_param() in conjunction with call_user_func_array(). Note that mysqli_stmt_bind_param() requires parameters to be passed by reference, whereas call_user_func_array() can accept as a parameter a list of variables that can represent references or values.

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。
`types`

  A string that contains one or more characters which specify the types for the corresponding bind variables:

  Type specification chars
  Character | Description
  --- | ---
  i | corresponding variable has type int
  d | corresponding variable has type float
  s | corresponding variable has type string
  b | corresponding variable is a blob and will be sent in packets

`var`
`vars`

  The number of variables and length of string `types` must match the parameters in the statement.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 示例

示例 #1 mysqli_stmt::bind_param() example

面向对象风格

    <?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("%d row inserted.\n", $stmt->affected_rows);

    /* Clean up table CountryLanguage */
    $mysqli->query("DELETE FROM CountryLanguage WHERE Language='Bavarian'");
    printf("%d row deleted.\n", $mysqli->affected_rows);

过程化风格

    <?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("%d row inserted.\n", mysqli_stmt_affected_rows($stmt));

    /* Clean up table CountryLanguage */
    mysqli_query($link, "DELETE FROM CountryLanguage WHERE Language='Bavarian'");
    printf("%d row deleted.\n", mysqli_affected_rows($link));

以上示例会输出：

    1 row inserted.
    1 row deleted.

示例 #2 Using `...` to provide arguments

The `...` operator can be used to provide variable-length argument list, e.g. in a `WHERE IN` clause.

    <?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 (?, ?)");
    /* Using ... to provide arguments */
    $stmt->bind_param('ss', ...['DEU', 'POL']);
    $stmt->execute();
    $stmt->store_result();

    printf("%d rows found.\n", $stmt->num_rows());

以上示例会输出：

    10 rows found.

### 参见

- mysqli_stmt_bind_result() - Binds variables to a prepared statement for result storage
- mysqli_stmt_execute() - Executes a prepared statement
- mysqli_stmt_fetch() - Fetch results from a prepared statement into the bound variables
- mysqli_prepare() - 预处理执行 SQL
- mysqli_stmt_send_long_data() - Send data in blocks
- mysqli_stmt_errno() - Returns the error code for the most recent statement call
- mysqli_stmt_error() - Returns a string description for last statement error

# mysqli_stmt::bind_result

# mysqli_stmt_bind_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::bind_result -- mysqli_stmt_bind_result — Binds variables to a prepared statement for result storage

### 说明

面向对象风格

public function mysqli_stmt::bind_result(mixed `&$var`, mixed `&...$vars`): bool

过程化风格

function mysqli_stmt_bind_result(mysqli_stmt `$statement`, mixed `&$var`, mixed `&...$vars`): bool

Binds columns in the result set to variables.

When mysqli_stmt_fetch() is called to fetch data, the MySQL client/server protocol places the data for the bound columns into the specified variables `var`/`vars`.

A column can be bound or rebound at any time, even after a result set has been partially retrieved. The new binding takes effect the next time mysqli_stmt_fetch() is called.

> 注意:

> All columns must be bound after mysqli_stmt_execute() and prior to calling mysqli_stmt_fetch().

> 注意:

> Depending on column types bound variables can silently change to the corresponding PHP type.

小技巧

This function is useful for simple results. To retrieve iterable result set, or fetch each row as an array or object, use mysqli_stmt_get_result().

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。
`var`

  The first variable to be bound.

`vars`

  Further variables to be bound.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 面向对象风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* prepare statement */
    $stmt = $mysqli->prepare("SELECT Code, Name FROM Country ORDER BY Name LIMIT 5");
    $stmt->execute();

    /* bind variables to prepared statement */
    $stmt->bind_result($col1, $col2);

    /* fetch values */
    while ($stmt->fetch()) {
        printf("%s %s\n", $col1, $col2);
    }

示例 #2 过程化风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* prepare statement */
    $stmt = mysqli_prepare($link, "SELECT Code, Name FROM Country ORDER BY Name LIMIT 5");
    mysqli_stmt_execute($stmt);

    /* bind variables to prepared statement */
    mysqli_stmt_bind_result($stmt, $col1, $col2);

    /* fetch values */
    while (mysqli_stmt_fetch($stmt)) {
        printf("%s %s\n", $col1, $col2);
    }

以上示例的输出类似于：

    AFG Afghanistan
    ALB Albania
    DZA Algeria
    ASM American Samoa
    AND Andorra

### 参见

- mysqli_stmt_get_result() - Gets a result set from a prepared statement as a mysqli_result object
- mysqli_stmt_bind_param() - Binds variables to a prepared statement as parameters
- mysqli_stmt_execute() - Executes a prepared statement
- mysqli_stmt_fetch() - Fetch results from a prepared statement into the bound variables
- mysqli_prepare() - 预处理执行 SQL
- mysqli_stmt_prepare() - Prepares an SQL statement for execution

# mysqli_stmt::close

# mysqli_stmt_close

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::close -- mysqli_stmt_close — Closes a prepared statement

### 说明

面向对象风格

public function mysqli_stmt::close(): true

过程化风格

function mysqli_stmt_close(mysqli_stmt `$statement`): true

Closes a prepared statement. mysqli_stmt_close() also deallocates the statement handle. If the current statement has pending or unread results, this function cancels them so that the next query can be executed.

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | This function now always returns `true`. Previously it returned `false` on failure.

### 参见

- mysqli_prepare() - 预处理执行 SQL

# mysqli_stmt::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::__construct — Constructs a new mysqli_stmt object

### 说明

public function mysqli_stmt::__construct(mysqli `$mysql`, ?string `$query` = `null`)

This method constructs a new mysqli_stmt object.

### 参数

`link`

  A valid mysqli object.

`query`

  The query, as a string. If this parameter is `null`, then the constructor behaves identically to mysqli_stmt_init(), otherwise it behaves as per mysqli_prepare().

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `query` is now nullable.

### 参见

- mysqli_prepare() - 预处理执行 SQL
- mysqli_stmt_init() - 初始化语句并返回用于 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 — Adjusts the result pointer to an arbitrary row in the buffered result

### 说明

面向对象风格

public function mysqli_stmt::data_seek(int `$offset`): void

过程化风格

function mysqli_stmt_data_seek(mysqli_stmt `$statement`, int `$offset`): void

This function moves the result set pointer of the buffered result set to an arbitrary row specified by the `offset` parameter.

This function works only on the buffered internal result set. mysqli_stmt_store_result() must be called prior to mysqli_stmt_data_seek().

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。
`offset`

  Must be between zero and the total number of rows minus one (0.. mysqli_stmt_num_rows() - 1).

### 返回值

没有返回值。

### 示例

示例 #1 面向对象风格

    <?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();

    /* seek to row no. 400 */
    $stmt->data_seek(399);

    $stmt->fetch();

    printf("City: %s  Countrycode: %s\n", $name, $code);

示例 #2 过程化风格

    <?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);

    /* seek to row no. 400 */
    mysqli_stmt_data_seek($stmt, 399);

    mysqli_stmt_fetch($stmt);

    printf("City: %s  Countrycode: %s\n", $name, $code);

以上示例会输出：

    City: Benin City  Countrycode: NGA

### 参见

- mysqli_prepare() - 预处理执行 SQL
- mysqli_stmt_store_result() - Stores a result set in an internal buffer
- mysqli_stmt_num_rows() - Returns the number of rows fetched from the server
- mysqli_data_seek() - Adjusts the result pointer to an arbitrary row in the result

# mysqli_stmt::$errno

# mysqli_stmt_errno

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$errno -- mysqli_stmt_errno — Returns the error code for the most recent statement call

### 说明

面向对象风格

int $mysqli_stmt->errno;

过程化风格

function mysqli_stmt_errno(mysqli_stmt `$statement`): int

Returns the error code for the most recently invoked statement function that can succeed or fail.

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。

### 返回值

An error code value. Zero means no error occurred.

### 示例

示例 #1 面向对象风格

    <?php
    /* Open a connection */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %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)) {

        /* drop table */
        $mysqli->query("DROP TABLE myCountry");

        /* execute query */
        $stmt->execute();

        printf("Error: %d.\n", $stmt->errno);

        /* close statement */
        $stmt->close();
    }

    /* close connection */
    $mysqli->close();
    ?>

示例 #2 过程化风格

    <?php
    /* Open a connection */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %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)) {

        /* drop table */
        mysqli_query($link, "DROP TABLE myCountry");

        /* execute query */
        mysqli_stmt_execute($stmt);

        printf("Error: %d.\n", mysqli_stmt_errno($stmt));

        /* close statement */
        mysqli_stmt_close($stmt);
    }

    /* close connection */
    mysqli_close($link);
    ?>

以上示例会输出：

    Error: 1146.

### 参见

- mysqli_stmt_error() - Returns a string description for last statement error
- mysqli_stmt_sqlstate() - Returns SQLSTATE error from previous statement operation

# mysqli_stmt::$error

# mysqli_stmt_error

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$error -- mysqli_stmt_error — Returns a string description for last statement error

### 说明

面向对象风格

string $mysqli_stmt->error;

过程化风格

function mysqli_stmt_error(mysqli_stmt `$statement`): string

Returns a string containing the error message for the most recently invoked statement function that can succeed or fail.

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。

### 返回值

A string that describes the error. An empty string if no error occurred.

### 示例

示例 #1 面向对象风格

    <?php
    /* Open a connection */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %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)) {

        /* drop table */
        $mysqli->query("DROP TABLE myCountry");

        /* execute query */
        $stmt->execute();

        printf("Error: %s.\n", $stmt->error);

        /* close statement */
        $stmt->close();
    }

    /* close connection */
    $mysqli->close();
    ?>

示例 #2 过程化风格

    <?php
    /* Open a connection */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %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)) {

        /* drop table */
        mysqli_query($link, "DROP TABLE myCountry");

        /* execute query */
        mysqli_stmt_execute($stmt);

        printf("Error: %s.\n", mysqli_stmt_error($stmt));

        /* close statement */
        mysqli_stmt_close($stmt);
    }

    /* close connection */
    mysqli_close($link);
    ?>

以上示例会输出：

    Error: Table 'world.myCountry' doesn't exist.

### 参见

- mysqli_stmt_errno() - Returns the error code for the most recent statement call
- mysqli_stmt_sqlstate() - Returns SQLSTATE error from previous statement operation

# 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 — Returns a list of errors from the last statement executed

### 说明

面向对象风格

array $mysqli_stmt->error_list;

过程化风格

function mysqli_stmt_error_list(mysqli_stmt `$statement`): array

Returns an array of errors for the most recently invoked statement function that can succeed or fail.

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。

### 返回值

A list of errors, each as an associative array containing the errno, error, and sqlstate.

### 示例

示例 #1 面向对象风格

    <?php
    /* Open a connection */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %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)) {

        /* drop table */
        $mysqli->query("DROP TABLE myCountry");

        /* execute query */
        $stmt->execute();

        echo "Error:\n";
        print_r($stmt->error_list);

        /* close statement */
        $stmt->close();
    }

    /* close connection */
    $mysqli->close();
    ?>

示例 #2 过程化风格

    <?php
    /* Open a connection */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %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)) {

        /* drop table */
        mysqli_query($link, "DROP TABLE myCountry");

        /* execute query */
        mysqli_stmt_execute($stmt);

        echo "Error:\n";
        print_r(mysqli_stmt_error_list($stmt));

        /* close statement */
        mysqli_stmt_close($stmt);
    }

    /* close connection */
    mysqli_close($link);
    ?>

以上示例会输出：

    Error:
    Array
    (
        [0] => Array
            (
                [errno] => 1146
                [sqlstate] => 42S02
                [error] => Table 'world.myCountry' doesn't exist
            )

    )

### 参见

- mysqli_stmt_error() - Returns a string description for last statement error
- mysqli_stmt_errno() - Returns the error code for the most recent statement call
- mysqli_stmt_sqlstate() - Returns SQLSTATE error from previous statement operation

# mysqli_stmt::execute

# mysqli_stmt_execute

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::execute -- mysqli_stmt_execute — Executes a prepared statement

### 说明

面向对象风格

public function mysqli_stmt::execute(?array `$params` = `null`): bool

过程化风格

function mysqli_stmt_execute(mysqli_stmt `$statement`, ?array `$params` = `null`): bool

Executes previously prepared statement. The statement must be successfully prepared prior to execution, using either the mysqli_prepare() or mysqli_stmt_prepare() function, or by passing the second argument to mysqli_stmt::__construct().

If the statement is `UPDATE`, `DELETE`, or `INSERT`, the total number of affected rows can be determined by using the mysqli_stmt_affected_rows() function. If the query yields a result set, it can be fetched using mysqli_stmt_get_result() function or by fetching it row by row directly from the statement using mysqli_stmt_fetch() function.

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。
`params`

  An optional list array with as many elements as there are bound parameters in the SQL statement being executed. Each value is treated as a string.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The optional `params` parameter has been added.

### 示例

示例 #1 Execute a prepared statement with bound variables

面向对象风格

    <?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");

    /* Prepare an insert statement */
    $stmt = $mysqli->prepare("INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)");

    /* Bind variables to parameters */
    $stmt->bind_param("sss", $val1, $val2, $val3);

    $val1 = 'Stuttgart';
    $val2 = 'DEU';
    $val3 = 'Baden-Wuerttemberg';

    /* Execute the statement */
    $stmt->execute();

    $val1 = 'Bordeaux';
    $val2 = 'FRA';
    $val3 = 'Aquitaine';

    /* Execute the statement */
    $stmt->execute();

    /* Retrieve all rows from myCity */
    $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]);
    }

过程化风格

    <?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");

    /* Prepare an insert statement */
    $stmt = mysqli_prepare($link, "INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)");

    /* Bind variables to parameters */
    mysqli_stmt_bind_param($stmt, "sss", $val1, $val2, $val3);

    $val1 = 'Stuttgart';
    $val2 = 'DEU';
    $val3 = 'Baden-Wuerttemberg';

    /* Execute the statement */
    mysqli_stmt_execute($stmt);

    $val1 = 'Bordeaux';
    $val2 = 'FRA';
    $val3 = 'Aquitaine';

    /* Execute the statement */
    mysqli_stmt_execute($stmt);

    /* Retrieve all rows from myCity */
    $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]);
    }

以上示例会输出：

    Stuttgart (DEU,Baden-Wuerttemberg)
    Bordeaux (FRA,Aquitaine)

示例 #2 Execute a prepared statement with an array of values

面向对象风格

    <?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');

    /* Prepare an insert statement */
    $stmt = $mysqli->prepare('INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)');

    /* Execute the statement */
    $stmt->execute(['Stuttgart', 'DEU', 'Baden-Wuerttemberg']);

    /* Retrieve all rows from myCity */
    $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]);
    }

过程化风格

    <?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');

    /* Prepare an insert statement */
    $stmt = mysqli_prepare($link, 'INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)');

    /* Execute the statement */
    mysqli_stmt_execute($stmt, ['Stuttgart', 'DEU', 'Baden-Wuerttemberg']);

    /* Retrieve all rows from myCity */
    $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]);
    }

以上示例会输出：

    Stuttgart (DEU,Baden-Wuerttemberg)

### 参见

- mysqli_execute_query() - Prepares, binds parameters, and executes SQL statement
- mysqli_prepare() - 预处理执行 SQL
- mysqli_stmt_bind_param() - Binds variables to a prepared statement as parameters
- mysqli_stmt_get_result() - Gets a result set from a prepared statement as a mysqli_result object

# mysqli_stmt::fetch

# mysqli_stmt_fetch

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::fetch -- mysqli_stmt_fetch — Fetch results from a prepared statement into the bound variables

### 说明

面向对象风格

public function mysqli_stmt::fetch(): ?bool

过程化风格

function mysqli_stmt_fetch(mysqli_stmt `$statement`): ?bool

Fetch the result from a prepared statement into the variables bound by mysqli_stmt_bind_result().

> 注意:

> Note that all columns must be bound by the application before calling mysqli_stmt_fetch().

> 注意:

> Data is transferred unbuffered without calling mysqli_stmt_store_result() which can decrease performance (but reduces memory cost).

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。

### 返回值

返回值
Value | Description
--- | ---
`true` | Success. Data has been fetched
`false` | Error occurred
`null` | No more rows/data exists or data truncation occurred

### 错误／异常

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.

### 示例

示例 #1 面向对象风格

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 150,5";

    if ($stmt = $mysqli->prepare($query)) {

        /* execute statement */
        $stmt->execute();

        /* bind result variables */
        $stmt->bind_result($name, $code);

        /* fetch values */
        while ($stmt->fetch()) {
            printf ("%s (%s)\n", $name, $code);
        }

        /* close statement */
        $stmt->close();
    }

    /* close connection */
    $mysqli->close();
    ?>

示例 #2 过程化风格

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %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)) {

        /* execute statement */
        mysqli_stmt_execute($stmt);

        /* bind result variables */
        mysqli_stmt_bind_result($stmt, $name, $code);

        /* fetch values */
        while (mysqli_stmt_fetch($stmt)) {
            printf ("%s (%s)\n", $name, $code);
        }

        /* close statement */
        mysqli_stmt_close($stmt);
    }

    /* close connection */
    mysqli_close($link);
    ?>

以上示例会输出：

    Rockford (USA)
    Tallahassee (USA)
    Salinas (USA)
    Santa Clarita (USA)
    Springfield (USA)

### 参见

- mysqli_prepare() - 预处理执行 SQL
- mysqli_stmt_errno() - Returns the error code for the most recent statement call
- mysqli_stmt_error() - Returns a string description for last statement error
- mysqli_stmt_bind_result() - Binds variables to a prepared statement for result storage

# mysqli_stmt::$field_count

# mysqli_stmt_field_count

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$field_count -- mysqli_stmt_field_count — Returns the number of columns in the given statement

### 说明

面向对象风格

int $mysqli_stmt->field_count;

过程化风格

function mysqli_stmt_field_count(mysqli_stmt `$statement`): int

Returns the number of columns in the prepared statement.

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。

### 返回值

Returns an integer representing the number of columns.

### 示例

示例 #1 面向对象风格

    <?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("Value of column number %d is %s", $i, $row[$i]);
    }

示例 #2 过程化风格

    <?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("Value of column number %d is %s", $i, $row[$i]);
    }

以上示例的输出类似于：

    Value of column number 0 is France

### 参见

- mysqli_stmt_num_rows() - Returns the number of rows fetched from the server

# mysqli_stmt::free_result

# mysqli_stmt_free_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::free_result -- mysqli_stmt_free_result — Frees stored result memory for the given statement handle

### 说明

面向对象风格

public function mysqli_stmt::free_result(): void

过程化风格

function mysqli_stmt_free_result(mysqli_stmt `$statement`): void

Frees the result memory associated with the statement, which was allocated by mysqli_stmt_store_result().

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。

### 返回值

没有返回值。

### 参见

- mysqli_stmt_store_result() - Stores a result set in an internal buffer

# 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 — Gets a result set from a prepared statement as a mysqli_result object

### 说明

面向对象风格

public function mysqli_stmt::get_result(): mysqli_result|false

过程化风格

function mysqli_stmt_get_result(mysqli_stmt `$statement`): mysqli_result|false

Retrieves a result set from a prepared statement as a mysqli_result object. The data will be fetched from the MySQL server to PHP. This method should be called only for queries which produce a result set.

> 注意:

> 仅可用于 mysqlnd。

> 注意:

> This function cannot be used together with mysqli_stmt_store_result(). Both of these functions retrieve the full result set from the MySQL server.

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。

### 返回值

Returns `false` on failure. For successful queries which produce a result set, such as `SELECT, SHOW, DESCRIBE` or `EXPLAIN`, mysqli_stmt_get_result() will return a mysqli_result object. For other successful queries, mysqli_stmt_get_result() will return `false`. The mysqli_stmt_errno() function can be used to distinguish between the two reasons for `false`; due to a bug, prior to PHP 7.4.13, mysqli_errno() had to be used for this purpose.

### 错误／异常

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.

### 示例

示例 #1 面向对象风格

    <?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";
        }
    }

示例 #2 过程化风格

    <?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";
        }
    }

以上示例的输出类似于：

    Albania 3401200 Europe
    Algeria 31471000 Africa
    Afghanistan 22720000 Asia
    Anguilla 8000 North America

### 参见

- mysqli_prepare() - 预处理执行 SQL
- mysqli_stmt_result_metadata() - Returns result set metadata from a prepared statement
- mysqli_stmt_fetch() - Fetch results from a prepared statement into the bound variables
- mysqli_fetch_array() - Fetch the next row of a result set as an associative, a numeric array, or both
- mysqli_stmt_store_result() - Stores a result set in an internal buffer

# 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 — Get result of SHOW WARNINGS

### 说明

面向对象风格

public function mysqli_stmt::get_warnings(): mysqli_warning|false

过程化风格

function mysqli_stmt_get_warnings(mysqli_stmt `$statement`): mysqli_warning|false
警告

本函数还未编写文档，仅有参数列表。

# mysqli_stmt::$insert_id

# mysqli_stmt_insert_id

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$insert_id -- mysqli_stmt_insert_id — Get the ID generated from the previous INSERT operation

### 说明

面向对象风格

int|string $mysqli_stmt->insert_id;

过程化风格

function mysqli_stmt_insert_id(mysqli_stmt `$statement`): int|string
警告

本函数还未编写文档，仅有参数列表。

# 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 — Check if there are more query results from a multiple query

### 说明

面向对象风格

public function mysqli_stmt::more_results(): bool

过程化风格:

function mysqli_stmt_more_results(mysqli_stmt `$statement`): bool

Checks if there are more query results from a multiple query.

> 注意:

> 仅可用于 mysqlnd。

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。

### 返回值

Returns `true` if more results exist, otherwise `false`.

### 参见

- mysqli_stmt::next_result() - Reads the next result from a multiple query
- mysqli::multi_query() - 在数据库上执行一个或多个查询

# 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 — Reads the next result from a multiple query

### 说明

面向对象风格

public function mysqli_stmt::next_result(): bool

过程化风格:

function mysqli_stmt_next_result(mysqli_stmt `$statement`): bool

Reads the next result from a multiple query.

> 注意:

> Prior to PHP 8.1.0, available only with mysqlnd.

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | Now also available when linking against libmysqlclient.

### 参见

- mysqli_stmt::more_results() - Check if there are more query results from a multiple query
- mysqli::multi_query() - 在数据库上执行一个或多个查询

# 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 — Returns the number of rows fetched from the server

### 说明

面向对象风格

int|string $mysqli_stmt->num_rows;
public function mysqli_stmt::num_rows(): int|string

过程化风格

function mysqli_stmt_num_rows(mysqli_stmt `$statement`): int|string

Returns the number of rows buffered in the statement. This function will only work after mysqli_stmt_store_result() is called to buffer the entire result set in the statement handle.

This function returns `0` unless all rows have been fetched from the server.

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。

### 返回值

An int representing the number of buffered rows. Returns `0` in unbuffered mode unless all rows have been fetched from the server.

> 注意: If the number of rows is greater than `PHP_INT_MAX`, the number will be returned as a string.

### 示例

示例 #1 面向对象风格

    <?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();

    /* store the result in an internal buffer */
    $stmt->store_result();

    printf("Number of rows: %d.\n", $stmt->num_rows);

示例 #2 过程化风格

    <?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);

    /* store the result in an internal buffer */
    mysqli_stmt_store_result($stmt);

    printf("Number of rows: %d.\n", mysqli_stmt_num_rows($stmt));

以上示例会输出：

    Number of rows: 20.

### 参见

- mysqli_stmt_store_result() - Stores a result set in an internal buffer
- mysqli_stmt_affected_rows() - Returns the total number of rows changed, deleted, inserted, or matched by the last statement executed
- mysqli_prepare() - 预处理执行 SQL

# mysqli_stmt::$param_count

# mysqli_stmt_param_count

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$param_count -- mysqli_stmt_param_count — Returns the number of parameters for the given statement

### 说明

面向对象风格

int $mysqli_stmt->param_count;

过程化风格

function mysqli_stmt_param_count(mysqli_stmt `$statement`): int

Returns the number of parameter markers present in the prepared statement.

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。

### 返回值

Returns an integer representing the number of parameters.

### 示例

示例 #1 面向对象风格

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    if ($stmt = $mysqli->prepare("SELECT Name FROM Country WHERE Name=? OR Code=?")) {

        $marker = $stmt->param_count;
        printf("Statement has %d markers.\n", $marker);

        /* close statement */
        $stmt->close();
    }

    /* close connection */
    $mysqli->close();
    ?>

示例 #2 过程化风格

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %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("Statement has %d markers.\n", $marker);

        /* close statement */
        mysqli_stmt_close($stmt);
    }

    /* close connection */
    mysqli_close($link);
    ?>

以上示例会输出：

    Statement has 2 markers.

### 参见

- mysqli_prepare() - 预处理执行 SQL

# mysqli_stmt::prepare

# mysqli_stmt_prepare

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::prepare -- mysqli_stmt_prepare — Prepares an SQL statement for execution

### 说明

面向对象风格

public function mysqli_stmt::prepare(string `$query`): bool

过程化风格

function mysqli_stmt_prepare(mysqli_stmt `$statement`, string `$query`): bool

Prepares a statement for execution. The query must consist of a single SQL statement.

The statement template can contain zero or more question mark (`?`) parameter markers⁠—also called placeholders. The parameter markers must be bound to application variables using mysqli_stmt_bind_param() before executing the statement.

> 注意:

> In the case where a statement is passed to mysqli_stmt_prepare() that is longer than `max_allowed_packet` of the server, the returned error codes are different depending on whether you are using MySQL Native Driver (`mysqlnd`) or MySQL Client Library (`libmysqlclient`). The behavior is as follows:

> - `mysqlnd` on Linux returns an error code of 1153. The error message means got a packet bigger than `max_allowed_packet` bytes.

> - `mysqlnd` on Windows returns an error code 2006. This error message means server has gone away.

> - `libmysqlclient` on all platforms returns an error code 2006. This error message means server has gone away.

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。
`query`

  The query, as a string. It must consist of a single SQL statement.

  The SQL statement may contain zero or more parameter markers represented by question mark (`?`) characters at the appropriate positions.

  > 注意:

  > The markers are legal only in certain places in SQL statements. For example, they are permitted in the `VALUES()` list of an `INSERT` statement (to specify column values for a row), or in a comparison with a column in a `WHERE` clause to specify a comparison value. However, they are not permitted for identifiers (such as table or column names).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 示例

示例 #1 mysqli_stmt::prepare() example

面向对象风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $city = "Amersfoort";

    /* create a prepared statement */
    $stmt = $mysqli->stmt_init();
    $stmt->prepare("SELECT District FROM City WHERE Name=?");

    /* bind parameters for markers */
    $stmt->bind_param("s", $city);

    /* execute query */
    $stmt->execute();

    /* bind result variables */
    $stmt->bind_result($district);

    /* fetch value */
    $stmt->fetch();

    printf("%s is in district %s\n", $city, $district);

过程化风格

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $city = "Amersfoort";

    /* create a prepared statement */
    $stmt = mysqli_stmt_init($link);
    mysqli_stmt_prepare($stmt, "SELECT District FROM City WHERE Name=?");

    /* bind parameters for markers */
    mysqli_stmt_bind_param($stmt, "s", $city);

    /* execute query */
    mysqli_stmt_execute($stmt);

    /* bind result variables */
    mysqli_stmt_bind_result($stmt, $district);

    /* fetch value */
    mysqli_stmt_fetch($stmt);

    printf("%s is in district %s\n", $city, $district);

以上示例会输出：

    Amersfoort is in district Utrecht

### 参见

- mysqli_stmt_init() - 初始化语句并返回用于 mysqli_stmt_prepare（调用）的对象
- mysqli_stmt_execute() - Executes a prepared statement
- mysqli_stmt_fetch() - Fetch results from a prepared statement into the bound variables
- mysqli_stmt_bind_param() - Binds variables to a prepared statement as parameters
- mysqli_stmt_bind_result() - Binds variables to a prepared statement for result storage
- mysqli_stmt_get_result() - Gets a result set from a prepared statement as a mysqli_result object
- mysqli_stmt_close() - Closes a prepared statement

# mysqli_stmt::reset

# mysqli_stmt_reset

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::reset -- mysqli_stmt_reset — Resets a prepared statement

### 说明

面向对象风格

public function mysqli_stmt::reset(): bool

过程化风格

function mysqli_stmt_reset(mysqli_stmt `$statement`): bool

Resets a prepared statement on client and server to state after prepare.

It resets the statement on the server, data sent using mysqli_stmt_send_long_data(), unbuffered result sets and current errors. It does not clear bindings or stored result sets. Stored result sets will be cleared when executing the prepared statement (or closing it).

To prepare a statement with another query use function mysqli_stmt_prepare().

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- mysqli_prepare() - 预处理执行 SQL

# mysqli_stmt::result_metadata

# mysqli_stmt_result_metadata

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::result_metadata -- mysqli_stmt_result_metadata — Returns result set metadata from a prepared statement

### 说明

面向对象风格

public function mysqli_stmt::result_metadata(): mysqli_result|false

过程化风格

function mysqli_stmt_result_metadata(mysqli_stmt `$statement`): mysqli_result|false

If a statement passed to mysqli_prepare() is one that produces a result set, mysqli_stmt_result_metadata() returns the result object that can be used to process the meta information such as total number of fields and individual field information.

This function returns an empty mysqli_result object which can be used to access metadata information from the prepared statement without having to fetch the actual rows of data. There is no need to use this function when using mysqli_stmt_get_result() to retrieve the entire result set from a prepared statement as a result object.

> 注意:

> This result set object can be passed as an argument only to the field-based functions that process result set metadata, such as:

> - 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()

> 注意: The result set returned by mysqli_stmt_result_metadata() contains only metadata. It does not contain any row results. The rows are obtained by calling mysqli_stmt_get_result() on the statement handle or with mysqli_stmt_fetch().

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。

### 返回值

Returns a result object or `false` if an error occurred. If the statement does not produce a result set, `false` is returned as well.

### 错误／异常

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.

### 示例

示例 #1 面向对象风格

    <?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();

    /* get resultset for metadata */
    $result = $stmt->result_metadata();

    /* retrieve field information from metadata result set */
    $field = $result->fetch_field();

    printf("Fieldname: %s\n", $field->name);
    ?>

示例 #2 过程化风格

    <?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);

    /* get resultset for metadata */
    $result = mysqli_stmt_result_metadata($stmt);

    /* retrieve field information from metadata result set */
    $field = mysqli_fetch_field($result);

    printf("Fieldname: %s\n", $field->name);
    ?>

### 参见

- mysqli_prepare() - 预处理执行 SQL
- mysqli_free_result() - Frees the memory associated with a result
- mysqli_stmt_get_result() - Gets a result set from a prepared statement as a mysqli_result object

# 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 — Send data in blocks

### 说明

面向对象风格

public function mysqli_stmt::send_long_data(int `$param_num`, string `$data`): bool

过程化风格

function mysqli_stmt_send_long_data(mysqli_stmt `$statement`, int `$param_num`, string `$data`): bool

Allows to send parameter data to the server in pieces (or chunks), e.g. if the size of a blob exceeds the size of `max_allowed_packet`. This function can be called multiple times to send the parts of a character or binary data value for a column, which must be one of the TEXT or BLOB datatypes.

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。
`param_num`

  Indicates which parameter to associate the data with. Parameters are numbered beginning with 0.

`data`

  A string containing data to be sent.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 面向对象风格

    <?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();
    ?>

### 参见

- mysqli_prepare() - 预处理执行 SQL
- mysqli_stmt_bind_param() - Binds variables to a prepared statement as parameters

# mysqli_stmt::$sqlstate

# mysqli_stmt_sqlstate

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$sqlstate -- mysqli_stmt_sqlstate — Returns SQLSTATE error from previous statement operation

### 说明

面向对象风格

string $mysqli_stmt->sqlstate;

过程化风格

function mysqli_stmt_sqlstate(mysqli_stmt `$statement`): string

Returns a string containing the SQLSTATE error code for the most recently invoked prepared statement function that can succeed or fail. The error code consists of five characters. `'00000'` means no error. The values are specified by ANSI SQL and ODBC. For a list of possible values, see » http://dev.mysql.com/doc/mysql/en/error-handling.html.

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。

### 返回值

Returns a string containing the SQLSTATE error code for the last error. The error code consists of five characters. `'00000'` means no error.

### 示例

示例 #1 面向对象风格

    <?php
    /* Open a connection */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %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)) {

        /* drop table */
        $mysqli->query("DROP TABLE myCountry");

        /* execute query */
        $stmt->execute();

        printf("Error: %s.\n", $stmt->sqlstate);

        /* close statement */
        $stmt->close();
    }

    /* close connection */
    $mysqli->close();
    ?>

示例 #2 过程化风格

    <?php
    /* Open a connection */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %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)) {

        /* drop table */
        mysqli_query($link, "DROP TABLE myCountry");

        /* execute query */
        mysqli_stmt_execute($stmt);

        printf("Error: %s.\n", mysqli_stmt_sqlstate($stmt));

        /* close statement */
        mysqli_stmt_close($stmt);
    }

    /* close connection */
    mysqli_close($link);
    ?>

以上示例会输出：

    Error: 42S02.

### 注释

> 注意:

> Note that not all MySQL errors are yet mapped to SQLSTATE's. The value `HY000` (general error) is used for unmapped errors.

### 参见

- mysqli_stmt_errno() - Returns the error code for the most recent statement call
- mysqli_stmt_error() - Returns a string description for last statement error

# mysqli_stmt::store_result

# mysqli_stmt_store_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::store_result -- mysqli_stmt_store_result — Stores a result set in an internal buffer

### 说明

面向对象风格

public function mysqli_stmt::store_result(): bool

过程化风格

function mysqli_stmt_store_result(mysqli_stmt `$statement`): bool

This function should be called for queries that successfully produce a result set (e.g. `SELECT, SHOW, DESCRIBE, EXPLAIN`) only if the complete result set needs to be buffered in PHP. Each subsequent mysqli_stmt_fetch() call will return buffered data.

> 注意:

> It is unnecessary to call mysqli_stmt_store_result() for other queries, but if you do, it will not harm or cause any notable performance loss in all cases. You can detect whether the query produced a result set by checking if mysqli_stmt_result_metadata() returns `false`.

### 参数

`statement`
  仅以过程化样式：由 mysqli_stmt_init() 返回的 mysqli_stmt 对象。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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.

### 示例

示例 #1 面向对象风格

    <?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();

    /* store the result in an internal buffer */
    $stmt->store_result();

    printf("Number of rows: %d.\n", $stmt->num_rows);

示例 #2 过程化风格

    <?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);

    /* store the result in an internal buffer */
    mysqli_stmt_store_result($stmt);

    printf("Number of rows: %d.\n", mysqli_stmt_num_rows($stmt));

以上示例会输出：

    Number of rows: 20.

### 参见

- mysqli_prepare() - 预处理执行 SQL
- mysqli_stmt_result_metadata() - Returns result set metadata from a prepared statement
- mysqli_stmt_fetch() - Fetch results from a prepared statement into the bound variables

## 目录

- mysqli_stmt::$affected_rows — Returns the total number of rows changed, deleted, inserted, or matched by the last statement executed
- mysqli_stmt::attr_get — Used to get the current value of a statement attribute
- mysqli_stmt::attr_set — Used to modify the behavior of a prepared statement
- mysqli_stmt::bind_param — Binds variables to a prepared statement as parameters
- mysqli_stmt::bind_result — Binds variables to a prepared statement for result storage
- mysqli_stmt::close — Closes a prepared statement
- mysqli_stmt::__construct — Constructs a new mysqli_stmt object
- mysqli_stmt::data_seek — Adjusts the result pointer to an arbitrary row in the buffered result
- mysqli_stmt::$errno — Returns the error code for the most recent statement call
- mysqli_stmt::$error — Returns a string description for last statement error
- mysqli_stmt::$error_list — Returns a list of errors from the last statement executed
- mysqli_stmt::execute — Executes a prepared statement
- mysqli_stmt::fetch — Fetch results from a prepared statement into the bound variables
- mysqli_stmt::$field_count — Returns the number of columns in the given statement
- mysqli_stmt::free_result — Frees stored result memory for the given statement handle
- mysqli_stmt::get_result — Gets a result set from a prepared statement as a mysqli_result object
- mysqli_stmt::get_warnings — Get result of SHOW WARNINGS
- mysqli_stmt::$insert_id — Get the ID generated from the previous INSERT operation
- mysqli_stmt::more_results — Check if there are more query results from a multiple query
- mysqli_stmt::next_result — Reads the next result from a multiple query
- mysqli_stmt::$num_rows — Returns the number of rows fetched from the server
- mysqli_stmt::$param_count — Returns the number of parameters for the given statement
- mysqli_stmt::prepare — Prepares an SQL statement for execution
- mysqli_stmt::reset — Resets a prepared statement
- mysqli_stmt::result_metadata — Returns result set metadata from a prepared statement
- mysqli_stmt::send_long_data — Send data in blocks
- mysqli_stmt::$sqlstate — Returns SQLSTATE error from previous statement operation
- mysqli_stmt::store_result — Stores a result set in an internal buffer

# mysqli_result 类

(PHP 5, PHP 7, PHP 8)

## 简介

代表从一个数据库查询中获取的结果集。

## 类摘要

class mysqli_result implements IteratorAggregate {
/* 属性 */
public readonly int $current_field;
public readonly int $field_count;
public readonly ?array $lengths;
public readonly int|string $num_rows;
public int $type;
/* 方法 */
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
}

## 属性

type

  存储的是否为缓冲的结果，int 形式（分别是 `MYSQLI_STORE_RESULT` 或 `MYSQLI_USE_RESULT`）。

## 更新日志

版本 | 说明
--- | ---
8.0.0 | mysqli_result 现在实现 IteratorAggregate。之前实现的是 Traversable。

# mysqli_result::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_result::__construct — Constructs a mysqli_result object

### 说明

public function mysqli_result::__construct(mysqli `$mysql`, int `$result_mode` = `MYSQLI_STORE_RESULT`)

This method constructs a new mysqli_result object.

It can be used to create the mysqli_result object after calling the mysqli_real_query() or mysqli_multi_query() function. Constructing the object manually is equivalent to calling the mysqli_store_result() or mysqli_use_result() function.

### 参数

`mysql`
  仅以过程化样式：由 mysqli_connect() 或 mysqli_init() 返回的 mysqli 对象。
`result_mode`

  The result mode can be one of 2 constants indicating how the result will be returned from the MySQL server.

  `MYSQLI_STORE_RESULT` (default) - creates a mysqli_result object with buffered result set.

  `MYSQLI_USE_RESULT` - creates a mysqli_result object with unbuffered result set. As long as there are pending records waiting to be fetched, the connection line will be busy and all subsequent calls will return error `Commands out of sync`. To avoid the error all records must be fetched from the server or the result set must be discarded by calling mysqli_free_result(). The connection must remain open for the rows to be fetched.

### 错误／异常

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.

### 示例

示例 #1 Creation of a mysqli_result object

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Select queries return a result set */
    $mysqli->real_query("SELECT Name FROM City LIMIT 10");

    $result = new mysqli_result($mysqli);
    printf("Select returned %d rows.\n", $result->num_rows);

以上示例的输出类似于：

    Select returned 10 rows.

### 参见

- mysqli_multi_query() - 在数据库上执行一个或多个查询
- mysqli_real_query() - 执行一个mysql查询
- mysqli_store_result() - 传输上次查询的结果集
- mysqli_use_result() - Initiate a result set retrieval

# mysqli_result::$current_field

# mysqli_field_tell

(PHP 5, PHP 7, PHP 8)

mysqli_result::$current_field -- mysqli_field_tell — Get current field offset of a result pointer

### 说明

面向对象风格

int $mysqli_result->current_field;

过程化风格

function mysqli_field_tell(mysqli_result `$result`): int

Returns the position of the field cursor used for the last mysqli_fetch_field() call. This value can be used as an argument to mysqli_field_seek().

### 参数

`result`
  仅以过程化样式：由 mysqli_query()、mysqli_store_result()、 mysqli_use_result()、mysqli_stmt_get_result() 返回的 mysqli_result 对象。

### 返回值

Returns current offset of field cursor.

### 示例

示例 #1 面向对象风格

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Get field information for all columns */
        while ($finfo = $result->fetch_field()) {

            /* get fieldpointer offset */
            $currentfield = $result->current_field;

            printf("Column %d:\n", $currentfield);
            printf("Name:     %s\n", $finfo->name);
            printf("Table:    %s\n", $finfo->table);
            printf("max. Len: %d\n", $finfo->max_length);
            printf("Flags:    %d\n", $finfo->flags);
            printf("Type:     %d\n\n", $finfo->type);
        }
        $result->close();
    }

    /* close connection */
    $mysqli->close();
    ?>

示例 #2 过程化风格

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Get field information for all fields */
        while ($finfo = mysqli_fetch_field($result)) {

            /* get fieldpointer offset */
            $currentfield = mysqli_field_tell($result);

            printf("Column %d:\n", $currentfield);
            printf("Name:     %s\n", $finfo->name);
            printf("Table:    %s\n", $finfo->table);
            printf("max. Len: %d\n", $finfo->max_length);
            printf("Flags:    %d\n", $finfo->flags);
            printf("Type:     %d\n\n", $finfo->type);
        }
        mysqli_free_result($result);
    }

    /* close connection */
    mysqli_close($link);
    ?>

以上示例会输出：

    Column 1:
    Name:     Name
    Table:    Country
    max. Len: 11
    Flags:    1
    Type:     254

    Column 2:
    Name:     SurfaceArea
    Table:    Country
    max. Len: 10
    Flags:    32769
    Type:     4

### 参见

- mysqli_fetch_field() - Returns the next field in the result set
- mysqli_field_seek() - Set result pointer to a specified field offset

# mysqli_result::data_seek

# mysqli_data_seek

(PHP 5, PHP 7, PHP 8)

mysqli_result::data_seek -- mysqli_data_seek — Adjusts the result pointer to an arbitrary row in the result

### 说明

面向对象风格

public function mysqli_result::data_seek(int `$offset`): bool

过程化风格

function mysqli_data_seek(mysqli_result `$result`, int `$offset`): bool

The mysqli_data_seek() function seeks to an arbitrary result pointer specified by the `offset` in the result set.

### 参数

`result`
  仅以过程化样式：由 mysqli_query()、mysqli_store_result()、 mysqli_use_result()、mysqli_stmt_get_result() 返回的 mysqli_result 对象。
`offset`

  The row offset. Must be between zero and the total number of rows minus one (0..mysqli_num_rows() - 1).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 mysqli::data_seek() example

面向对象风格

    <?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);

    /* Seek to row no. 401 */
    $result->data_seek(400);

    /* Fetch single row */
    $row = $result->fetch_row();

    printf("City: %s  Countrycode: %s\n", $row[0], $row[1]);

过程化风格

    <?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);

    /* Seek to row no. 401 */
    mysqli_data_seek($result, 400);

    /* Fetch single row */
    $row = mysqli_fetch_row($result);

    printf ("City: %s  Countrycode: %s\n", $row[0], $row[1]);

以上示例会输出：

    City: Benin City  Countrycode: NGA

示例 #2 Adjusting the result pointer when iterating

This function can be useful when iterating over the result set to impose a custom order or rewind the result set when iterating multiple times.

    <?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);

    /* Iterate the result set in reverse order */
    for ($row_no = $result->num_rows - 1; $row_no >= 0; $row_no--) {
        $result->data_seek($row_no);

        /* Fetch single row */
        $row = $result->fetch_row();

        printf("City: %s  Countrycode: %s\n", $row[0], $row[1]);
    }

    /* Reset pointer to the beginning of the result set */
    $result->data_seek(0);

    print "\n";

    /* Iterate the same result set again */
    while ($row = $result->fetch_row()) {
        printf("City: %s  Countrycode: %s\n", $row[0], $row[1]);
    }

以上示例会输出：

    City: Acmbaro  Countrycode: MEX
    City: Abuja  Countrycode: NGA
    City: Abu Dhabi  Countrycode: ARE
    City: Abottabad  Countrycode: PAK

    City: Abottabad  Countrycode: PAK
    City: Abu Dhabi  Countrycode: ARE
    City: Abuja  Countrycode: NGA
    City: Acmbaro  Countrycode: MEX

### 注释

> 注意:

> This function can only be used with buffered results attained from the use of the mysqli_store_result(), mysqli_query() or mysqli_stmt_get_result() functions.

### 参见

- mysqli_store_result() - 传输上次查询的结果集
- mysqli_fetch_row() - Fetch the next row of a result set as an enumerated array
- mysqli_fetch_array() - Fetch the next row of a result set as an associative, a numeric array, or both
- mysqli_fetch_assoc() - Fetch the next row of a result set as an associative array
- mysqli_fetch_object() - Fetch the next row of a result set as an object
- mysqli_query() - 对数据库执行查询
- mysqli_num_rows() - Gets the number of rows in the result set

# mysqli_result::fetch_all

# mysqli_fetch_all

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_result::fetch_all -- mysqli_fetch_all — Fetch all result rows as an associative array, a numeric array, or both

### 说明

面向对象风格

public function mysqli_result::fetch_all(int `$mode` = `MYSQLI_NUM`): array

过程化风格

function mysqli_fetch_all(mysqli_result `$result`, int `$mode` = `MYSQLI_NUM`): array

Returns a two-dimensional array of all result rows as an associative array, a numeric array, or both.

> 注意:

> Prior to PHP 8.1.0, available only with mysqlnd.

### 参数

`result`
  仅以过程化样式：由 mysqli_query()、mysqli_store_result()、 mysqli_use_result()、mysqli_stmt_get_result() 返回的 mysqli_result 对象。
`mode`

  This optional parameter is a constant indicating what type of array should be produced from the current row data. The possible values for this parameter are the constants `MYSQLI_ASSOC`, `MYSQLI_NUM`, or `MYSQLI_BOTH`.

### 返回值

Returns an array of associative or numeric arrays holding result rows.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | Now also available when linking against libmysqlclient.

### 示例

示例 #1 mysqli_result::fetch_all() example

面向对象风格

    <?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"]);
    }

过程化风格

    <?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"]);
    }

以上示例会输出：

    Kabul (AFG)
    Qandahar (AFG)
    Herat (AFG)

### 参见

- mysqli_fetch_array() - Fetch the next row of a result set as an associative, a numeric array, or both
- mysqli_fetch_column() - Fetch a single column from the next row of a result set
- mysqli_query() - 对数据库执行查询

# mysqli_result::fetch_array

# mysqli_fetch_array

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_array -- mysqli_fetch_array — Fetch the next row of a result set as an associative, a numeric array, or both

### 说明

面向对象风格

public function mysqli_result::fetch_array(int `$mode` = `MYSQLI_BOTH`): array|null|false

过程化风格

function mysqli_fetch_array(mysqli_result `$result`, int `$mode` = `MYSQLI_BOTH`): array|null|false

Fetches one row of data from the result set and returns it as an array. Each subsequent call to this function will return the next row within the result set, or `null` if there are no more rows.

In addition to storing the data in the numeric indices of the result array, this function can also store the data in associative indices by using the field names of the result set as keys.

If two or more columns of the result have the same name, the last column will take precedence and overwrite any previous data. To access multiple columns with the same name, the numerically indexed version of the row must be used.

> 注意: 此函数返回的字段名大小写敏感。

> 注意: 此函数将 NULL 字段设置为 PHP `null` 值。

### 参数

`result`
  仅以过程化样式：由 mysqli_query()、mysqli_store_result()、 mysqli_use_result()、mysqli_stmt_get_result() 返回的 mysqli_result 对象。
`mode`

  This optional parameter is a constant indicating what type of array should be produced from the current row data. The possible values for this parameter are the constants `MYSQLI_ASSOC`, `MYSQLI_NUM`, or `MYSQLI_BOTH`.

  By using the `MYSQLI_ASSOC` constant this function will behave identically to the mysqli_fetch_assoc(), while `MYSQLI_NUM` will behave identically to the mysqli_fetch_row() function. The final option `MYSQLI_BOTH` will create a single array with the attributes of both.

### 返回值

Returns an array representing the fetched row, `null` if there are no more rows in the result set, 或者在失败时返回 `false`.

### 示例

示例 #1 mysqli_result::fetch_array() example

面向对象风格

    <?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);

    /* numeric array */
    $row = $result->fetch_array(MYSQLI_NUM);
    printf("%s (%s)\n", $row[0], $row[1]);

    /* associative array */
    $row = $result->fetch_array(MYSQLI_ASSOC);
    printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);

    /* associative and numeric array */
    $row = $result->fetch_array(MYSQLI_BOTH);
    printf("%s (%s)\n", $row[0], $row["CountryCode"]);

过程化风格

    <?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);

    /* numeric array */
    $row = mysqli_fetch_array($result, MYSQLI_NUM);
    printf("%s (%s)\n", $row[0], $row[1]);

    /* associative array */
    $row = mysqli_fetch_array($result, MYSQLI_ASSOC);
    printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);

    /* associative and numeric array */
    $row = mysqli_fetch_array($result, MYSQLI_BOTH);
    printf("%s (%s)\n", $row[0], $row["CountryCode"]);

以上示例的输出类似于：

    Kabul (AFG)
    Qandahar (AFG)
    Herat (AFG)

### 参见

- mysqli_fetch_assoc() - Fetch the next row of a result set as an associative array
- mysqli_fetch_column() - Fetch a single column from the next row of a result set
- mysqli_fetch_row() - Fetch the next row of a result set as an enumerated array
- mysqli_fetch_object() - Fetch the next row of a result set as an object
- mysqli_query() - 对数据库执行查询
- mysqli_data_seek() - Adjusts the result pointer to an arbitrary row in the result

# mysqli_result::fetch_assoc

# mysqli_fetch_assoc

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_assoc -- mysqli_fetch_assoc — Fetch the next row of a result set as an associative array

### 说明

面向对象风格

public function mysqli_result::fetch_assoc(): array|null|false

过程化风格

function mysqli_fetch_assoc(mysqli_result `$result`): array|null|false

Fetches one row of data from the result set and returns it as an associative array. Each subsequent call to this function will return the next row within the result set, or `null` if there are no more rows.

If two or more columns of the result have the same name, the last column will take precedence and overwrite any previous data. To access multiple columns with the same name, mysqli_fetch_row() may be used to fetch the numerically indexed array, or aliases may be used in the SQL query select list to give columns different names.

> 注意: 此函数返回的字段名大小写敏感。

> 注意: 此函数将 NULL 字段设置为 PHP `null` 值。

### 参数

`result`
  仅以过程化样式：由 mysqli_query()、mysqli_store_result()、 mysqli_use_result()、mysqli_stmt_get_result() 返回的 mysqli_result 对象。

### 返回值

Returns an associative array representing the fetched row, where each key in the array represents the name of one of the result set's columns, `null` if there are no more rows in the result set, 或者在失败时返回 `false`.

### 示例

示例 #1 mysqli_result::fetch_assoc() example

面向对象风格

    <?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);

    /* fetch associative array */
    while ($row = $result->fetch_assoc()) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

过程化风格

    <?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);

    /* fetch associative array */
    while ($row = mysqli_fetch_assoc($result)) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

以上示例的输出类似于：

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

示例 #2 Comparison of mysqli_result iterator and mysqli_result::fetch_assoc() usage

mysqli_result can be iterated using `foreach`. The result set will always be iterated from the first row, regardless of the current 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';

    // Using iterators
    $result = $mysqli->query($query);
    foreach ($result as $row) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

    echo "\n==================\n";

    // Not using iterators
    $result = $mysqli->query($query);
    while ($row = $result->fetch_assoc()) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

以上示例的输出类似于：

    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)

### 参见

- mysqli_fetch_array() - Fetch the next row of a result set as an associative, a numeric array, or both
- mysqli_fetch_column() - Fetch a single column from the next row of a result set
- mysqli_fetch_row() - Fetch the next row of a result set as an enumerated array
- mysqli_fetch_object() - Fetch the next row of a result set as an object
- mysqli_query() - 对数据库执行查询
- mysqli_data_seek() - Adjusts the result pointer to an arbitrary row in the result

# mysqli_result::fetch_column

# mysqli_fetch_column

(PHP 8 >= 8.1.0)

mysqli_result::fetch_column -- mysqli_fetch_column — Fetch a single column from the next row of a result set

### 说明

面向对象风格

public function mysqli_result::fetch_column(int `$column` = 0): null|int|float|string|false

过程化风格

function mysqli_fetch_column(mysqli_result `$result`, int `$column` = 0): null|int|float|string|false

Fetches one row of data from the result set and returns the 0-indexed column. Each subsequent call to this function will return the value from the next row within the result set, or `false` if there are no more rows.

> 注意: 此函数将 NULL 字段设置为 PHP `null` 值。

### 参数

`result`
  仅以过程化样式：由 mysqli_query()、mysqli_store_result()、 mysqli_use_result()、mysqli_stmt_get_result() 返回的 mysqli_result 对象。
`column`

  0-indexed number of the column you wish to retrieve from the row. If no value is supplied, the first column will be returned.

### 返回值

Returns a single column from the next row of a result set or `false` if there are no more rows.

警告

There is no way to return another column from the same row if you use this function to retrieve data.

### 示例

示例 #1 mysqli_result::fetch_column() example

面向对象风格

    <?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);

    /* fetch a single value from the second column */
    while ($Name = $result->fetch_column(1)) {
        printf("%s\n", $Name);
    }

过程化风格

    <?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);

    /* fetch a single value from the second column */
    while ($Name = mysqli_fetch_column($result, 1)) {
        printf("%s\n", $Name);
    }

以上示例的输出类似于：

    Rafah
    Nablus
    Jabaliya
    Hebron
    Khan Yunis

### 参见

- mysqli_fetch_all() - Fetch all result rows as an associative array, a numeric array, or both
- mysqli_fetch_array() - Fetch the next row of a result set as an associative, a numeric array, or both
- mysqli_fetch_assoc() - Fetch the next row of a result set as an associative array
- mysqli_fetch_object() - Fetch the next row of a result set as an object
- mysqli_fetch_row() - Fetch the next row of a result set as an enumerated array
- mysqli_data_seek() - Adjusts the result pointer to an arbitrary row in the result

# mysqli_result::fetch_field

# mysqli_fetch_field

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_field -- mysqli_fetch_field — Returns the next field in the result set

### 说明

面向对象风格

public function mysqli_result::fetch_field(): object|false

过程化风格

function mysqli_fetch_field(mysqli_result `$result`): object|false

Returns the definition of one column of a result set as an object. Call this function repeatedly to retrieve information about all columns in the result set.

### 参数

`result`
  仅以过程化样式：由 mysqli_query()、mysqli_store_result()、 mysqli_use_result()、mysqli_stmt_get_result() 返回的 mysqli_result 对象。

### 返回值

Returns an object which contains field definition information or `false` if no field information is available.

Object properties
Property | Description
--- | ---
name | The name of the column
orgname | Original column name if an alias was specified
table | The name of the table this field belongs to (if not calculated)
orgtable | Original table name if an alias was specified
def | Unused. Always an empty string
db | The name of the database
catalog | Unused. Always `"def"`
max_length | The maximum width of the field for the result set. As of PHP 8.1, this value is always `0`.
length | The width of the field in bytes. For string columns, the length value varies on the connection character set. For example, if the character set is `latin1`, a single-byte character set, the length value for a `SELECT 'abc'` query is 3. If the character set is `utf8mb4`, a multibyte character set in which characters take up to 4 bytes, the length value is 12.
charsetnr | The character set number for the field.
flags | An integer representing the bit-flags for the field.
type | The data type used for this field
decimals | The number of decimals for numeric fields, and the fractional seconds precision for temporal fields.

### 示例

示例 #1 面向对象风格

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Get field information for all columns */
        while ($finfo = $result->fetch_field()) {

            printf("Name:     %s\n", $finfo->name);
            printf("Table:    %s\n", $finfo->table);
            printf("max. Len: %d\n", $finfo->max_length);
            printf("Flags:    %d\n", $finfo->flags);
            printf("Type:     %d\n\n", $finfo->type);
        }
        $result->close();
    }

    /* close connection */
    $mysqli->close();
    ?>

示例 #2 过程化风格

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Get field information for all fields */
        while ($finfo = mysqli_fetch_field($result)) {

            printf("Name:     %s\n", $finfo->name);
            printf("Table:    %s\n", $finfo->table);
            printf("max. Len: %d\n", $finfo->max_length);
            printf("Flags:    %d\n", $finfo->flags);
            printf("Type:     %d\n\n", $finfo->type);
        }
        mysqli_free_result($result);
    }

    /* close connection */
    mysqli_close($link);
    ?>

以上示例会输出：

    Name:     Name
    Table:    Country
    max. Len: 11
    Flags:    1
    Type:     254

    Name:     SurfaceArea
    Table:    Country
    max. Len: 10
    Flags:    32769
    Type:     4

### 参见

- mysqli_num_fields() - Gets the number of fields in the result set
- mysqli_fetch_field_direct() - Fetch meta-data for a single field
- mysqli_fetch_fields() - Returns an array of objects representing the fields in a result set
- mysqli_field_seek() - Set result pointer to a specified field offset

# mysqli_result::fetch_field_direct

# mysqli_fetch_field_direct

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_field_direct -- mysqli_fetch_field_direct — Fetch meta-data for a single field

### 说明

面向对象风格

public function mysqli_result::fetch_field_direct(int `$index`): object|false

过程化风格

function mysqli_fetch_field_direct(mysqli_result `$result`, int `$index`): object|false

Returns an object which contains field definition information from the specified result set.

### 参数

`result`
  仅以过程化样式：由 mysqli_query()、mysqli_store_result()、 mysqli_use_result()、mysqli_stmt_get_result() 返回的 mysqli_result 对象。
`index`

  The field number. This value must be in the range from `0` to `number of fields - 1`.

### 返回值

Returns an object which contains field definition information or `false` if no field information for specified `index` is available.

Object properties
Property | Description
--- | ---
name | The name of the column
orgname | Original column name if an alias was specified
table | The name of the table this field belongs to (if not calculated)
orgtable | Original table name if an alias was specified
def | Unused. Always an empty string
db | The name of the database
catalog | Unused. Always `"def"`
max_length | The maximum width of the field for the result set. As of PHP 8.1, this value is always `0`.
length | The width of the field in bytes. For string columns, the length value varies on the connection character set. For example, if the character set is `latin1`, a single-byte character set, the length value for a `SELECT 'abc'` query is 3. If the character set is `utf8mb4`, a multibyte character set in which characters take up to 4 bytes, the length value is 12.
charsetnr | The character set number for the field.
flags | An integer representing the bit-flags for the field.
type | The data type used for this field
decimals | The number of decimals for numeric fields, and the fractional seconds precision for temporal fields.

### 示例

示例 #1 面向对象风格

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Name LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Get field information for column 'SurfaceArea' */
        $finfo = $result->fetch_field_direct(1);

        printf("Name:     %s\n", $finfo->name);
        printf("Table:    %s\n", $finfo->table);
        printf("max. Len: %d\n", $finfo->max_length);
        printf("Flags:    %d\n", $finfo->flags);
        printf("Type:     %d\n", $finfo->type);

        $result->close();
    }

    /* close connection */
    $mysqli->close();
    ?>

示例 #2 过程化风格

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Name LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Get field information for column 'SurfaceArea' */
        $finfo = mysqli_fetch_field_direct($result, 1);

        printf("Name:     %s\n", $finfo->name);
        printf("Table:    %s\n", $finfo->table);
        printf("max. Len: %d\n", $finfo->max_length);
        printf("Flags:    %d\n", $finfo->flags);
        printf("Type:     %d\n", $finfo->type);

        mysqli_free_result($result);
    }

    /* close connection */
    mysqli_close($link);
    ?>

以上示例会输出：

    Name:     SurfaceArea
    Table:    Country
    max. Len: 10
    Flags:    32769
    Type:     4

### 参见

- mysqli_num_fields() - Gets the number of fields in the result set
- mysqli_fetch_field() - Returns the next field in the result set
- mysqli_fetch_fields() - Returns an array of objects representing the fields in a result set

# mysqli_result::fetch_fields

# mysqli_fetch_fields

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_fields -- mysqli_fetch_fields — Returns an array of objects representing the fields in a result set

### 说明

面向对象风格

public function mysqli_result::fetch_fields(): array

过程化风格

function mysqli_fetch_fields(mysqli_result `$result`): array

This function serves an identical purpose to the mysqli_fetch_field() function with the single difference that, instead of returning one object at a time for each field, the columns are returned as an array of objects.

### 参数

`result`
  仅以过程化样式：由 mysqli_query()、mysqli_store_result()、 mysqli_use_result()、mysqli_stmt_get_result() 返回的 mysqli_result 对象。

### 返回值

Returns an array of objects containing field definition information.

Object properties
Property | Description
--- | ---
name | The name of the column
orgname | Original column name if an alias was specified
table | The name of the table this field belongs to (if not calculated)
orgtable | Original table name if an alias was specified
def | Unused. Always an empty string
db | The name of the database
catalog | Unused. Always `"def"`
max_length | The maximum width of the field for the result set. As of PHP 8.1, this value is always `0`.
length | The width of the field in bytes. For string columns, the length value varies on the connection character set. For example, if the character set is `latin1`, a single-byte character set, the length value for a `SELECT 'abc'` query is 3. If the character set is `utf8mb4`, a multibyte character set in which characters take up to 4 bytes, the length value is 12.
charsetnr | The character set number for the field.
flags | An integer representing the bit-flags for the field.
type | The data type used for this field
decimals | The number of decimals for numeric fields, and the fractional seconds precision for temporal fields.

### 示例

示例 #1 面向对象风格

    <?php
    $mysqli = new mysqli("127.0.0.1", "root", "foofoo", "sakila");

    /* check connection */
    if ($mysqli->connect_errno) {
        printf("Connect failed: %s\n", $mysqli->connect_error);
        exit();
    }

    foreach (array('latin1', 'utf8') as $charset) {

        // Set character set, to show its impact on some values (e.g., length in bytes)
        $mysqli->set_charset($charset);

        $query = "SELECT actor_id, last_name from actor ORDER BY actor_id";

        echo "======================\n";
        echo "Character Set: $charset\n";
        echo "======================\n";

        if ($result = $mysqli->query($query)) {

            /* Get field information for all columns */
            $finfo = $result->fetch_fields();

            foreach ($finfo as $val) {
                printf("Name:      %s\n",   $val->name);
                printf("Table:     %s\n",   $val->table);
                printf("Max. Len:  %d\n",   $val->max_length);
                printf("Length:    %d\n",   $val->length);
                printf("charsetnr: %d\n",   $val->charsetnr);
                printf("Flags:     %d\n",   $val->flags);
                printf("Type:      %d\n\n", $val->type);
            }
            $result->free();
        }
    }
    $mysqli->close();
    ?>

示例 #2 过程化风格

    <?php
    $link = mysqli_connect("127.0.0.1", "my_user", "my_password", "sakila");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    foreach (array('latin1', 'utf8') as $charset) {

        // Set character set, to show its impact on some values (e.g., length in bytes)
        mysqli_set_charset($link, $charset);

        $query = "SELECT actor_id, last_name from actor ORDER BY actor_id";

        echo "======================\n";
        echo "Character Set: $charset\n";
        echo "======================\n";

        if ($result = mysqli_query($link, $query)) {

            /* Get field information for all columns */
            $finfo = mysqli_fetch_fields($result);

            foreach ($finfo as $val) {
                printf("Name:      %s\n",   $val->name);
                printf("Table:     %s\n",   $val->table);
                printf("Max. Len:  %d\n",   $val->max_length);
                printf("Length:    %d\n",   $val->length);
                printf("charsetnr: %d\n",   $val->charsetnr);
                printf("Flags:     %d\n",   $val->flags);
                printf("Type:      %d\n\n", $val->type);
            }
            mysqli_free_result($result);
        }
    }

    mysqli_close($link);
    ?>

以上示例会输出：

    ======================
    Character Set: latin1
    ======================
    Name:      actor_id
    Table:     actor
    Max. Len:  3
    Length:    5
    charsetnr: 63
    Flags:     49699
    Type:      2

    Name:      last_name
    Table:     actor
    Max. Len:  12
    Length:    45
    charsetnr: 8
    Flags:     20489
    Type:      253

    ======================
    Character Set: utf8
    ======================
    Name:      actor_id
    Table:     actor
    Max. Len:  3
    Length:    5
    charsetnr: 63
    Flags:     49699
    Type:      2

    Name:      last_name
    Table:     actor
    Max. Len:  12
    Length:    135
    charsetnr: 33
    Flags:     20489

### 参见

- mysqli_num_fields() - Gets the number of fields in the result set
- mysqli_fetch_field_direct() - Fetch meta-data for a single field
- mysqli_fetch_field() - Returns the next field in the result set

# mysqli_result::fetch_object

# mysqli_fetch_object

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_object -- mysqli_fetch_object — Fetch the next row of a result set as an object

### 说明

面向对象风格

public function mysqli_result::fetch_object(string `$class` = "stdClass", array `$constructor_args` = []): object|null|false

过程化风格

function mysqli_fetch_object(mysqli_result `$result`, string `$class` = "stdClass", array `$constructor_args` = []): object|null|false

Fetches one row of data from the result set and returns it as an object, where each property represents the name of the result set's column. Each subsequent call to this function will return the next row within the result set, or `null` if there are no more rows.

If two or more columns of the result have the same name, the last column will take precedence and overwrite any previous data. To access multiple columns with the same name, mysqli_fetch_row() may be used to fetch the numerically indexed array, or aliases may be used in the SQL query select list to give columns different names.

> 注意: This function sets the properties of the object before calling the object constructor.

> 注意: 此函数返回的字段名大小写敏感。

> 注意: 此函数将 NULL 字段设置为 PHP `null` 值。

### 参数

`result`
  仅以过程化样式：由 mysqli_query()、mysqli_store_result()、 mysqli_use_result()、mysqli_stmt_get_result() 返回的 mysqli_result 对象。
`class`

  The name of the class to instantiate, set the properties of and return. If not specified, a stdClass object is returned.

`constructor_args`

  An optional array of parameters to pass to the constructor for `class` objects.

### 返回值

Returns an object representing the fetched row, where each property represents the name of the result set's column, `null` if there are no more rows in the result set, 或者在失败时返回 `false`.

### 错误／异常

A ValueError is thrown when the `constructor_args` is non-empty with the class not having constructor.

### 更新日志

版本 | 说明
--- | ---
8.3.0 | Now throws a ValueError exception when the `constructor_args` is non-empty with the class not having constructor; previously an Exception was thrown.
8.0.0 | `constructor_args` now accepts `[]` for constructors with 0 parameters; previously an exception was thrown.

### 示例

示例 #1 mysqli_result::fetch_object() example

面向对象风格

    <?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);
    }

过程化风格

    <?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);
    }

以上示例的输出类似于：

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

### 参见

- mysqli_fetch_array() - Fetch the next row of a result set as an associative, a numeric array, or both
- mysqli_fetch_assoc() - Fetch the next row of a result set as an associative array
- mysqli_fetch_column() - Fetch a single column from the next row of a result set
- mysqli_fetch_row() - Fetch the next row of a result set as an enumerated array
- mysqli_query() - 对数据库执行查询
- mysqli_data_seek() - Adjusts the result pointer to an arbitrary row in the result

# mysqli_result::fetch_row

# mysqli_fetch_row

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_row -- mysqli_fetch_row — Fetch the next row of a result set as an enumerated array

### 说明

面向对象风格

public function mysqli_result::fetch_row(): array|null|false

过程化风格

function mysqli_fetch_row(mysqli_result `$result`): array|null|false

Fetches one row of data from the result set and returns it as an enumerated array, where each column is stored in an array offset starting from 0 (zero). Each subsequent call to this function will return the next row within the result set, or `null` if there are no more rows.

> 注意: 此函数将 NULL 字段设置为 PHP `null` 值。

### 参数

`result`
  仅以过程化样式：由 mysqli_query()、mysqli_store_result()、 mysqli_use_result()、mysqli_stmt_get_result() 返回的 mysqli_result 对象。

### 返回值

Returns an enumerated array representing the fetched row, `null` if there are no more rows in the result set, 或者在失败时返回 `false`.

### 示例

示例 #1 mysqli_result::fetch_row() example

面向对象风格

    <?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);

    /* fetch object array */
    while ($row = $result->fetch_row()) {
        printf("%s (%s)\n", $row[0], $row[1]);
    }

过程化风格

    <?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);

    /* fetch associative array */
    while ($row = mysqli_fetch_row($result)) {
        printf("%s (%s)\n", $row[0], $row[1]);
    }

以上示例的输出类似于：

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

### 参见

- mysqli_fetch_array() - Fetch the next row of a result set as an associative, a numeric array, or both
- mysqli_fetch_assoc() - Fetch the next row of a result set as an associative array
- mysqli_fetch_column() - Fetch a single column from the next row of a result set
- mysqli_fetch_object() - Fetch the next row of a result set as an object
- mysqli_query() - 对数据库执行查询
- mysqli_data_seek() - Adjusts the result pointer to an arbitrary row in the result

# mysqli_result::$field_count

# mysqli_num_fields

(PHP 5, PHP 7, PHP 8)

mysqli_result::$field_count -- mysqli_num_fields — Gets the number of fields in the result set

### 说明

面向对象风格

int $mysqli_result->field_count;

过程化风格

function mysqli_num_fields(mysqli_result `$result`): int

Returns the number of fields in the result set.

### 参数

`result`
  仅以过程化样式：由 mysqli_query()、mysqli_store_result()、 mysqli_use_result()、mysqli_stmt_get_result() 返回的 mysqli_result 对象。

### 返回值

An int representing the number of fields.

### 示例

示例 #1 面向对象风格

    <?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");

    /* Get the number of fields in the result set */
    $field_cnt = $result->field_count;

    printf("Result set has %d fields.\n", $field_cnt);

示例 #2 过程化风格

    <?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");

    /* Get the number of fields in the result set */
    $field_cnt = mysqli_num_fields($result);

    printf("Result set has %d fields.\n", $field_cnt);

以上示例会输出：

    Result set has 4 fields.

### 参见

- mysqli_fetch_field() - Returns the next field in the result set

# mysqli_result::field_seek

# mysqli_field_seek

(PHP 5, PHP 7, PHP 8)

mysqli_result::field_seek -- mysqli_field_seek — Set result pointer to a specified field offset

### 说明

面向对象风格

public function mysqli_result::field_seek(int `$index`): true

过程化风格

function mysqli_field_seek(mysqli_result `$result`, int `$index`): true

Sets the field cursor to the given offset. The next call to mysqli_fetch_field() will retrieve the field definition of the column associated with that offset.

> 注意:

> To seek to the beginning of a row, pass an offset value of zero.

### 参数

`result`
  仅以过程化样式：由 mysqli_query()、mysqli_store_result()、 mysqli_use_result()、mysqli_stmt_get_result() 返回的 mysqli_result 对象。
`index`

  The field number. This value must be in the range from `0` to `number of fields - 1`.

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | This function now always returns `true`. Previously it returned `false` on failure.

### 示例

示例 #1 面向对象风格

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Get field information for 2nd column */
        $result->field_seek(1);
        $finfo = $result->fetch_field();

        printf("Name:     %s\n", $finfo->name);
        printf("Table:    %s\n", $finfo->table);
        printf("max. Len: %d\n", $finfo->max_length);
        printf("Flags:    %d\n", $finfo->flags);
        printf("Type:     %d\n\n", $finfo->type);

        $result->close();
    }

    /* close connection */
    $mysqli->close();
    ?>

示例 #2 过程化风格

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Get field information for 2nd column */
        mysqli_field_seek($result, 1);
        $finfo = mysqli_fetch_field($result);

        printf("Name:     %s\n", $finfo->name);
        printf("Table:    %s\n", $finfo->table);
        printf("max. Len: %d\n", $finfo->max_length);
        printf("Flags:    %d\n", $finfo->flags);
        printf("Type:     %d\n\n", $finfo->type);

        mysqli_free_result($result);
    }

    /* close connection */
    mysqli_close($link);
    ?>

以上示例会输出：

    Name:     SurfaceArea
    Table:    Country
    max. Len: 10
    Flags:    32769
    Type:     4

### 参见

- mysqli_fetch_field() - Returns the next field in the result set

# 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 — Frees the memory associated with a result

### 说明

面向对象风格

public function mysqli_result::free(): void
public function mysqli_result::close(): void
public function mysqli_result::free_result(): void

过程化风格

function mysqli_free_result(mysqli_result `$result`): void

Frees the memory associated with the result.

### 参数

`result`
  仅以过程化样式：由 mysqli_query()、mysqli_store_result()、 mysqli_use_result()、mysqli_stmt_get_result() 返回的 mysqli_result 对象。

### 返回值

没有返回值。

### 参见

- mysqli_query() - 对数据库执行查询
- mysqli_stmt_get_result() - Gets a result set from a prepared statement as a mysqli_result object
- mysqli_store_result() - 传输上次查询的结果集
- mysqli_use_result() - Initiate a result set retrieval

# mysqli_result::getIterator

(PHP 8)

mysqli_result::getIterator — Retrieve an external iterator

### 说明

public function mysqli_result::getIterator(): Iterator

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# mysqli_result::$lengths

# mysqli_fetch_lengths

(PHP 5, PHP 7, PHP 8)

mysqli_result::$lengths -- mysqli_fetch_lengths — Returns the lengths of the columns of the current row in the result set

### 说明

面向对象风格

?array $mysqli_result->lengths;

过程化风格

function mysqli_fetch_lengths(mysqli_result `$result`): array|false

The mysqli_fetch_lengths() function returns an array containing the lengths of every column of the current row within the result set.

### 参数

`result`
  仅以过程化样式：由 mysqli_query()、mysqli_store_result()、 mysqli_use_result()、mysqli_stmt_get_result() 返回的 mysqli_result 对象。

### 返回值

An array of integers representing the size of each column (not including any terminating null characters). `false` if an error occurred.

mysqli_fetch_lengths() is valid only for the current row of the result set. It returns `false` if you call it before calling mysqli_fetch_row/array/object or after retrieving all rows in the result.

### 示例

示例 #1 面向对象风格

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT * from Country ORDER BY Code LIMIT 1";

    if ($result = $mysqli->query($query)) {

        $row = $result->fetch_row();

        /* display column lengths */
        foreach ($result->lengths as $i => $val) {
            printf("Field %2d has Length %2d\n", $i+1, $val);
        }
        $result->close();
    }

    /* close connection */
    $mysqli->close();
    ?>

示例 #2 过程化风格

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* check connection */
    if (mysqli_connect_errno()) {
        printf("Connect failed: %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);

        /* display column lengths */
        foreach (mysqli_fetch_lengths($result) as $i => $val) {
            printf("Field %2d has Length %2d\n", $i+1, $val);
        }
        mysqli_free_result($result);
    }

    /* close connection */
    mysqli_close($link);
    ?>

以上示例会输出：

    Field  1 has Length  3
    Field  2 has Length  5
    Field  3 has Length 13
    Field  4 has Length  9
    Field  5 has Length  6
    Field  6 has Length  1
    Field  7 has Length  6
    Field  8 has Length  4
    Field  9 has Length  6
    Field 10 has Length  6
    Field 11 has Length  5
    Field 12 has Length 44
    Field 13 has Length  7
    Field 14 has Length  3
    Field 15 has Length  2

# mysqli_result::$num_rows

# mysqli_num_rows

(PHP 5, PHP 7, PHP 8)

mysqli_result::$num_rows -- mysqli_num_rows — Gets the number of rows in the result set

### 说明

面向对象风格

int|string $mysqli_result->num_rows;

过程化风格

function mysqli_num_rows(mysqli_result `$result`): int|string

Returns the number of rows in the result set.

The behaviour of mysqli_num_rows() depends on whether buffered or unbuffered result sets are being used. This function returns `0` for unbuffered result sets unless all rows have been fetched from the server.

### 参数

`result`
  仅以过程化样式：由 mysqli_query()、mysqli_store_result()、 mysqli_use_result()、mysqli_stmt_get_result() 返回的 mysqli_result 对象。

### 返回值

An int representing the number of fetched rows. Returns `0` in unbuffered mode unless all rows have been fetched from the server.

> 注意: If the number of rows is greater than `PHP_INT_MAX`, the number will be returned as a string.

### 示例

示例 #1 面向对象风格

    <?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");

    /* Get the number of rows in the result set */
    $row_cnt = $result->num_rows;

    printf("Result set has %d rows.\n", $row_cnt);

示例 #2 过程化风格

    <?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");

    /* Get the number of rows in the result set */
    $row_cnt = mysqli_num_rows($result);

    printf("Result set has %d rows.\n", $row_cnt);

以上示例会输出：

    Result set has 239 rows.

### 注释

> 注意:

> In contrast to the mysqli_stmt_num_rows() function, this function doesn't have object-oriented method variant. In the object-oriented style, use the getter property.

### 参见

- mysqli_affected_rows() - Gets the number of affected rows in a previous MySQL operation
- mysqli_store_result() - 传输上次查询的结果集
- mysqli_use_result() - Initiate a result set retrieval
- mysqli_query() - 对数据库执行查询
- mysqli_stmt_num_rows() - Returns the number of rows fetched from the server

## 目录

- mysqli_result::__construct — Constructs a mysqli_result object
- mysqli_result::$current_field — Get current field offset of a result pointer
- mysqli_result::data_seek — Adjusts the result pointer to an arbitrary row in the result
- mysqli_result::fetch_all — Fetch all result rows as an associative array, a numeric array, or both
- mysqli_result::fetch_array — Fetch the next row of a result set as an associative, a numeric array, or both
- mysqli_result::fetch_assoc — Fetch the next row of a result set as an associative array
- mysqli_result::fetch_column — Fetch a single column from the next row of a result set
- mysqli_result::fetch_field — Returns the next field in the result set
- mysqli_result::fetch_field_direct — Fetch meta-data for a single field
- mysqli_result::fetch_fields — Returns an array of objects representing the fields in a result set
- mysqli_result::fetch_object — Fetch the next row of a result set as an object
- mysqli_result::fetch_row — Fetch the next row of a result set as an enumerated array
- mysqli_result::$field_count — Gets the number of fields in the result set
- mysqli_result::field_seek — Set result pointer to a specified field offset
- mysqli_result::free — Frees the memory associated with a result
- mysqli_result::getIterator — Retrieve an external iterator
- mysqli_result::$lengths — Returns the lengths of the columns of the current row in the result set
- mysqli_result::$num_rows — Gets the number of rows in the result set

# mysqli_driver 类

(PHP 5, PHP 7, PHP 8)

## 简介

mysqli_driver 类是单例模式的实例，即任意数量的 mysqli_driver 实例只访问一个驱动。

## 类摘要

final class mysqli_driver {
/* 属性 */
public readonly string $client_info;
public readonly int $client_version;
public readonly int $driver_version;
public int $report_mode;
}

## 属性

client_info

  客户端 API 报头版本

client_version

  客户端版本

driver_version

  MySQLi Driver 版本

  警告

  自 PHP 8.1.0 起弃用此属性。强烈不推荐依赖此属性。

embedded

  是否开启 MySQLi Embedded 支持

  警告

  此属性自 PHP 8.0.0 起移除。

reconnect

  允许或阻止重连（查看 mysqli.reconnect INI 指令）

  警告

  自 PHP 8.2.0 起，此属性已与 mysqli.reconnect INI 指令一起移除。

report_mode

  设置 `MYSQLI_REPORT_OFF`、`MYSQLI_REPORT_ALL` 或为 `MYSQLI_REPORT_STRICT`（错误抛出异常，译注：需要和 MYSQLI_REPORT_ERROR 联合使用）、`MYSQLI_REPORT_ERROR`（报告错误）和 `MYSQLI_REPORT_INDEX`（关于索引的错误）的任意组合。参阅mysqli_report()。

## 更新日志

版本 | 说明
--- | ---
8.2.0 | 移除 mysqli_driver::$reconnect。
8.1.0 | 弃用 mysqli_driver::$driver_version。
8.0.0 | 移除 mysqli_driver::$embedded。
7.4.0 | 移除 mysqli_driver::embedded_server_start() 和 mysqli_driver:embedded_server_end()。

# 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 — Stop embedded server

警告

该函数已在 PHP 7.4.0 中 移除。

### 说明

面向对象风格

public function mysqli_driver::embedded_server_end(): void

过程化风格

function mysqli_embedded_server_end(): void
警告

本函数还未编写文档，仅有参数列表。

# 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 — Initialize and start embedded server

警告

该函数已在 PHP 7.4.0 中 移除。

### 说明

面向对象风格

public function mysqli_driver::embedded_server_start(int `$start`, array `$arguments`, array `$groups`): bool

过程化风格

function mysqli_embedded_server_start(int `$start`, array `$arguments`, array `$groups`): bool
警告

本函数还未编写文档，仅有参数列表。

# mysqli_driver::$report_mode

# mysqli_report

(PHP 5, PHP 7, PHP 8)

mysqli_driver::$report_mode -- mysqli_report — Sets mysqli error reporting mode

### 说明

面向对象风格

int $mysqli_driver->report_mode;

过程化风格

function mysqli_report(int `$flags`): true

Depending on the flags, it sets mysqli error reporting mode to exception, warning or none. When set to `MYSQLI_REPORT_ALL` or `MYSQLI_REPORT_INDEX` it will also inform about queries that don't use an index (or use a bad index).

As of PHP 8.1.0, the default setting is `MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT`. Previously, it was `MYSQLI_REPORT_OFF`.

### 参数

`flags`

  Supported flags
  Name | Description
  --- | ---
  `MYSQLI_REPORT_OFF` | Turns reporting off
  `MYSQLI_REPORT_ERROR` | Report errors from mysqli function calls
  `MYSQLI_REPORT_STRICT` | Throw mysqli_sql_exception for errors instead of warnings
  `MYSQLI_REPORT_INDEX` | Report if no index or bad index was used in a query
  `MYSQLI_REPORT_ALL` | Set all options (report all)

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The default value is now `MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT`. Previously, it was `MYSQLI_REPORT_OFF`.

### 示例

示例 #1 面向对象风格

    <?php

    /* activate reporting */
    $driver = new mysqli_driver();
    $driver->report_mode = MYSQLI_REPORT_ALL;

    try {
        /* if the connection fails, a mysqli_sql_exception will be thrown */
        $mysqli = new mysqli("localhost", "my_user", "my_password", "my_db");

        /* this query should report an error */
        $result = $mysqli->query("SELECT Name FROM Nonexistingtable WHERE population > 50000");

        /* this query should report a bad index if the column population doesn't have an index */
        $result = $mysqli->query("SELECT Name FROM City WHERE population > 50000");
    } catch (mysqli_sql_exception $e) {
        error_log($e->__toString());
    }

示例 #2 过程化风格

    <?php

    /* activate reporting */
    mysqli_report(MYSQLI_REPORT_ALL);

    try {
        /* if the connection fails, a mysqli_sql_exception will be thrown */
        $link = mysqli_connect("localhost", "my_user", "my_password", "my_db");

        /* this query should report an error */
        $result = mysqli_query($link, "SELECT Name FROM Nonexistingtable WHERE population > 50000");

        /* this query should report a bad index if the column population doesn't have an index */
        $result = mysqli_query($link, "SELECT Name FROM City WHERE population > 50000");
    } catch (mysqli_sql_exception $e) {
        error_log($e->__toString());
    }

示例 #3 Error reporting except bad index errors

    <?php

    /* activate reporting */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    try {
        /* if the connection fails, a mysqli_sql_exception will be thrown */
        $mysqli = new mysqli("localhost", "my_user", "my_password", "my_db");

        /* this query should report an error */
        $result = $mysqli->query("SELECT Name FROM Nonexistingtable WHERE population > 50000");

        /* this WILL NOT report any errors even if index is not available */
        $result = $mysqli->query("SELECT Name FROM City WHERE population > 50000");
    } catch (mysqli_sql_exception $e) {
        error_log($e->__toString());
    }

### 参见

- mysqli_sql_exception
- set_exception_handler() - 设置用户自定义的异常处理函数
- error_reporting() - 设置应该报告何种 PHP 错误

## 目录

- mysqli_driver::embedded_server_end — Stop embedded server
- mysqli_driver::embedded_server_start — Initialize and start embedded server
- mysqli_driver::$report_mode — Sets mysqli error reporting mode

# mysqli_warning 类

(PHP 5, PHP 7, PHP 8)

## 简介

表示 MySQL 警告。

## 类摘要

final class mysqli_warning {
/* 属性 */
public string $message;
public string $sqlstate;
public int $errno;
/* 方法 */
private function __construct()
public function next(): bool
}

## 属性

message

  消息字符串

sqlstate

  SQL 状态

errno

  错误编号

# mysqli_warning::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_warning::__construct — Private constructor to disallow direct instantiation

### 说明

private function mysqli_warning::__construct()

### 参数

此函数没有参数。

# mysqli_warning::next

(PHP 5, PHP 7, PHP 8)

mysqli_warning::next — Fetch next warning

### 说明

public function mysqli_warning::next(): bool

Change warning information to the next warning if possible.

Once the warning has been set to the next warning, new values of properties `message`, `sqlstate` and `errno` of mysqli_warning are available.

### 参数

此函数没有参数。

### 返回值

Returns `true` if next warning was fetched successfully. If there are no more warnings, it will return `false`

## 目录

- mysqli_warning::__construct — Private constructor to disallow direct instantiation
- mysqli_warning::next — Fetch next warning

# mysqli_sql_exception 类

(PHP 5, PHP 7, PHP 8)

## 简介

mysqli 异常处理类。

## 类摘要

final class mysqli_sql_exception extends RuntimeException {
/* 属性 */
protected string $sqlstate = "00000";
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 方法 */
public function getSqlState(): string
/* 继承的方法 */
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
}

## 属性

sqlstate

  出现错误的 sql 状态。

# mysqli_sql_exception::getSqlState

(PHP 8 >= 8.1.2)

mysqli_sql_exception::getSqlState — Returns the SQLSTATE error code

### 说明

public function mysqli_sql_exception::getSqlState(): string

Returns a string containing the SQLSTATE error code for the last error. The error code consists of five characters. The values are specified by ANSI SQL and ODBC. For a list of possible values, see » http://dev.mysql.com/doc/mysql/en/error-handling.html.

> 注意:

> Note that not all MySQL errors are yet mapped to SQLSTATE's. The value `HY000` (general error) is used for unmapped errors.

### 参数

此函数没有参数。

### 返回值

Returns a string containing the SQLSTATE error code for the last error. The error code consists of five characters.

## 目录

- mysqli_sql_exception::getSqlState — Returns the SQLSTATE error code

# 别名和过时的 Mysqli 函数

# mysqli_connect

(PHP 5, PHP 7, PHP 8)

mysqli_connect — 别名 mysqli::__construct()

### 说明

此函数是该函数的别名： mysqli::__construct()

> 注意:

> 如果未启用 mysqli 异常模式，并且连接失败，则 mysqli_connect() 返回 `false` 而不是对象。mysqli_connect_error() 函数可用于获取连接错误。

# mysqli::escape_string

# mysqli_escape_string

(PHP 5, PHP 7, PHP 8)

mysqli::escape_string -- mysqli_escape_string — 别名 mysqli_real_escape_string()

### 说明

此函数是该函数的别名： mysqli_real_escape_string().

# mysqli_execute

(PHP 5, PHP 7, PHP 8)

mysqli_execute — 别名 mysqli_stmt_execute()

### 说明

此函数是该函数的别名： 这个函数是 mysqli_stmt_execute() 的一个别名。

### 注释

> 注意:

> mysqli_execute() 已经被废弃并且将会被移除。

### 参见

- mysqli_stmt_execute() - Executes a prepared statement

# mysqli_get_client_stats

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_get_client_stats — 返回客户端进程统计信息

### 说明

function mysqli_get_client_stats(): array

返回客户端每个进程的统计信息。

> 注意:

> 仅可用于 mysqlnd。

### 参数

此函数没有参数。

### 返回值

返回包含客户端状态的数组。

### 示例

示例 #1 A mysqli_get_client_stats() 示例

    <?php
    $link = mysqli_connect();
    print_r(mysqli_get_client_stats());
    ?>

以上示例的输出类似于：

    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
    )

### 参见

- 统计信息描述

# mysqli_get_links_stats

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

mysqli_get_links_stats — 返回打开和缓存的链接相关信息

### 说明

function mysqli_get_links_stats(): array

mysqli_get_links_stats() 返回已经打开和不活跃的 MySQL 链接的相关信息。

### 参数

此函数没有参数。

### 返回值

mysqli_get_links_stats() 返回一个有三个元素的关联数组, 键如下:

`total`

  int 类型，表示任何状态下未关闭链接的总数。

`active_plinks`

  int 类型，表示活跃的持久链接数。

`cached_plinks`

  int 类型，表示不活跃的持久链接数。

# mysqli_report

(PHP 5, PHP 7, PHP 8)

mysqli_report — 别名 mysqli_driver->report_mode

### 说明

此函数是该函数的别名： mysqli_driver->report_mode

# mysqli::set_opt

# mysqli_set_opt

(PHP 5, PHP 7, PHP 8)

mysqli::set_opt -- mysqli_set_opt — 别名 mysqli_options()

### 说明

此函数是该函数的别名： 这个函数是 mysqli_options() 的一个别名。

## 目录

- mysqli_connect — 别名 mysqli::__construct
- mysqli::escape_string — 别名 mysqli_real_escape_string
- mysqli_execute — 别名 mysqli_stmt_execute
- mysqli_get_client_stats — 返回客户端进程统计信息
- mysqli_get_links_stats — 返回打开和缓存的链接相关信息
- mysqli_report — 别名 mysqli_driver->report_mode
- mysqli::set_opt — 别名 mysqli_options

# 更新日志

对本扩展的类／函数／方法有以下更新。

Version | Function | Description
--- | --- | ---
8.4.0 | mysqli::kill | mysqli::kill 和 mysqli_kill 都已弃用。使用 KILL SQL 命令代替。
| mysqli::ping | mysqli::ping 和 mysqli_ping 都已弃用。自 PHP 8.2.0 起，reconnect 功能已不可用，因此该函数已过时。
| mysqli::refresh | mysqli::refresh 和 mysqli_refresh 都已弃用。使用 FLUSH SQL 命令代替。
| mysqli::store_result | 现在弃用传递 mode 参数。该参数自 PHP 8.1.0 起不再有效。
8.3.0 | mysqli_result::fetch_object | Now throws a ValueError exception when the constructor_args is non-empty with the class not having constructor; previously an Exception was thrown.
| mysqli::poll | 现在，当没有传递 read 和 error 参数时抛出 ValueError 异常。
8.1.0 | mysqli_driver::$report_mode | The default value is now MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT. Previously, it was MYSQLI_REPORT_OFF.
| mysqli_result::fetch_all | Now also available when linking against libmysqlclient.
| mysqli_stmt::execute | The optional params parameter has been added.
| mysqli_stmt::next_result | Now also available when linking against libmysqlclient.
| mysqli::__construct | mysqli::connect now returns true instead of null on success.
| mysqli::$client_info | 弃用使用 mysql 参数调用 mysqli_get_client_info。此函数从不需要参数，但错误的允许其作为可选参数。
| mysqli::$client_info | 弃用面向对象风格的 mysqli::get_client_info。
| mysqli::init | 弃用面向对象风格的 mysqli::init 方法。用 parent::__construct 替换对 parent::init 的调用。
8.0.0 | mysqli_result::fetch_object | constructor_args now accepts [] for constructors with 0 parameters; previously an exception was thrown.
| mysqli_result::field_seek | This function now always returns true. Previously it returned false on failure.
| mysqli_stmt::close | This function now always returns true. Previously it returned false on failure.
| mysqli_stmt::__construct | query is now nullable.
| mysqli::begin_transaction | name is now nullable.
| mysqli::close | 此函数始终返回 true。之前失败时返回 false。
| mysqli::commit | name 现在允许为 null。
| mysqli::debug | This function now always returns true. Previously it returned false on failure.
| mysqli::rollback | name 现在可以为 null。
7.4.0 | mysqli::__construct | All parameters are now nullable.
| mysqli::real_connect | 所有的参数都可为 null。

- 概述
- 快速入门指南
  - 面向过程和面向对象，两种接口
  - Connections
  - Executing statements
  - Prepared Statements
  - Stored Procedures
  - Multiple Statements
  - API support for transactions
  - Metadata
- 安装/配置
  - 需求
  - 安装
  - 运行时配置
- mysqli 扩展和持久化连接
- 预定义常量
- Notes
- MySQLi 扩展的函数概述
- mysqli — mysqli 类
  - mysqli::$affected_rows — Gets the number of affected rows in a previous MySQL operation
  - mysqli::autocommit — 打开或关闭本次数据库连接的自动命令提交事务模式
  - mysqli::begin_transaction — Starts a transaction
  - mysqli::change_user — Changes the user of the database connection
  - mysqli::character_set_name — 返回当前数据库连接的字符编码
  - mysqli::close — 关闭先前打开的数据库连接
  - mysqli::commit — 提交当前事务
  - mysqli::$connect_errno — Returns the error code from last connect call
  - mysqli::$connect_error — Returns a description of the last connection error
  - mysqli::__construct — Open a new connection to the MySQL server
  - mysqli::debug — Performs debugging operations
  - mysqli::dump_debug_info — 将调试信息输出到日志
  - mysqli::$errno — 返回最近函数调用的错误代码
  - mysqli::$error — Returns a string description of the last error
  - mysqli::$error_list — Returns a list of errors from the last command executed
  - mysqli::execute_query — Prepares, binds parameters, and executes SQL statement
  - mysqli::$field_count — Returns the number of columns for the most recent query
  - mysqli::get_charset — Returns a character set object
  - mysqli::$client_info — 获取 MySQL 客户端信息
  - mysqli::$client_version — 作为整数返回 MySQL 客户端的版本
  - mysqli::get_connection_stats — 返回客户端连接的统计数据
  - mysqli::$host_info — 返回表述使用的连接类型的字符串
  - mysqli::$protocol_version — 返回 MySQL 协议使用的版本号
  - mysqli::$server_info — 返回 MySQL 服务器的版本号
  - mysqli::$server_version — 作为一个整数返回MySQL服务器的版本
  - mysqli::get_warnings — Get result of SHOW WARNINGS
  - mysqli::$info — 返回最近执行的 SQL 语句的信息
  - mysqli::init — 初始化 MySQLi 并返回用于 mysqli_real_connect() 的对象
  - mysqli::$insert_id — 返回上次查询为 AUTO_INCREMENT 列生成的值
  - mysqli::kill — 让服务器杀死一个 MySQL 线程
  - mysqli::more_results — 检查批量查询中是否还有查询结果
  - mysqli::multi_query — 在数据库上执行一个或多个查询
  - mysqli::next_result — 为读取 multi_query 执行之后的下一个结果集做准备
  - mysqli::options — 设置选项
  - mysqli::ping — ping 一个连接，或者如果连接处于断开状态，重新连接
  - mysqli::poll — 轮询连接
  - mysqli::prepare — 预处理执行 SQL
  - mysqli::query — 对数据库执行查询
  - mysqli::real_connect — 建立一个 MySQL 服务器连接
  - mysqli::real_escape_string — 根据当前连接的字符集，对于 SQL 语句中的特殊字符进行转义
  - mysqli::real_query — 执行一个mysql查询
  - mysqli::reap_async_query — 获取异步查询的结果
  - mysqli::refresh — 刷新
  - mysqli::release_savepoint — 从当前事务的保存点中移除一个命名保存点
  - mysqli::rollback — 回滚当前事务
  - mysqli::savepoint — 在当前事务中设置命名保存点
  - mysqli::select_db — 选择用于数据库查询的默认数据库
  - mysqli::set_charset — 设置客户端字符集
  - mysqli::$sqlstate — 返回上一次 MySQL 操作的 SQLSTATE 错误
  - mysqli::ssl_set — 用于使用 SSL 建立安全连接
  - mysqli::stat — 获取当前系统状态信息
  - mysqli::stmt_init — 初始化语句并返回用于 mysqli_stmt_prepare（调用）的对象
  - mysqli::store_result — 传输上次查询的结果集
  - mysqli::$thread_id — 返回当前连接的线程 ID
  - mysqli::thread_safe — 返回是否线程安全
  - mysqli::use_result — Initiate a result set retrieval
  - mysqli::$warning_count — Returns the number of warnings generated by the most recently executed query
- mysqli_stmt — mysqli_stmt 类
  - mysqli_stmt::$affected_rows — Returns the total number of rows changed, deleted, inserted, or matched by the last statement executed
  - mysqli_stmt::attr_get — Used to get the current value of a statement attribute
  - mysqli_stmt::attr_set — Used to modify the behavior of a prepared statement
  - mysqli_stmt::bind_param — Binds variables to a prepared statement as parameters
  - mysqli_stmt::bind_result — Binds variables to a prepared statement for result storage
  - mysqli_stmt::close — Closes a prepared statement
  - mysqli_stmt::__construct — Constructs a new mysqli_stmt object
  - mysqli_stmt::data_seek — Adjusts the result pointer to an arbitrary row in the buffered result
  - mysqli_stmt::$errno — Returns the error code for the most recent statement call
  - mysqli_stmt::$error — Returns a string description for last statement error
  - mysqli_stmt::$error_list — Returns a list of errors from the last statement executed
  - mysqli_stmt::execute — Executes a prepared statement
  - mysqli_stmt::fetch — Fetch results from a prepared statement into the bound variables
  - mysqli_stmt::$field_count — Returns the number of columns in the given statement
  - mysqli_stmt::free_result — Frees stored result memory for the given statement handle
  - mysqli_stmt::get_result — Gets a result set from a prepared statement as a mysqli_result object
  - mysqli_stmt::get_warnings — Get result of SHOW WARNINGS
  - mysqli_stmt::$insert_id — Get the ID generated from the previous INSERT operation
  - mysqli_stmt::more_results — Check if there are more query results from a multiple query
  - mysqli_stmt::next_result — Reads the next result from a multiple query
  - mysqli_stmt::$num_rows — Returns the number of rows fetched from the server
  - mysqli_stmt::$param_count — Returns the number of parameters for the given statement
  - mysqli_stmt::prepare — Prepares an SQL statement for execution
  - mysqli_stmt::reset — Resets a prepared statement
  - mysqli_stmt::result_metadata — Returns result set metadata from a prepared statement
  - mysqli_stmt::send_long_data — Send data in blocks
  - mysqli_stmt::$sqlstate — Returns SQLSTATE error from previous statement operation
  - mysqli_stmt::store_result — Stores a result set in an internal buffer
- mysqli_result — mysqli_result 类
  - mysqli_result::__construct — Constructs a mysqli_result object
  - mysqli_result::$current_field — Get current field offset of a result pointer
  - mysqli_result::data_seek — Adjusts the result pointer to an arbitrary row in the result
  - mysqli_result::fetch_all — Fetch all result rows as an associative array, a numeric array, or both
  - mysqli_result::fetch_array — Fetch the next row of a result set as an associative, a numeric array, or both
  - mysqli_result::fetch_assoc — Fetch the next row of a result set as an associative array
  - mysqli_result::fetch_column — Fetch a single column from the next row of a result set
  - mysqli_result::fetch_field — Returns the next field in the result set
  - mysqli_result::fetch_field_direct — Fetch meta-data for a single field
  - mysqli_result::fetch_fields — Returns an array of objects representing the fields in a result set
  - mysqli_result::fetch_object — Fetch the next row of a result set as an object
  - mysqli_result::fetch_row — Fetch the next row of a result set as an enumerated array
  - mysqli_result::$field_count — Gets the number of fields in the result set
  - mysqli_result::field_seek — Set result pointer to a specified field offset
  - mysqli_result::free — Frees the memory associated with a result
  - mysqli_result::getIterator — Retrieve an external iterator
  - mysqli_result::$lengths — Returns the lengths of the columns of the current row in the result set
  - mysqli_result::$num_rows — Gets the number of rows in the result set
- mysqli_driver — mysqli_driver 类
  - mysqli_driver::embedded_server_end — Stop embedded server
  - mysqli_driver::embedded_server_start — Initialize and start embedded server
  - mysqli_driver::$report_mode — Sets mysqli error reporting mode
- mysqli_warning — mysqli_warning 类
  - mysqli_warning::__construct — Private constructor to disallow direct instantiation
  - mysqli_warning::next — Fetch next warning
- mysqli_sql_exception — mysqli_sql_exception 类
  - mysqli_sql_exception::getSqlState — Returns the SQLSTATE error code
- 别名和过时的 Mysqli 函数
  - mysqli_connect — 别名 mysqli::__construct
  - mysqli::escape_string — 别名 mysqli_real_escape_string
  - mysqli_execute — 别名 mysqli_stmt_execute
  - mysqli_get_client_stats — 返回客户端进程统计信息
  - mysqli_get_links_stats — 返回打开和缓存的链接相关信息
  - mysqli_report — 别名 mysqli_driver->report_mode
  - mysqli::set_opt — 别名 mysqli_options
- 更新日志

# Mysql_xdevapi

# 简介

This extension provides access to the MySQL Document Store via the X DevAPI. The X DevAPI is a common API provided by multiple MySQL Connectors providing easy access to relational tables as well as collections of documents, which are represented in JSON, from a API with CRUD-style operations.

The X DevAPI uses the X Protocol, the new generation client-server protocol of the MySQL 8.0 server.

For general information about the MySQL Document Store, please refer to the » MySQL Document Store chapter in the MySQL manual.

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置
- Building / Compiling From Source

## 需求

This extension requires a MySQL 8+ server with the X plugin enabled (default).

Prerequisite libraries for compiling this extension are: Boost (1.53.0 or higher), OpenSSL, and Protobuf.

## 安装

此 » PECL 扩展未与 PHP 捆绑。

An example installation procedure on Ubuntu 18.04 with PHP 7.2:

    // Dependencies
    $ apt install build-essential libprotobuf-dev libboost-dev openssl protobuf-compiler liblz4-tool zstd

    // PHP with the desired extensions; php7.2-dev is required to compile
    $ apt install php7.2-cli php7.2-dev php7.2-mysql php7.2-pdo php7.2-xml

    // Compile the extension
    $ pecl install mysql_xdevapi

The `pecl install` command does not enable PHP extensions (by default) and enabling PHP extensions can be done in several ways. Another PHP 7.2 on Ubuntu 18.04 example:

    // Create its own ini file
    $ echo "extension=mysql_xdevapi.so" > /etc/php/7.2/mods-available/mysql_xdevapi.ini

    // Use the 'phpenmod' command (note: it's Debian/Ubuntu specific)
    $ phpenmod -v 7.2 -s ALL mysql_xdevapi

    // A 'phpenmod' alternative is to manually symlink it
    // $ ln -s /etc/php/7.2/mods-available/mysql_xdevapi.ini /etc/php/7.2/cli/conf.d/20-mysql_xdevapi.ini

    // Let's see which MySQL extensions are enabled now
    $ php -m |grep mysql

    mysql_xdevapi
    mysqli
    mysqlnd
    pdo_mysql

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/mysql_xdevapi.

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

Mysql_xdevapi 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
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` |

这是配置指令的简短说明。

`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

## Building / Compiling From Source

Considerations for compiling this extension from source.

- The extension name is 'mysql_xdevapi', so use `--enable-mysql-xdevapi`.

- Boost: required, optionally use the --with-boost=DIR configure option or set the MYSQL_XDEVAPI_BOOST_ROOT environment variable. Only the boost header files are required; not the binaries.

- Google Protocol Buffers (protobuf): required, optionally use the --with-protobuf=DIR configure option or set the MYSQL_XDEVAPI_PROTOBUF_ROOT environment variable.

  Optionally use `make protobufs` to generate protobuf files (*.pb.cc/.h), and `make clean-protobufs` to delete generate protobuf files.

  Windows specific protobuf note: depending on your environment, the static library with a multi-threaded DLL runtime may be needed. To prepare, use the following options: -Dprotobuf_MSVC_STATIC_RUNTIME=OFF -Dprotobuf_BUILD_SHARED_LIBS=OFF

- Google Protocol Buffers / protocol compiler (protoc): required, ensure that proper 'protoc' is available in the PATH while building. It is especially important as Windows PHP SDK batch scripts may overwrite the environment.

- Bison: required, and available from the PATH.

  Windows specific bison note: we strongly recommended that bison delivered with the chosen PHP SDKis used else an error similar to "zend_globals_macros.h(39): error C2375: 'zendparse': redefinition; different linkage Zend/zend_language_parser.h(214): note: see declaration of 'zendparse'" may be the result. Also, Windows PHP SDK batch scripts may overwrite the environment.

- Windows Specific Notes: To prepare the environment, see the official Windows build documentation for » the current SDK.

  We recommend using the backslash '\\' instead of a slash '/' for all paths.

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`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)

# 更新日志

对本扩展的类／函数／方法有以下更新。

### General Changelog for the ext/mysql_xdevapi extension

This changelog references the ext/mysql_xdevapi extension.

### Global ext/mysql_xdevapi changes

版本 | 说明
--- | ---
8.0.28 | Removed TLSv1 and TLSv1.1 support. The values "TLSv1", "TLSv1.0", and "TLSv1.1" are now considered invalid for the "tls-versions" connection attribute.
8.0.26 | Deprecated TLSv1 and TLSv1.1 support.

# 示例

The central entry point to the X DevAPI is the mysql_xdevapi\getSession() function, which receives a URI to a MySQL 8.0 Server and returns a mysql_xdevapi\Session object.

示例 #1 Connecting to a MySQL Server

    <?php
    try {
        $session = mysql_xdevapi\getSession("mysqlx://user:password@host");
    } catch(Exception $e) {
        die("Connection could not be established: " . $e->getMessage());
    }

    // ... use $session
    ?>

The session provides full access to the API. For a new MySQL Server installation, the first step is to create a database schema with a collection to store data:

示例 #2 Creating a Schema and Collection on the MySQL Server

    <?php
    $schema = $session->createSchema("test");
    $collection = $schema->createCollection("example");
    ?>

When storing data, typically json_encode() is used to encode the data into JSON, which can then be stored inside a collection.

The following example stores data into the collection we created earlier, and then retrieve parts of it again.

示例 #3 Storing and Retrieving Data

    <?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());
    ?>

以上示例的输出类似于：

    array(4) {
      ["_id"]=>
      string(28) "00005ad66aaf0000000000000003"
      ["age"]=>
      int(39)
      ["job"]=>
      string(7) "Manager"
      ["name"]=>
      string(4) "Mike"
    }

The example demonstrates that the MySQL Server adds an extra field named `_id`, which serves as primary key to the document.

The example also demonstrates that retrieved data is sorted alphabetically. That specific order comes from the efficient binary storage inside the MySQL server, but it should not be relied upon. Refer to the MySQL JSON datatype documentation for details.

Optionally use PHP's iterators to fetch multiple documents:

示例 #4 Fetching and Iterating Multiple Documents

    <?php
    $result = $collection->find()->execute();
    foreach ($result as $doc) {
      echo "{$doc["name"]} is a {$doc["job"]}.\n";
    }
    ?>

以上示例的输出类似于：

    Marco is a Programmer.
    Mike is a Manager.

# Mysql_xdevapi 函数

# expression

(No version information available, might only be in Git)

expression — Bind prepared statement variables as parameters

### 说明

function mysql_xdevapi\expression(string `$expression`): object

警告

本函数还未编写文档，仅有参数列表。

### 参数

`expression`

### 返回值

### 示例

示例 #1 mysql_xdevapi\Expression() example

    <?php
    $expression = mysql_xdevapi\Expression("[age,job]");

    $res  = $coll->find("age > 30")->fields($expression)->limit(3)->execute();
    $data = $res->fetchAll();

    print_r($data);
    ?>

以上示例的输出类似于：

    <?php

# getSession

(No version information available, might only be in Git)

getSession — Connect to a MySQL server

### 说明

function mysql_xdevapi\getSession(string `$uri`): mysql_xdevapi\Session

Connects to the MySQL server.

### 参数

`uri`

  The URI to the MySQL server, such as `mysqlx://user:password@host`.

  URI format:

  `scheme://[user[:[password]]@]target[:port][?attribute1=value1&attribute2=value2...`

  - `scheme`: required, the connection protocol

    In mysql_xdevapi it is always 'mysqlx' (for X Protocol)

  - `user`: optional, the MySQL user account for authentication

  - `password`: optional, the MySQL user's password for authentication

  - `target`: required, the server instance the connection refers to:

    * TCP connection (host name, IPv4 address, or IPv6 address)

    * Unix socket path (local file path)

    * Windows named-pipe (local file path)

  - `port`: optional, network port of MySQL server.

    by default port for X Protocol is 33060

  - `?attribute=value`: this element is optional and specifies a data dictionary that contains different options, including:

    - The `auth` (authentication mechanism) attribute as it relates to encrypted connections. For additional information, see » Command Options for Encrypted Connections. The following 'auth' values are supported: `plain`, `mysql41`, `external`, and `sha256_mem`.

    - The `connect-timeout` attribute affects the connection and not subsequent operations. It is set per connection whether on a single or multiple hosts.

      Pass in a positive integer to define the connection timeout in seconds, or pass in 0 (zero) to disable the timeout (infinite). Not defining connect-timeout uses the default value of 10.

      Related, the MYSQLX_CONNECTION_TIMEOUT (timeout in seconds) and MYSQLX_TEST_CONNECTION_TIMEOUT (used while running tests) environment variables can be set and used instead of connect-timeout in the URI. The connect-timeout URI option has precedence over these environment variables.

    - The optional `compression` attribute accepts these values: `preferred` (client negotiates with server to find a supported algorithm; connection is uncompressed if a mutually supported algorithm is not found), `required` (like "preferred", but connection is terminated if a mutually supported algorithm is not found), or `disabled` (connection is uncompressed). Defaults to `preferred`.

      This option was added in version 8.0.20.

    - The optional `compression-algorithms` attribute defines the desired compression algorithms (and their preferred usage order): `zstd_stream` (alias: zstd), `lz4_message` (alias: lz4), or `deflate_stream` (aliases: deflate or zlib). By default, the order used (depending on system availability) is lz4_message, zstd_stream, then deflate_stream. For example, passing in compression-algorithms=[lz4,zstd_stream] uses lz4 if it's available, otherwise zstd_stream is used. If both are unavailable then behavior depends on the compression value e.g., if compression=required then it'll fail with an error.

      This option was added in version 8.0.22.

  示例 #1 URI examples

      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]

  For related information, see MySQL Shell's » Connecting using a URI String.

### 返回值

A Session object.

### 错误／异常

A connection failure throws an Exception.

### 示例

示例 #2 mysql_xdevapi\getSession() example

    <?php
    try {
        $session = mysql_xdevapi\getSession("mysqlx://user:password@host");
    } catch(Exception $e) {
        die("Connection could not be established: " . $e->getMessage());
    }

    $schemas = $session->getSchemas();
    print_r($schemas);

    $mysql_version = $session->getServerVersion();
    print_r($mysql_version);

    var_dump($collection->find("name = 'Alfred'")->execute()->fetchOne());
    ?>

以上示例的输出类似于：

    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"
    }

## 目录

- expression — Bind prepared statement variables as parameters
- getSession — Connect to a MySQL server

# BaseResult interface

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\BaseResult {
/* 方法 */
abstract public function getWarnings(): array
abstract public function getWarningsCount(): int
}

# BaseResult::getWarnings

(No version information available, might only be in Git)

BaseResult::getWarnings — Fetch warnings from last operation

### 说明

abstract public function mysql_xdevapi\BaseResult::getWarnings(): array

Fetches warnings generated by MySQL server's last operation.

### 参数

此函数没有参数。

### 返回值

An array of Warning objects from the last operation. Each object defines an error 'message', error 'level', and error 'code'. An empty array is returned if no errors are present.

### 示例

示例 #1 mysql_xdevapi\RowResult::getWarnings() example

    <?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);
    ?>

以上示例的输出类似于：

    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 — Fetch warning count from last operation

### 说明

abstract public function mysql_xdevapi\BaseResult::getWarningsCount(): int

Returns the number of warnings raised by the last operation. Specifically, these warnings are raised by the MySQL server.

### 参数

此函数没有参数。

### 返回值

The number of warnings from the last operation.

### 示例

示例 #1 mysql_xdevapi\RowResult::getWarningsCount() example

    <?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();
    ?>

以上示例的输出类似于：

    2

## 目录

- BaseResult::getWarnings — Fetch warnings from last operation
- BaseResult::getWarningsCount — Fetch warning count from last operation

# Client class

(No version information available, might only be in Git)

## 简介

Provides access to the connection pool.

## 类摘要

class mysql_xdevapi\Client {
/* 方法 */
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 — Close client

### 说明

public function mysql_xdevapi\Client::close(): bool

Close all client connections with the server.

### 参数

此函数没有参数。

### 返回值

`true` if connections are closed.

# Client::__construct

(No version information available, might only be in Git)

Client::__construct — Client constructor

### 说明

private function mysql_xdevapi\Client::__construct()

Construct a client object.

### 参数

此函数没有参数。

### 示例

示例 #1 mysql_xdevapi\Client::__construct() example

    <?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 — Get client session

### 说明

public function mysql_xdevapi\Client::getSession(): mysql_xdevapi\Session

Get session associated with the client.

### 参数

此函数没有参数。

### 返回值

A Session object.

## 目录

- mysql_xdevapi\Client::close — Close client
- Client::__construct — Client constructor
- Client::getClient — Get client session

# Collection class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\Collection implements mysql_xdevapi\SchemaObject {
/* 属性 */
public $name;
/* 方法 */
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
}

## 属性

name

# Collection::add

(No version information available, might only be in Git)

Collection::add — Add collection document

### 说明

public function mysql_xdevapi\Collection::add(mixed `$document`): mysql_xdevapi\CollectionAdd

Triggers the insertion of the given document(s) into the collection, and multiple variants of this method are supported. Options include:

1. Add a single document as a JSON string.

2. Add a single document as an array as: `[ 'field' => 'value', 'field2' => 'value2' ... ]`

3. A mix of both, and multiple documents can be added in the same operation.

### 参数

`document`

  One or multiple documents, and this can be either JSON or an array of fields with their associated values. This cannot be an empty array.

  The MySQL server automatically generates unique `_id` values for each document (recommended), although this can be manually added as well. This value must be unique as otherwise the add operation will fail.

### 返回值

A CollectionAdd object. Use execute() to return a Result that can be used to query the number of affected items, the number warnings generated by the operation, or to fetch a list of generated IDs for the inserted documents.

### 示例

示例 #1 mysql_xdevapi\Collection::add() example

    <?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");

    // Add two documents
    $collection->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    // Add two documents using a single JSON object
    $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();

    // Fetch a list of generated ID's from the last add()
    $ids = $result->getGeneratedIds();
    print_r($ids);
    ?>

以上示例的输出类似于：

    Array
    (
        [0] => 00005b6b53610000000000000056
        [1] => 00005b6b53610000000000000057
    )

### 注释

> 注意:

> A unique _id is generated by MySQL Server 8.0 or higher, as demonstrated in the example. The _id field must be manually defined if using MySQL Server 5.7.

# Collection::addOrReplaceOne

(No version information available, might only be in Git)

Collection::addOrReplaceOne — Add or replace collection document

### 说明

public function mysql_xdevapi\Collection::addOrReplaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result

Add a new document, or replace a document if it already exists.

Here are several scenarios for this method:

- If neither the id or any unique key values conflict with any document in the collection, then the document is added.

- If the id does not match any document but one or more unique key values conflict with a document in the collection, then an error is raised.

- If id matches an existing document and no unique keys are defined for the collection, then the document is replaced.

- If id matches an existing document, and either all unique keys in the replacement document match that same document or they don't conflict with any other documents in the collection, then the document is replaced.

- If id matches an existing document and one or more unique keys match a different document from the collection, then an error is raised.

### 参数

`id`

  This is the filter id. If this id or any other field that has a unique index already exists in the collection, then it will update the matching document instead.

  By default, this id is automatically generated by MySQL Server when the record was added, and is referenced as a field named '_id'.

`doc`

  This is the document to add or replace, which is a JSON string.

### 返回值

A Result object.

### 示例

示例 #1 mysql_xdevapi\Collection::addOrReplaceOne() example

    <?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");

    // Using add()
    $result = $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    // Using addOrReplaceOne()
    // Note: we're passing in a known _id value here
    $result = $collection->addOrReplaceOne('00005b6b53610000000000000056', '{"name": "Fred",  "age": 21, "job": "Construction"}');

    ?>

# Collection::__construct

(No version information available, might only be in Git)

Collection::__construct — Collection constructor

### 说明

private function mysql_xdevapi\Collection::__construct()

Construct a Collection object.

### 参数

此函数没有参数。

### 示例

示例 #1 mysql_xdevapi\Collection::getOne() example

    <?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();

    // A unique _id is (by default, and recommended) generated by MySQL Server
    // This retrieves the generated _id's; only one in this example, so $ids[0]
    $ids        = $result->getGeneratedIds();
    $alfreds_id = $ids[0];

    // ...

    print_r($alfreds_id);
    print_r($collection->getOne($alfreds_id));
    ?>

以上示例的输出类似于：

    00005b6b536100000000000000b1

    Array
    (
        [_id] => 00005b6b536100000000000000b1
        [age] => 42
        [job] => Butler
        [name] => Alfred
    )

# Collection::count

(No version information available, might only be in Git)

Collection::count — Get document count

### 说明

public function mysql_xdevapi\Collection::count(): int

This functionality is similar to a `SELECT COUNT(*)` SQL operation against the MySQL server for the current schema and collection. In other words, it counts the number of documents in the collection.

### 参数

此函数没有参数。

### 返回值

The number of documents in the collection.

### 示例

示例 #1 mysql_xdevapi\Collection::count() example

    <?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());
    ?>

以上示例会输出：

    int(2)

# Collection::createIndex

(No version information available, might only be in Git)

Collection::createIndex — Create collection index

### 说明

public function mysql_xdevapi\Collection::createIndex(string `$index_name`, string `$index_desc_json`): void

Creates an index on the collection.

An exception is thrown if an index with the same name already exists, or if index definition is not correctly formed.

### 参数

`index_name`

  The name of the index that to create. This name must be a valid index name as accepted by the `CREATE INDEX` SQL query.

`index_desc_json`

  Definition of the index to create. It contains an array of IndexField objects, and each object describes a single document member to include in the index, and an optional string for the type of index that might be INDEX (default) or SPATIAL.

  A single IndexField description consists of the following fields:

  - `field`: string, the full document path to the document member or field to be indexed.

  - `type`: string, one of the supported SQL column types to map the field into. For numeric types, the optional UNSIGNED keyword may follow. For the TEXT type, the length to consider for indexing may be added.

  - `required`: bool, (optional) true if the field is required to exist in the document. Defaults to `false`, except for `GEOJSON` where it defaults to `true`.

  - `options`: integer, (optional) special option flags for use when decoding `GEOJSON` data.

  - `srid`: integer, (optional) srid value for use when decoding `GEOJSON` data.

  It is an error to include other fields not described above in IndexDefinition or IndexField documents.

### 返回值

### 示例

示例 #1 mysql_xdevapi\Collection::createIndex() example

    <?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");

    // Creating a text index
    $collection->createIndex(
      'myindex1',
      '{"fields": [{
        "field": "$.name",
        "type": "TEXT(25)",
        "required": true}],
        "unique": false}'
    );

    // A spatial index
    $collection->createIndex(
      'myindex2',
      '{"fields": [{
        "field": "$.home",
        "type": "GEOJSON",
        "required": true}],
        "type": "SPATIAL"}'
    );

    // Index with multiple fields
    $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 — Drop collection index

### 说明

public function mysql_xdevapi\Collection::dropIndex(string `$index_name`): bool

Drop a collection index.

This operation does not yield an error if the index does not exist, but `false` is returned in that case.

### 参数

`index_name`

  Name of collection index to drop.

### 返回值

`true` if the DROP INDEX operation succeeded, otherwise `false`.

### 示例

示例 #1 mysql_xdevapi\Collection::dropIndex() example

    <?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 "An index named 'myindex' was found, and dropped.";
    }
    ?>

以上示例会输出：

    An index named 'myindex' was found, and dropped.

# Collection::existsInDatabase

(No version information available, might only be in Git)

Collection::existsInDatabase — Check if collection exists in database

### 说明

public function mysql_xdevapi\Collection::existsInDatabase(): bool

Checks if the Collection object refers to a collection in the database (schema).

### 参数

此函数没有参数。

### 返回值

Returns `true` if collection exists in the database, else `false` if it does not.

A table defined with two columns (doc and _id) is considered a collection, and a third _json_schema column as of MySQL 8.0.21. Adding an additional column means existsInDatabase() will no longer see it as a collection.

### 示例

示例 #1 mysql_xdevapi\Collection::existsInDatabase() example

    <?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 "The collection no longer exists in the database named addressbook. What happened?";
    }
    ?>

# Collection::find

(No version information available, might only be in Git)

Collection::find — Search for document

### 说明

public function mysql_xdevapi\Collection::find(string `$search_condition` = ?): mysql_xdevapi\CollectionFind

Search a database collection for a document or set of documents. The found documents are returned as a CollectionFind object is to further modify or fetch results from.

### 参数

`search_condition`

  Although optional, normally a condition is defined to limit the results to a subset of documents.

  Multiple elements might build the condition and the syntax supports parameter binding. The expression used as search condition must be a valid SQL expression. If no search condition is provided (field empty) then find('true') is assumed.

### 返回值

A CollectionFind object to verify the operation, or fetch the found documents.

### 示例

示例 #1 mysql_xdevapi\Collection::find() example

    <?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());
    ?>

以上示例会输出：

    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 — Get collection name

### 说明

public function mysql_xdevapi\Collection::getName(): string

Retrieve the collection's name.

### 参数

此函数没有参数。

### 返回值

The collection name, as a string.

### 示例

示例 #1 mysql_xdevapi\Collection::getName() example

    <?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());
    ?>

以上示例的输出类似于：

    string(6) "people"

# Collection::getOne

(No version information available, might only be in Git)

Collection::getOne — Get one document

### 说明

public function mysql_xdevapi\Collection::getOne(string `$id`): Document

Fetches one document from the collection.

This is a shortcut for: `Collection.find("_id = :id").bind("id", id).execute().fetchOne();`

### 参数

`id`

  The document _id in the collection.

### 返回值

The collection object, or `null` if the _id does not match a document.

### 示例

示例 #1 mysql_xdevapi\Collection::getOne() example

    <?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();

    // A unique _id is (by default, and recommended) generated by MySQL Server
    // This retrieves the generated _id's; only one in this example, so $ids[0]
    $ids        = $result->getGeneratedIds();
    $alfreds_id = $ids[0];

    // ...

    print_r($alfreds_id);
    print_r($collection->getOne($alfreds_id));
    ?>

以上示例的输出类似于：

    00005b6b536100000000000000b1

    Array
    (
        [_id] => 00005b6b536100000000000000b1
        [age] => 42
        [job] => Butler
        [name] => Alfred
    )

# Collection::getSchema

(No version information available, might only be in Git)

Collection::getSchema — Get schema object

### 说明

public function mysql_xdevapi\Collection::getSchema(): Schema Object

Retrieve the schema object that contains the collection.

### 参数

此函数没有参数。

### 返回值

The schema object on success, or `null` if the object cannot be retrieved for the given collection.

### 示例

示例 #1 mysql_xdevapi\Collection::getSchema() example

    <?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());
    ?>

以上示例的输出类似于：

    object(mysql_xdevapi\Schema)#9 (1) {
      ["name"]=>
      string(11) "addressbook"
    }

# Collection::getSession

(No version information available, might only be in Git)

Collection::getSession — Get session object

### 说明

public function mysql_xdevapi\Collection::getSession(): Session

Get a new Session object from the Collection object.

### 参数

此函数没有参数。

### 返回值

A Session object.

### 示例

示例 #1 mysql_xdevapi\Collection::getSession() example

    <?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);
    ?>

以上示例的输出类似于：

    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 — Modify collection documents

### 说明

public function mysql_xdevapi\Collection::modify(string `$search_condition`): mysql_xdevapi\CollectionModify

Modify the documents of a collection that meet specific search conditions. Multiple operations are allowed, and parameter binding is supported.

### 参数

`search_condition`

  Must be a valid SQL expression used to match the documents to modify. This expression might be as simple as `true`, which matches all documents, or it might use functions and operators such as `'CAST(_id AS SIGNED) >= 10'`, `'age MOD 2 = 0 OR age MOD 3 = 0'`, or `'_id IN ["2","5","7","10"]'`.

### 返回值

If the operation is not executed, then the function will return a Modify object that can be used to add additional modify operations.

If the modify operation is executed, then the returned object will contain the result of the operation.

### 示例

示例 #1 mysql_xdevapi\Collection::modify() example

    <?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();

    // Add two new jobs for all Painters: Artist and Crafter
    $collection
      ->modify("job in ('Butler', 'Painter')")
      ->arrayAppend('job', 'Artist')
      ->arrayAppend('job', 'Crafter')
      ->execute();

    // Remove the 'beer' field from all documents with the age 21
    $collection
      ->modify('age < 21')
      ->unset(['beer'])
      ->execute();
    ?>

# Collection::remove

(No version information available, might only be in Git)

Collection::remove — Remove collection documents

### 说明

public function mysql_xdevapi\Collection::remove(string `$search_condition`): mysql_xdevapi\CollectionRemove

Removes documents of a collection that meet specific search conditions. Multiple operations are allowed, and parameter binding is supported.

### 参数

`search_condition`

  Must be a valid SQL expression used to match the documents to remove. This expression might be as simple as `true`, which matches all documents, or it might use functions and operators such as `'CAST(_id AS SIGNED) >= 10'`, `'age MOD 2 = 0 OR age MOD 3 = 0'`, or `'_id IN ["2","5","7","10"]'`.

### 返回值

If the operation is not executed, then the function will return a Remove object that can be used to add additional remove operations.

If the remove operation is executed, then the returned object will contain the result of the operation.

### 示例

示例 #1 mysql_xdevapi\Collection::remove() example

    <?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();

    // Remove all painters
    $collection
      ->remove("job in ('Painter')")
      ->execute();

    // Remove the oldest butler
    $collection
      ->remove("job in ('Butler')")
      ->sort('age desc')
      ->limit(1)
      ->execute();

    // Remove record with highest age
    $collection
      ->remove('true')
      ->sort('age desc')
      ->limit(1)
      ->execute();
    ?>

# Collection::removeOne

(No version information available, might only be in Git)

Collection::removeOne — Remove one collection document

### 说明

public function mysql_xdevapi\Collection::removeOne(string `$id`): mysql_xdevapi\Result

Remove one document from the collection with the corresponding ID. This is a shortcut for `Collection.remove("_id = :id").bind("id", id).execute()`.

### 参数

`id`

  The ID of the collection document to remove. Typically this is the _id that was generated by MySQL Server when the record was added.

### 返回值

A Result object that can be used to query the number of affected items or the number warnings generated by the operation.

### 示例

示例 #1 mysql_xdevapi\Collection::removeOne() example

    <?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();

    // Normally the _id is known by other means,
    // but for this example let's fetch the generated id and use it
    $ids       = $result->getGeneratedIds();
    $alfred_id = $ids[0];

    $result = $collection->removeOne($alfred_id);

    if(!$result->getAffectedItemsCount()) {
        echo "Alfred with id $alfred_id was not removed.";
    } else {
        echo "Goodbye, Alfred, you can take _id $alfred_id with you.";
    }
    ?>

以上示例的输出类似于：

    Goodbye, Alfred, you can take _id 00005b6b536100000000000000cb with you.

# Collection::replaceOne

(No version information available, might only be in Git)

Collection::replaceOne — Replace one collection document

### 说明

public function mysql_xdevapi\Collection::replaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result

Updates (or replaces) the document identified by ID, if it exists.

### 参数

`id`

  ID of the document to replace or update. Typically this is the _id that was generated by MySQL Server when the record was added.

`doc`

  Collection document to update or replace the document matching the id parameter.

  This document can be either a document object or a valid JSON string describing the new document.

### 返回值

A Result object that can be used to query the number of affected items and the number warnings generated by the operation.

### 示例

示例 #1 mysql_xdevapi\Collection::replaceOne() example

    <?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();

    // Normally the _id is known by other means,
    // but for this example let's fetch the generated id and use it
    $ids       = $result->getGeneratedIds();
    $alfred_id = $ids[0];

    // ...

    $alfred = $collection->getOne($alfred_id);
    $alfred['age'] = 81;
    $alfred['job'] = 'Guru';

    $collection->replaceOne($alfred_id, $alfred);

    ?>

## 目录

- Collection::add — Add collection document
- Collection::addOrReplaceOne — Add or replace collection document
- Collection::__construct — Collection constructor
- Collection::count — Get document count
- Collection::createIndex — Create collection index
- Collection::dropIndex — Drop collection index
- Collection::existsInDatabase — Check if collection exists in database
- Collection::find — Search for document
- Collection::getName — Get collection name
- Collection::getOne — Get one document
- Collection::getSchema — Get schema object
- Collection::getSession — Get session object
- Collection::modify — Modify collection documents
- Collection::remove — Remove collection documents
- Collection::removeOne — Remove one collection document
- Collection::replaceOne — Replace one collection document

# CollectionAdd class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\CollectionAdd implements mysql_xdevapi\Executable {
/* 方法 */
public function execute(): mysql_xdevapi\Result
}

# CollectionAdd::__construct

(No version information available, might only be in Git)

CollectionAdd::__construct — CollectionAdd constructor

### 说明

private function mysql_xdevapi\CollectionAdd::__construct()

Use to add a document to a collection; called from a Collection object.

### 参数

此函数没有参数。

### 示例

示例 #1 mysql_xdevapi\CollectionAdd::__construct() example

    <?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");

    // Add two documents
    $collection
      ->add('{"name": "Fred",  "age": 21, "job": "Construction"}')
      ->execute();

    $collection
      ->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')
      ->execute();

    // Add two documents using a single JSON object
    $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();

    // Fetch a list of generated ID's from the last add()
    $ids = $result->getGeneratedIds();
    print_r($ids);

    ?>

以上示例的输出类似于：

    Array
    (
        [0] => 00005b6b53610000000000000056
        [1] => 00005b6b53610000000000000057
    )

### 注释

> 注意:

> A unique _id is generated by MySQL Server 8.0 or higher, as demonstrated in the example. The _id field must be manually defined if using MySQL Server 5.7.

# CollectionAdd::execute

(No version information available, might only be in Git)

CollectionAdd::execute — Execute the statement

### 说明

public function mysql_xdevapi\CollectionAdd::execute(): mysql_xdevapi\Result

The execute method is required to send the CRUD operation request to the MySQL server.

### 参数

此函数没有参数。

### 返回值

A Result object that can be used to verify the status of the operation, such as the number of affected rows.

### 示例

示例 #1 mysql_xdevapi\CollectionAdd::execute() example

    <?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");

    // Add two documents
    $collection
      ->add('{"name": "Fred",  "age": 21, "job": "Construction"}')
      ->execute();

    $collection
      ->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')
      ->execute();

    // Add two documents using a single JSON object
    $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();

    // Fetch a list of generated ID's from the last add()
    $ids = $result->getGeneratedIds();
    print_r($ids);
    ?>

以上示例的输出类似于：

    Array
    (
        [0] => 00005b6b53610000000000000056
        [1] => 00005b6b53610000000000000057
    )

## 目录

- CollectionAdd::__construct — CollectionAdd constructor
- CollectionAdd::execute — Execute the statement

# CollectionFind class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\CollectionFind implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSortable {
/* 方法 */
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 — Bind value to query placeholder

### 说明

public function mysql_xdevapi\CollectionFind::bind(array `$placeholder_values`): mysql_xdevapi\CollectionFind

It allows the user to bind a parameter to the placeholder in the search condition of the find operation. The placeholder has the form of :NAME where ':' is a common prefix that must always exists before any NAME, NAME is the actual name of the placeholder. The bind function accepts a list of placeholders if multiple entities have to be substituted in the search condition.

### 参数

`placeholder_values`

  Values to substitute in the search condition; multiple values are allowed and are passed as an array where "PLACEHOLDER_NAME => PLACEHOLDER_VALUE".

### 返回值

A CollectionFind object, or chain with execute() to return a Result object.

### 示例

示例 #1 mysql_xdevapi\CollectionFind::bind() example

    <?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());
    ?>

以上示例的输出类似于：

    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 — CollectionFind constructor

### 说明

private function mysql_xdevapi\CollectionFind::__construct()

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 示例

示例 #1 CollectionFind example

    <?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());
    ?>

以上示例的输出类似于：

    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 — Execute the statement

### 说明

public function mysql_xdevapi\CollectionFind::execute(): mysql_xdevapi\DocResult

Execute the find operation; this functionality allows for method chaining.

### 参数

此函数没有参数。

### 返回值

A mysql_xdevapi\DocResult object that can be used to either fetch results from, or to query the status of the operation.

### 示例

示例 #1 CollectionFind example

    <?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());
    ?>

以上示例的输出类似于：

    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 — Set document field filter

### 说明

public function mysql_xdevapi\CollectionFind::fields(string `$projection`): mysql_xdevapi\CollectionFind

Defines the columns for the query to return. If not defined, all columns are used.

### 参数

`projection`

  Can either be a single string or an array of strings identifying the columns to be returned for each document that match the search condition.

### 返回值

A CollectionFind object that can be used for further processing.

### 示例

示例 #1 mysql_xdevapi\CollectionFind::fields() example

    <?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());
    ?>

以上示例的输出类似于：

    array(1) {
      [0]=>
      array(1) {
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::groupBy

(No version information available, might only be in Git)

CollectionFind::groupBy — Set grouping criteria

### 说明

public function mysql_xdevapi\CollectionFind::groupBy(string `$sort_expr`): mysql_xdevapi\CollectionFind

This function can be used to group the result set by one or more columns. It is often used with aggregate functions such as `COUNT`, `MAX`, `MIN`, `SUM` etc.

### 参数

`sort_expr`

  The column or columns that have to be used for the group operation, this can either be a single string or an array of string arguments, one for each column.

### 返回值

A CollectionFind object that can be used for further processing.

### 示例

示例 #1 mysql_xdevapi\CollectionFind::groupBy() example

    <?php

    // Assuming $coll is a valid Collection object

    // Extract all the documents from the Collection and group the results by the 'name' field
    $res = $coll->find()->groupBy('name')->execute();

    ?>

# CollectionFind::having

(No version information available, might only be in Git)

CollectionFind::having — Set condition for aggregate functions

### 说明

public function mysql_xdevapi\CollectionFind::having(string `$sort_expr`): mysql_xdevapi\CollectionFind

This function can be used after the 'field' operation in order to make a selection on the documents to extract.

### 参数

`sort_expr`

  This must be a valid SQL expression, the use of aggreate functions is allowed

### 返回值

CollectionFind object that can be used for further processing

### 示例

示例 #1 mysql_xdevapi\CollectionFind::having() example

    <?php

    //Assuming $coll is a valid Collection object

    //Find all the documents for which the 'age' is greather than 40,
    //Only the columns 'name' and 'age' are returned in the Result object
    $res = $coll->find()->fields(['name','age'])->having('age > 40')->execute();

    ?>

# CollectionFind::limit

(No version information available, might only be in Git)

CollectionFind::limit — Limit number of returned documents

### 说明

public function mysql_xdevapi\CollectionFind::limit(int `$rows`): mysql_xdevapi\CollectionFind

Set the maximum number of documents to return.

### 参数

`rows`

  Maximum number of documents.

### 返回值

A CollectionFind object that can be used for additional processing; chain with the execute() method to return a DocResult object.

### 示例

示例 #1 mysql_xdevapi\CollectionFind::limit() example

    <?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());
    ?>

以上示例的输出类似于：

    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 — Execute operation with EXCLUSIVE LOCK

### 说明

public function mysql_xdevapi\CollectionFind::lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind

Locks the document exclusively. As long as the document is locked, other transactions can't update the document, use `SELECT ... LOCK IN SHARE MODE`, or read the data in certain transaction isolation levels. Consistent reads ignore any locks set on the records that exist in the read view.

To avoid concurrency problems, it makes sense to use this function with the mysql_xdevapi\Collection::modify() method. Essentially, this function uses row locks to serialise access to rows.

### 参数

`lock_waiting_option`

  Optional waiting option. By default it is `MYSQLX_LOCK_DEFAULT`. Valid values are these constants:

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### 返回值

Returns a CollectionFind object that can be used for further processing.

### 示例

示例 #1 mysql_xdevapi\CollectionFind::lockExclusive() example

    <?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();

    // ... do an operation on the object

    // Complete the transaction and unlock the document
    $session->commit();
    ?>

# CollectionFind::lockShared

(No version information available, might only be in Git)

CollectionFind::lockShared — Execute operation with SHARED LOCK

### 说明

public function mysql_xdevapi\CollectionFind::lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind

Allows to share the documents between multiple transactions which are locking in shared mode.

Other sessions can read the rows, but cannot modify them until your transaction commits.

If any of these rows were changed by another transaction that hasn't been committed, the query will wait until that transaction has ended to be able to use the latest values.

### 参数

`lock_waiting_option`

  Optional waiting option. By default it is `MYSQLX_LOCK_DEFAULT`. Valid values are these constants:

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### 返回值

A CollectionFind object that can be used for further processing

### 示例

示例 #1 mysql_xdevapi\CollectionFind::lockShared() example

    <?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();

    // ... read the object in shared mode

    // Complete the transaction and unlock the document
    $session->commit();
    ?>

# CollectionFind::offset

(No version information available, might only be in Git)

CollectionFind::offset — Skip given number of elements to be returned

### 说明

public function mysql_xdevapi\CollectionFind::offset(int `$position`): mysql_xdevapi\CollectionFind

Skip (offset) these number of elements that otherwise would be returned by the find operation. Use with the limit() method.

Defining an offset larger than the result set size results in an empty set.

### 参数

`position`

  Number of elements to skip for the limit() operation.

### 返回值

A CollectionFind object that can be used for additional processing.

### 示例

示例 #1 mysql_xdevapi\CollectionFind::offset() example

    <?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());
    ?>

以上示例的输出类似于：

    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 — Set the sorting criteria

### 说明

public function mysql_xdevapi\CollectionFind::sort(string `$sort_expr`): mysql_xdevapi\CollectionFind

Sort the result set by the field selected in the sort_expr argument. The allowed orders are ASC (Ascending) or DESC (Descending). This operation is equivalent to the 'ORDER BY' SQL operation and it follows the same set of rules.

### 参数

`sort_expr`

  One or more sorting expressions can be provided. The evaluation is from left to right, and each expression is separated by a comma.

### 返回值

A CollectionFind object that can be used to execute the command, or to add additional operations.

### 示例

示例 #1 mysql_xdevapi\CollectionFind::sort() example

    <?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());
    ?>

以上示例的输出类似于：

    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"
      }
    }

## 目录

- CollectionFind::bind — Bind value to query placeholder
- CollectionFind::__construct — CollectionFind constructor
- CollectionFind::execute — Execute the statement
- CollectionFind::fields — Set document field filter
- CollectionFind::groupBy — Set grouping criteria
- CollectionFind::having — Set condition for aggregate functions
- CollectionFind::limit — Limit number of returned documents
- CollectionFind::lockExclusive — Execute operation with EXCLUSIVE LOCK
- CollectionFind::lockShared — Execute operation with SHARED LOCK
- CollectionFind::offset — Skip given number of elements to be returned
- CollectionFind::sort — Set the sorting criteria

# CollectionModify class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\CollectionModify implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSkippable, mysql_xdevapi\CrudOperationSortable {
/* 方法 */
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 — Append element to an array field

### 说明

public function mysql_xdevapi\CollectionModify::arrayAppend(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Add an element to a document's field, as multiple elements of a field are represented as an array. Unlike arrayInsert(), arrayAppend() always appends the new element at the end of the array, whereas arrayInsert() can define the location.

### 参数

`collection_field`

  The identifier of the field where the new element is inserted.

`expression_or_literal`

  The new element to insert at the end of the document field array.

### 返回值

A CollectionModify object that can be used to execute the command, or to add additional operations.

### 示例

示例 #1 mysql_xdevapi\CollectionModify::arrayAppend() example

    <?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());
    ?>

以上示例的输出类似于：

    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 — Insert element into an array field

### 说明

public function mysql_xdevapi\CollectionModify::arrayInsert(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Adds an element to a document's field, as multiple elements of a field are represented as an array. Unlike mysql_xdevapi\CollectionModify::arrayAppend() this method allows to specify where the new element is inserted by defining which item it is after, whereas mysql_xdevapi\CollectionModify::arrayAppend() always appends the new element at the end of the array.

### 参数

`collection_field`

  Identifies the item in the array after which the new element will be inserted. The format of this parameter is `FIELD_NAME[ INDEX ]` where FIELD_NAME is the name of the document field to add the element to, and INDEX is the INDEX of the element within the field.

  The INDEX field is zero based, so the first item of the array has an index of 0.

`expression_or_literal`

  The new element to insert after FIELD_NAME[ INDEX ]

### 返回值

A CollectionModify object that can be used to execute the command, or to add additional operations

### 示例

示例 #1 mysql_xdevapi\CollectionModify::arrayInsert() example

    <?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());
    ?>

以上示例的输出类似于：

    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 — Bind value to query placeholder

### 说明

public function mysql_xdevapi\CollectionModify::bind(array `$placeholder_values`): mysql_xdevapi\CollectionModify

Bind a parameter to the placeholder in the search condition of the modify operation.

The placeholder has the form of :NAME where ':' is a common prefix that must always exists before any NAME where NAME is the name of the placeholder. The bind method accepts a list of placeholders if multiple entities have to be substituted in the search condition of the modify operation.

### 参数

`placeholder_values`

  Placeholder values to substitute in the search condition. Multiple values are allowed and have to be passed as an array of mappings PLACEHOLDER_NAME->PLACEHOLDER_VALUE.

### 返回值

A CollectionModify object that can be used to execute the command, or to add additional operations.

### 示例

示例 #1 mysql_xdevapi\CollectionModify::bind() example

    <?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());
    ?>

以上示例的输出类似于：

    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 — CollectionModify constructor

### 说明

private function mysql_xdevapi\CollectionModify::__construct()

Modifies (updates) a collection and is instantiated by the mysql_xdevapi\Collection::modify() method.

### 参数

此函数没有参数。

### 示例

示例 #1 mysql_xdevapi\CollectionModify::__construct() example

    <?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());
    ?>

以上示例的输出类似于：

    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 — Execute modify operation

### 说明

public function mysql_xdevapi\CollectionModify::execute(): mysql_xdevapi\Result

The execute method is required to send the CRUD operation request to the MySQL server.

### 参数

此函数没有参数。

### 返回值

A Result object that can be used to verify the status of the operation, such as the number of affected rows.

### 示例

示例 #1 mysql_xdevapi\CollectionModify::execute() example

    <?php

    /* ... */

    ?>

# CollectionModify::limit

(No version information available, might only be in Git)

CollectionModify::limit — Limit number of modified documents

### 说明

public function mysql_xdevapi\CollectionModify::limit(int `$rows`): mysql_xdevapi\CollectionModify

Limit the number of documents modified by this operation. Optionally combine with skip() to define an offset value.

### 参数

`rows`

  The maximum number of documents to modify.

### 返回值

A CollectionModify object.

### 示例

示例 #1 mysql_xdevapi\CollectionModify::limit() example

    <?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());
    ?>

以上示例的输出类似于：

    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 — Patch document

### 说明

public function mysql_xdevapi\CollectionModify::patch(string `$document`): mysql_xdevapi\CollectionModify

Takes a patch object and applies it on one or more documents, and can update multiple document properties.

### 参数

`document`

  A document with the properties to apply to the matching documents.

### 返回值

A CollectionModify object.

### 示例

示例 #1 mysql_xdevapi\CollectionModify::patch() example

    <?php

    $res = $coll->modify('"Programmatore" IN job')->patch('{"Hobby" : "Programmare"}')->execute();

    ?>

# CollectionModify::replace

(No version information available, might only be in Git)

CollectionModify::replace — Replace document field

### 说明

public function mysql_xdevapi\CollectionModify::replace(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Replace (update) a given field value with a new one.

### 参数

`collection_field`

  The document path of the item to set.

`expression_or_literal`

  The value to set on the specified attribute.

### 返回值

A CollectionModify object.

### 示例

示例 #1 mysql_xdevapi\CollectionModify::replace() example

    <?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());
    ?>

以上示例的输出类似于：

    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 — Set document attribute

### 说明

public function mysql_xdevapi\CollectionModify::set(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Sets or updates attributes on documents in a collection.

### 参数

`collection_field`

  The document path (name) of the item to set.

`expression_or_literal`

  The value to set it to.

### 返回值

A CollectionModify object.

### 示例

示例 #1 mysql_xdevapi\CollectionModify::set() example

    <?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());
    ?>

以上示例的输出类似于：

    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 — Skip elements

### 说明

public function mysql_xdevapi\CollectionModify::skip(int `$position`): mysql_xdevapi\CollectionModify

Skips the first N elements that would otherwise be returned by a find operation. If the number of elements skipped is larger than the size of the result set, then the find operation returns an empty set.

### 参数

`position`

  Number of elements to skip.

### 返回值

A CollectionModify object to use for further processing.

### 示例

示例 #1 mysql_xdevapi\CollectionModify::skip() example

    <?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 — Set the sorting criteria

### 说明

public function mysql_xdevapi\CollectionModify::sort(string `$sort_expr`): mysql_xdevapi\CollectionModify

Sorts the result set by the field selected in the sort_expr argument. The allowed orders are ASC (Ascending) or DESC (Descending). This operation is equivalent to the 'ORDER BY' SQL operation and it follows the same set of rules.

### 参数

`sort_expr`

  One or more sort expressions can be provided. The evaluation is from left to right and each expression must be separated by a comma.

### 返回值

CollectionModify object that can be used for further processing.

### 示例

示例 #1 mysql_xdevapi\CollectionModify::sort() example

    <?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 — Unset the value of document fields

### 说明

public function mysql_xdevapi\CollectionModify::unset(array `$fields`): mysql_xdevapi\CollectionModify

Removes attributes from documents in a collection.

### 参数

`fields`

  The attributes to remove from documents in a collection.

### 返回值

CollectionModify object that can be used for further processing.

### 示例

示例 #1 mysql_xdevapi\CollectionModify::unset() example

    <?php

    $res = $coll->modify('job like :job_name')->unset(["age", "name"])->bind(['job_name' => 'Plumber'])->execute();

    ?>

## 目录

- CollectionModify::arrayAppend — Append element to an array field
- CollectionModify::arrayInsert — Insert element into an array field
- CollectionModify::bind — Bind value to query placeholder
- CollectionModify::__construct — CollectionModify constructor
- CollectionModify::execute — Execute modify operation
- CollectionModify::limit — Limit number of modified documents
- CollectionModify::patch — Patch document
- CollectionModify::replace — Replace document field
- CollectionModify::set — Set document attribute
- CollectionModify::skip — Skip elements
- CollectionModify::sort — Set the sorting criteria
- CollectionModify::unset — Unset the value of document fields

# CollectionRemove class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\CollectionRemove implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSortable {
/* 方法 */
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 — Bind value to placeholder

### 说明

public function mysql_xdevapi\CollectionRemove::bind(array `$placeholder_values`): mysql_xdevapi\CollectionRemove

Bind a parameter to the placeholder in the search condition of the remove operation.

The placeholder has the form of :NAME where ':' is a common prefix that must always exists before any NAME where NAME is the name of the placeholder. The bind method accepts a list of placeholders if multiple entities have to be substituted in the search condition of the remove operation.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`placeholder_values`

  Placeholder values to substitute in the search condition. Multiple values are allowed and have to be passed as an array of mappings PLACEHOLDER_NAME->PLACEHOLDER_VALUE.

### 返回值

A CollectionRemove object that can be used to execute the command, or to add additional operations.

### 示例

示例 #1 mysql_xdevapi\CollectionRemove::bind() example

    <?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 — CollectionRemove constructor

### 说明

private function mysql_xdevapi\CollectionRemove::__construct()

Removes collection documents and is instantiated by the mysql_xdevapi\Collection::remove() method.

### 参数

此函数没有参数。

### 示例

示例 #1 mysql_xdevapi\Collection::remove() example

    <?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();

    // Remove all painters
    $collection
      ->remove("job in ('Painter')")
      ->execute();

    // Remove the oldest butler
    $collection
      ->remove("job in ('Butler')")
      ->sort('age desc')
      ->limit(1)
      ->execute();

    // Remove record with lowest age
    $collection
      ->remove('true')
      ->sort('age desc')
      ->limit(1)
      ->execute();
    ?>

# CollectionRemove::execute

(No version information available, might only be in Git)

CollectionRemove::execute — Execute remove operation

### 说明

public function mysql_xdevapi\CollectionRemove::execute(): mysql_xdevapi\Result

The execute function needs to be invoked in order to trigger the client to send the CRUD operation request to the server.

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

Result object.

### 示例

示例 #1 mysql_xdevapi\CollectionRemove::execute() example

    <?php

    $res = $coll->remove('true')->sort('age desc')->limit(2)->execute();

    ?>

# CollectionRemove::limit

(No version information available, might only be in Git)

CollectionRemove::limit — Limit number of documents to remove

### 说明

public function mysql_xdevapi\CollectionRemove::limit(int `$rows`): mysql_xdevapi\CollectionRemove

Sets the maximum number of documents to remove.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`rows`

  The maximum number of documents to remove.

### 返回值

Returns a CollectionRemove object that can be used to execute the command, or to add additional operations.

### 示例

示例 #1 mysql_xdevapi\CollectionRemove::limit() example

    <?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 — Set the sorting criteria

### 说明

public function mysql_xdevapi\CollectionRemove::sort(string `$sort_expr`): mysql_xdevapi\CollectionRemove

Sort the result set by the field selected in the sort_expr argument. The allowed orders are ASC (Ascending) or DESC (Descending). This operation is equivalent to the 'ORDER BY' SQL operation and it follows the same set of rules.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`sort_expr`

  One or more sorting expressions can be provided. The evaluation is from left to right, and each expression is separated by a comma.

### 返回值

A CollectionRemove object that can be used to execute the command, or to add additional operations.

### 示例

示例 #1 mysql_xdevapi\CollectionRemove::sort() example

    <?php

    $res = $coll->remove('true')->sort('age desc')->limit(2)->execute();

    ?>

## 目录

- CollectionRemove::bind — Bind value to placeholder
- CollectionRemove::__construct — CollectionRemove constructor
- CollectionRemove::execute — Execute remove operation
- CollectionRemove::limit — Limit number of documents to remove
- CollectionRemove::sort — Set the sorting criteria

# ColumnResult class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\ColumnResult {
/* 方法 */
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 — ColumnResult constructor

### 说明

private function mysql_xdevapi\ColumnResult::__construct()

Retrieves column metadata, such as its character set; this is instantiated by the mysql_xdevapi\RowResult::getColumns() method.

### 参数

此函数没有参数。

### 示例

示例 #1 mysql_xdevapi\ColumnResult::__construct() example

    <?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();

    // Returns an array of ColumnResult objects
    $columns = $result1->getColumns();

    foreach ($columns as $column) {
        echo "\nColumn label " , $column->getColumnLabel();
        echo " is type "       , $column->getType();
        echo " and is ", ($column->isNumberSigned() === 0) ? "unsigned." : "signed.";
    }

    // Alternatively
    $result2 = $session->sql("SELECT * FROM nonsense.numbers")->execute();

    // Returns an array of FieldMetadata objects
    print_r($result2->getColumns());

以上示例的输出类似于：

    Column label hello is type 19 and is signed.
    Column label world is type 4  and is unsigned.

    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 — Get character set

### 说明

public function mysql_xdevapi\ColumnResult::getCharacterSetName(): string

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

### 示例

示例 #1 mysql_xdevapi\ColumnResult::getCharacterSetName() example

    <?php

    /* ... */

    ?>

# ColumnResult::getCollationName

(No version information available, might only be in Git)

ColumnResult::getCollationName — Get collation name

### 说明

public function mysql_xdevapi\ColumnResult::getCollationName(): string

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

### 示例

示例 #1 mysql_xdevapi\ColumnResult::getCollationName() example

    <?php

    /* ... */

    ?>

# ColumnResult::getColumnLabel

(No version information available, might only be in Git)

ColumnResult::getColumnLabel — Get column label

### 说明

public function mysql_xdevapi\ColumnResult::getColumnLabel(): string

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

### 示例

示例 #1 mysql_xdevapi\ColumnResult::getColumnLabel() example

    <?php

    /* ... */

    ?>

# ColumnResult::getColumnName

(No version information available, might only be in Git)

ColumnResult::getColumnName — Get column name

### 说明

public function mysql_xdevapi\ColumnResult::getColumnName(): string

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

### 示例

示例 #1 mysql_xdevapi\ColumnResult::getColumnName() example

    <?php

    /* ... */

    ?>

# ColumnResult::getFractionalDigits

(No version information available, might only be in Git)

ColumnResult::getFractionalDigits — Get fractional digit length

### 说明

public function mysql_xdevapi\ColumnResult::getFractionalDigits(): int

Fetch the number of fractional digits for column.

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

### 示例

示例 #1 mysql_xdevapi\ColumnResult::getFractionalDigits() example

    <?php

    /* ... */

    ?>

# ColumnResult::getLength

(No version information available, might only be in Git)

ColumnResult::getLength — Get column field length

### 说明

public function mysql_xdevapi\ColumnResult::getLength(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

### 示例

示例 #1 mysql_xdevapi\ColumnResult::getLength() example

    <?php

    /* ... */

    ?>

# ColumnResult::getSchemaName

(No version information available, might only be in Git)

ColumnResult::getSchemaName — Get schema name

### 说明

public function mysql_xdevapi\ColumnResult::getSchemaName(): string

Fetch the schema name where the column is stored.

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

### 示例

示例 #1 mysql_xdevapi\ColumnResult::getSchemaName() example

    <?php

    /* ... */

    ?>

# ColumnResult::getTableLabel

(No version information available, might only be in Git)

ColumnResult::getTableLabel — Get table label

### 说明

public function mysql_xdevapi\ColumnResult::getTableLabel(): string

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

### 示例

示例 #1 mysql_xdevapi\ColumnResult::getTableLabel() example

    <?php

    /* ... */

    ?>

# ColumnResult::getTableName

(No version information available, might only be in Git)

ColumnResult::getTableName — Get table name

### 说明

public function mysql_xdevapi\ColumnResult::getTableName(): string

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

Name of the table for the column.

### 示例

示例 #1 mysql_xdevapi\ColumnResult::getTableName() example

    <?php

    /* ... */

    ?>

# ColumnResult::getType

(No version information available, might only be in Git)

ColumnResult::getType — Get column type

### 说明

public function mysql_xdevapi\ColumnResult::getType(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

### 示例

示例 #1 mysql_xdevapi\ColumnResult::getType() example

    <?php

    /* ... */

    ?>

# ColumnResult::isNumberSigned

(No version information available, might only be in Git)

ColumnResult::isNumberSigned — Check if signed type

### 说明

public function mysql_xdevapi\ColumnResult::isNumberSigned(): int

Retrieves a table's column information and is instantiated by the mysql_xdevapi\RowResult::getColumns() method.

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

`true` if a given column has a signed type.

### 示例

示例 #1 mysql_xdevapi\ColumnResult::isNumberSigned() example

    <?php

    /* ... */

    ?>

# ColumnResult::isPadded

(No version information available, might only be in Git)

ColumnResult::isPadded — Check if padded

### 说明

public function mysql_xdevapi\ColumnResult::isPadded(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

`true` if a given column is padded.

### 示例

示例 #1 mysql_xdevapi\ColumnResult::isPadded() example

    <?php

    /* ... */

    ?>

## 目录

- ColumnResult::__construct — ColumnResult constructor
- ColumnResult::getCharacterSetName — Get character set
- ColumnResult::getCollationName — Get collation name
- ColumnResult::getColumnLabel — Get column label
- ColumnResult::getColumnName — Get column name
- ColumnResult::getFractionalDigits — Get fractional digit length
- ColumnResult::getLength — Get column field length
- ColumnResult::getSchemaName — Get schema name
- ColumnResult::getTableLabel — Get table label
- ColumnResult::getTableName — Get table name
- ColumnResult::getType — Get column type
- ColumnResult::isNumberSigned — Check if signed type
- ColumnResult::isPadded — Check if padded

# CrudOperationBindable interface

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\CrudOperationBindable {
/* 方法 */
abstract public function bind(array `$placeholder_values`): mysql_xdevapi\CrudOperationBindable
}

# CrudOperationBindable::bind

(No version information available, might only be in Git)

CrudOperationBindable::bind — Bind value to placeholder

### 说明

abstract public function mysql_xdevapi\CrudOperationBindable::bind(array `$placeholder_values`): mysql_xdevapi\CrudOperationBindable

Binds a value to a specific placeholder.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`placeholder_values`

  The name of the placeholders and the values to bind.

### 返回值

A CrudOperationBindable object.

### 示例

示例 #1 mysql_xdevapi\CrudOperationBindable::bind() example

    <?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();

    ?>

## 目录

- CrudOperationBindable::bind — Bind value to placeholder

# CrudOperationLimitable interface

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\CrudOperationLimitable {
/* 方法 */
abstract public function limit(int `$rows`): mysql_xdevapi\CrudOperationLimitable
}

# CrudOperationLimitable::limit

(No version information available, might only be in Git)

CrudOperationLimitable::limit — Set result limit

### 说明

abstract public function mysql_xdevapi\CrudOperationLimitable::limit(int `$rows`): mysql_xdevapi\CrudOperationLimitable

Sets the maximum number of records or documents to return.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`rows`

  The maximum number of records or documents.

### 返回值

A CrudOperationLimitable object.

### 示例

示例 #1 mysql_xdevapi\CrudOperationLimitable::limit() example

    <?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();

    ?>

## 目录

- CrudOperationLimitable::limit — Set result limit

# CrudOperationSkippable interface

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\CrudOperationSkippable {
/* 方法 */
abstract public function skip(int `$skip`): mysql_xdevapi\CrudOperationSkippable
}

# CrudOperationSkippable::skip

(No version information available, might only be in Git)

CrudOperationSkippable::skip — Number of operations to skip

### 说明

abstract public function mysql_xdevapi\CrudOperationSkippable::skip(int `$skip`): mysql_xdevapi\CrudOperationSkippable

Skip this number of records in the returned operation.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`skip`

  Number of elements to skip.

### 返回值

A CrudOperationSkippable object.

### 示例

示例 #1 mysql_xdevapi\CrudOperationSkippable::skip() example

    <?php

    $res = $coll->find('job like \'Programmatore\'')->limit(1)->skip(3)->sort('age asc')->execute();

    ?>

## 目录

- CrudOperationSkippable::skip — Number of operations to skip

# CrudOperationSortable interface

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\CrudOperationSortable {
/* 方法 */
abstract public function sort(string `$sort_expr`): mysql_xdevapi\CrudOperationSortable
}

# CrudOperationSortable::sort

(No version information available, might only be in Git)

CrudOperationSortable::sort — Sort results

### 说明

abstract public function mysql_xdevapi\CrudOperationSortable::sort(string `$sort_expr`): mysql_xdevapi\CrudOperationSortable

Sort the result set by the field selected in the sort_expr argument. The allowed orders are ASC (Ascending) or DESC (Descending). This operation is equivalent to the 'ORDER BY' SQL operation and it follows the same set of rules.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`sort_expr`

  One or more sorting expressions can be provided. The evaluation is from left to right, and each expression is separated by a comma.

### 返回值

A CrudOperationSortable object.

### 示例

示例 #1 mysql_xdevapi\CrudOperationSortable::sort() example

    <?php

    $res = $coll->find('job like \'Cavia\'')->sort('age desc', '_id desc')->execute();

    ?>

## 目录

- CrudOperationSortable::sort — Sort results

# DatabaseObject interface

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\DatabaseObject {
/* 方法 */
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 — Check if object exists in database

### 说明

abstract public function mysql_xdevapi\DatabaseObject::existsInDatabase(): bool

Verifies if the database object refers to an object that exists in the database.

### 参数

此函数没有参数。

### 返回值

Returns `true` if object exists in the database, else `false` if it does not.

### 示例

示例 #1 mysql_xdevapi\DatabaseObject::existsInDatabase() example

    <?php

    $existInDb = $dbObj->existsInDatabase();

    ?>

# DatabaseObject::getName

(No version information available, might only be in Git)

DatabaseObject::getName — Get object name

### 说明

abstract public function mysql_xdevapi\DatabaseObject::getName(): string

Fetch name of this database object.

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

The name of this database object.

### 示例

示例 #1 mysql_xdevapi\DatabaseObject::getName() example

    <?php

    $dbObjName = $dbObj->getName();

    ?>

# DatabaseObject::getSession

(No version information available, might only be in Git)

DatabaseObject::getSession — Get session name

### 说明

abstract public function mysql_xdevapi\DatabaseObject::getSession(): mysql_xdevapi\Session

Fetch session associated to the database object.

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

The Session object.

### 示例

示例 #1 mysql_xdevapi\DatabaseObject::getSession() example

    <?php

    $session = $dbObj->getSession();

    ?>

## 目录

- DatabaseObject::existsInDatabase — Check if object exists in database
- DatabaseObject::getName — Get object name
- DatabaseObject::getSession — Get session name

# DocResult class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\DocResult implements mysql_xdevapi\BaseResult, Traversable {
/* 方法 */
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 — DocResult constructor

### 说明

private function mysql_xdevapi\DocResult::__construct()

Fetch document results and warnings, and is instantiated by CollectionFind.

### 参数

此函数没有参数。

### 示例

示例 #1 A DocResult example

    <?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");

    // Yields a DocResult object
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->limit(1)
      ->execute();

    var_dump($result->fetchAll());
    ?>

以上示例的输出类似于：

    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 — Get all rows

### 说明

public function mysql_xdevapi\DocResult::fetchAll(): array

Fetch all results from a result set.

### 参数

此函数没有参数。

### 返回值

A numerical array with all results from the query; each result is an associative array. An empty array is returned if no rows are present.

### 示例

示例 #1 mysql_xdevapi\DocResult::fetchAll() example

    <?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");

    // Yields a DocResult object
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    var_dump($result->fetchAll());
    ?>

以上示例的输出类似于：

    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 — Get one row

### 说明

public function mysql_xdevapi\DocResult::fetchOne(): array

Fetch one result from a result set.

### 参数

此函数没有参数。

### 返回值

The result, as an associative array or `null` if no results are present.

### 示例

示例 #1 mysql_xdevapi\DocResult::fetchOne() example

    <?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");

    // Yields a DocResult object
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    var_dump($result->fetchOne());
    ?>

以上示例的输出类似于：

    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 — Get warnings from last operation

### 说明

public function mysql_xdevapi\DocResult::getWarnings(): Array

Fetches warnings generated by MySQL server's last operation.

### 参数

此函数没有参数。

### 返回值

An array of Warning objects from the last operation. Each object defines an error 'message', error 'level', and error 'code'. An empty array is returned if no errors are present.

### 示例

示例 #1 mysql_xdevapi\DocResult::getWarnings() example

    <?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");

    // Yields a DocResult object
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    if (!$result->getWarningsCount()) {
        echo "There was an error:\n";
        print_r($result->getWarnings());
        exit;
    }

    var_dump($result->fetchOne());
    ?>

以上示例的输出类似于：

    There was an error:

    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 — Get warning count from last operation

### 说明

public function mysql_xdevapi\DocResult::getWarningsCount(): int

Returns the number of warnings raised by the last operation. Specifically, these warnings are raised by the MySQL server.

### 参数

此函数没有参数。

### 返回值

The number of warnings from the last operation.

### 示例

示例 #1 mysql_xdevapi\DocResult::getWarningsCount() example

    <?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");

    // Yields a DocResult object
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    if (!$result->getWarningsCount()) {
        echo "There was an error:\n";
        print_r($result->getWarnings());
        exit;
    }

    var_dump($result->fetchOne());
    ?>

以上示例的输出类似于：

    array(4) {
      ["_id"]=>
      string(28) "00005b6b53610000000000000135"
      ["age"]=>
      int(42)
      ["job"]=>
      string(6) "Butler"
      ["name"]=>
      string(8) "Reginald"
    }

## 目录

- DocResult::__construct — DocResult constructor
- DocResult::fetchAll — Get all rows
- DocResult::fetchOne — Get one row
- DocResult::getWarnings — Get warnings from last operation
- DocResult::getWarningsCount — Get warning count from last operation

# Exception class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\Exception extends RuntimeException implements Throwable {
}

# Executable interface

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\Executable {
/* 方法 */
abstract public function execute(): mysql_xdevapi\Result
}

# Executable::execute

(No version information available, might only be in Git)

Executable::execute — Execute statement

### 说明

abstract public function mysql_xdevapi\Executable::execute(): mysql_xdevapi\Result

Execute the statement from either a collection operation or a table query; this functionality allows for method chaining.

### 参数

此函数没有参数。

### 返回值

One of the Result objects, such as Result or SqlStatementResult.

### 示例

示例 #1 execute() examples

    <?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);
    ?>

以上示例的输出类似于：

    object(mysql_xdevapi\SqlStatementResult)#3 (0) {
    }

    object(mysql_xdevapi\CollectionAdd)#5 (0) {
    }

    object(mysql_xdevapi\Result)#7 (0) {
    }

## 目录

- Executable::execute — Execute statement

# ExecutionStatus class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\ExecutionStatus {
/* 属性 */
public $affectedItems;
public $matchedItems;
public $foundItems;
public $lastInsertId;
public $lastDocumentId;
/* Constructor */
private function __construct()
}

## 属性

affectedItems

matchedItems

foundItems

lastInsertId

lastDocumentId

# ExecutionStatus::__construct

(No version information available, might only be in Git)

ExecutionStatus::__construct — ExecutionStatus constructor

### 说明

private function mysql_xdevapi\ExecutionStatus::__construct()

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 示例

示例 #1 mysql_xdevapi\ExecutionStatus::__construct() example

    <?php

    /* ... */

    ?>

## 目录

- ExecutionStatus::__construct — ExecutionStatus constructor

# Expression class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\Expression {
/* 属性 */
public $name;
/* Constructor */
public function __construct(string `$expression`)
}

## 属性

name

# Expression::__construct

(No version information available, might only be in Git)

Expression::__construct — Expression constructor

### 说明

public function mysql_xdevapi\Expression::__construct(string `$expression`)

警告

本函数还未编写文档，仅有参数列表。

### 参数

`expression`

### 示例

示例 #1 mysql_xdevapi\Expression::__construct() example

    <?php

    /* ... */

    ?>

## 目录

- Expression::__construct — Expression constructor

# Result class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\Result implements mysql_xdevapi\BaseResult, Traversable {
/* 方法 */
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 — Result constructor

### 说明

private function mysql_xdevapi\Result::__construct()

An object that retrieves generated IDs, AUTO_INCREMENT values, and warnings, for a Result set.

### 参数

此函数没有参数。

### 示例

示例 #1 mysql_xdevapi\Result::__construct() example

    <?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);
    ?>

以上示例会输出：

    int(3)

# Result::getAffectedItemsCount

(No version information available, might only be in Git)

Result::getAffectedItemsCount — Get affected row count

### 说明

public function mysql_xdevapi\Result::getAffectedItemsCount(): int

Get the number of affected rows by the previous operation.

### 参数

此函数没有参数。

### 返回值

The number (as an integer) of affected rows.

### 示例

示例 #1 mysql_xdevapi\Result::getAffectedItemsCount() example

    <?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() );
    ?>

以上示例会输出：

    int(1)

# Result::getAutoIncrementValue

(No version information available, might only be in Git)

Result::getAutoIncrementValue — Get autoincremented value

### 说明

public function mysql_xdevapi\Result::getAutoIncrementValue(): int

Get the last AUTO_INCREMENT value (last insert id).

### 参数

此函数没有参数。

### 返回值

The last AUTO_INCREMENT value.

### 示例

示例 #1 mysql_xdevapi\Result::getAutoIncrementValue() example

    <?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);
    ?>

以上示例会输出：

    int(3)

# Result::getGeneratedIds

(No version information available, might only be in Git)

Result::getGeneratedIds — Get generated ids

### 说明

public function mysql_xdevapi\Result::getGeneratedIds(): array

Fetch the generated _id values from the last operation. The unique _id field is generated by the MySQL server.

### 参数

此函数没有参数。

### 返回值

An array of generated _id's from the last operation, or an empty array if there are none.

### 示例

示例 #1 mysql_xdevapi\Result::getGeneratedIds() example

    <?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);
    ?>

以上示例的输出类似于：

    array(2) {
      [0]=>
      string(28) "00005b6b53610000000000000064"
      [1]=>
      string(28) "00005b6b53610000000000000065"
    }

# Result::getWarnings

(No version information available, might only be in Git)

Result::getWarnings — Get warnings from last operation

### 说明

public function mysql_xdevapi\Result::getWarnings(): array

Retrieve warnings from the last Result operation.

### 参数

此函数没有参数。

### 返回值

An array of Warning objects from the last operation. Each object defines an error 'message', error 'level', and error 'code'. An empty array is returned if no errors are present.

### 示例

示例 #1 mysql_xdevapi\RowResult::getWarnings() example

    <?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);
    ?>

以上示例的输出类似于：

    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 — Get warning count from last operation

### 说明

public function mysql_xdevapi\Result::getWarningsCount(): int

Retrieve the number of warnings from the last Result operation.

### 参数

此函数没有参数。

### 返回值

The number of warnings generated by the last operation.

### 示例

示例 #1 mysql_xdevapi\RowResult::getWarningsCount() example

    <?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();
    ?>

以上示例的输出类似于：

    2

## 目录

- Result::__construct — Result constructor
- Result::getAffectedItemsCount — Get affected row count
- Result::getAutoIncrementValue — Get autoincremented value
- Result::getGeneratedIds — Get generated ids
- Result::getWarnings — Get warnings from last operation
- Result::getWarningsCount — Get warning count from last operation

# RowResult class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\RowResult implements mysql_xdevapi\BaseResult, Traversable {
/* 方法 */
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 — RowResult constructor

### 说明

private function mysql_xdevapi\RowResult::__construct()

Represents the result set obtained from querying the database.

### 参数

此函数没有参数。

### 示例

示例 #1 mysql_xdevapi\RowResult::__construct() example

    <?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);

以上示例的输出类似于：

    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 — Get all rows from result

### 说明

public function mysql_xdevapi\RowResult::fetchAll(): array

Fetch all the rows from the result set.

### 参数

此函数没有参数。

### 返回值

A numerical array with all results from the query; each result is an associative array. An empty array is returned if no rows are present.

### 示例

示例 #1 mysql_xdevapi\RowResult::fetchAll() example

    <?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);

以上示例的输出类似于：

    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 — Get row from result

### 说明

public function mysql_xdevapi\RowResult::fetchOne(): array

Fetch one result from the result set.

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

The result, as an associative array or `null` if no results are present.

### 示例

示例 #1 mysql_xdevapi\RowResult::fetchOne() example

    <?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);

以上示例的输出类似于：

    Array
    (
        [name] => Sam
        [age] => 33
    )

# RowResult::getColumnsCount

(No version information available, might only be in Git)

RowResult::getColumnsCount — Get column count

### 说明

public function mysql_xdevapi\RowResult::getColumnsCount(): int

Retrieve the column count for columns present in the result set.

### 参数

此函数没有参数。

### 返回值

The number of columns; 0 if there are none.

### 更新日志

版本 | 说明
--- | ---
8.0.14 | Method renamed from getColumnCount() to getColumnsCount().

### 示例

示例 #1 mysql_xdevapi\RowResult::getColumnsCount() example

    <?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();

以上示例的输出类似于：

    2

# RowResult::getColumnNames

(No version information available, might only be in Git)

RowResult::getColumnNames — Get all column names

### 说明

public function mysql_xdevapi\RowResult::getColumnNames(): array

Retrieve column names for columns present in the result set.

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

A numerical array of table columns names, or an empty array if the result set is empty.

### 示例

示例 #1 mysql_xdevapi\RowResult::getColumnNames() example

    <?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);

以上示例的输出类似于：

    Array
    (
        [0] => name
        [1] => age
    )

# RowResult::getColumns

(No version information available, might only be in Git)

RowResult::getColumns — Get column metadata

### 说明

public function mysql_xdevapi\RowResult::getColumns(): array

Retrieve column metadata for columns present in the result set.

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

An array of FieldMetadata objects representing the columns in the result, or an empty array if the result set is empty.

### 示例

示例 #1 mysql_xdevapi\RowResult::getColumns() example

    <?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);

以上示例的输出类似于：

    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 — Get warnings from last operation

### 说明

public function mysql_xdevapi\RowResult::getWarnings(): array

Retrieve warnings from the last RowResult operation.

### 参数

此函数没有参数。

### 返回值

An array of Warning objects from the last operation. Each object defines an error 'message', error 'level', and error 'code'. An empty array is returned if no errors are present.

### 示例

示例 #1 mysql_xdevapi\RowResult::getWarnings() example

    <?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);
    ?>

以上示例的输出类似于：

    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 — Get warning count from last operation

### 说明

public function mysql_xdevapi\RowResult::getWarningsCount(): int

Retrieve the number of warnings from the last RowResult operation.

### 参数

此函数没有参数。

### 返回值

The number of warnings generated by the last operation.

### 示例

示例 #1 mysql_xdevapi\RowResult::getWarningsCount() example

    <?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();
    ?>

以上示例的输出类似于：

    2

## 目录

- RowResult::__construct — RowResult constructor
- RowResult::fetchAll — Get all rows from result
- RowResult::fetchOne — Get row from result
- RowResult::getColumnsCount — Get column count
- RowResult::getColumnNames — Get all column names
- RowResult::getColumns — Get column metadata
- RowResult::getWarnings — Get warnings from last operation
- RowResult::getWarningsCount — Get warning count from last operation

# Schema class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\Schema implements mysql_xdevapi\DatabaseObject {
/* 属性 */
public $name;
/* 方法 */
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
}

## 属性

name

# Schema::__construct

(No version information available, might only be in Git)

Schema::__construct — Schema constructor

### 说明

private function mysql_xdevapi\Schema::__construct()

The Schema object provides full access to the schema (database).

### 参数

此函数没有参数。

### 示例

示例 #1 mysql_xdevapi\Schema::__construct() example

    <?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());

以上示例的输出类似于：

    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 — Add collection to schema

### 说明

public function mysql_xdevapi\Schema::createCollection(string `$name`, string `$validate` = ?): mysql_xdevapi\Collection

Create a collection within the schema.

### 参数

`name`

  Collection name.

`validate`

  Validation definition, as a JSON object.

### 返回值

The Collection object.

### 更新日志

版本 | 说明
--- | ---
8.0.20 | Added the optional validate parameter.

### 示例

示例 #1 mysql_xdevapi\Schema::createCollection() example

    <?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());

以上示例的输出类似于：

    Array
    (
        [fruit] => mysql_xdevapi\Table Object
            (
                [name] => fruit
            )
    )
    Array
    (
        [trees] => mysql_xdevapi\Collection Object
            (
                [name] => trees
            )
    )

示例 #2 mysql_xdevapi\Schema::createCollection() example

    <?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"]
            }
        }
    }');
    // Succeeds
    $collection->add('{"latitude": 10, "longitude": 20}')->execute();

    // Fails, invalid types (not numbers)
    $collection->add('{"latitude": "lat", "longitude": "long"}')->execute();

# Schema::dropCollection

(No version information available, might only be in Git)

Schema::dropCollection — Drop collection from schema

### 说明

public function mysql_xdevapi\Schema::dropCollection(string `$collection_name`): bool

警告

本函数还未编写文档，仅有参数列表。

### 参数

`collection_name`

### 返回值

### 示例

示例 #1 mysql_xdevapi\Schema::dropCollection() example

    <?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());

以上示例的输出类似于：

    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 — Check if exists in database

### 说明

public function mysql_xdevapi\Schema::existsInDatabase(): bool

Checks if the current object (schema, table, collection, or view) exists in the schema object.

### 参数

此函数没有参数。

### 返回值

`true` if the schema, table, collection, or view still exists in the schema, else `false`.

### 示例

示例 #1 mysql_xdevapi\Schema::existsInDatabase() example

    <?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");

    // ...

    // Is this collection still in the database (schema)?
    if ($trees->existsInDatabase()) {
        echo "Yes, the 'trees' collection is still present.";
    }

以上示例的输出类似于：

    Yes, the 'trees' collection is still present.

# Schema::getCollection

(No version information available, might only be in Git)

Schema::getCollection — Get collection from schema

### 说明

public function mysql_xdevapi\Schema::getCollection(string `$name`): mysql_xdevapi\Collection

Get a collection from the schema.

### 参数

`name`

  Collection name to retrieve.

### 返回值

The Collection object for the selected collection.

### 示例

示例 #1 mysql_xdevapi\Schema::getCollection() example

    <?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);

以上示例的输出类似于：

    object(mysql_xdevapi\Collection)#3 (1) {
      ["name"]=>
      string(5) "trees"
    }

# Schema::getCollectionAsTable

(No version information available, might only be in Git)

Schema::getCollectionAsTable — Get collection as a Table object

### 说明

public function mysql_xdevapi\Schema::getCollectionAsTable(string `$name`): mysql_xdevapi\Table

Get a collection, but as a Table object instead of a Collection object.

### 参数

`name`

  Name of the collection to instantiate a Table object from.

### 返回值

A mysql_xdevapi\Table object for the collection.

### 示例

示例 #1 mysql_xdevapi\Schema::getCollectionAsTable() example

    <?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);

以上示例的输出类似于：

    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 — Get all schema collections

### 说明

public function mysql_xdevapi\Schema::getCollections(): array

Fetch a list of collections for this schema.

### 参数

此函数没有参数。

### 返回值

Array of all collections in this schema, where each array element value is a Collection object with the collection name as the key.

### 示例

示例 #1 mysql_xdevapi\Schema::getCollections() example

    <?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);
    ?>

以上示例的输出类似于：

    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 — Get schema name

### 说明

public function mysql_xdevapi\Schema::getName(): string

Get the name of the schema.

### 参数

此函数没有参数。

### 返回值

The name of the schema connected to the schema object, as a string.

### 示例

示例 #1 mysql_xdevapi\Schema::getName() example

    <?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());
    ?>

以上示例的输出类似于：

    string(11) "addressbook"

# Schema::getSession

(No version information available, might only be in Git)

Schema::getSession — Get schema session

### 说明

public function mysql_xdevapi\Schema::getSession(): mysql_xdevapi\Session

Get a new Session object from the Schema object.

### 参数

此函数没有参数。

### 返回值

A Session object.

### 示例

示例 #1 mysql_xdevapi\Schema::getSession() example

    <?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);
    ?>

以上示例的输出类似于：

    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 — Get schema table

### 说明

public function mysql_xdevapi\Schema::getTable(string `$name`): mysql_xdevapi\Table

Fetch a Table object for the provided table in the schema.

### 参数

`name`

  Name of the table.

### 返回值

A Table object.

### 示例

示例 #1 mysql_xdevapi\Schema::getTable() example

    <?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);
    ?>

以上示例的输出类似于：

    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 — Get schema tables

### 说明

public function mysql_xdevapi\Schema::getTables(): array

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

Array of all tables in this schema, where each array element value is a Table object with the table name as the key.

### 示例

示例 #1 mysql_xdevapi\Schema::getTables() example

    <?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);
    ?>

以上示例的输出类似于：

    array(2) {
      ["cities"]=>
      object(mysql_xdevapi\Table)#3 (1) {
        ["name"]=>
        string(6) "cities"
      }

      ["names"]=>
      object(mysql_xdevapi\Table)#4 (1) {
        ["name"]=>
        string(5) "names"
      }
    }

## 目录

- Schema::__construct — Schema constructor
- Schema::createCollection — Add collection to schema
- Schema::dropCollection — Drop collection from schema
- Schema::existsInDatabase — Check if exists in database
- Schema::getCollection — Get collection from schema
- Schema::getCollectionAsTable — Get collection as a Table object
- Schema::getCollections — Get all schema collections
- Schema::getName — Get schema name
- Schema::getSession — Get schema session
- Schema::getTable — Get schema table
- Schema::getTables — Get schema tables

# SchemaObject interface

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\SchemaObject implements mysql_xdevapi\DatabaseObject {
/* 方法 */
abstract function getSchema(): mysql_xdevapi\Schema
}

# SchemaObject::getSchema

(No version information available, might only be in Git)

SchemaObject::getSchema — Get schema object

### 说明

abstract function mysql_xdevapi\SchemaObject::getSchema(): mysql_xdevapi\Schema

Used by other objects to retrieve a schema object.

### 参数

此函数没有参数。

### 返回值

The current Schema object.

### 示例

示例 #1 mysql_xdevapi\Session::getSchema() example

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $schema  = $session->getSchema("addressbook");

    print_r($schema);

以上示例的输出类似于：

    mysql_xdevapi\Schema Object
    (
        [name] => addressbook
    )

## 目录

- SchemaObject::getSchema — Get schema object

# Session class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\Session {
/* 方法 */
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 — Close session

### 说明

public function mysql_xdevapi\Session::close(): bool

Close the session with the server.

### 参数

此函数没有参数。

### 返回值

`true` if the session closed.

### 示例

示例 #1 mysql_xdevapi\Session::close() example

    <?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 — Commit transaction

### 说明

public function mysql_xdevapi\Session::commit(): Object

Commit the transaction.

### 参数

此函数没有参数。

### 返回值

An SqlStatementResult object.

### 示例

示例 #1 mysql_xdevapi\Session::commit() example

    <?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 — Description constructor

### 说明

private function mysql_xdevapi\Session::__construct()

A Session object, as initiated by getSession().

### 参数

此函数没有参数。

### 示例

示例 #1 mysql_xdevapi\Session::__construct() example

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->close();
    ?>

# Session::createSchema

(No version information available, might only be in Git)

Session::createSchema — Create new schema

### 说明

public function mysql_xdevapi\Session::createSchema(string `$schema_name`): mysql_xdevapi\Schema

Creates a new schema.

### 参数

`schema_name`

  Name of the schema to create.

### 返回值

A Schema object on success, and emits an exception on failure.

### 示例

示例 #1 mysql_xdevapi\Session::createSchema() example

    <?php
    $uri  = 'mysqlx://happyuser:password@127.0.0.1:33060/';
    $sess = mysql_xdevapi\getSession($uri);

    try {

        if ($schema = $sess->createSchema('fruit')) {
            echo "Info: I created a schema named 'fruit'\n";
        }

    } catch (Exception $e) {

       echo $e->getMessage();

    }
    ?>

以上示例的输出类似于：

    Info: I created a schema named 'fruit'

# Session::dropSchema

(No version information available, might only be in Git)

Session::dropSchema — Drop a schema

### 说明

public function mysql_xdevapi\Session::dropSchema(string `$schema_name`): bool

Drop a schema (database).

### 参数

`schema_name`

  Name of the schema to drop.

### 返回值

`true` if the schema is dropped, or `false` if it does not exist or can't be dropped.

An `E_WARNING` level error is generated if the schema does not exist.

### 示例

示例 #1 mysql_xdevapi\Session::dropSchema() example

    <?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 — Get new UUID

### 说明

public function mysql_xdevapi\Session::generateUUID(): string

Generate a Universal Unique IDentifier (UUID) generated according to » RFC 4122.

### 参数

此函数没有参数。

### 返回值

The UUID; a string with a length of 32.

### 示例

示例 #1 mysql_xdevapi\Session::generateUuid() example

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $uuid = $session->generateUuid();

    var_dump($uuid);

以上示例的输出类似于：

    string(32) "484B18AC7980F8D4FE84613CDA5EE84B"

# Session::getDefaultSchema

(No version information available, might only be in Git)

Session::getDefaultSchema — Get default schema name

### 说明

public function mysql_xdevapi\Session::getDefaultSchema(): ?mysql_xdevapi\Schema

Retrieve the default schema that's typically set in the connection URI.

### 参数

此函数没有参数。

### 返回值

The default schema defined by the connection, or `null` if one was not set.

### 示例

示例 #1 mysql_xdevapi\Session::getSchema() example

    <?php
    $uri = "mysqlx://testuser:testpasswd@localhost:33160/testx?ssl-mode=disabled";
    $session = mysql_xdevapi\getSession($uri);

    $schema = $session->getDefaultSchema();
    echo $schema->getName();
    ?>

以上示例会输出：

    testx

# Session::getSchema

(No version information available, might only be in Git)

Session::getSchema — Get a new schema object

### 说明

public function mysql_xdevapi\Session::getSchema(string `$schema_name`): mysql_xdevapi\Schema

A new Schema object for the provided schema name.

### 参数

`schema_name`

  Name of the schema (database) to fetch a Schema object for.

### 返回值

A Schema object.

### 示例

示例 #1 mysql_xdevapi\Session::getSchema() example

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $schema  = $session->getSchema("addressbook");

    print_r($schema);

以上示例的输出类似于：

    mysql_xdevapi\Schema Object
    (
        [name] => addressbook
    )

# Session::getSchemas

(No version information available, might only be in Git)

Session::getSchemas — Get the schemas

### 说明

public function mysql_xdevapi\Session::getSchemas(): array

Get schema objects for all schemas available to the session.

### 参数

此函数没有参数。

### 返回值

An array containing objects that represent all of the schemas available to the session.

### 示例

示例 #1 mysql_xdevapi\Session::getSchemas() example

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $schemas  = $session->getSchemas();

    print_r($schemas);

以上示例的输出类似于：

    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 — Get server version

### 说明

public function mysql_xdevapi\Session::getServerVersion(): int

Retrieve the MySQL server version for the session.

### 参数

此函数没有参数。

### 返回值

The MySQL server version for the session, as an integer such as "80012".

### 示例

示例 #1 mysql_xdevapi\Session::getServerVersion() example

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $version = $session->getServerVersion();

    var_dump($version);

以上示例的输出类似于：

    int(80012)

# Session::listClients

(No version information available, might only be in Git)

Session::listClients — Get client list

### 说明

public function mysql_xdevapi\Session::listClients(): array

Get a list of client connections to the session's MySQL server.

### 参数

此函数没有参数。

### 返回值

An array containing the currently logged clients. The array elements are "client_id", "user", "host", and "sql_session".

### 示例

示例 #1 mysql_xdevapi\Session::listClients() example

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $ids = $session->listClients();

    var_dump($ids);
    ?>

以上示例的输出类似于：

    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 — Add quotes

### 说明

public function mysql_xdevapi\Session::quoteName(string `$name`): string

A quoting function to escape SQL names and identifiers. It escapes the identifier given in accordance to the settings of the current connection. This escape function should not be used to escape values.

### 参数

`name`

  The string to quote.

### 返回值

The quoted string.

### 示例

示例 #1 mysql_xdevapi\Session::quoteName() example

    <?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));
    ?>

以上示例的输出类似于：

    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 — Release set savepoint

### 说明

public function mysql_xdevapi\Session::releaseSavepoint(string `$name`): void

Release a previously set savepoint.

### 参数

`name`

  Name of the savepoint to release.

### 返回值

An SqlStatementResult object.

### 示例

示例 #1 mysql_xdevapi\Session::releaseSavepoint() example

    <?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 — Rollback transaction

### 说明

public function mysql_xdevapi\Session::rollback(): void

Rollback the transaction.

### 参数

此函数没有参数。

### 返回值

An SqlStatementResult object.

### 示例

示例 #1 mysql_xdevapi\Session::rollback() example

    <?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 — Rollback transaction to savepoint

### 说明

public function mysql_xdevapi\Session::rollbackTo(string `$name`): void

Rollback the transaction back to the savepoint.

### 参数

`name`

  Name of the savepoint to rollback to; case-insensitive.

### 返回值

An SqlStatementResult object.

### 示例

示例 #1 mysql_xdevapi\Session::rollbackTo() example

    <?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 — Create savepoint

### 说明

public function mysql_xdevapi\Session::setSavepoint(string `$name` = ?): string

Create a new savepoint for the transaction.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`name`

  The name of the savepoint. The name is auto-generated if the optional `name` parameter is not defined as 'SAVEPOINT1', 'SAVEPOINT2', and so on.

### 返回值

The name of the save point.

### 示例

示例 #1 mysql_xdevapi\Session::setSavepoint() example

    <?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 — Create SQL query

### 说明

public function mysql_xdevapi\Session::sql(string `$query`): mysql_xdevapi\SqlStatement

Create a native SQL statement. Placeholders are supported using the native "?" syntax. Use the `execute` method to execute the SQL statement.

### 参数

`query`

  SQL statement to execute.

### 返回值

An SqlStatement object.

### 示例

示例 #1 mysql_xdevapi\Session::sql() example

    <?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 — Start transaction

### 说明

public function mysql_xdevapi\Session::startTransaction(): void

Start a new transaction.

### 参数

此函数没有参数。

### 返回值

An SqlStatementResult object.

### 示例

示例 #1 mysql_xdevapi\Session::startTransaction() example

    <?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::close — Close session
- Session::commit — Commit transaction
- Session::__construct — Description constructor
- Session::createSchema — Create new schema
- Session::dropSchema — Drop a schema
- Session::generateUUID — Get new UUID
- Session::getDefaultSchema — Get default schema name
- Session::getSchema — Get a new schema object
- Session::getSchemas — Get the schemas
- Session::getServerVersion — Get server version
- Session::listClients — Get client list
- Session::quoteName — Add quotes
- Session::releaseSavepoint — Release set savepoint
- Session::rollback — Rollback transaction
- Session::rollbackTo — Rollback transaction to savepoint
- Session::setSavepoint — Create savepoint
- Session::sql — Create SQL query
- Session::startTransaction — Start transaction

# SqlStatement class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\SqlStatement {
/* 常量 */
const int EXECUTE_ASYNC = 1;
const int BUFFERED = 2;
/* 属性 */
public $statement;
/* 方法 */
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
}

## 属性

statement

## 预定义常量

`mysql_xdevapi\SqlStatement::EXECUTE_ASYNC`

`mysql_xdevapi\SqlStatement::BUFFERED`

# SqlStatement::bind

(No version information available, might only be in Git)

SqlStatement::bind — Bind statement parameters

### 说明

public function mysql_xdevapi\SqlStatement::bind(string `$param`): mysql_xdevapi\SqlStatement

警告

本函数还未编写文档，仅有参数列表。

### 参数

`param`

### 返回值

### 示例

示例 #1 mysql_xdevapi\SqlStatement::bind() example

    <?php

    /* ... */

    ?>

# SqlStatement::__construct

(No version information available, might only be in Git)

SqlStatement::__construct — Description constructor

### 说明

private function mysql_xdevapi\SqlStatement::__construct()

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 示例

示例 #1 mysql_xdevapi\SqlStatement::__construct() example

    <?php

    /* ... */

    ?>

# SqlStatement::execute

(No version information available, might only be in Git)

SqlStatement::execute — Execute the operation

### 说明

public function mysql_xdevapi\SqlStatement::execute(): mysql_xdevapi\Result

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

### 示例

示例 #1 mysql_xdevapi\SqlStatement::execute() example

    <?php

    /* ... */

    ?>

# SqlStatement::getNextResult

(No version information available, might only be in Git)

SqlStatement::getNextResult — Get next result

### 说明

public function mysql_xdevapi\SqlStatement::getNextResult(): mysql_xdevapi\Result

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

### 示例

示例 #1 mysql_xdevapi\SqlStatement::getNextResult() example

    <?php

    /* ... */

    ?>

# SqlStatement::getResult

(No version information available, might only be in Git)

SqlStatement::getResult — Get result

### 说明

public function mysql_xdevapi\SqlStatement::getResult(): mysql_xdevapi\Result

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

### 示例

示例 #1 mysql_xdevapi\SqlStatement::getResult() example

    <?php

    /* ... */

    ?>

# SqlStatement::hasMoreResults

(No version information available, might only be in Git)

SqlStatement::hasMoreResults — Check for more results

### 说明

public function mysql_xdevapi\SqlStatement::hasMoreResults(): bool

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

`true` if the result set has more objects to fetch.

### 示例

示例 #1 mysql_xdevapi\SqlStatement::hasMoreResults() example

    <?php

    /* ... */

    ?>

## 目录

- SqlStatement::bind — Bind statement parameters
- SqlStatement::__construct — Description constructor
- SqlStatement::execute — Execute the operation
- SqlStatement::getNextResult — Get next result
- SqlStatement::getResult — Get result
- SqlStatement::hasMoreResults — Check for more results

# SqlStatementResult class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\SqlStatementResult implements mysql_xdevapi\BaseResult, Traversable {
/* 方法 */
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 — Description constructor

### 说明

private function mysql_xdevapi\SqlStatementResult::__construct()

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 示例

示例 #1 mysql_xdevapi\SqlStatementResult::__construct() example

    <?php

    /* ... */

    ?>

# SqlStatementResult::fetchAll

(No version information available, might only be in Git)

SqlStatementResult::fetchAll — Get all rows from result

### 说明

public function mysql_xdevapi\SqlStatementResult::fetchAll(): array

Fetch all the rows from the result set.

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

A numerical array with all results from the query; each result is an associative array. An empty array is returned if no rows are present.

### 示例

示例 #1 mysql_xdevapi\SqlStatementResult::fetchAll() example

    <?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);
    ?>

以上示例的输出类似于：

    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 — Get single row

### 说明

public function mysql_xdevapi\SqlStatementResult::fetchOne(): array

Fetch one row from the result set.

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

The result, as an associative array. In case there is not any result, null will be returned.

### 示例

示例 #1 mysql_xdevapi\SqlStatementResult::fetchOne() example

    <?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);
    ?>

以上示例的输出类似于：

    Array
    (
        [name] => John
        [age] => 42
        [job] => bricklayer
    )

# SqlStatementResult::getAffectedItemsCount

(No version information available, might only be in Git)

SqlStatementResult::getAffectedItemsCount — Get affected row count

### 说明

public function mysql_xdevapi\SqlStatementResult::getAffectedItemsCount(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

### 示例

示例 #1 mysql_xdevapi\SqlStatementResult::getAffectedItemsCount() example

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumnsCount

(No version information available, might only be in Git)

SqlStatementResult::getColumnsCount — Get column count

### 说明

public function mysql_xdevapi\SqlStatementResult::getColumnsCount(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

The number of columns; 0 if there are none.

### 更新日志

版本 | 说明
--- | ---
8.0.14 | Method renamed from getColumnCount() to getColumnsCount().

### 示例

示例 #1 mysql_xdevapi\SqlStatementResult::getColumnsCount() example

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumnNames

(No version information available, might only be in Git)

SqlStatementResult::getColumnNames — Get column names

### 说明

public function mysql_xdevapi\SqlStatementResult::getColumnNames(): array

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

### 示例

示例 #1 mysql_xdevapi\SqlStatementResult::getColumnNames() example

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumns

(No version information available, might only be in Git)

SqlStatementResult::getColumns — Get columns

### 说明

public function mysql_xdevapi\SqlStatementResult::getColumns(): Array

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

### 示例

示例 #1 mysql_xdevapi\SqlStatementResult::getColumns() example

    <?php

    /* ... */

    ?>

# SqlStatementResult::getGeneratedIds

(No version information available, might only be in Git)

SqlStatementResult::getGeneratedIds — Get generated ids

### 说明

public function mysql_xdevapi\SqlStatementResult::getGeneratedIds(): array

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

An array of generated _id's from the last operation, or an empty array if there are none.

### 示例

示例 #1 mysql_xdevapi\SqlStatementResult::getGeneratedIds() example

    <?php

    /* ... */

    ?>

# SqlStatementResult::getLastInsertId

(No version information available, might only be in Git)

SqlStatementResult::getLastInsertId — Get last insert id

### 说明

public function mysql_xdevapi\SqlStatementResult::getLastInsertId(): String

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

The ID for the last insert operation.

### 示例

示例 #1 mysql_xdevapi\SqlStatementResult::getLastInsertId() example

    <?php

    /* ... */

    ?>

# SqlStatementResult::getWarnings

(No version information available, might only be in Git)

SqlStatementResult::getWarnings — Get warnings from last operation

### 说明

public function mysql_xdevapi\SqlStatementResult::getWarnings(): array

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

An array of Warning objects from the last operation. Each object defines an error 'message', error 'level', and error 'code'. An empty array is returned if no errors are present.

### 示例

示例 #1 mysql_xdevapi\SqlStatementResult::getWarnings() example

    <?php

    /* ... */

    ?>

# SqlStatementResult::getWarningsCount

(No version information available, might only be in Git)

SqlStatementResult::getWarningsCount — Get warning count from last operation

### 说明

public function mysql_xdevapi\SqlStatementResult::getWarningCounts(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

The number of warnings raised during the last CRUD operation.

### 示例

示例 #1 mysql_xdevapi\SqlStatementResult::getWarningsCount() example

    <?php

    /* ... */

    ?>

# SqlStatementResult::hasData

(No version information available, might only be in Git)

SqlStatementResult::hasData — Check if result has data

### 说明

public function mysql_xdevapi\SqlStatementResult::hasData(): bool

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

`true` if the result set has data.

### 示例

示例 #1 mysql_xdevapi\SqlStatementResult::hasData() example

    <?php

    /* ... */

    ?>

# SqlStatementResult::nextResult

(No version information available, might only be in Git)

SqlStatementResult::nextResult — Get next result

### 说明

public function mysql_xdevapi\SqlStatementResult::nextResult(): mysql_xdevapi\Result

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

The next Result object from the result set.

### 示例

示例 #1 mysql_xdevapi\SqlStatementResult::nextResult() example

    <?php

    /* ... */

    ?>

## 目录

- SqlStatementResult::__construct — Description constructor
- SqlStatementResult::fetchAll — Get all rows from result
- SqlStatementResult::fetchOne — Get single row
- SqlStatementResult::getAffectedItemsCount — Get affected row count
- SqlStatementResult::getColumnsCount — Get column count
- SqlStatementResult::getColumnNames — Get column names
- SqlStatementResult::getColumns — Get columns
- SqlStatementResult::getGeneratedIds — Get generated ids
- SqlStatementResult::getLastInsertId — Get last insert id
- SqlStatementResult::getWarnings — Get warnings from last operation
- SqlStatementResult::getWarningsCount — Get warning count from last operation
- SqlStatementResult::hasData — Check if result has data
- SqlStatementResult::nextResult — Get next result

# Statement class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\Statement {
/* 常量 */
const int EXECUTE_ASYNC = 1;
const int BUFFERED = 2;
/* 方法 */
public function getNextResult(): mysql_xdevapi\Result
public function getResult(): mysql_xdevapi\Result
public function hasMoreResults(): bool
}

## 预定义常量

`mysql_xdevapi\Statement::EXECUTE_ASYNC`

`mysql_xdevapi\Statement::BUFFERED`

# Statement::__construct

(No version information available, might only be in Git)

Statement::__construct — Description constructor

### 说明

private function mysql_xdevapi\Statement::__construct()

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 示例

示例 #1 mysql_xdevapi\Statement::__construct() example

    <?php

    /* ... */

    ?>

# Statement::getNextResult

(No version information available, might only be in Git)

Statement::getNextResult — Get next result

### 说明

public function mysql_xdevapi\Statement::getNextResult(): mysql_xdevapi\Result

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

### 示例

示例 #1 mysql_xdevapi\Statement::getNextResult() example

    <?php

    /* ... */

    ?>

# Statement::getResult

(No version information available, might only be in Git)

Statement::getResult — Get result

### 说明

public function mysql_xdevapi\Statement::getResult(): mysql_xdevapi\Result

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

### 示例

示例 #1 mysql_xdevapi\Statement::getResult() example

    <?php

    /* ... */

    ?>

# Statement::hasMoreResults

(No version information available, might only be in Git)

Statement::hasMoreResults — Check if more results

### 说明

public function mysql_xdevapi\Statement::hasMoreResults(): bool

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

### 示例

示例 #1 mysql_xdevapi\Statement::hasMoreResults() example

    <?php

    /* ... */

    ?>

## 目录

- Statement::__construct — Description constructor
- Statement::getNextResult — Get next result
- Statement::getResult — Get result
- Statement::hasMoreResults — Check if more results

# Table class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

Provides access to the table through INSERT/SELECT/UPDATE/DELETE statements.

## 类摘要

class mysql_xdevapi\Table implements mysql_xdevapi\SchemaObject {
/* 属性 */
public $name;
/* 方法 */
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
}

## 属性

name

# Table::__construct

(No version information available, might only be in Git)

Table::__construct — Table constructor

### 说明

private function mysql_xdevapi\Table::__construct()

Construct a table object.

### 参数

此函数没有参数。

### 示例

示例 #1 mysql_xdevapi\Table::__construct() example

    <?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 — Get row count

### 说明

public function mysql_xdevapi\Table::count(): int

Fetch the number of rows in the table.

### 参数

此函数没有参数。

### 返回值

The total number of rows in the table.

### 示例

示例 #1 mysql_xdevapi\Table::count() example

    <?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());
    ?>

以上示例会输出：

    int(2)

# Table::delete

(No version information available, might only be in Git)

Table::delete — Delete rows from table

### 说明

public function mysql_xdevapi\Table::delete(): mysql_xdevapi\TableDelete

Deletes rows from a table.

### 参数

此函数没有参数。

### 返回值

A TableDelete object; use the execute() method to execute the delete query.

### 示例

示例 #1 mysql_xdevapi\Table::delete() example

    <?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 — Check if table exists in database

### 说明

public function mysql_xdevapi\Table::existsInDatabase(): bool

Verifies if this table exists in the database.

### 参数

此函数没有参数。

### 返回值

Returns `true` if table exists in the database, else `false` if it does not.

### 示例

示例 #1 mysql_xdevapi\Table::existsInDatabase() example

    <?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 "Yes, this table still exists in the session's schema.";
    }
    ?>

以上示例的输出类似于：

    Yes, this table still exists in the session's schema.

# Table::getName

(No version information available, might only be in Git)

Table::getName — Get table name

### 说明

public function mysql_xdevapi\Table::getName(): string

Returns the name of this database object.

### 参数

此函数没有参数。

### 返回值

The name of this database object.

### 示例

示例 #1 mysql_xdevapi\Table::getName() example

    <?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());
    ?>

以上示例的输出类似于：

    string(5) "names"

# Table::getSchema

(No version information available, might only be in Git)

Table::getSchema — Get table schema

### 说明

public function mysql_xdevapi\Table::getSchema(): mysql_xdevapi\Schema

Fetch the schema associated with the table.

### 参数

此函数没有参数。

### 返回值

A Schema object.

### 示例

示例 #1 mysql_xdevapi\Table::getSchema() example

    <?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());
    ?>

以上示例的输出类似于：

    object(mysql_xdevapi\Schema)#9 (1) {
      ["name"]=>
      string(11) "addressbook"
    }

# Table::getSession

(No version information available, might only be in Git)

Table::getSession — Get table session

### 说明

public function mysql_xdevapi\Table::getSession(): mysql_xdevapi\Session

Get session associated with the table.

### 参数

此函数没有参数。

### 返回值

A Session object.

### 示例

示例 #1 mysql_xdevapi\Table::getSession() example

    <?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());
    ?>

以上示例的输出类似于：

    object(mysql_xdevapi\Session)#9 (0) {
    }

# Table::insert

(No version information available, might only be in Git)

Table::insert — Insert table rows

### 说明

public function mysql_xdevapi\Table::insert(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableInsert

Inserts rows into a table.

### 参数

`columns`

  The columns to insert data into. Can be an array with one or more values, or a string.

`more_columns`

  Additional columns definitions.

### 返回值

A TableInsert object; use the execute() method to execute the insert statement.

### 示例

示例 #1 mysql_xdevapi\Table::insert() example

    <?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 — Check if table is view

### 说明

public function mysql_xdevapi\Table::isView(): bool

Determine if the underlying object is a view or not.

### 参数

此函数没有参数。

### 返回值

`true` if the underlying object is a view, otherwise `false`.

### 示例

示例 #1 mysql_xdevapi\Table::isView() example

    <?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 "This is a view.";
    } else {
        echo "This is not a view.";
    }
    ?>

以上示例会输出：

    This is not a view.

# Table::select

(No version information available, might only be in Git)

Table::select — Select rows from table

### 说明

public function mysql_xdevapi\Table::select(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableSelect

Fetches data from a table.

### 参数

`columns`

  The columns to select data from. Can be an array with one or more values, or a string.

`more_columns`

  Additional columns parameter definitions.

### 返回值

A TableSelect object; use the execute() method to execute the select and return a RowResult object.

### 示例

示例 #1 mysql_xdevapi\Table::count() example

    <?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);

以上示例的输出类似于：

    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 — Update rows in table

### 说明

public function mysql_xdevapi\Table::update(): mysql_xdevapi\TableUpdate

Updates columns in a table.

### 参数

此函数没有参数。

### 返回值

A TableUpdate object; use the execute() method to execute the update statement.

### 示例

示例 #1 mysql_xdevapi\Table::update() example

    <?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();
    ?>

## 目录

- Table::__construct — Table constructor
- Table::count — Get row count
- Table::delete — Delete rows from table
- Table::existsInDatabase — Check if table exists in database
- Table::getName — Get table name
- Table::getSchema — Get table schema
- Table::getSession — Get table session
- Table::insert — Insert table rows
- Table::isView — Check if table is view
- Table::select — Select rows from table
- Table::update — Update rows in table

# TableDelete class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

A statement for delete operations on Table.

## 类摘要

class mysql_xdevapi\TableDelete implements mysql_xdevapi\Executable {
/* 方法 */
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 — Bind delete query parameters

### 说明

public function mysql_xdevapi\TableDelete::bind(array `$placeholder_values`): mysql_xdevapi\TableDelete

Binds a value to a specific placeholder.

### 参数

`placeholder_values`

  The name of the placeholder and the value to bind.

### 返回值

A TableDelete object.

### 示例

示例 #1 mysql_xdevapi\TableDelete::bind() example

    <?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 — TableDelete constructor

### 说明

private function mysql_xdevapi\TableDelete::__construct()

Initiated by using the delete() method.

### 参数

此函数没有参数。

### 示例

示例 #1 mysql_xdevapi\TableDelete::__construct() example

    <?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 — Execute delete query

### 说明

public function mysql_xdevapi\TableDelete::execute(): mysql_xdevapi\Result

Execute the delete query.

### 参数

此函数没有参数。

### 返回值

A Result object.

### 示例

示例 #1 mysql_xdevapi\TableDelete::execute() example

    <?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 — Limit deleted rows

### 说明

public function mysql_xdevapi\TableDelete::limit(int `$rows`): mysql_xdevapi\TableDelete

Sets the maximum number of records or documents to delete.

### 参数

`rows`

  The maximum number of records or documents to delete.

### 返回值

TableDelete object.

### 示例

示例 #1 mysql_xdevapi\TableDelete::limit() example

    <?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 — Set delete sort criteria

### 说明

public function mysql_xdevapi\TableDelete::orderby(string `$orderby_expr`): mysql_xdevapi\TableDelete

Set the order options for a result set.

### 参数

`orderby_expr`

  The sort definition.

### 返回值

A TableDelete object.

### 示例

示例 #1 mysql_xdevapi\TableDelete::orderBy() example

    <?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 — Set delete search condition

### 说明

public function mysql_xdevapi\TableDelete::where(string `$where_expr`): mysql_xdevapi\TableDelete

Sets the search condition to filter.

### 参数

`where_expr`

  Define the search condition to filter documents or records.

### 返回值

TableDelete object.

### 示例

示例 #1 mysql_xdevapi\TableDelete::where() example

    <?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();

    ?>

## 目录

- TableDelete::bind — Bind delete query parameters
- TableDelete::__construct — TableDelete constructor
- TableDelete::execute — Execute delete query
- TableDelete::limit — Limit deleted rows
- TableDelete::orderby — Set delete sort criteria
- TableDelete::where — Set delete search condition

# TableInsert class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

A statement for insert operations on Table.

## 类摘要

class mysql_xdevapi\TableInsert implements mysql_xdevapi\Executable {
/* 方法 */
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 — TableInsert constructor

### 说明

private function mysql_xdevapi\TableInsert::__construct()

Initiated by using the insert() method.

### 参数

此函数没有参数。

### 示例

示例 #1 mysql_xdevapi\TableInsert::__construct() example

    <?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 — Execute insert query

### 说明

public function mysql_xdevapi\TableInsert::execute(): mysql_xdevapi\Result

Execute the statement.

### 参数

此函数没有参数。

### 返回值

A Result object.

### 示例

示例 #1 mysql_xdevapi\TableInsert::execute() example

    <?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 — Add insert row values

### 说明

public function mysql_xdevapi\TableInsert::values(array `$row_values`): mysql_xdevapi\TableInsert

Set the values to be inserted.

### 参数

`row_values`

  Values (an array) of columns to insert.

### 返回值

A TableInsert object.

### 示例

示例 #1 mysql_xdevapi\TableInsert::values() example

    <?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::__construct — TableInsert constructor
- TableInsert::execute — Execute insert query
- TableInsert::values — Add insert row values

# TableSelect class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

A statement for record retrieval operations on a Table.

## 类摘要

class mysql_xdevapi\TableSelect implements mysql_xdevapi\Executable {
/* 方法 */
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 — Bind select query parameters

### 说明

public function mysql_xdevapi\TableSelect::bind(array `$placeholder_values`): mysql_xdevapi\TableSelect

Binds a value to a specific placeholder.

### 参数

`placeholder_values`

  The name of the placeholder, and the value to bind.

### 返回值

A TableSelect object.

### 示例

示例 #1 mysql_xdevapi\TableSelect::bind() example

    <?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);
    ?>

以上示例的输出类似于：

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::__construct

(No version information available, might only be in Git)

TableSelect::__construct — TableSelect constructor

### 说明

private function mysql_xdevapi\TableSelect::__construct()

An object returned by the select() method; use execute() to execute the query.

### 参数

此函数没有参数。

### 示例

示例 #1 mysql_xdevapi\TableSelect::__construct() example

    <?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);

    ?>

以上示例的输出类似于：

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::execute

(No version information available, might only be in Git)

TableSelect::execute — Execute select statement

### 说明

public function mysql_xdevapi\TableSelect::execute(): mysql_xdevapi\RowResult

Execute the select statement by chaining it with the execute() method.

### 参数

此函数没有参数。

### 返回值

A RowResult object.

### 示例

示例 #1 mysql_xdevapi\TableSelect::execute() example

    <?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();
    ?>

以上示例的输出类似于：

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::groupBy

(No version information available, might only be in Git)

TableSelect::groupBy — Set select grouping criteria

### 说明

public function mysql_xdevapi\TableSelect::groupBy(mixed `$sort_expr`): mysql_xdevapi\TableSelect

Sets a grouping criteria for the result set.

### 参数

`sort_expr`

  The grouping criteria.

### 返回值

A TableSelect object.

### 示例

示例 #1 mysql_xdevapi\TableSelect::groupBy() example

    <?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);
    ?>

以上示例的输出类似于：

    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 — Set select having condition

### 说明

public function mysql_xdevapi\TableSelect::having(string `$sort_expr`): mysql_xdevapi\TableSelect

Sets a condition for records to consider in aggregate function operations.

### 参数

`sort_expr`

  A condition on the aggregate functions used on the grouping criteria.

### 返回值

A TableSelect object.

### 示例

示例 #1 mysql_xdevapi\TableSelect::having() example

    <?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);
    ?>

以上示例的输出类似于：

    Array
    (
        [0] => Array
            (
                [count] => 2
                [age] => 42
            )
    )

# TableSelect::limit

(No version information available, might only be in Git)

TableSelect::limit — Limit selected rows

### 说明

public function mysql_xdevapi\TableSelect::limit(int `$rows`): mysql_xdevapi\TableSelect

Sets the maximum number of records or documents to return.

### 参数

`rows`

  The maximum number of records or documents.

### 返回值

A TableSelect object.

### 示例

示例 #1 mysql_xdevapi\TableSelect::limit() example

    <?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);
    ?>

以上示例的输出类似于：

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::lockExclusive

(No version information available, might only be in Git)

TableSelect::lockExclusive — Execute EXCLUSIVE LOCK

### 说明

public function mysql_xdevapi\TableSelect::lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect

Execute a read operation with EXCLUSIVE LOCK. Only one lock can be active at a time.

### 参数

`lock_waiting_option`

  The optional waiting option that defaults to `MYSQLX_LOCK_DEFAULT`. Valid values are:

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### 返回值

TableSelect object.

### 示例

示例 #1 mysql_xdevapi\TableSelect::lockExclusive() example

    <?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);
    ?>

以上示例的输出类似于：

    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 — Execute SHARED LOCK

### 说明

public function mysql_xdevapi\TableSelect::lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect

Execute a read operation with SHARED LOCK. Only one lock can be active at a time.

### 参数

`lock_waiting_option`

  The optional waiting option that defaults to `MYSQLX_LOCK_DEFAULT`. Valid values are:

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### 返回值

A TableSelect object.

### 示例

示例 #1 mysql_xdevapi\TableSelect::lockShared() example

    <?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);
    ?>

以上示例的输出类似于：

    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 — Set limit offset

### 说明

public function mysql_xdevapi\TableSelect::offset(int `$position`): mysql_xdevapi\TableSelect

Skip given number of rows in result.

### 参数

`position`

  The limit offset.

### 返回值

A TableSelect object.

### 示例

示例 #1 mysql_xdevapi\TableSelect::offset() example

    <?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);
    ?>

以上示例的输出类似于：

    Array
    (
        [0] => Array
            (
                [name] => Sam
                [age] => 42
            )
    )

# TableSelect::orderby

(No version information available, might only be in Git)

TableSelect::orderby — Set select sort criteria

### 说明

public function mysql_xdevapi\TableSelect::orderby(mixed `$sort_expr`, mixed `...$sort_exprs`): mysql_xdevapi\TableSelect

Sets the order by criteria.

### 参数

`sort_expr`

  The expressions that define the order by criteria. Can be an array with one or more expressions, or a string.

`sort_exprs`

  Additional sort_expr parameters.

### 返回值

A TableSelect object.

### 示例

示例 #1 mysql_xdevapi\TableSelect::orderBy() example

    <?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);
    ?>

以上示例的输出类似于：

    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 — Set select search condition

### 说明

public function mysql_xdevapi\TableSelect::where(string `$where_expr`): mysql_xdevapi\TableSelect

Sets the search condition to filter.

### 参数

`where_expr`

  Define the search condition to filter documents or records.

### 返回值

A TableSelect object.

### 示例

示例 #1 mysql_xdevapi\TableSelect::where() example

    <?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);
    ?>

以上示例的输出类似于：

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

## 目录

- TableSelect::bind — Bind select query parameters
- TableSelect::__construct — TableSelect constructor
- TableSelect::execute — Execute select statement
- TableSelect::groupBy — Set select grouping criteria
- TableSelect::having — Set select having condition
- TableSelect::limit — Limit selected rows
- TableSelect::lockExclusive — Execute EXCLUSIVE LOCK
- TableSelect::lockShared — Execute SHARED LOCK
- TableSelect::offset — Set limit offset
- TableSelect::orderby — Set select sort criteria
- TableSelect::where — Set select search condition

# TableUpdate class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

A statement for record update operations on a Table.

## 类摘要

class mysql_xdevapi\TableUpdate implements mysql_xdevapi\Executable {
/* 方法 */
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 — Bind update query parameters

### 说明

public function mysql_xdevapi\TableUpdate::bind(array `$placeholder_values`): mysql_xdevapi\TableUpdate

Binds a value to a specific placeholder.

### 参数

`placeholder_values`

  The name of the placeholder, and the value to bind, defined as a JSON array.

### 返回值

A TableUpdate object.

### 示例

示例 #1 mysql_xdevapi\TableUpdate::bind() example

    <?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 — TableUpdate constructor

### 说明

private function mysql_xdevapi\TableUpdate::__construct()

Initiated by using the update() method.

### 参数

此函数没有参数。

### 示例

示例 #1 mysql_xdevapi\TableUpdate::__construct() example

    <?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 — Execute update query

### 说明

public function mysql_xdevapi\TableUpdate::execute(): mysql_xdevapi\TableUpdate

Executes the update statement.

### 参数

此函数没有参数。

### 返回值

A TableUpdate object.

### 示例

示例 #1 mysql_xdevapi\TableUpdate::execute() example

    <?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 — Limit update row count

### 说明

public function mysql_xdevapi\TableUpdate::limit(int `$rows`): mysql_xdevapi\TableUpdate

Set the maximum number of records or documents update.

### 参数

`rows`

  The maximum number of records or documents to update.

### 返回值

A TableUpdate object.

### 示例

示例 #1 mysql_xdevapi\TableUpdate::limit() example

    <?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 — Set sorting criteria

### 说明

public function mysql_xdevapi\TableUpdate::orderby(mixed `$orderby_expr`, mixed `...$orderby_exprs`): mysql_xdevapi\TableUpdate

Sets the sorting criteria.

### 参数

`orderby_expr`

  The expressions that define the order by criteria. Can be an array with one or more expressions, or a string.

`orderby_exprs`

  Additional sort_expr parameters.

### 返回值

TableUpdate object.

### 示例

示例 #1 mysql_xdevapi\TableUpdate::orderby() example

    <?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 — Add field to be updated

### 说明

public function mysql_xdevapi\TableUpdate::set(string `$table_field`, string `$expression_or_literal`): mysql_xdevapi\TableUpdate

Updates the column value on records in a table.

### 参数

`table_field`

  The column name to be updated.

`expression_or_literal`

  The value to be set on the specified column.

### 返回值

TableUpdate object.

### 示例

示例 #1 mysql_xdevapi\TableUpdate::set() example

    <?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 — Set search filter

### 说明

public function mysql_xdevapi\TableUpdate::where(string `$where_expr`): mysql_xdevapi\TableUpdate

Set the search condition to filter.

### 参数

`where_expr`

  The search condition to filter documents or records.

### 返回值

A TableUpdate object.

### 示例

示例 #1 mysql_xdevapi\TableUpdate::where() example

    <?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::bind — Bind update query parameters
- TableUpdate::__construct — TableUpdate constructor
- TableUpdate::execute — Execute update query
- TableUpdate::limit — Limit update row count
- TableUpdate::orderby — Set sorting criteria
- TableUpdate::set — Add field to be updated
- TableUpdate::where — Set search filter

# Warning class

(PECL mysql-xdevapi >= 8.0.11)

## 简介

## 类摘要

class mysql_xdevapi\Warning {
/* 属性 */
public $message;
public $level;
public $code;
/* Constructor */
private function __construct()
}

## 属性

message

level

code

# Warning::__construct

(No version information available, might only be in Git)

Warning::__construct — Warning constructor

### 说明

private function mysql_xdevapi\Warning::__construct()

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 示例

示例 #1 mysql_xdevapi\Warning::__construct() example

    <?php

    /* ... */

    ?>

## 目录

- Warning::__construct — Warning constructor

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
  - Building / Compiling From Source
- 预定义常量
- 更新日志
- 示例
- Mysql_xdevapi 函数
  - expression — Bind prepared statement variables as parameters
  - getSession — Connect to a MySQL server
- mysql_xdevapi\BaseResult — BaseResult interface
  - BaseResult::getWarnings — Fetch warnings from last operation
  - BaseResult::getWarningsCount — Fetch warning count from last operation
- mysql_xdevapi\Client — Client class
  - mysql_xdevapi\Client::close — Close client
  - Client::__construct — Client constructor
  - Client::getClient — Get client session
- mysql_xdevapi\Collection — Collection class
  - Collection::add — Add collection document
  - Collection::addOrReplaceOne — Add or replace collection document
  - Collection::__construct — Collection constructor
  - Collection::count — Get document count
  - Collection::createIndex — Create collection index
  - Collection::dropIndex — Drop collection index
  - Collection::existsInDatabase — Check if collection exists in database
  - Collection::find — Search for document
  - Collection::getName — Get collection name
  - Collection::getOne — Get one document
  - Collection::getSchema — Get schema object
  - Collection::getSession — Get session object
  - Collection::modify — Modify collection documents
  - Collection::remove — Remove collection documents
  - Collection::removeOne — Remove one collection document
  - Collection::replaceOne — Replace one collection document
- mysql_xdevapi\CollectionAdd — CollectionAdd class
  - CollectionAdd::__construct — CollectionAdd constructor
  - CollectionAdd::execute — Execute the statement
- mysql_xdevapi\CollectionFind — CollectionFind class
  - CollectionFind::bind — Bind value to query placeholder
  - CollectionFind::__construct — CollectionFind constructor
  - CollectionFind::execute — Execute the statement
  - CollectionFind::fields — Set document field filter
  - CollectionFind::groupBy — Set grouping criteria
  - CollectionFind::having — Set condition for aggregate functions
  - CollectionFind::limit — Limit number of returned documents
  - CollectionFind::lockExclusive — Execute operation with EXCLUSIVE LOCK
  - CollectionFind::lockShared — Execute operation with SHARED LOCK
  - CollectionFind::offset — Skip given number of elements to be returned
  - CollectionFind::sort — Set the sorting criteria
- mysql_xdevapi\CollectionModify — CollectionModify class
  - CollectionModify::arrayAppend — Append element to an array field
  - CollectionModify::arrayInsert — Insert element into an array field
  - CollectionModify::bind — Bind value to query placeholder
  - CollectionModify::__construct — CollectionModify constructor
  - CollectionModify::execute — Execute modify operation
  - CollectionModify::limit — Limit number of modified documents
  - CollectionModify::patch — Patch document
  - CollectionModify::replace — Replace document field
  - CollectionModify::set — Set document attribute
  - CollectionModify::skip — Skip elements
  - CollectionModify::sort — Set the sorting criteria
  - CollectionModify::unset — Unset the value of document fields
- mysql_xdevapi\CollectionRemove — CollectionRemove class
  - CollectionRemove::bind — Bind value to placeholder
  - CollectionRemove::__construct — CollectionRemove constructor
  - CollectionRemove::execute — Execute remove operation
  - CollectionRemove::limit — Limit number of documents to remove
  - CollectionRemove::sort — Set the sorting criteria
- mysql_xdevapi\ColumnResult — ColumnResult class
  - ColumnResult::__construct — ColumnResult constructor
  - ColumnResult::getCharacterSetName — Get character set
  - ColumnResult::getCollationName — Get collation name
  - ColumnResult::getColumnLabel — Get column label
  - ColumnResult::getColumnName — Get column name
  - ColumnResult::getFractionalDigits — Get fractional digit length
  - ColumnResult::getLength — Get column field length
  - ColumnResult::getSchemaName — Get schema name
  - ColumnResult::getTableLabel — Get table label
  - ColumnResult::getTableName — Get table name
  - ColumnResult::getType — Get column type
  - ColumnResult::isNumberSigned — Check if signed type
  - ColumnResult::isPadded — Check if padded
- mysql_xdevapi\CrudOperationBindable — CrudOperationBindable interface
  - CrudOperationBindable::bind — Bind value to placeholder
- mysql_xdevapi\CrudOperationLimitable — CrudOperationLimitable interface
  - CrudOperationLimitable::limit — Set result limit
- mysql_xdevapi\CrudOperationSkippable — CrudOperationSkippable interface
  - CrudOperationSkippable::skip — Number of operations to skip
- mysql_xdevapi\CrudOperationSortable — CrudOperationSortable interface
  - CrudOperationSortable::sort — Sort results
- mysql_xdevapi\DatabaseObject — DatabaseObject interface
  - DatabaseObject::existsInDatabase — Check if object exists in database
  - DatabaseObject::getName — Get object name
  - DatabaseObject::getSession — Get session name
- mysql_xdevapi\DocResult — DocResult class
  - DocResult::__construct — DocResult constructor
  - DocResult::fetchAll — Get all rows
  - DocResult::fetchOne — Get one row
  - DocResult::getWarnings — Get warnings from last operation
  - DocResult::getWarningsCount — Get warning count from last operation
- mysql_xdevapi\Exception — Exception class
- mysql_xdevapi\Executable — Executable interface
  - Executable::execute — Execute statement
- mysql_xdevapi\ExecutionStatus — ExecutionStatus class
  - ExecutionStatus::__construct — ExecutionStatus constructor
- mysql_xdevapi\Expression — Expression class
  - Expression::__construct — Expression constructor
- mysql_xdevapi\Result — Result class
  - Result::__construct — Result constructor
  - Result::getAffectedItemsCount — Get affected row count
  - Result::getAutoIncrementValue — Get autoincremented value
  - Result::getGeneratedIds — Get generated ids
  - Result::getWarnings — Get warnings from last operation
  - Result::getWarningsCount — Get warning count from last operation
- mysql_xdevapi\RowResult — RowResult class
  - RowResult::__construct — RowResult constructor
  - RowResult::fetchAll — Get all rows from result
  - RowResult::fetchOne — Get row from result
  - RowResult::getColumnsCount — Get column count
  - RowResult::getColumnNames — Get all column names
  - RowResult::getColumns — Get column metadata
  - RowResult::getWarnings — Get warnings from last operation
  - RowResult::getWarningsCount — Get warning count from last operation
- mysql_xdevapi\Schema — Schema class
  - Schema::__construct — Schema constructor
  - Schema::createCollection — Add collection to schema
  - Schema::dropCollection — Drop collection from schema
  - Schema::existsInDatabase — Check if exists in database
  - Schema::getCollection — Get collection from schema
  - Schema::getCollectionAsTable — Get collection as a Table object
  - Schema::getCollections — Get all schema collections
  - Schema::getName — Get schema name
  - Schema::getSession — Get schema session
  - Schema::getTable — Get schema table
  - Schema::getTables — Get schema tables
- mysql_xdevapi\SchemaObject — SchemaObject interface
  - SchemaObject::getSchema — Get schema object
- mysql_xdevapi\Session — Session class
  - Session::close — Close session
  - Session::commit — Commit transaction
  - Session::__construct — Description constructor
  - Session::createSchema — Create new schema
  - Session::dropSchema — Drop a schema
  - Session::generateUUID — Get new UUID
  - Session::getDefaultSchema — Get default schema name
  - Session::getSchema — Get a new schema object
  - Session::getSchemas — Get the schemas
  - Session::getServerVersion — Get server version
  - Session::listClients — Get client list
  - Session::quoteName — Add quotes
  - Session::releaseSavepoint — Release set savepoint
  - Session::rollback — Rollback transaction
  - Session::rollbackTo — Rollback transaction to savepoint
  - Session::setSavepoint — Create savepoint
  - Session::sql — Create SQL query
  - Session::startTransaction — Start transaction
- mysql_xdevapi\SqlStatement — SqlStatement class
  - SqlStatement::bind — Bind statement parameters
  - SqlStatement::__construct — Description constructor
  - SqlStatement::execute — Execute the operation
  - SqlStatement::getNextResult — Get next result
  - SqlStatement::getResult — Get result
  - SqlStatement::hasMoreResults — Check for more results
- mysql_xdevapi\SqlStatementResult — SqlStatementResult class
  - SqlStatementResult::__construct — Description constructor
  - SqlStatementResult::fetchAll — Get all rows from result
  - SqlStatementResult::fetchOne — Get single row
  - SqlStatementResult::getAffectedItemsCount — Get affected row count
  - SqlStatementResult::getColumnsCount — Get column count
  - SqlStatementResult::getColumnNames — Get column names
  - SqlStatementResult::getColumns — Get columns
  - SqlStatementResult::getGeneratedIds — Get generated ids
  - SqlStatementResult::getLastInsertId — Get last insert id
  - SqlStatementResult::getWarnings — Get warnings from last operation
  - SqlStatementResult::getWarningsCount — Get warning count from last operation
  - SqlStatementResult::hasData — Check if result has data
  - SqlStatementResult::nextResult — Get next result
- mysql_xdevapi\Statement — Statement class
  - Statement::__construct — Description constructor
  - Statement::getNextResult — Get next result
  - Statement::getResult — Get result
  - Statement::hasMoreResults — Check if more results
- mysql_xdevapi\Table — Table class
  - Table::__construct — Table constructor
  - Table::count — Get row count
  - Table::delete — Delete rows from table
  - Table::existsInDatabase — Check if table exists in database
  - Table::getName — Get table name
  - Table::getSchema — Get table schema
  - Table::getSession — Get table session
  - Table::insert — Insert table rows
  - Table::isView — Check if table is view
  - Table::select — Select rows from table
  - Table::update — Update rows in table
- mysql_xdevapi\TableDelete — TableDelete class
  - TableDelete::bind — Bind delete query parameters
  - TableDelete::__construct — TableDelete constructor
  - TableDelete::execute — Execute delete query
  - TableDelete::limit — Limit deleted rows
  - TableDelete::orderby — Set delete sort criteria
  - TableDelete::where — Set delete search condition
- mysql_xdevapi\TableInsert — TableInsert class
  - TableInsert::__construct — TableInsert constructor
  - TableInsert::execute — Execute insert query
  - TableInsert::values — Add insert row values
- mysql_xdevapi\TableSelect — TableSelect class
  - TableSelect::bind — Bind select query parameters
  - TableSelect::__construct — TableSelect constructor
  - TableSelect::execute — Execute select statement
  - TableSelect::groupBy — Set select grouping criteria
  - TableSelect::having — Set select having condition
  - TableSelect::limit — Limit selected rows
  - TableSelect::lockExclusive — Execute EXCLUSIVE LOCK
  - TableSelect::lockShared — Execute SHARED LOCK
  - TableSelect::offset — Set limit offset
  - TableSelect::orderby — Set select sort criteria
  - TableSelect::where — Set select search condition
- mysql_xdevapi\TableUpdate — TableUpdate class
  - TableUpdate::bind — Bind update query parameters
  - TableUpdate::__construct — TableUpdate constructor
  - TableUpdate::execute — Execute update query
  - TableUpdate::limit — Limit update row count
  - TableUpdate::orderby — Set sorting criteria
  - TableUpdate::set — Add field to be updated
  - TableUpdate::where — Set search filter
- mysql_xdevapi\Warning — Warning class
  - Warning::__construct — Warning constructor

# 原始的 MySQL API

# 简介

从 PHP 5.5.0 起这个扩展已经被废弃，并且从 PHP 7.0.0. 开始被移除。作为替代，可以使用 mysqli 或者 PDO_MySQL 扩展代替。 参见 MySQL API 概览 寻找关于选择 MySQL API 的更多帮助。

这些函数允许你接入 MySQL 数据库服务器。更多关于 MySQL 的信息： » http://www.mysql.com/。

关于 MySQL 的文档能在此找到： » http://dev.mysql.com/doc/。

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置
- 资源类型

## 需求

为了使这些函数能够使用，你必须编译加入 PHP 对 MySQL 的支持。

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

## 安装

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

编译时，只要使用 --with-mysql[=DIR] 配置选项即可，其中可选的 `[DIR]` 指向 MySQL 的安装目录。

虽然本 MySQL 扩展库兼容 MySQL 4.1.0 及其以后版本，但是它不支持这些版本提供的额外功能。要使用这些功能，请使用 MySQLi 扩展库。

如果要同时安装 mysql 扩展库和 mysqli 扩展库，必须使用同一个客户端库以避免任何冲突。

## 在 Linux 系统下安装

Note: `[DIR]` is the path to the MySQL client library files (headers and libraries), which can be downloaded from » MySQL.

ext/mysql compile time support matrix
PHP 版本 | 默认 | 配置选项: mysqlnd | 配置选项: `libmysql` | 更新日志
--- | --- | --- | --- | ---
4.x.x | libmysql | 不适用 | --without-mysql to disable | MySQL enabled by default, MySQL client libraries are bundled
5.0.x, 5.1.x, 5.2.x | libmysql | 不适用 | --with-mysql=[DIR] | MySQL is no longer enabled by default, and the MySQL client libraries are no longer bundled
5.3.x | libmysql | --with-mysql=mysqlnd | --with-mysql=[DIR] | mysqlnd is now available
5.4.x | mysqlnd | --with-mysql | --with-mysql=[DIR] | mysqlnd is now the default

## 在 Windows 系统下安装

## PHP 5+

MySQL 默认未启用，因此必须在 php.ini 中激活 php_mysql.dll 动态连接库。此外，PHP 还需要访问 MySQL 客户端连接库。PHP 的 Windows 发行版包括了一个 libmysql.dll，为了让 PHP 能和 MySQL 对话，此文件必须放在 Windows 的系统路径 PATH 中。怎样做见 FAQ 中的“怎样把 PHP 目录加入到 Windows PATH中”。尽管将 libmysql.dll 拷贝到 Windows 系统目录中也可以（因为系统目录默认在系统路径 PATH 中），但不推荐这样做。

要激活任何 PHP 扩展库（例如 php_mysql.dll），PHP 指令 extension_dir 要被设为 PHP 扩展库所在的目录。参见手工 Windows 安装指南。PHP 5 下 extension_dir 取值的一个例子是 `c:\php\ext`。

> 注意: 如果启动 web 服务器时出现类似如下的错误：`"Unable to load dynamic library './php_mysql.dll'"`，这是因为系统找不到 php_mysql.dll 和／或 libmysql.dll。

## PHP 5.3.0+

The MySQL Native Driver is enabled by default. Include php_mysql.dll, but libmysql.dll is no longer required or used.

## MySQL 安装注意事项

警告

当同时加在本扩展库和 recode 扩展库时 PHP 可能会崩溃。更多信息见 recode 扩展库。

> 注意: 如果需要不同于 latin（默认值）的字符集，必须安装外部的（非绑定的）已编译入所需字符集支持的 libmysql。

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

MySQL 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
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` |

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`mysql.allow_local_infile` int
  Allow accessing, from PHP's perspective, local files with LOAD DATA statements
`mysql.allow_persistent` bool
  是否允许 MySQL 的持久连接。
`mysql.max_persistent` int
  每个进程中最大的持久连接数目。
`mysql.max_links` int
  每个进程中最大的连接数，包括持久连接。
`mysql.trace_mode` bool
  跟踪模式。当激活 `mysql.trace_mode` 时，将会显示 table/index 扫描的警告，未释放的结果集以及 SQL 错误。（PHP 4.3.0 引进）
`mysql.default_port` string
  指定默认连接数据库的 TCP 端口号。如果没有指定默认端口号，则按顺序从 MYSQL_TCP_PORT 环境变量，/etc/services 文件中的 `mysql-tcp` 项或者编译时指定的 `MYSQL_PORT` 常量中取得。Win32 环境下只会使用 `MYSQL_PORT` 常量。
`mysql.default_socket` string
  当使用本地连接的时候，默认的 socket 名称。
`mysql.default_host` string
  默认连接的数据库服务器地址。不适用于 SQL 安全模式。
`mysql.default_user` string
  默认连接数据库时使用的用户名。不适用于 SQL 安全模式。
`mysql.default_password` string
  默认连接数据库时使用的密码。不适用于 SQL 安全模式。
`mysql.connect_timeout` int
  连接超时秒数。在 Linux 中，此参数设定了等候来自服务器的响应的时长。

## 资源类型

在 MySQL 模块中用到了两种资源类型。第一种是数据库链接的链接标识符，第二种是资源标识符，包含了查询结果集。

# 更新日志

对本扩展的类／函数／方法有以下更新。

### ext/mysql 扩展更新日志概要

ext/mysql 扩展相关的更新日志。

### 全局 ext/mysql 的变更

以下列表是整个 ext/mysql 扩展的变动更新。

版本 | 说明
--- | ---
7.0.0 | 此扩展已从 PHP 中移除。详见 Choosing an API.

### 函数的变更项

以下列表为 ext/mysql 函数完整的更新历史项。

Version | Function | Description
--- | --- | ---

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

允许在 mysql_connect() 函数和 mysql_pconnect() 函数中指定更多的客户端标记。下面列出所定义的常量：

MySQL 客户端常量
常量 | 说明
--- | ---
`MYSQL_CLIENT_COMPRESS` | 使用压缩的通讯协议
`MYSQL_CLIENT_IGNORE_SPACE` | 允许在函数名后留空格位
`MYSQL_CLIENT_INTERACTIVE` | 允许设置断开连接之前所空闲等候的 interactive_timeout 时间（代替 wait_timeout）。
`MYSQL_CLIENT_SSL` | 使用 SSL 加密。本标志仅在 MySQL 客户端库版本为 4.x 或更高版本时可用。在 PHP 4 和 Windows 版的 PHP 5 安装包中绑定的都是 3.23.x。

mysql_fetch_array() 函数使用一个常量来表示所返回数组的类型。下面是常量的定义：

MySQL fetch 常量
常量 | 说明
--- | ---
`MYSQL_ASSOC` | 返回的数据列使用字段名作为数组的索引名。
`MYSQL_BOTH` | 返回的数据列使用字段名及数字索引作为数组的索引名。
`MYSQL_NUM` | 返回的数据列使用数字索引作为数组的索引名。索引从 0 开始，表示返回结果的第一个字段。

# 示例

## 目录

- MySQL 扩展概述范例

## MySQL 扩展概述范例

这个简单的范例展示了如何连接、执行一个查询，打印结果集后断开 MySQL 数据库的连接。

示例 #1 MySQL 扩展概述范例

    <?php
    // 连接、选择数据库
    $link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')
        or die('Could not connect: ' . mysql_error());
    echo 'Connected successfully';
    mysql_select_db('my_database') or die('Could not select database');

    // 执行 SQL 查询
    $query = 'SELECT * FROM my_table';
    $result = mysql_query($query) or die('Query failed: ' . mysql_error());

    // 以 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";

    // 释放结果集
    mysql_free_result($result);

    // 关闭连接
    mysql_close($link);
    ?>

# MySQL 函数

## 注释

> 注意: 大多数 MySQL 函数的最后一个可选参数是 `link_identifier`。 如果没有提供这个参数，则会使用最后一个打开的连接。 若不存在这个最后打开的连接，则会尝试用 php.ini 里定义的默认参数来连接。 如果没有成功连接，函数会返回 `false`。

# mysql_affected_rows

(PHP 4, PHP 5)

mysql_affected_rows — 取得前一次 MySQL 操作所影响的记录行数

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_affected_rows()
- PDOStatement::rowCount()

### 说明

function mysql_affected_rows(resource `$link_identifier` = NULL): int

取得最近一次与 `link_identifier` 关联的 INSERT，UPDATE 或 DELETE 查询所影响的记录行数。

### 参数

`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

执行成功则返回受影响的行的数目，如果最近一次查询失败的话，函数返回 -1。

如果最近一次操作是没有任何条件（WHERE）的 DELETE 查询，在表中所有的记录都会被删除，但本函数返回值在 4.1.2 版之前都为 0。

当使用 UPDATE 查询，MySQL 不会将原值和新值一样的列更新。这样使得 mysql_affected_rows() 函数返回值不一定就是查询条件所符合的记录数，只有真正被修改的记录数才会被返回。

REPLACE 语句首先删除具有相同主键的记录，然后插入一个新记录。本函数返回的是被删除的记录数加上被插入的记录数。

"INSERT ... ON DUPLICATE KEY UPDATE" 这种情况的查询，当执行了一次 INSERT 返回的值会是 `1`；如果是对已经存在的记录执行一次 UPDATE 将返回 `2`。

### 示例

示例 #1 mysql_affected_rows() 例子

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Could not connect: ' . mysql_error());
    }
    mysql_select_db('mydb');

    /* 本例返回被删除记录的准确数目 */
    mysql_query('DELETE FROM mytable WHERE id < 10');
    printf("Records deleted: %d\n", mysql_affected_rows());

    /* 对于非真值的 WHERE 子句，应返回 0 */
    mysql_query('DELETE FROM mytable WHERE 0');
    printf("Records deleted: %d\n", mysql_affected_rows());
    ?>

以上示例的输出类似于：

    Records deleted: 10
    Records deleted: 0

示例 #2 使用事务处理的 mysql_affected_rows() 例子

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Could not connect: ' . mysql_error());
    }
    mysql_select_db('mydb');

    /* Update records */
    mysql_query("UPDATE mytable SET used=1 WHERE id < 10");
    printf ("Updated records: %d\n", mysql_affected_rows());
    mysql_query("COMMIT");
    ?>

以上示例的输出类似于：

    Updated Records: 10

### 注释

> 注意: 事务处理
> 如果使用事务处理（transactions），需要在 INSERT，UPDATE 或 DELETE 查询后调用 mysql_affected_rows() 函数，而不是在 COMMIT 命令之后。

> 注意: SELECT 语句
> 要获取 SELECT 所返回的行数，可以用 mysql_num_rows()。

> 注意: Cascaded 外键
> mysql_affected_rows() does not count rows affected implicitly through the use of ON DELETE CASCADE and/or ON UPDATE CASCADE in foreign key constraints.

### 参见

- mysql_num_rows() - 获取结果中行数
- mysql_info() - 获取最近查询的有关信息

# mysql_client_encoding

(PHP 4 >= 4.3.0, PHP 5)

mysql_client_encoding — 返回字符集的名称

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_character_set_name()

### 说明

function mysql_client_encoding(resource `$link_identifier` = ?): string

从 MySQL 中取得 `character_set` 变量的值。

### 参数

`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

返回当前连接的默认字符集名称。

### 示例

示例 #1 mysql_client_encoding() 示例

    <?php
    $link    = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $charset = mysql_client_encoding($link);

    echo "The current character set is: $charset\n";
    ?>

以上示例的输出类似于：

    The current character set is: latin1

### 参见

- mysql_real_escape_string() - 将字符串中的特殊字符进行转义，以在 SQL 语句中使用

# mysql_close

(PHP 4, PHP 5)

mysql_close — 关闭 MySQL 连接

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_close()
- PDO: 为 PDO 对象设置一个 `null` 值

### 说明

function mysql_close(resource `$link_identifier` = NULL): bool

mysql_close() 关闭指定的连接标识所关联的到 MySQL 服务器的非持久连接。如果没有指定 `link_identifier`，则关闭上一个打开的连接。

建立非持久性的 MySQL 连接，会在 PHP 执行完毕后自动销毁，所以手动关闭连接，并释放资源是可选的。但是还是推荐你在代码中显性的执行该操作，这对提高代码性能有帮助。参考文档 资源释放

### 参数

`link_identifier`
  MySQL 连接. 如果该连接标识符未给出, 将使用最近一次mysql_connect()建立的连接. 如果没有找到可使用的连接, 将产生一个 `E_WARNING` 错误.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 mysql_close() 示例

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Could not connect: ' . mysql_error());
    }
    echo 'Connected successfully';
    mysql_close($link);
    ?>

以上示例会输出：

    Connected successfully

### 注释

> 注意: mysql_close() 不会关闭由 mysql_pconnect() 建立的持久连接。 有关其他详细信息，请参阅有关持久连接的手册页。

### 参见

- mysql_connect() - 打开一个到 MySQL 服务器的连接
- mysql_free_result() - 释放结果内存

# mysql_connect

(PHP 4, PHP 5)

mysql_connect — 打开一个到 MySQL 服务器的连接

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_connect()
- PDO::__construct()

### 说明

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

打开或重复使用一个到 MySQL 服务器的连接。

### 参数

`server`
  MySQL 服务器。可以包括端口号，例如 "hostname:port"，或者到本地套接字的路径，例如对于 localhost 的 ":/path/to/socket"。 如果 PHP 指令 mysql.default_host 未定义（默认情况），则默认值是 'localhost:3306'。 在 SQL 安全模式 时，参数被忽略，总是使用 'localhost:3306'。
`username`
  用户名。默认值由 mysql.default_user 定义。 在 SQL 安全模式 时，参数被忽略，总是使用服务器进程所有者的用户名。
`password`
  密码。默认值由mysql.default_password定义。在 SQL 安全模式 时，参数被忽略，总是使用空密码。
`new_link`
  如果用同样的参数第二次调用 mysql_connect()，将不会建立新连接，而将返回已经打开的连接标识。参数 `new_link` 改变此行为并使 mysql_connect() 总是打开新的连接，甚至当 mysql_connect() 曾在前面被用同样的参数调用过。
`client_flags`
  `client_flags` 参数可以是以下常量的组合：`MYSQL_CLIENT_SSL`，`MYSQL_CLIENT_COMPRESS`，`MYSQL_CLIENT_IGNORE_SPACE` 或 `MYSQL_CLIENT_INTERACTIVE`。进一步信息见 MySQL 客户端常量。

### 返回值

如果成功则返回一个 MySQL 连接标识， 或者在失败时返回 `false`。

### 示例

示例 #1 mysql_connect() 示例

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Could not connect: ' . mysql_error());
    }
    echo 'Connected successfully';
    mysql_close($link);
    ?>

示例 #2 mysql_connect() 示例：使用 `hostname:port` 语法

    <?php
    // we connect to example.com and port 3307
    $link = mysql_connect('example.com:3307', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Could not connect: ' . mysql_error());
    }
    echo 'Connected successfully';
    mysql_close($link);

    // we connect to localhost at port 3307
    $link = mysql_connect('127.0.0.1:3307', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Could not connect: ' . mysql_error());
    }
    echo 'Connected successfully';
    mysql_close($link);
    ?>

示例 #3 mysql_connect() 示例：使用 ":/path/to/socket" 语法

    <?php
    // we connect to localhost and socket e.g. /tmp/mysql.sock

    // variant 1: omit localhost
    $link = mysql_connect(':/tmp/mysql', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Could not connect: ' . mysql_error());
    }
    echo 'Connected successfully';
    mysql_close($link);

    // variant 2: with localhost
    $link = mysql_connect('localhost:/tmp/mysql.sock', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Could not connect: ' . mysql_error());
    }
    echo 'Connected successfully';
    mysql_close($link);
    ?>

### 注释

> 注意: 只要将 server 指定为 "localhost" 或 "localhost:port"，MySQL 客户端库会越过此值并尝试连接到本地套接字（Windows 中的名字管道）。如果想用 TCP/IP，应该用 "127.0.0.1" 代替 "localhost"。如果 MySQL 客户端库试图连接到一个错误的本地套接字，则应该在 php.ini 中设置 mysql.default_host 的正确路径并把 server 留空。

> 注意: 脚本一结束，到服务器的连接就被关闭，除非之前已经明确调用 mysql_close() 关闭了。

> 注意: Error "Can't create TCP/IP socket (10106)" usually means that the variables_order configure directive doesn't contain character `E`. On Windows, if the environment is not copied the `SYSTEMROOT` environment variable won't be available and PHP will have problems loading Winsock.

### 参见

- mysql_pconnect() - 打开一个到 MySQL 服务器的持久连接
- mysql_close() - 关闭 MySQL 连接

# mysql_create_db

(PHP 4, PHP 5)

mysql_create_db — 新建一个 MySQL 数据库

警告

本函数自 PHP 4.3.0 起已废弃，并且它和整个 MySQL 扩展自 PHP 7.0.0 开始被移除。 可以选择出于活跃开发中的 MySQLi 或 PDO_MySQL 扩展来作为替代。 参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_query()
- PDO::query()

### 说明

function mysql_create_db(string `$database name`, resource `$link_identifier` = ?): bool

mysql_create_db() 尝试在指定的连接标识所关联的服务器上建立一个新数据库。

### 参数

`database_name`
  要创建的数据库名。
`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 替代 mysql_create_db() 示例

mysql_create_db() 函数已废弃。最好用 mysql_query() 来提交一条 SQL 的 `CREATE DATABASE` 语句来代替。

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Could not connect: ' . mysql_error());
    }

    $sql = 'CREATE DATABASE my_db';
    if (mysql_query($sql, $link)) {
        echo "Database my_db created successfully\n";
    } else {
        echo 'Error creating database: ' . mysql_error() . "\n";
    }
    ?>

以上示例的输出类似于：

    Database my_db created successfully

### 注释

> 注意: 为了向下兼容，可以使用下列已废弃的别名： mysql_createdb()

> 注意: 如果 MySQL 扩展是基于 MySQL 4.x 客户端库编译的话则本函数不可用。

### 参见

- mysql_query() - 发送一条 MySQL 查询
- mysql_select_db() - 选择 MySQL 数据库

# mysql_data_seek

(PHP 4, PHP 5)

mysql_data_seek — 移动内部结果的指针

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_data_seek()
- `PDO::FETCH_ORI_ABS`

### 说明

function mysql_data_seek(resource `$result`, int `$row_number`): bool

mysql_data_seek() 将指定的结果标识所关联的 MySQL 结果内部的行指针移动到指定的行号。接着调用 mysql_fetch_row() 将返回那一行。

`row_number` 从 0 开始。`row_number` 的取值范围应该从 0 到 mysql_num_rows - 1。但是如果结果集为空（mysql_num_rows() == 0），要将指针移动到 0 会失败并发出 `E_WARNING` 级的错误，mysql_data_seek() 将返回 `false`。

### 参数

`result`
  resource 型的结果集。此结果集来自对 mysql_query() 的调用。
`row_number`
  想要设定的新的结果集指针的行数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 mysql_data_seek() 示例

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Could not connect: ' . mysql_error());
    }
    $db_selected = mysql_select_db('sample_db');
    if (!$db_selected) {
        die('Could not select database: ' . mysql_error());
    }
    $query = 'SELECT last_name, first_name FROM friends';
    $result = mysql_query($query);
    if (!$result) {
        die('Query failed: ' . mysql_error());
    }
    /* fetch rows in reverse order */
    for ($i = mysql_num_rows($result) - 1; $i >= 0; $i--) {
        if (!mysql_data_seek($result, $i)) {
            echo "Cannot seek to row $i: " . mysql_error() . "\n";
            continue;
        }

        if (!($row = mysql_fetch_assoc($result))) {
            continue;
        }

        echo $row['last_name'] . ' ' . $row['first_name'] . "<br />\n";
    }

    mysql_free_result($result);
    ?>

### 注释

> 注意: mysql_data_seek() 只能和 mysql_query() 结合起来使用，而不能用于 mysql_unbuffered_query()。

### 参见

- mysql_query() - 发送一条 MySQL 查询
- mysql_num_rows() - 获取结果中行数
- mysql_fetch_row() - 从结果集中取得一行作为枚举数组
- mysql_fetch_assoc() - 从结果集中取得一行作为关联数组
- mysql_fetch_array() - 从结果集中取得一行作为关联数组
- mysql_fetch_object() - 从结果集中取得一行作为对象返回

# mysql_db_name

(PHP 4, PHP 5)

mysql_db_name — 取得 mysql_list_dbs() 返回的结果数据

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- Query: `SELECT DATABASE()`

### 说明

function mysql_db_name(resource `$result`, int `$row`, mixed `$field` = NULL): string

取得 mysql_list_dbs() 调用所返回的数据库名。

### 参数

`result`
  mysql_list_dbs() 调用所返回的结果指针。
`row`
  结果集中的行号。
`field`
  字段名。

### 返回值

如果成功则返回数据库名，失败返回 `false`。如果返回了 `false`，用 mysql_error() 来判断错误的种类。

### 示例

示例 #1 mysql_db_name() 示例

    <?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++;
    }
    ?>

### 注释

> 注意: 为了向下兼容，可以使用下列已废弃的别名： mysql_dbname()

### 参见

- mysql_list_dbs() - 列出 MySQL 服务器中可用的数据库
- mysql_tablename() - 取得表名

# mysql_db_query

(PHP 4, PHP 5)

mysql_db_query — 选择数据库并执行查询

警告

本函数自 PHP 5.3.0 起已废弃，并且它和整个 MySQL 扩展自 PHP 7.0.0 开始被移除。 可以选择出于活跃开发中的 MySQLi 或 PDO_MySQL 扩展来作为替代。 参见 MySQL：选择 API 指南获取更多信息。用以替代本函数的有：

- mysqli_select_db() 然后查询
- PDO::__construct()

### 说明

function mysql_db_query(string `$database`, string `$query`, resource `$link_identifier` = NULL): resource|bool

mysql_db_query() 选择数据库并执行查询。

### 参数

`database`
  要选择的数据库名。
`query`
  MySQL 查询。 查询中的数据应正确转义。
`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

返回正的 MySQL 结果资源到查询结果，出错时返回 `false`。本函数会对 `INSERT`/`UPDATE`/`DELETE` 查询返回 `true`/`false` 来指示成功或失败。

### 示例

示例 #1 替代 mysql_db_query() 示例

    <?php

    if (!$link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')) {
        echo 'Could not connect to mysql';
        exit;
    }

    if (!mysql_select_db('mysql_dbname', $link)) {
        echo 'Could not select database';
        exit;
    }

    $sql    = 'SELECT foo FROM bar WHERE id = 42';
    $result = mysql_query($sql, $link);

    if (!$result) {
        echo "DB Error, could not query the database\n";
        echo 'MySQL Error: ' . mysql_error();
        exit;
    }

    while ($row = mysql_fetch_assoc($result)) {
        echo $row['foo'];
    }

    mysql_free_result($result);

    ?>

### 注释

> 注意: 注意此函数不会切换回先前连接到的数据库。换句话说，不能用此函数临时在另一个数据库上执行 sql 查询，只能手工切换回来。强烈建议用户在 sql 查询中使用 `database.table` 语法或 mysql_select_db() 替代此函数。

### 参见

- mysql_query() - 发送一条 MySQL 查询
- mysql_select_db() - 选择 MySQL 数据库

# mysql_drop_db

(PHP 4, PHP 5)

mysql_drop_db — 丢弃（删除）一个 MySQL 数据库

警告

本函数自 PHP 4.3.0 起已废弃，并且它和整个 MySQL 扩展自 PHP 7.0.0 开始被移除。 可以选择出于活跃开发中的 MySQLi 或 PDO_MySQL 扩展来作为替代。 参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- Execute a `DROP DATABASE` query

### 说明

function mysql_drop_db(string `$database_name`, resource `$ link_identifier` = ?): bool

mysql_drop_db() 尝试丢弃（删除）指定连接标识所关联的服务器上的一整个数据库。

成功时返回 `true`， 或者在失败时返回 `false`。

为向下兼容也可以用 mysql_dropdb()，但反对这样做。

> 注意: 不提倡使用 mysql_drop_db() 函数。最好用 mysql_query() 提交一条 `SQL DROP DATABASE` 语句来替代。

警告

如果 MySQL 扩展库是基于 MySQL 4.x 客户端库建立的，则本函数不可用。

参见 mysql_create_db() 和 mysql_query()。

### 参数

`database_name`
  The name of the database that will be deleted.
`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 mysql_drop_db() alternative example

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Could not connect: ' . mysql_error());
    }

    $sql = 'DROP DATABASE my_db';
    if (mysql_query($sql, $link)) {
        echo "Database my_db was successfully dropped\n";
    } else {
        echo 'Error dropping database: ' . mysql_error() . "\n";
    }
    ?>

### 注释

警告

This function will not be available if the MySQL extension was built against a MySQL 4.x client library.

> 注意: 为了向下兼容，可以使用下列已废弃的别名： mysql_dropdb()

### 参见

- mysql_query() - 发送一条 MySQL 查询

# mysql_errno

(PHP 4, PHP 5)

mysql_errno — 返回上一个 MySQL 操作中的错误信息的数值

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_errno()
- PDO::errorCode()

### 说明

function mysql_errno(resource `$link_identifier` = NULL): int

返回上一个 MySQL 函数的错误号码。

从 MySQL 数据库后端来的错误不再发出警告。要用 mysql_errno() 来检索错误代码。注意本函数仅返回最近执行的 MySQL 函数（不包括 mysql_error() 和 mysql_errno()）的错误代码，因此如果要使用此函数，确保在调用另一个 MySQL 函数之前检查它的值。

### 参数

`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

Returns the error number from the last MySQL function, or `0` (zero) if no error occurred.

### 示例

示例 #1 mysql_errno() 示例

    <?php
    $link = mysql_connect("localhost", "mysql_user", "mysql_password");

    if (!mysql_select_db("nonexistentdb", $link)) {
        echo mysql_errno($link) . ": " . mysql_error($link). "\n";
    }

    mysql_select_db("kossu", $link);
    if (!mysql_query("SELECT * FROM nonexistenttable", $link)) {
        echo mysql_errno($link) . ": " . mysql_error($link) . "\n";
    }
    ?>

以上示例的输出类似于：

    1049: Unknown database 'nonexistentdb'
    1146: Table 'kossu.nonexistenttable' doesn't exist

### 参见

- mysql_error() - 返回上一个 MySQL 操作中的错误信息的文本
- » MySQL 错误代码

# mysql_error

(PHP 4, PHP 5)

mysql_error — 返回上一个 MySQL 操作中的错误信息的文本

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_error()
- PDO::errorInfo()

### 说明

function mysql_error(resource `$link_identifier` = NULL): string

返回上一个 MySQL 函数的错误文本。 从 MySQL 数据库后端来的错误不再发出警告。要用 mysql_error() 来检索错误文本。注意本函数仅返回最近执行的 MySQL 函数（不包括 mysql_error() 和 mysql_errno()）的错误文本，因此如果要使用此函数，确保在调用另一个 MySQL 函数之前检查它的值。

### 参数

`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

返回上一个 MySQL 函数的错误文本，如果没有出错则返回 `''`（空字符串）。

### 示例

示例 #1 mysql_error() 示例

    <?php
    $link = mysql_connect("localhost", "mysql_user", "mysql_password");

    mysql_select_db("nonexistentdb", $link);
    echo mysql_errno($link) . ": " . mysql_error($link). "\n";

    mysql_select_db("kossu", $link);
    mysql_query("SELECT * FROM nonexistenttable", $link);
    echo mysql_errno($link) . ": " . mysql_error($link) . "\n";
    ?>

以上示例的输出类似于：

    1049: Unknown database 'nonexistentdb'
    1146: Table 'kossu.nonexistenttable' doesn't exist

### 参见

- mysql_errno() - 返回上一个 MySQL 操作中的错误信息的数值
- » MySQL 错误代码

# mysql_escape_string

(PHP 4 >= 4.0.3, PHP 5)

mysql_escape_string — 转义字符串用于 mysql_query

警告

本函数自 PHP 4.3.0 起已废弃，并且它和整个 MySQL 扩展自 PHP 7.0.0 开始被移除。 可以选择出于活跃开发中的 MySQLi 或 PDO_MySQL 扩展来作为替代。 参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_escape_string()
- PDO::quote()

### 说明

function mysql_escape_string(string `$unescaped_string`): string

本函数将转义 `unescaped_string`，使之可以安全用于 mysql_query()。此函数已弃用。

本函数和 mysql_real_escape_string() 相同，除了 mysql_real_escape_string() 接受连接处理程序并根据当前字符集进行转义。mysql_escape_string() 不接受连接参数，也不遵循当前字符集设定。

### 参数

`unescaped_string`
  要转义的字符串。

### 返回值

返回转义后的字符串。

### 示例

示例 #1 mysql_escape_string() 示例

    <?php
    $item = "Zak's Laptop";
    $escaped_item = mysql_escape_string($item);
    printf("Escaped string: %s\n", $escaped_item);
    ?>

以上示例会输出：

    Escaped string: Zak\'s Laptop

### 注释

> 注意: mysql_escape_string() 不转义 `%` 和 `_`。

### 参见

- mysql_real_escape_string() - 将字符串中的特殊字符进行转义，以在 SQL 语句中使用

# mysql_fetch_array

(PHP 4, PHP 5)

mysql_fetch_array — 从结果集中取得一行作为关联数组

### 说明

function mysql_fetch_array(resource `$result`, int `$result_type` = ?): array

mysql_fetch_array() 是 mysql_fetch_row() 的扩展版本。除了将数据以数字索引方式储存在数组中之外，还可以将数据作为关联索引储存，用字段名作为键名。

有一点很重要必须指出，用 mysql_fetch_array() 并不明显 比用 mysql_fetch_row() 慢，而且还提供了明显更多的值。

### 参数

`result`
  resource 型的结果集。此结果集来自对 mysql_query() 的调用。
`result_type`
  接受以下常量值： `MSQL_ASSOC`，`MSQL_NUM` 和 `MSQL_BOTH`，默认为 `MSQL_BOTH`。如果用了 MYSQL_BOTH，将得到一个同时包含关联和数字索引的数组。用 MYSQL_ASSOC 只得到关联索引（如同 mysql_fetch_assoc() 那样），用 MYSQL_NUM 只得到数字索引（如同 mysql_fetch_row() 那样）。

### 返回值

返回根据从结果集取得的行生成的数组，如果没有更多行则返回 `false`。

### 示例

示例 #1 msql_fetch_array() 示例

    <?php
    $con = msql_connect();
    if (!$con) {
        die('Server connection problem: ' . msql_error());
    }

    if (!msql_select_db('test', $con)) {
        die('Database connection problem: ' . msql_error());
    }

    $result = msql_query('SELECT id, name FROM people', $con);
    if (!$result) {
        die('Query execution problem: ' . msql_error());
    }

    while ($row = msql_fetch_array($result, MSQL_ASSOC)) {
        echo $row['id'] . ': ' . $row['name'] . "\n";
    }

    msql_free_result($result);
    ?>

### 参见

- msql_fetch_row()
- msql_fetch_object()
- msql_data_seek()
- msql_result()

# mysql_fetch_assoc

(PHP 4 >= 4.0.3, PHP 5)

mysql_fetch_assoc — 从结果集中取得一行作为关联数组

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_fetch_assoc()
- PDOStatement::fetch() with `mode` as `PDO::FETCH_ASSOC`

### 说明

function mysql_fetch_assoc(resource `$result`): array

返回对应结果集的关联数组，并且继续移动内部数据指针。 mysql_fetch_assoc() 和用 mysql_fetch_array() 加上第二个可选参数 MYSQL_ASSOC 完全相同。它仅仅返回关联数组。

### 参数

`result`
  resource 型的结果集。此结果集来自对 mysql_query() 的调用。

### 返回值

返回根据从结果集取得的行生成的关联数组；如果没有更多行则返回 `false`。

如果结果中的两个或以上的列具有相同字段名，最后一列将优先。要访问同名的其它列，要么用 mysql_fetch_row() 来取得数字索引或给该列起个别名。 参见 mysql_fetch_array() 例子中有关别名说明。

### 示例

示例 #1 扩展的 mysql_fetch_assoc() 例子

    <?php

    $conn = mysql_connect("localhost", "mysql_user", "mysql_password");

    if (!$conn) {
        echo "Unable to connect to DB: " . mysql_error();
        exit;
    }

    if (!mysql_select_db("mydbname")) {
        echo "Unable to select mydbname: " . mysql_error();
        exit;
    }

    $sql = "SELECT id as userid, fullname, userstatus
            FROM   sometable
            WHERE  userstatus = 1";

    $result = mysql_query($sql);

    if (!$result) {
        echo "Could not successfully run query ($sql) from DB: " . mysql_error();
        exit;
    }

    if (mysql_num_rows($result) == 0) {
        echo "No rows found, nothing to print so am exiting";
        exit;
    }

    // While a row of data exists, put that row in $row as an associative array
    // Note: If you're expecting just one row, no need to use a loop
    // Note: If you put extract($row); inside the following loop, you'll
    //       then create $userid, $fullname, and $userstatus
    while ($row = mysql_fetch_assoc($result)) {
        echo $row["userid"];
        echo $row["fullname"];
        echo $row["userstatus"];
    }

    mysql_free_result($result);

    ?>

### 注释

> 注意: 性能
> 必须指出一个要点： mysql_fetch_assoc() 比 mysql_fetch_row() 并不明显 慢，而且还提供了更多有用的值。

> 注意: 此函数返回的字段名大小写敏感。

> 注意: 此函数将 NULL 字段设置为 PHP `null` 值。

### 参见

- mysql_fetch_row() - 从结果集中取得一行作为枚举数组
- mysql_fetch_array() - 从结果集中取得一行作为关联数组
- mysql_data_seek() - 移动内部结果的指针
- mysql_query() - 发送一条 MySQL 查询
- mysql_error() - 返回上一个 MySQL 操作中的错误信息的文本

# mysql_fetch_field

(PHP 4, PHP 5)

mysql_fetch_field — 从结果集中取得列信息并作为对象返回

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_fetch_field()
- PDOStatement::getColumnMeta()

### 说明

function mysql_fetch_field(resource `$result`, int `$field_offset` = ?): object

返回一个包含字段信息的对象。

mysql_fetch_field() 可以用来从某个查询结果中取得字段的信息。如果没有指定字段偏移量，则下一个尚未被 mysql_fetch_field() 取得的字段被提取。

对象的属性为：

- name - 列名
- table - 该列所在的表名，which is the alias name if one is defined
- max_length - 该列最大长度
- not_null - 1，如果该列不能为 `null`
- primary_key - 1，如果该列是 primary key
- unique_key - 1，如果该列是 unique key
- multiple_key - 1，如果该列是 non-unique key
- numeric - 1，如果该列是 numeric
- blob - 1，如果该列是 BLOB
- type - 该列的类型
- unsigned - 1，如果该列是无符号数
- zerofill - 1，如果该列是 zero-filled

> 注意: 此函数返回的字段名大小写敏感。

示例 #1 mysql_fetch_field()

    <?php
    mysql_connect('localhost:3306', $user, $password)
        or die("Could not connect: " . mysql_error());
    mysql_select_db("database");
    $result = mysql_query("select * from table")
        or die("Query failed: " . mysql_error());
    /* get column metadata */
    $i = 0;
    while ($i < mysql_num_fields($result)) {
        echo "Information for column $i:<br />\n";
        $meta = mysql_fetch_field($result);
        if (!$meta) {
            echo "No information available<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);
    ?>

参见 mysql_field_seek()。

### 参数

`result`
  resource 型的结果集。此结果集来自对 mysql_query() 的调用。
`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`.

### 返回值

Returns an object containing field information. The properties of the object are:

- name - column name
- table - name of the table the column belongs to
- 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

### 示例

示例 #2 mysql_fetch_field() example

    <?php
    $conn = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$conn) {
        die('Could not connect: ' . mysql_error());
    }
    mysql_select_db('database');
    $result = mysql_query('select * from table');
    if (!$result) {
        die('Query failed: ' . mysql_error());
    }
    /* get column metadata */
    $i = 0;
    while ($i < mysql_num_fields($result)) {
        echo "Information for column $i:<br />\n";
        $meta = mysql_fetch_field($result, $i);
        if (!$meta) {
            echo "No information available<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);
    ?>

### 注释

> 注意: 此函数返回的字段名大小写敏感。

> 注意: If field or tablenames are aliased in the SQL query the aliased name will be returned. The original name can be retrieved for instance by using mysqli_result::fetch_field().

### 参见

- mysql_field_seek() - 将结果指针设置为指定的字段偏移量

# mysql_fetch_lengths

(PHP 4, PHP 5)

mysql_fetch_lengths — 取得结果集中每个输出的长度

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_fetch_lengths()
- PDOStatement::getColumnMeta()

### 说明

function mysql_fetch_lengths(resource `$result`): array|false

返回数组，对应 MySQL 查询中获取的最后一行的每个字段的长度。

mysql_fetch_lengths() 将上一次 mysql_fetch_row()、mysql_fetch_assoc()、mysql_fetch_array() 和 mysql_fetch_object() 所返回的最后一行的每个字段的长度储存到一个数组中，偏移量从 0 开始。

### 参数

`result`
  resource 型的结果集。此结果集来自对 mysql_query() 的调用。

### 返回值

An array of lengths on success 或者在失败时返回 `false`.

### 示例

示例 #1 mysql_fetch_lengths() 示例

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Could not run query: ' . mysql_error();
        exit;
    }
    $row     = mysql_fetch_assoc($result);
    $lengths = mysql_fetch_lengths($result);

    print_r($row);
    print_r($lengths);
    ?>

以上示例的输出类似于：

    Array
    (
        [id] => 42
        [email] => user@example.com
    )
    Array
    (
        [0] => 2
        [1] => 16
    )

### 参见

- mysql_field_len() - 返回指定字段的长度
- mysql_fetch_row() - 从结果集中取得一行作为枚举数组
- strlen() - 获取字符串长度

# mysql_fetch_object

(PHP 4, PHP 5)

mysql_fetch_object — 从结果集中取得一行作为对象返回

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_fetch_object()
- PDOStatement::fetch() with `mode` as `PDO::FETCH_OBJ`

### 说明

function mysql_fetch_object(resource `$result`, string `$class_name` = ?, array `$params` = ?): object

返回一个对象，其属性与获取的行相对应，并将内部数据指针向前移动。

### 参数

`result`
  resource 型的结果集。此结果集来自对 mysql_query() 的调用。
`class_name`
  要实例化、设置属性并返回的类的名称，如果不指定，默认返回 stdClass 对象。
`params`
  可选 array 数组参数，会传递给 `class_name` 类的构造函数。

### 返回值

返回根据所取得的行生成的对象 object，如果没有更多行则返回 `false`。

### 示例

示例 #1 mysql_fetch_object() example

    <?php
    mysql_connect("hostname", "user", "password");
    mysql_select_db("mydb");
    $result = mysql_query("select * from mytable");
    while ($row = mysql_fetch_object($result)) {
        echo $row->user_id;
        echo $row->fullname;
    }
    mysql_free_result($result);
    ?>

示例 #2 mysql_fetch_object() example

    <?php
    class foo {
        public $name;
    }

    mysql_connect("hostname", "user", "password");
    mysql_select_db("mydb");

    $result = mysql_query("select name from mytable limit 1");
    $obj = mysql_fetch_object($result, 'foo');
    var_dump($obj);
    ?>

### 注释

> 注意: Performance
> 速度上，本函数和 mysql_fetch_array() 一样，也几乎和 mysql_fetch_row() 一样快（差别很不明显）。

> 注意: mysql_fetch_object() 和 mysql_fetch_array() 类似，只有一点区别 - 返回一个对象而不是数组。间接地也意味着只能通过字段名来访问数组，而不是偏移量（数字是合法的属性名）。

> 注意: 此函数返回的字段名大小写敏感。

> 注意: 此函数将 NULL 字段设置为 PHP `null` 值。

### 参见

- mysql_fetch_array() - 从结果集中取得一行作为关联数组
- mysql_fetch_assoc() - 从结果集中取得一行作为关联数组
- mysql_fetch_row() - 从结果集中取得一行作为枚举数组
- mysql_data_seek() - 移动内部结果的指针
- mysql_query() - 发送一条 MySQL 查询

# mysql_fetch_row

(PHP 4, PHP 5)

mysql_fetch_row — 从结果集中取得一行作为枚举数组

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_fetch_row()
- PDOStatement::fetch() with `mode` as `PDO::FETCH_NUM`

### 说明

function mysql_fetch_row(resource `$result`): array

返回根据所取得的行生成的数组，如果没有更多行则返回 `false`。

mysql_fetch_row() 从和指定的结果标识关联的结果集中取得一行数据并作为数组返回。每个结果的列储存在一个数组的单元中，偏移量从 0 开始。

依次调用 mysql_fetch_row() 将返回结果集中的下一行，如果没有更多行则返回 `false`。

参见 mysql_fetch_array()，mysql_fetch_assoc()，mysql_fetch_object()，mysql_data_seek()，mysql_fetch_lengths() 和 mysql_result()。

### 参数

`result`
  resource 型的结果集。此结果集来自对 mysql_query() 的调用。

### 返回值

Returns an numerical array of strings that corresponds to the fetched row, or `false` if there are no more rows.

mysql_fetch_row() fetches one row of data from the result associated with the specified result identifier. The row is returned as an array. Each result column is stored in an array offset, starting at offset 0.

### 示例

示例 #1 Fetching one row with mysql_fetch_row()

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Could not run query: ' . mysql_error();
        exit;
    }
    $row = mysql_fetch_row($result);

    echo $row[0]; // 42
    echo $row[1]; // the email value
    ?>

### 注释

> 注意: 此函数将 NULL 字段设置为 PHP `null` 值。

### 参见

- mysql_fetch_array() - 从结果集中取得一行作为关联数组
- mysql_fetch_assoc() - 从结果集中取得一行作为关联数组
- mysql_fetch_object() - 从结果集中取得一行作为对象返回
- mysql_data_seek() - 移动内部结果的指针
- mysql_fetch_lengths() - 取得结果集中每个输出的长度
- mysql_result() - 取得结果数据

# mysql_field_flags

(PHP 4, PHP 5)

mysql_field_flags — 从结果中取得和指定字段关联的 flags

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_fetch_field_direct() [flags]
- PDOStatement::getColumnMeta() [flags]

### 说明

function mysql_field_flags(resource `$result`, int `$field_offset`): string|false

mysql_field_flags() 返回指定字段的字段 flags。每个 flag 都用一个单词表示，之间用一个空格分开，因此可以用 explode() 将返回值分开。

### 参数

`result`
  resource 型的结果集。此结果集来自对 mysql_query() 的调用。
`field_offset`
  数值型字段偏移量。 `field_offset` 从 `0` 开始。如果 `field_offset` 不存在，则会发出一个 `E_WARNING` 级别的错误

### 返回值

Returns a string of flags associated with the result 或者在失败时返回 `false`.

如果 MySQL 版本足够新，以便支持这些 flag，则会报告以下 flag：`"not_null"`、`"primary_key"`、`"unique_key"`、`"multiple_key"`、`"blob"`、`"unsigned"`、`"zerofill"`,`"binary"`、`"enum"`、`"auto_increment"` 和 `"timestamp"`。

### 示例

示例 #1 mysql_field_flags() 示例

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Could not run query: ' . mysql_error();
        exit;
    }
    $flags = mysql_field_flags($result, 0);

    echo $flags;
    print_r(explode(' ', $flags));
    ?>

以上示例的输出类似于：

    not_null primary_key auto_increment
    Array
    (
        [0] => not_null
        [1] => primary_key
        [2] => auto_increment
    )

### 注释

> 注意: 为了向下兼容，可以使用下列已废弃的别名： mysql_fieldflags()

### 参见

- mysql_field_type() - 取得结果集中指定字段的类型
- mysql_field_len() - 返回指定字段的长度

# mysql_field_len

(PHP 4, PHP 5)

mysql_field_len — 返回指定字段的长度

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_fetch_field_direct() [length]
- PDOStatement::getColumnMeta() [len]

### 说明

function mysql_field_len(resource `$result`, int `$field_offset`): int|false

mysql_field_len() 返回指定字段的长度。

### 参数

`result`
  resource 型的结果集。此结果集来自对 mysql_query() 的调用。
`field_offset`
  数值型字段偏移量。 `field_offset` 从 `0` 开始。如果 `field_offset` 不存在，则会发出一个 `E_WARNING` 级别的错误

### 返回值

The length of the specified field index on success 或者在失败时返回 `false`.

### 示例

示例 #1 mysql_field_len() 示例

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Could not run query: ' . mysql_error();
        exit;
    }

    // Will get the length of the id field as specified in the database
    // schema.
    $length = mysql_field_len($result, 0);
    echo $length;
    ?>

### 注释

> 注意: 为了向下兼容，可以使用下列已废弃的别名： mysql_fieldlen()

### 参见

- mysql_fetch_lengths() - 取得结果集中每个输出的长度
- strlen() - 获取字符串长度

# mysql_field_name

(PHP 4, PHP 5)

mysql_field_name — 取得结果中指定字段的字段名

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_fetch_field_direct() [name] or [orgname]
- PDOStatement::getColumnMeta() [name]

### 说明

function mysql_field_name(resource `$result`, int `$field_offset`): string|false

mysql_field_name() 返回指定字段索引的字段名。`result` 必须是一个合法的结果标识符，`field_index` 是该字段的数字偏移量。

> 注意: `field_index` 从 0 开始。 例如，第三个字段的索引值其实是 2，第四个字段的索引值是 3，以此类推。

> 注意: 此函数返回的字段名大小写敏感。

示例 #1 mysql_field_name() 例子

    <?php
    /* The users table consists of three fields:
     *   user_id
     *   username
     *   password.
     */
    $link = mysql_connect('localhost', "mysql_user", "mysql_password");
    $dbname = "mydb";
    mysql_select_db($dbname, $link)
        or die("Could not set $dbname: " . mysql_error());
    $res = mysql_query("select * from users", $link);

    echo mysql_field_name($res, 0) . "\n";
    echo mysql_field_name($res, 2);
    ?>

以上例子将产生如下输出：

    user_id
    password

为向下兼容仍然可以使用 mysql_fieldname()，但反对这样做。

### 参数

`result`
  resource 型的结果集。此结果集来自对 mysql_query() 的调用。
`field_offset`
  数值型字段偏移量。 `field_offset` 从 `0` 开始。如果 `field_offset` 不存在，则会发出一个 `E_WARNING` 级别的错误

### 返回值

The name of the specified field index on success 或者在失败时返回 `false`.

### 示例

示例 #2 mysql_field_name() example

    <?php
    /* The users table consists of three fields:
     *   user_id
     *   username
     *   password.
     */
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Could not connect to MySQL server: ' . mysql_error());
    }
    $dbname = 'mydb';
    $db_selected = mysql_select_db($dbname, $link);
    if (!$db_selected) {
        die("Could not set $dbname: " . mysql_error());
    }
    $res = mysql_query('select * from users', $link);

    echo mysql_field_name($res, 0) . "\n";
    echo mysql_field_name($res, 2);
    ?>

以上示例会输出：

    user_id
    password

### 注释

> 注意: 此函数返回的字段名大小写敏感。

> 注意: 为了向下兼容，可以使用下列已废弃的别名： mysql_fieldname()

### 参见

- mysql_field_type() - 取得结果集中指定字段的类型
- mysql_field_len() - 返回指定字段的长度

# mysql_field_seek

(PHP 4, PHP 5)

mysql_field_seek — 将结果指针设置为指定的字段偏移量

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_field_seek()
- PDOStatement::fetch() 使用 `cursor_orientation` 和 `offset` 参数

### 说明

function mysql_field_seek(resource `$result`, int `$field_offset`): bool

定位到指定字段偏移量。如果下次调用 mysql_fetch_field() 不包含字段偏移量，则会返回 mysql_field_seek() 中指定字段的偏移量。

### 参数

`result`
  resource 型的结果集。此结果集来自对 mysql_query() 的调用。
`field_offset`
  数值型字段偏移量。 `field_offset` 从 `0` 开始。如果 `field_offset` 不存在，则会发出一个 `E_WARNING` 级别的错误

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- mysql_fetch_field() - 从结果集中取得列信息并作为对象返回

# mysql_field_table

(PHP 4, PHP 5)

mysql_field_table — 取得指定字段所在的表名

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_fetch_field_direct() [table] 或 [orgtable]
- PDOStatement::getColumnMeta() [table]

### 说明

function mysql_field_table(resource `$result`, int `$field_offset`): string

返回指定字段所在的表名。

### 参数

`result`
  resource 型的结果集。此结果集来自对 mysql_query() 的调用。
`field_offset`
  数值型字段偏移量。 `field_offset` 从 `0` 开始。如果 `field_offset` 不存在，则会发出一个 `E_WARNING` 级别的错误

### 返回值

The name of the table on success.

### 示例

示例 #1 mysql_field_table() 示例

    <?php

    $query = "SELECT account.*, country.* FROM account, country WHERE country.name = 'Portugal' AND account.country_id = country.id";

    // get the result from the DB
    $result = mysql_query($query);

    // Lists the table name and then the field name
    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";
    }

    ?>

### 注释

> 注意: 为了向下兼容，可以使用下列已废弃的别名： mysql_fieldtable()

### 参见

- mysql_list_tables() - 列出 MySQL 数据库中的表

# mysql_field_type

(PHP 4, PHP 5)

mysql_field_type — 取得结果集中指定字段的类型

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_fetch_field_direct() [type]
- PDOStatement::getColumnMeta() [driver:decl_type] or [pdo_type]

### 说明

function mysql_field_type(resource `$result`, int `$field_offset`): string

mysql_field_type() 和 mysql_field_name() 函数相似。参数完全相同，但返回的是字段类型而不是字段名。字段类型有“int”，“real”，“string”，“blob”以及其它，详见 » MySQL 手册。

示例 #1 mysql_field_type() 例子

    <?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 "Your '".$table."' table has ".$fields." fields and ".$rows." record(s)\n";
        echo "The table has the following fields:\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();
    ?>

以上例子将产生如下输出：

    Your 'func' table has 4 fields and 1 record(s)
    The table has the following fields:
    string name 64 not_null primary_key binary
    int ret 1 not_null
    string dl 128 not_null
    string type 9 not_null enum

为向下兼容仍然可以使用 mysql_fieldtype()，但反对这样做。

### 参数

`result`
  resource 型的结果集。此结果集来自对 mysql_query() 的调用。
`field_offset`
  数值型字段偏移量。 `field_offset` 从 `0` 开始。如果 `field_offset` 不存在，则会发出一个 `E_WARNING` 级别的错误

### 返回值

The returned field type will be one of `"int"`, `"real"`, `"string"`, `"blob"`, and others as detailed in the » MySQL documentation.

### 示例

示例 #2 mysql_field_type() example

    <?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 "Your '" . $table . "' table has " . $fields . " fields and " . $rows . " record(s)\n";
    echo "The table has the following fields:\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();
    ?>

以上示例的输出类似于：

    Your 'func' table has 4 fields and 1 record(s)
    The table has the following fields:
    string name 64 not_null primary_key binary
    int ret 1 not_null
    string dl 128 not_null
    string type 9 not_null enum

### 注释

> 注意: 为了向下兼容，可以使用下列已废弃的别名： mysql_fieldtype()

### 参见

- mysql_field_name() - 取得结果中指定字段的字段名
- mysql_field_len() - 返回指定字段的长度

# mysql_free_result

(PHP 4, PHP 5)

mysql_free_result — 释放结果内存

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_free_result()
- Assign the value of `null` to the PDO object, or PDOStatement::closeCursor()

### 说明

function mysql_free_result(resource `$result`): bool

mysql_free_result() 将释放所有与结果标识符 `result` 所关联的内存。

mysql_free_result() 仅需要在考虑到返回很大的结果集时会占用多少内存时调用。在脚本结束后所有关联的内存都会被自动释放。

成功时返回 `true`， 或者在失败时返回 `false`。

为向下兼容仍然可以使用 mysql_freeresult()，但反对这样做。

### 参数

`result`
  resource 型的结果集。此结果集来自对 mysql_query() 的调用。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

If a non-resource is used for the `result`, an error of level E_WARNING will be emitted. It's worth noting that mysql_query() only returns a resource for SELECT, SHOW, EXPLAIN, and DESCRIBE queries.

### 示例

示例 #1 A mysql_free_result() example

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Could not run query: ' . mysql_error();
        exit;
    }
    /* Use the result, assuming we're done with it afterwards */
    $row = mysql_fetch_assoc($result);

    /* Now we free up the result and continue on with our script */
    mysql_free_result($result);

    echo $row['id'];
    echo $row['email'];
    ?>

### 注释

> 注意: 为了向下兼容，可以使用下列已废弃的别名： mysql_freeresult()

### 参见

- mysql_query() - 发送一条 MySQL 查询
- is_resource() - 查找变量是否为资源

# mysql_get_client_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_client_info — 取得 MySQL 客户端信息

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_get_client_info()
- PDO::getAttribute() with `attribute` as `PDO::ATTR_CLIENT_VERSION`

### 说明

function mysql_get_client_info(): string

mysql_get_client_info() 返回表示客户端库版本的字符串。

### 参数

此函数没有参数。

### 返回值

MySQL 客户端版本。

### 示例

示例 #1 mysql_get_client_info() 示例

    <?php
    printf("MySQL client info: %s\n", mysql_get_client_info());
    ?>

以上示例的输出类似于：

    MySQL client info: 3.23.39

### 参见

- mysql_get_host_info() - 取得 MySQL 主机信息
- mysql_get_proto_info() - 取得 MySQL 协议信息
- mysql_get_server_info() - 取得 MySQL 服务器信息

# mysql_get_host_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_host_info — 取得 MySQL 主机信息

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_get_host_info()
- PDO::getAttribute() with `attribute` as `PDO::ATTR_CONNECTION_STATUS`

### 说明

function mysql_get_host_info(resource `$link_identifier` = NULL): string|false

描述 connection 中使用的连接类型，包括服务器主机名。

### 参数

`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

Returns a string describing the type of MySQL connection in use for the connection 或者在失败时返回 `false`.

### 示例

示例 #1 mysql_get_host_info() 示例

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Could not connect: ' . mysql_error());
    }
    printf("MySQL host info: %s\n", mysql_get_host_info());
    ?>

以上示例的输出类似于：

    MySQL host info: Localhost via UNIX socket

### 参见

- mysql_get_client_info() - 取得 MySQL 客户端信息
- mysql_get_proto_info() - 取得 MySQL 协议信息
- mysql_get_server_info() - 取得 MySQL 服务器信息

# mysql_get_proto_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_proto_info — 取得 MySQL 协议信息

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_get_proto_info()

### 说明

function mysql_get_proto_info(resource `$link_identifier` = NULL): int|false

检索 MySQL 协议。

### 参数

`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

Returns the MySQL protocol on success 或者在失败时返回 `false`.

### 示例

示例 #1 mysql_get_proto_info() 示例

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Could not connect: ' . mysql_error());
    }
    printf("MySQL protocol version: %s\n", mysql_get_proto_info());
    ?>

以上示例的输出类似于：

    MySQL protocol version: 10

### 参见

- mysql_get_client_info() - 取得 MySQL 客户端信息
- mysql_get_host_info() - 取得 MySQL 主机信息
- mysql_get_server_info() - 取得 MySQL 服务器信息

# mysql_get_server_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_server_info — 取得 MySQL 服务器信息

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_get_server_info()
- PDO::getAttribute() with `attribute` as `PDO::ATTR_SERVER_VERSION`

### 说明

function mysql_get_server_info(resource `$link_identifier` = NULL): string|false

检索 MySQL 服务器版本。

### 参数

`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

Returns the MySQL server version on success 或者在失败时返回 `false`.

### 示例

示例 #1 mysql_get_server_info() 示例

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Could not connect: ' . mysql_error());
    }
    printf("MySQL server version: %s\n", mysql_get_server_info());
    ?>

以上示例的输出类似于：

    MySQL server version: 4.0.1-alpha

### 参见

- mysql_get_client_info() - 取得 MySQL 客户端信息
- mysql_get_host_info() - 取得 MySQL 主机信息
- mysql_get_proto_info() - 取得 MySQL 协议信息
- phpversion() - 获取当前的PHP版本

# mysql_info

(PHP 4 >= 4.3.0, PHP 5)

mysql_info — 获取最近查询的有关信息

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_info()

### 说明

function mysql_info(resource `$link_identifier` = NULL): string

返回最近一条查询的详细信息。

### 参数

`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

在成功时返回语句信息，在失败时返回 `false`。请查看下面的示例，了解哪些语句提供信息，以及返回值可能是什么样子。未列出的语句将返回 `false`。

### 示例

示例 #1 相关的 MySQL 语句

返回字符串值的语句。这些数字仅用于说明目的；它们的值将与查询相对应。

    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

### 注释

> 注意: mysql_info() 对于 INSERT ... VALUES 语句仅在该语句中列出了多个值的情况下返回非 `false` 的值。

### 参见

- mysql_affected_rows() - 取得前一次 MySQL 操作所影响的记录行数
- mysql_insert_id() - 取得上一条查询生成的 ID
- mysql_stat() - 获取当前系统状态

# mysql_insert_id

(PHP 4, PHP 5)

mysql_insert_id — 取得上一条查询生成的 ID

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_insert_id()
- PDO::lastInsertId()

### 说明

function mysql_insert_id(resource `$link_identifier` = NULL): int

检索通过之前查询（通常是 INSERT）中 AUTO_INCREMENT 列生成的 ID。

### 参数

`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

成功时返回通过之前查询中 AUTO_INCREMENT 列生成的 ID，如果之前查询没有生成 AUTO_INCREMENT 值，则为 `0`。如果没有建立 MySQL 连接，则为 `false`。

### 示例

示例 #1 mysql_insert_id() 示例

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Could not connect: ' . mysql_error());
    }
    mysql_select_db('mydb');

    mysql_query("INSERT INTO mytable (product) values ('kossu')");
    printf("Last inserted record has id %d\n", mysql_insert_id());
    ?>

### 注释

警告

mysql_insert_id() will convert the return type of the native MySQL C API function `mysql_insert_id()` to a type of `long` (named int in PHP). If your AUTO_INCREMENT column has a column type of BIGINT (64 bits) the conversion may result in an incorrect value. Instead, use the internal MySQL SQL function LAST_INSERT_ID() in an SQL query. For more information about PHP's maximum integer values, please see the integer documentation.

> 注意: Because mysql_insert_id() acts on the last performed query, be sure to call mysql_insert_id() immediately after the query that generates the value.

> 注意: The value of the MySQL SQL function `LAST_INSERT_ID()` always contains the most recently generated AUTO_INCREMENT value, and is not reset between queries.

### 参见

- mysql_query() - 发送一条 MySQL 查询
- mysql_info() - 获取最近查询的有关信息

# mysql_list_dbs

(PHP 4, PHP 5)

mysql_list_dbs — 列出 MySQL 服务器中可用的数据库

警告

本函数自 PHP 5.4.0 起已废弃，并且它和整个MySQL 扩展自 PHP 7.0.0 开始被移除。 可以选择出于活跃开发中的MySQLi或PDO_MySQL扩展来作为替代。 参见MySQL：选择 API 指南来获取更多信息。 用以替代本函数的有：

- SQL 查询：`SHOW DATABASES`

### 说明

function mysql_list_dbs(resource `$link_identifier` = NULL): resource

返回结果指针，包含当前 MySQL 守护进程中可用的数据库。

### 参数

`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

Returns a result pointer resource on success, or `false` on failure. 使用 mysql_tablename() 函数或任何使用结果表的函数（比如 mysql_fetch_array()）来遍历此结果指针。

### 示例

示例 #1 mysql_list_dbs() 示例

    <?php
    // Usage without 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";
    }

    // Deprecated as of 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";
    }
    ?>

以上示例的输出类似于：

    database1
    database2
    database3

### 注释

> 注意: 为了向下兼容，可以使用下列已废弃的别名： mysql_listdbs()

### 参见

- mysql_db_name() - 取得 mysql_list_dbs 返回的结果数据
- mysql_select_db() - 选择 MySQL 数据库

# mysql_list_fields

(PHP 4, PHP 5)

mysql_list_fields — 列出 MySQL 表字段

警告

本函数自 PHP 5.4.0 起已废弃，并且它和整个MySQL 扩展自 PHP 7.0.0 开始被移除。 可以选择出于活跃开发中的MySQLi或PDO_MySQL扩展来作为替代。 参见MySQL：选择 API 指南来获取更多信息。 用以替代本函数的有：

- SQL 查询：`SHOW COLUMNS FROM sometable`

### 说明

function mysql_list_fields(string `$database_name`, string `$table_name`, resource `$link_identifier` = NULL): resource

检索指定表名的信息。

此函数已弃用。最好使用 mysql_query() 发出 SQL `SHOW COLUMNS FROM table [LIKE 'name']` 语句代替。

### 参数

`database_name`
  The name of the database that's being queried.
`table_name`
  The name of the table that's being queried.
`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

A result pointer resource on success, or `false` on failure.

结果指针，可以用于 mysql_field_flags()、mysql_field_len()、mysql_field_name() 和 mysql_field_type()。

### 示例

示例 #1 替代弃用 mysql_list_fields()

    <?php
    $result = mysql_query("SHOW COLUMNS FROM sometable");
    if (!$result) {
        echo 'Could not run query: ' . mysql_error();
        exit;
    }
    if (mysql_num_rows($result) > 0) {
        while ($row = mysql_fetch_assoc($result)) {
            print_r($row);
        }
    }
    ?>

以上示例的输出类似于：

    Array
    (
        [Field] => id
        [Type] => int(7)
        [Null] =>
        [Key] => PRI
        [Default] =>
        [Extra] => auto_increment
    )
    Array
    (
        [Field] => email
        [Type] => varchar(100)
        [Null] =>
        [Key] =>
        [Default] =>
        [Extra] =>
    )

### 注释

> 注意: 为了向下兼容，可以使用下列已废弃的别名： mysql_listfields()

### 参见

- mysql_field_flags() - 从结果中取得和指定字段关联的 flags
- mysql_info() - 获取最近查询的有关信息

# mysql_list_processes

(PHP 4 >= 4.3.0, PHP 5)

mysql_list_processes — 列出 MySQL 进程

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_thread_id()

### 说明

function mysql_list_processes(resource `$link_identifier` = NULL): resource|false

检索当前 MySQL 服务器线程。

### 参数

`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

A result pointer resource on success 或者在失败时返回 `false`.

### 示例

示例 #1 mysql_list_processes() 示例

    <?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);
    ?>

以上示例的输出类似于：

    1 localhost test Processlist 0
    4 localhost mysql sleep 5

### 参见

- mysql_thread_id() - 返回当前线程的 ID
- mysql_stat() - 获取当前系统状态

# mysql_list_tables

(PHP 4, PHP 5)

mysql_list_tables — 列出 MySQL 数据库中的表

警告

本函数自 PHP 4.3.0 起已废弃，并且它和整个 MySQL 扩展自 PHP 7.0.0 开始被移除。 可以选择出于活跃开发中的 MySQLi 或 PDO_MySQL 扩展来作为替代。 参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- SQL Query: `SHOW TABLES FROM dbname`

### 说明

function mysql_list_tables(string `$database`, resource `$link_identifier` = ?): resource|false

列出 MySQL 数据库中的表。

此函数已废弃。推荐使用 mysql_query() 来执行 SQL `SHOW TABLES [FROM db_name] [LIKE 'pattern']` 来实现同样的操作。

### 参数

`database`
  数据库名称
`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

成功时返回结果指针 resource 或者在失败时返回 `false`。

可以使用 mysql_tablename() 函数来遍历该结果指针，或者使用任何针对表操作的函数，类似 mysql_fetch_array()。

### 示例

示例 #1 mysql_list_tables() 例子

    <?php
    $dbname = 'mysql_dbname';

    if (!mysql_connect('mysql_host', 'mysql_user', 'mysql_password')) {
        echo 'Could not connect to mysql';
        exit;
    }

    $sql = "SHOW TABLES FROM $dbname";
    $result = mysql_query($sql);

    if (!$result) {
        echo "DB Error, could not list tables\n";
        echo 'MySQL Error: ' . mysql_error();
        exit;
    }

    while ($row = mysql_fetch_row($result)) {
        echo "Table: {$row[0]}\n";
    }

    mysql_free_result($result);
    ?>

### 注释

> 注意: 为了向下兼容，可以使用下列已废弃的别名： mysql_listtables()

### 参见

- mysql_list_dbs() - 列出 MySQL 服务器中可用的数据库
- mysql_tablename() - 取得表名

# mysql_num_fields

(PHP 4, PHP 5)

mysql_num_fields — 取得结果中字段的数量

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_num_fields()
- PDOStatement::columnCount()

### 说明

function mysql_num_fields(resource `$result`): int|false

从查询中检索字段的数量。

### 参数

`result`
  resource 型的结果集。此结果集来自对 mysql_query() 的调用。

### 返回值

Returns the number of fields in the result set resource on success 或者在失败时返回 `false`.

### 示例

示例 #1 mysql_num_fields() 示例

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Could not run query: ' . mysql_error();
        exit;
    }

    /* returns 2 because id,email === two fields */
    echo mysql_num_fields($result);
    ?>

### 注释

> 注意: 为了向下兼容，可以使用下列已废弃的别名： mysql_numfields()

### 参见

- mysql_select_db() - 选择 MySQL 数据库
- mysql_query() - 发送一条 MySQL 查询
- mysql_fetch_field() - 从结果集中取得列信息并作为对象返回
- mysql_num_rows() - 获取结果中行数

# mysql_num_rows

(PHP 4, PHP 5)

mysql_num_rows — 获取结果中行数

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_num_rows()
- mysqli_stmt_num_rows()
- PDOStatement::rowCount()

### 说明

function mysql_num_rows(resource `$result`): int|false

检索结果集中的行数。此命令仅适用于返回实际结果集的 SELECT 或 SHOW 语句。要检索受 INSERT、UPDATE、REPLACE 或 DELETE 查询影响的行数，请使用 mysql_affected_rows() 函数。

### 参数

`result`
  resource 型的结果集。此结果集来自对 mysql_query() 的调用。

### 返回值

The number of rows in a result set on success 或者在失败时返回 `false`.

### 示例

示例 #1 mysql_num_rows() 示例

    <?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 Rows\n";

    ?>

### 注释

> 注意: 如果使用 mysql_unbuffered_query()，则直到检索到结果集中的所有行后 mysql_num_rows() 才能返回正确的值。

> 注意: 为了向下兼容，可以使用下列已废弃的别名： mysql_numrows()

### 参见

- mysql_affected_rows() - 取得前一次 MySQL 操作所影响的记录行数
- mysql_connect() - 打开一个到 MySQL 服务器的连接
- mysql_data_seek() - 移动内部结果的指针
- mysql_select_db() - 选择 MySQL 数据库
- mysql_query() - 发送一条 MySQL 查询

# mysql_pconnect

(PHP 4, PHP 5)

mysql_pconnect — 打开一个到 MySQL 服务器的持久连接

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_connect() with `p:` host prefix
- PDO::__construct() with `PDO::ATTR_PERSISTENT` as a driver option

### 说明

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

打开一个到 MySQL 服务器的持久连接。

mysql_pconnect() 和 mysql_connect() 非常相似，但有两个主要区别。

首先，当连接的时候本函数将先尝试寻找一个在同一个主机上用同样的用户名和密码已经打开的（持久）连接，如果找到，则返回此连接标识而不打开新连接。

其次，当脚本执行完毕后到 SQL 服务器的连接不会被关闭，此连接将保持打开以备以后使用（mysql_close() 不会关闭由 mysql_pconnect() 建立的连接）。

此种连接称为“持久的”。

### 参数

`server`
  MySQL 服务器地址，参数也可以包括端口号，例如 “hostname:port“ 或者是本机套接字的的路径，例如 “:/path/to/socket“ 如果 PHP 配置文件中 mysql.default_host 的值未设置（默认情况下），则默认值为 'localhost:3306'
`username`
  数据库连接使用的用户名。默认为当前服务器进程的用户。
`password`
  数据库连接使用的密码。默认为空密码。
`client_flags`
  参数 `client_flags` 可以为以下常量： 128 (enable `LOAD DATA LOCAL` handling), `MYSQL_CLIENT_SSL`, `MYSQL_CLIENT_COMPRESS`, `MYSQL_CLIENT_IGNORE_SPACE` 或 `MYSQL_CLIENT_INTERACTIVE`。

### 返回值

如果成功则返回一个正的 MySQL 持久连接标识符，出错则返回 `false`。

### 注释

> 注意: 需要注意的是，此函数仅当在 PHP 模块化运行时才会生效。更多信息请参阅 持久数据库连接 章节。

警告

使用持久连接可能需要对 Apache 和 MySQL 配置进行一些调整，以确保不超过 MySQL 服务器允许的最大连接数。

### 参见

- mysql_connect() - 打开一个到 MySQL 服务器的连接
- Persistent Database Connections

# mysql_ping

(PHP 4 >= 4.3.0, PHP 5)

mysql_ping — Ping 服务器连接的状态，如果没有连接则重新连接

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_ping()

### 说明

function mysql_ping(resource `$link_identifier` = NULL): bool

检查到服务器的连接是否正常。如果断开，则自动尝试连接。本函数可用于空闲很久的脚本来检查服务器是否关闭了连接，如果有必要则重新连接上。。

> 注意: 从 MySQL 版本 5.0.3 开始，默认情况下不启用自动重新连接功能。

### 参数

`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

如果到服务器的连接可用则，返回 `true`，否则返回 `false`。

### 示例

示例 #1 mysql_ping() 示例

    <?php
    set_time_limit(0);

    $conn = mysql_connect('localhost', 'mysqluser', 'mypass');
    $db   = mysql_select_db('mydb');

    /* Assuming this query will take a long time */
    $result = mysql_query($sql);
    if (!$result) {
        echo 'Query #1 failed, exiting.';
        exit;
    }

    /* Make sure the connection is still alive, if not, try to reconnect */
    if (!mysql_ping($conn)) {
        echo 'Lost connection, exiting after query #1';
        exit;
    }
    mysql_free_result($result);

    /* So the connection is still alive, let's run another query */
    $result2 = mysql_query($sql2);
    ?>

### 参见

- mysql_thread_id() - 返回当前线程的 ID
- mysql_list_processes() - 列出 MySQL 进程

# mysql_query

(PHP 4, PHP 5)

mysql_query — 发送一条 MySQL 查询

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_query()
- PDO::query()

### 说明

function mysql_query(string `$query`, resource `$link_identifier` = NULL): mixed

mysql_query() 向与指定的 `link_identifier` 关联的服务器中的当前活动数据库发送一条查询（不支持多条查询）。

### 参数

`query`
  SQL 查询语句 查询字符串不应以分号结束。 查询中被嵌入的数据应该正确地转义。
`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

mysql_query() 仅对 SELECT，SHOW，DESCRIBE, EXPLAIN 和其他语句 语句返回一个 resource，如果查询出现错误则返回 `false`。

对于其它类型的 SQL 语句，比如INSERT, UPDATE, DELETE, DROP 之类， mysql_query() 在执行成功时返回 `true`，出错时返回 `false`。

返回的结果资源应该传递给 mysql_fetch_array() 和其他函数来处理结果表,取出返回的数据。

假定查询成功，可以调用 mysql_num_rows() 来查看对应于 SELECT 语句返回了多少行，或者调用 mysql_affected_rows() 来查看对应于 DELETE，INSERT，REPLACE 或 UPDATE 语句影响到了多少行。

如果没有权限访问查询语句中引用的表时，mysql_query() 也会返回 `false`。

### 示例

示例 #1 无效的查询

以下查询语法上有错，因此 mysql_query() 失败并返回 `false`。

    <?php
    $result = mysql_query('SELECT * WHERE 1=1');
    if (!$result) {
        die('Invalid query: ' . mysql_error());
    }

    ?>

示例 #2 有效的查询

以下查询语法正确，所以 mysql_query() 返回了一个 resource。

    <?php
    // 这应该由用户提供,下面是一个示例
    $firstname = 'fred';
    $lastname  = 'fox';

    // 构造查询
    // 这是执行 SQL 最好的方式
    // 更多例子参见 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));

    // 执行查询
    $result = mysql_query($query);

    // 检查结果
    // 下面显示了实际发送给 MySQL 的查询，以及出现的错误。这对调试很有帮助。
    if (!$result) {
        $message  = 'Invalid query: ' . mysql_error() . "\n";
        $message .= 'Whole query: ' . $query;
        die($message);
    }

    // 结果的使用
    // 尝试 print $result 并不会取出结果资源中的信息
    // 所以必须至少使用其中一个 mysql 结果函数
    // 参见 mysql_result(), mysql_fetch_array(), mysql_fetch_row() 等。
    while ($row = mysql_fetch_assoc($result)) {
        echo $row['firstname'];
        echo $row['lastname'];
        echo $row['address'];
        echo $row['age'];
    }

    // 释放关联结果集的资源
    // 在脚本结束的时候会自动进行
    mysql_free_result($result);
    ?>

### 参见

- mysql_connect() - 打开一个到 MySQL 服务器的连接
- mysql_error() - 返回上一个 MySQL 操作中的错误信息的文本
- mysql_real_escape_string() - 将字符串中的特殊字符进行转义，以在 SQL 语句中使用
- mysql_result() - 取得结果数据
- mysql_fetch_assoc() - 从结果集中取得一行作为关联数组
- mysql_unbuffered_query() - 向 MySQL 发送 SQL 查询，无需获取和缓冲结果行

# mysql_real_escape_string

(PHP 4 >= 4.3.0, PHP 5)

mysql_real_escape_string — 将字符串中的特殊字符进行转义，以在 SQL 语句中使用

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_real_escape_string()
- PDO::quote()

### 说明

function mysql_real_escape_string(string `$unescaped_string`, resource `$link_identifier` = NULL): string

考虑到连接的当前字符集，对 `unescaped_string` 进行特殊字符转义，以便安全地将其放置在 mysql_query() 中。如果要插入二进制数据，则必须使用此函数。

mysql_real_escape_string() 调用 mysql 库的函数 mysql_real_escape_string, 在以下字符前添加反斜线：`\x00`、`\n`、`\r`、`\`、`'`、`"` 和 `\x1a`.

在向 MySQL 发送查询之前，必须始终（有少数例外）使用此函数来确保数据的安全。

警告

# 安全: 默认字符集

The character set must be set either at the server level, or with the API function mysql_set_charset() for it to affect mysql_real_escape_string(). See the concepts section on character sets for more information.

### 参数

`unescaped_string`
  The string that is to be escaped.
`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

Returns the escaped string, or `false` on error.

### 错误／异常

Executing this function without a MySQL connection present will also emit `E_WARNING` level PHP errors. Only execute this function with a valid MySQL connection present.

### 示例

示例 #1 简单 mysql_real_escape_string() 示例

    <?php
    // Connect
    $link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')
        OR die(mysql_error());

    // Query
    $query = sprintf("SELECT * FROM users WHERE user='%s' AND password='%s'",
                mysql_real_escape_string($user),
                mysql_real_escape_string($password));
    ?>

示例 #2 mysql_real_escape_string() requires a connection example

This example demonstrates what happens if a MySQL connection is not present when calling this function.

    <?php
    // We have not connected to MySQL

    $lastname  = "O'Reilly";
    $_lastname = mysql_real_escape_string($lastname);

    $query = "SELECT * FROM actors WHERE last_name = '$_lastname'";

    var_dump($_lastname);
    var_dump($query);
    ?>

以上示例的输出类似于：

    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 = ''"

示例 #3 An example SQL Injection Attack

    <?php
    // We didn't check $_POST['password'], it could be anything the user wanted! For example:
    $_POST['username'] = 'aidan';
    $_POST['password'] = "' OR ''='";

    // Query database to check if there are any matching users
    $query = "SELECT * FROM users WHERE user='{$_POST['username']}' AND password='{$_POST['password']}'";
    mysql_query($query);

    // This means the query sent to MySQL would be:
    echo $query;
    ?>

The query sent to MySQL:

    SELECT * FROM users WHERE user='aidan' AND password='' OR ''=''

This would allow anyone to log in without a valid password.

### 注释

> 注意: A MySQL connection is required before using mysql_real_escape_string() otherwise an error of level `E_WARNING` is generated, and `false` is returned. If `link_identifier` isn't defined, the last MySQL connection is used.

> 注意: If this function is not used to escape data, the query is vulnerable to SQL Injection Attacks.

> 注意: mysql_real_escape_string() does not escape `%` and `_`. These are wildcards in MySQL if combined with `LIKE`, `GRANT`, or `REVOKE`.

### 参见

- mysql_set_charset() - 设置客户端的字符集
- mysql_client_encoding() - 返回字符集的名称

# mysql_result

(PHP 4, PHP 5)

mysql_result — 取得结果数据

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_data_seek() 与 mysqli_field_seek() 和 mysqli_fetch_field() 结合使用
- PDOStatement::fetchColumn()

### 说明

function mysql_result(resource `$result`, int `$row`, mixed `$field` = 0): string

Retrieves the contents of one cell from a MySQL result set.

When working on large result sets, you should consider using one of the functions that fetch an entire row (specified below). As these functions return the contents of multiple cells in one function call, they're MUCH quicker than mysql_result(). Also, note that specifying a numeric offset for the field argument is much quicker than specifying a fieldname or tablename.fieldname argument.

### 参数

`result`
  resource 型的结果集。此结果集来自对 mysql_query() 的调用。
`row`
  The row number from the result that's 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.

### 返回值

The contents of one cell from a MySQL result set on success, or `false` on failure.

### 示例

示例 #1 mysql_result() 示例

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Could not connect: ' . mysql_error());
    }
    if (!mysql_select_db('database_name')) {
        die('Could not select database: ' . mysql_error());
    }
    $result = mysql_query('SELECT name FROM work.employee');
    if (!$result) {
        die('Could not query:' . mysql_error());
    }
    echo mysql_result($result, 2); // outputs third employee's name

    mysql_close($link);
    ?>

### 注释

> 注意: Calls to mysql_result() should not be mixed with calls to other functions that deal with the result set.

### 参见

- mysql_fetch_row() - 从结果集中取得一行作为枚举数组
- mysql_fetch_array() - 从结果集中取得一行作为关联数组
- mysql_fetch_assoc() - 从结果集中取得一行作为关联数组
- mysql_fetch_object() - 从结果集中取得一行作为对象返回

# mysql_select_db

(PHP 4, PHP 5)

mysql_select_db — 选择 MySQL 数据库

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_select_db()
- PDO::__construct() (part of dsn)

### 说明

function mysql_select_db(string `$database_name`, resource `$ link_identifier` = ?): bool

成功时返回 `true`， 或者在失败时返回 `false`。

mysql_select_db() 设定与指定的连接标识符所关联的服务器上的当前激活数据库。如果没有指定连接标识符，则使用上一个打开的连接。如果没有打开的连接，本函数将无参数调用 mysql_connect() 来尝试打开一个并使用之。

每个其后的 mysql_query() 调用都会作用于活动数据库。

示例 #1 mysql_select_db() 例子

    <?php

    $lnk = mysql_connect('localhost', 'mysql_user', 'mysql_password')
           or die ('Not connected : ' . mysql_error());

    // make foo the current db
    mysql_select_db('foo', $lnk) or die ('Can\'t use foo : ' . mysql_error());

    ?>

参见 mysql_connect()，mysql_pconnect() 和 mysql_query()。

为向下兼容仍然可以使用 mysql_selectdb()，但反对这样做。

### 参数

`database_name`
  The name of the database that is to be selected.
`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #2 mysql_select_db() example

    <?php

    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Not connected : ' . mysql_error());
    }

    // make foo the current db
    $db_selected = mysql_select_db('foo', $link);
    if (!$db_selected) {
        die ('Can\'t use foo : ' . mysql_error());
    }
    ?>

### 注释

> 注意: 为了向下兼容，可以使用下列已废弃的别名： mysql_selectdb()

### 参见

- mysql_connect() - 打开一个到 MySQL 服务器的连接
- mysql_pconnect() - 打开一个到 MySQL 服务器的持久连接
- mysql_query() - 发送一条 MySQL 查询

# mysql_set_charset

(PHP 5 >= 5.2.3)

mysql_set_charset — 设置客户端的字符集

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_set_charset()
- PDO: 添加 `charset` 到连接字符串，比如 `charset=utf8`

### 说明

function mysql_set_charset(string `$charset`, resource `$link_identifier` = NULL): bool

设置当前连接的默认字符集。

### 参数

`charset`
  一个有效的字符集名称。
`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 注释

> 注意: 本函数需要 MySQL 5.0.7 或更高版本。

> 注意: 这是改变字符集的最佳方式。不推荐您使用 mysql_query() 来设置 (比如 `SET NAMES utf8`)。 更多信息参见 MySQL character set concepts 一节。

### 参见

- Setting character sets in MySQL
- » List of character sets that MySQL supports
- mysql_client_encoding() - 返回字符集的名称

# mysql_stat

(PHP 4 >= 4.3.0, PHP 5)

mysql_stat — 获取当前系统状态

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_stat()
- PDO::getAttribute()，`attribute` 为 `PDO::ATTR_SERVER_INFO`

### 说明

function mysql_stat(resource `$link_identifier` = NULL): string

mysql_stat() 返回当前服务器状态。

### 参数

`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

返回字符串，其中包含正常运行时间、线程、查询、打开表、冲刷表和每秒查询的状态。要获得其他状态变量的完整列表，必须使用 `SHOW STATUS` SQL 命令。 如果 `link_identifier` 无效，则返回 `null`。

### 示例

示例 #1 mysql_stat() 示例

    <?php
    $link   = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $status = explode('  ', mysql_stat($link));
    print_r($status);
    ?>

以上示例的输出类似于：

    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
    )

示例 #2 替代 mysql_stat() 示例

    <?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";
    }
    ?>

以上示例的输出类似于：

    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/
    ...

### 参见

- mysql_get_server_info() - 取得 MySQL 服务器信息
- mysql_list_processes() - 列出 MySQL 进程

# mysql_tablename

(PHP 4, PHP 5)

mysql_tablename — 取得表名

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- SQL Query: `SHOW TABLES`

### 说明

function mysql_tablename(resource `$result`, int `$i`): string|false

从 `result` 中取得表名。

此函数已废弃，推荐使用 mysql_query() 函数来执行 SQL `SHOW TABLES [FROM db_name] [LIKE 'pattern']` 替代。

### 参数

`result`
  接受 mysql_list_tables() 返回的结果指针以及一个整数索引作为参数并返回表名。
`i`
  The integer index (row/table number)

### 返回值

成功时返回表名 或者在失败时返回 `false`。

Use the mysql_tablename() function to traverse this result pointer, or any function for result tables, such as mysql_fetch_array().

### 示例

示例 #1 mysql_tablename() example

    <?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 "Table: ", mysql_tablename($result, $i), "\n";
    }

    mysql_free_result($result);
    ?>

### 注释

> 注意: The mysql_num_rows() function may be used to determine the number of tables in the result pointer.

### 参见

- mysql_list_tables() - 列出 MySQL 数据库中的表
- mysql_field_table() - 取得指定字段所在的表名
- mysql_db_name() - 取得 mysql_list_dbs 返回的结果数据

# mysql_thread_id

(PHP 4 >= 4.3.0, PHP 5)

mysql_thread_id — 返回当前线程的 ID

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- mysqli_thread_id()

### 说明

function mysql_thread_id(resource `$link_identifier` = NULL): int|false

检索当前线程 ID。如果连接丢失并执行 mysql_ping() 重新连接，会改变线程 ID。这意味着仅能在需要的时候再去获取。

### 参数

`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

The thread ID on success 或者在失败时返回 `false`.

### 示例

示例 #1 mysql_thread_id() 示例

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $thread_id = mysql_thread_id($link);
    if ($thread_id){
        printf("current thread id is %d\n", $thread_id);
    }
    ?>

以上示例的输出类似于：

    current thread id is 73

### 参见

- mysql_ping() - Ping 服务器连接的状态，如果没有连接则重新连接
- mysql_list_processes() - 列出 MySQL 进程

# mysql_unbuffered_query

(PHP 4 >= 4.0.6, PHP 5)

mysql_unbuffered_query — 向 MySQL 发送 SQL 查询，无需获取和缓冲结果行

警告

本扩展自 PHP 5.5.0 起已废弃，并在自 PHP 7.0.0 开始被移除。应使用 MySQLi 或 PDO_MySQL 扩展来替换之。参见 MySQL：选择 API 指南来获取更多信息。用以替代本函数的有：

- 参阅：缓冲和非缓冲查询

### 说明

function mysql_unbuffered_query(string `$query`, resource `$link_identifier` = NULL): resource

mysql_unbuffered_query() 将 SQL `query` 发送到 MySQL，而不像 mysql_query() 那样自动获取和缓冲结果行。对于生成大型结果集的 SQL 查询，这可以节省大量内存，并且可以在检索第一行后立即开始处理结果集，因为不必等到执行完整的 SQL 查询。要在打开多个数据库连接时使用 mysql_unbuffered_query()，必须指定可选参数 `link_identifier` 来标识要使用哪个连接。

### 参数

`query`
  要执行的 SQL 查询。 查询中的数据应正确转义。
`link_identifier`
  MySQL 连接。如不指定连接标识，则使用由 mysql_connect() 最近打开的连接。如果没有找到该连接，会尝试不带参数调用 mysql_connect() 来创建。如没有找到连接或无法建立连接，则会生成 `E_WARNING` 级别的错误。

### 返回值

对于 SELECT、SHOW、DESCRIBE 或 EXPLAIN 语句，mysql_unbuffered_query() 在成功时返回 resource，错误时返回 `false`。

对于其他类型的 SQL 语句，UPDATE、DELETE、DROP 等，mysql_unbuffered_query() 在成功时返回 `true`，在错误时返回 `false`。

### 注释

> 注意: mysql_unbuffered_query() 的好处是有代价的：在获取所有行之前，不能对 mysql_unbuffered_query() 返回的结果集使用 mysql_num_rows() 和 mysql_data_seek()。还必须使用相同的 `link_identifier` 从无缓冲的 SQL 查询中获取所有结果行，然后才能将新的 SQL 查询发送到 MySQL。

### 参见

- mysql_query() - 发送一条 MySQL 查询

## 目录

- mysql_affected_rows — 取得前一次 MySQL 操作所影响的记录行数
- mysql_client_encoding — 返回字符集的名称
- mysql_close — 关闭 MySQL 连接
- mysql_connect — 打开一个到 MySQL 服务器的连接
- mysql_create_db — 新建一个 MySQL 数据库
- mysql_data_seek — 移动内部结果的指针
- mysql_db_name — 取得 mysql_list_dbs 返回的结果数据
- mysql_db_query — 选择数据库并执行查询
- mysql_drop_db — 丢弃（删除）一个 MySQL 数据库
- mysql_errno — 返回上一个 MySQL 操作中的错误信息的数值
- mysql_error — 返回上一个 MySQL 操作中的错误信息的文本
- mysql_escape_string — 转义字符串用于 mysql_query
- mysql_fetch_array — 从结果集中取得一行作为关联数组
- mysql_fetch_assoc — 从结果集中取得一行作为关联数组
- mysql_fetch_field — 从结果集中取得列信息并作为对象返回
- mysql_fetch_lengths — 取得结果集中每个输出的长度
- mysql_fetch_object — 从结果集中取得一行作为对象返回
- mysql_fetch_row — 从结果集中取得一行作为枚举数组
- mysql_field_flags — 从结果中取得和指定字段关联的 flags
- mysql_field_len — 返回指定字段的长度
- mysql_field_name — 取得结果中指定字段的字段名
- mysql_field_seek — 将结果指针设置为指定的字段偏移量
- mysql_field_table — 取得指定字段所在的表名
- mysql_field_type — 取得结果集中指定字段的类型
- mysql_free_result — 释放结果内存
- mysql_get_client_info — 取得 MySQL 客户端信息
- mysql_get_host_info — 取得 MySQL 主机信息
- mysql_get_proto_info — 取得 MySQL 协议信息
- mysql_get_server_info — 取得 MySQL 服务器信息
- mysql_info — 获取最近查询的有关信息
- mysql_insert_id — 取得上一条查询生成的 ID
- mysql_list_dbs — 列出 MySQL 服务器中可用的数据库
- mysql_list_fields — 列出 MySQL 表字段
- mysql_list_processes — 列出 MySQL 进程
- mysql_list_tables — 列出 MySQL 数据库中的表
- mysql_num_fields — 取得结果中字段的数量
- mysql_num_rows — 获取结果中行数
- mysql_pconnect — 打开一个到 MySQL 服务器的持久连接
- mysql_ping — Ping 服务器连接的状态，如果没有连接则重新连接
- mysql_query — 发送一条 MySQL 查询
- mysql_real_escape_string — 将字符串中的特殊字符进行转义，以在 SQL 语句中使用
- mysql_result — 取得结果数据
- mysql_select_db — 选择 MySQL 数据库
- mysql_set_charset — 设置客户端的字符集
- mysql_stat — 获取当前系统状态
- mysql_tablename — 取得表名
- mysql_thread_id — 返回当前线程的 ID
- mysql_unbuffered_query — 向 MySQL 发送 SQL 查询，无需获取和缓冲结果行

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
  - 资源类型
- 更新日志
- 预定义常量
- 示例
  - MySQL 扩展概述范例
- MySQL 函数
  - mysql_affected_rows — 取得前一次 MySQL 操作所影响的记录行数
  - mysql_client_encoding — 返回字符集的名称
  - mysql_close — 关闭 MySQL 连接
  - mysql_connect — 打开一个到 MySQL 服务器的连接
  - mysql_create_db — 新建一个 MySQL 数据库
  - mysql_data_seek — 移动内部结果的指针
  - mysql_db_name — 取得 mysql_list_dbs 返回的结果数据
  - mysql_db_query — 选择数据库并执行查询
  - mysql_drop_db — 丢弃（删除）一个 MySQL 数据库
  - mysql_errno — 返回上一个 MySQL 操作中的错误信息的数值
  - mysql_error — 返回上一个 MySQL 操作中的错误信息的文本
  - mysql_escape_string — 转义字符串用于 mysql_query
  - mysql_fetch_array — 从结果集中取得一行作为关联数组
  - mysql_fetch_assoc — 从结果集中取得一行作为关联数组
  - mysql_fetch_field — 从结果集中取得列信息并作为对象返回
  - mysql_fetch_lengths — 取得结果集中每个输出的长度
  - mysql_fetch_object — 从结果集中取得一行作为对象返回
  - mysql_fetch_row — 从结果集中取得一行作为枚举数组
  - mysql_field_flags — 从结果中取得和指定字段关联的 flags
  - mysql_field_len — 返回指定字段的长度
  - mysql_field_name — 取得结果中指定字段的字段名
  - mysql_field_seek — 将结果指针设置为指定的字段偏移量
  - mysql_field_table — 取得指定字段所在的表名
  - mysql_field_type — 取得结果集中指定字段的类型
  - mysql_free_result — 释放结果内存
  - mysql_get_client_info — 取得 MySQL 客户端信息
  - mysql_get_host_info — 取得 MySQL 主机信息
  - mysql_get_proto_info — 取得 MySQL 协议信息
  - mysql_get_server_info — 取得 MySQL 服务器信息
  - mysql_info — 获取最近查询的有关信息
  - mysql_insert_id — 取得上一条查询生成的 ID
  - mysql_list_dbs — 列出 MySQL 服务器中可用的数据库
  - mysql_list_fields — 列出 MySQL 表字段
  - mysql_list_processes — 列出 MySQL 进程
  - mysql_list_tables — 列出 MySQL 数据库中的表
  - mysql_num_fields — 取得结果中字段的数量
  - mysql_num_rows — 获取结果中行数
  - mysql_pconnect — 打开一个到 MySQL 服务器的持久连接
  - mysql_ping — Ping 服务器连接的状态，如果没有连接则重新连接
  - mysql_query — 发送一条 MySQL 查询
  - mysql_real_escape_string — 将字符串中的特殊字符进行转义，以在 SQL 语句中使用
  - mysql_result — 取得结果数据
  - mysql_select_db — 选择 MySQL 数据库
  - mysql_set_charset — 设置客户端的字符集
  - mysql_stat — 获取当前系统状态
  - mysql_tablename — 取得表名
  - mysql_thread_id — 返回当前线程的 ID
  - mysql_unbuffered_query — 向 MySQL 发送 SQL 查询，无需获取和缓冲结果行

# MySQL Native Driver

# 简介

MySQL Native Driver is a replacement for the MySQL Client Library (libmysqlclient). MySQL Native Driver is part of the official PHP sources as of PHP 5.3.0.

The MySQL database extensions MySQL extension, `mysqli` and PDO MYSQL all communicate with the MySQL server. In the past, this was done by the extension using the services provided by the MySQL Client Library. The extensions were compiled against the MySQL Client Library in order to use its client-server protocol.

With MySQL Native Driver there is now an alternative, as the MySQL database extensions can be compiled to use MySQL Native Driver instead of the MySQL Client Library.

MySQL Native Driver is written in C as a PHP extension.

# Overview

What it is not

Although MySQL Native Driver is written as a PHP extension, it is important to note that it does not provide a new API to the PHP programmer. The programmer APIs for MySQL database connectivity are provided by the MySQL extension, `mysqli` and PDO MYSQL. These extensions can now use the services of MySQL Native Driver to communicate with the MySQL Server. Therefore, you should not think of MySQL Native Driver as an API.

Why use it?

Using the MySQL Native Driver offers a number of advantages over using the MySQL Client Library.

The older MySQL Client Library was written by MySQL AB (now Oracle Corporation) and so was released under the MySQL license. This ultimately led to MySQL support being disabled by default in PHP. However, the MySQL Native Driver has been developed as part of the PHP project, and is therefore released under the PHP license. This removes licensing issues that have been problematic in the past.

Also, in the past, you needed to build the MySQL database extensions against a copy of the MySQL Client Library. This typically meant you needed to have MySQL installed on a machine where you were building the PHP source code. Also, when your PHP application was running, the MySQL database extensions would call down to the MySQL Client library file at run time, so the file needed to be installed on your system. With MySQL Native Driver that is no longer the case as it is included as part of the standard distribution. So you do not need MySQL installed in order to build PHP or run PHP database applications.

Because MySQL Native Driver is written as a PHP extension, it is tightly coupled to the workings of PHP. This leads to gains in efficiency, especially when it comes to memory usage, as the driver uses the PHP memory management system. It also supports the PHP memory limit. Using MySQL Native Driver leads to comparable or better performance than using MySQL Client Library, it always ensures the most efficient use of memory. One example of the memory efficiency is the fact that when using the MySQL Client Library, each row is stored in memory twice, whereas with the MySQL Native Driver each row is only stored once in memory.

> 注意: Reporting memory usage
> Because MySQL Native Driver uses the PHP memory management system, its memory usage can be tracked with memory_get_usage(). This is not possible with libmysqlclient because it uses the C function malloc() instead.

Special features

MySQL Native Driver also provides some special features not available when the MySQL database extensions use MySQL Client Library. These special features are listed below:

- Improved persistent connections
- The special function mysqli_fetch_all()
- Performance statistics calls: mysqli_get_client_stats(), mysqli_get_connection_stats()

The performance statistics facility can prove to be very useful in identifying performance bottlenecks.

MySQL Native Driver also allows for persistent connections when used with the `mysqli` extension.

SSL Support

MySQL Native Driver supports SSL.

Compressed Protocol Support

MySQL Native Driver supports the compressed client server protocol. Extension `ext/mysqli`, if configured to use MySQL Native Driver, can also take advantage of this feature. Note that `PDO_MYSQL` does NOT support compression when used together with mysqlnd.

Named Pipes Support

Named pipes can be used to connect on Windows environments.

# Installation

Installation on Unix

In order to use the MySQL Native Driver, PHP needs to be built specifying that the MySQL database extensions are compiled with MySQL Native Driver support. This is done through configuration options prior to building the PHP source code.

For example, to build the MySQL extension, `mysqli` and PDO MYSQL using the MySQL Native Driver, the following command would be given:

    ./configure --with-mysql=mysqlnd \
    --with-mysqli=mysqlnd \
    --with-pdo-mysql=mysqlnd \
    [other options]

Installation on Windows

In the official PHP Windows distributions, MySQL Native Driver is enabled by default, so no additional configuration is required to use it. All MySQL database extensions will use MySQL Native Driver in this case.

SHA-256 Authentication Plugin support

The MySQL Native Driver requires the OpenSSL functionality of PHP to be loaded and enabled to connect to MySQL through accounts that use the MySQL SHA-256 Authentication Plugin. For example, PHP could be configured using:

    ./configure --with-mysql=mysqlnd \
    --with-mysqli=mysqlnd \
    --with-pdo-mysql=mysqlnd \
    --with-openssl
    [other options]

In Autotools, the extended SSL support in `mysqlnd` is enabled implicitly when building together with the `openssl` extension using the --with-openssl configure option. When building without the `openssl` extension, the --with-mysqlnd-ssl configure option can be used to enable extended SSL support explicitly.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | The --with-mysqlnd-ssl Autotools configure option was added to enable the extended SSL support explicitly when building without the `openssl` extension.

# 运行时配置

这些函数的行为受 php.ini 中的设置影响。

MySQL Native Driver Configuration Options
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
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` | Before PHP 7.2.0 the default value was "31536000" and the changeability was `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` | Removed as of PHP 8.1.0

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`mysqlnd.collect_statistics` bool
  Enables the collection of various client statistics which can be accessed through mysqli_get_client_stats(), mysqli_get_connection_stats(), and are shown in `mysqlnd` section of the output of the phpinfo() function as well. This configuration setting enables all MySQL Native Driver statistics except those relating to memory management.
`mysqlnd.collect_memory_statistics` bool
  Enable the collection of various memory statistics which can be accessed through mysqli_get_client_stats(), mysqli_get_connection_stats(), and are shown in `mysqlnd` section of the output of the phpinfo() function as well. This configuration setting enables the memory management statistics within the overall set of MySQL Native Driver statistics.
`mysqlnd.debug` string
  Records communication from all extensions using `mysqlnd` to the specified log file. The format of the directive is `mysqlnd.debug = "option1[,parameter_option1][:option2[,parameter_option2]]"`. The options for the format string are as follows:
  - A[,file] - Appends trace output to specified file. Also ensures that data is written after each write. This is done by closing and reopening the trace file (this is slow). It helps ensure a complete log file should the application crash.
  - a[,file] - Appends trace output to the specified file.
  - d - Enables output from DBUG_<N> macros for the current state. May be followed by a list of keywords which selects output only for the DBUG macros with that keyword. An empty list of keywords implies output for all macros.
  - f[,functions] - Limits debugger actions to the specified list of functions. An empty list of functions implies that all functions are selected.
  - F - Marks each debugger output line with the name of the source file containing the macro causing the output.
  - i - Marks each debugger output line with the PID of the current process.
  - L - Marks each debugger output line with the name of the source file line number of the macro causing the output.
  - n - Marks each debugger output line with the current function nesting depth
  - o[,file] - Similar to a[,file] but overwrites old file, and does not append.
  - O[,file] - Similar to A[,file] but overwrites old file, and does not append.
  - t[,N] - Enables function control flow tracing. The maximum nesting depth is specified by N, and defaults to 200.
  - x - This option activates profiling.
  - m - Trace memory allocation and deallocation related calls.
  Example:

      d:t:x:O,/tmp/mysqlnd.trace

  > 注意: This feature is only available with a debug build of PHP.

`mysqlnd.log_mask` int
  Defines which queries will be logged. The default 0, which disables logging. Define using an integer, and not with PHP constants. For example, a value of 48 (16 + 32) will log slow queries which either use 'no good index' (SERVER_QUERY_NO_GOOD_INDEX_USED = 16) or no index at all (SERVER_QUERY_NO_INDEX_USED = 32). A value of 2043 (1 + 2 + 8 + ... + 1024) will log all slow query types. The types are as follows: 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, and SERVER_QUERY_WAS_SLOW=1024.
`mysqlnd.mempool_default_size` int
  Default size of the mysqlnd memory pool, which is used by result sets.
`mysqlnd.net_read_timeout` int
  `mysqlnd` and the MySQL Client Library, `libmysqlclient` use different networking APIs. `mysqlnd` uses PHP streams, whereas `libmysqlclient` uses its own wrapper around the operating level network calls. PHP, by default, sets a read timeout of 60s for streams. This is set via php.ini, `default_socket_timeout`. This default applies to all streams that set no other timeout value. `mysqlnd` does not set any other value and therefore connections of long running queries can be disconnected after `default_socket_timeout` seconds resulting in an error message 2006 - MySQL Server has gone away. The MySQL Client Library sets a default timeout of 24 * 3600 seconds (1 day) and waits for other timeouts to occur, such as TCP/IP timeouts. `mysqlnd` now uses the same very long timeout. The value is configurable through a new php.ini setting: `mysqlnd.net_read_timeout`. `mysqlnd.net_read_timeout` gets used by any extension (`ext/mysql`, `ext/mysqli`, `PDO_MySQL`) that uses `mysqlnd`. `mysqlnd` tells PHP Streams to use `mysqlnd.net_read_timeout`. Please note that there may be subtle differences between `MYSQL_OPT_READ_TIMEOUT` from the MySQL Client Library and PHP Streams, for example `MYSQL_OPT_READ_TIMEOUT` is documented to work only for TCP/IP connections and, prior to MySQL 5.1.2, only for Windows. PHP streams may not have this limitation. Please check the streams documentation, if in doubt.
`mysqlnd.net_cmd_buffer_size` int
  `mysqlnd` allocates an internal command/network buffer of `mysqlnd.net_cmd_buffer_size` (in php.ini) bytes for every connection. If a MySQL Client Server protocol command, for example, `COM_QUERY` (normal query), does not fit into the buffer, `mysqlnd` will grow the buffer to the size required for sending the command. Whenever the buffer gets extended for one connection, `command_buffer_too_small` will be incremented by one. If `mysqlnd` has to grow the buffer beyond its initial size of `mysqlnd.net_cmd_buffer_size` bytes for almost every connection, you should consider increasing the default size to avoid re-allocations. The default buffer size is 4096 bytes, which is the smallest value possible. The value can also be set using `mysqli_options(link, MYSQLI_OPT_NET_CMD_BUFFER_SIZE, size)`.
`mysqlnd.net_read_buffer_size` int
  Maximum read chunk size in bytes when reading the body of a MySQL command packet. The MySQL client server protocol encapsulates all its commands in packets. The packets consist of a small header and a body with the actual payload. The size of the body is encoded in the header. `mysqlnd` reads the body in chunks of `MIN(header.size, mysqlnd.net_read_buffer_size)` bytes. If a packet body is larger than `mysqlnd.net_read_buffer_size` bytes, `mysqlnd` has to call `read()` multiple times. The value can also be set using `mysqli_options(link, MYSQLI_OPT_NET_READ_BUFFER_SIZE, size)`.
`mysqlnd.sha256_server_public_key` string
  SHA-256 Authentication Plugin related. File with the MySQL server public RSA key. Clients can either omit setting a public RSA key, specify the key through this PHP configuration setting or set the key at runtime using mysqli_options(). If not public RSA key file is given by the client, then the key will be exchanged as part of the standard SHA-256 Authentication Plugin authentication procedure.
`mysqlnd.trace_alloc` string
`mysqlnd.fetch_data_copy` int
  Enforce copying result sets from the internal result set buffers into PHP variables instead of using the default reference and copy-on-write logic. Please, see the memory management implementation notes for further details. Copying result sets instead of having PHP variables reference them allows releasing the memory occupied for the PHP variables earlier. Depending on the user API code, the actual database queries and the size of their result sets this may reduce the memory footprint of mysqlnd. Do not set if using PDO_MySQL. PDO_MySQL has not yet been updated to support the new fetch mode.

  > 注意: Removed as of PHP 8.1.0

# Incompatibilities

MySQL Native Driver is in most cases compatible with MySQL Client Library (`libmysql`). This section documents incompatibilities between these libraries.

- Values of `bit` data type are returned as binary strings (e.g. "\0" or "\x1F") with `libmysql` and as decimal strings (e.g. "0" or "31") with `mysqlnd`. If you want the code to be compatible with both libraries then always return bit fields as numbers from MySQL with a query like this: `SELECT bit + 0 FROM table`.

# Persistent Connections

Using Persistent Connections

If `mysqli` is used with `mysqlnd`, when a persistent connection is created it generates a `COM_CHANGE_USER` (`mysql_change_user()`) call on the server. This ensures that re-authentication of the connection takes place.

As there is some overhead associated with the `COM_CHANGE_USER` call, it is possible to switch this off at compile time. Reusing a persistent connection will then generate a `COM_PING` (`mysql_ping`) call to simply test the connection is reusable.

Generation of `COM_CHANGE_USER` can be switched off with the compile flag `MYSQLI_NO_CHANGE_USER_ON_PCONNECT`. For example:

    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

Or alternatively:

    shell# export CFLAGS="-DMYSQLI_NO_CHANGE_USER_ON_PCONNECT"
    shell# configure --whatever-option
    shell# make clean
    shell# make

Note that only `mysqli` on `mysqlnd` uses `COM_CHANGE_USER`. Other extension-driver combinations use `COM_PING` on initial use of a persistent connection.

# Statistics

MySQL Native Driver contains support for gathering statistics on the communication between the client and the server. The statistics gathered are of two main types:

- Client statistics
- Connection statistics

When using the mysqli extension, these statistics can be obtained through two API calls:

- mysqli_get_client_stats()
- mysqli_get_connection_stats()

> 注意: Statistics are aggregated among all extensions that use the MySQL Native Driver. For example, if the mysqli extension and the PDO MySQL driver are both set-up to use MySQLnd, then function calls from mysqli and method calls from PDO will affect the statistics. There is no way to find out how much a certain API call of any extension that has been compiled against MySQL Native Driver has impacted a certain statistic.

## Retrieving statistics

Client statistics can be retrieved by calling the mysqli_get_client_stats() function.

Connection statistics can be retrieved by calling the mysqli_get_connection_stats() function.

Both functions return an associative array, where the name of a statistic is the key for the corresponding statistical data.

## MySQL Native Driver Statistics

Most statistics are associated to a connection, but some are associated to the process in which case this will be mentioned.

The following statistics are produced by the MySQL Native Driver:

Network Related Statistics
`bytes_sent`
  Number of bytes sent from PHP to the MySQL server.
`bytes_received`
  Number of bytes received from the MySQL server.
`packets_sent`
  Number of packets sent by the MySQL Client Server protocol.
`packets_received`
  Number of packets received from the MySQL Client Server protocol.
`protocol_overhead_in`
  MySQL Client Server protocol overhead in bytes for incoming traffic. Currently only the Packet Header (4 bytes) is considered as overhead. `protocol_overhead_in = packets_received * 4`
`protocol_overhead_out`
  MySQL Client Server protocol overhead in bytes for outgoing traffic. Currently only the Packet Header (4 bytes) is considered as overhead. `protocol_overhead_out = packets_received * 4`
`bytes_received_ok_packet`
  Total size of bytes of MySQL Client Server protocol OK packets received. OK packets can contain a status message. The length of the status message can vary and thus the size of an OK packet is not fixed.

  > 注意: The total size in bytes includes the size of the header packet (4 bytes, see protocol overhead).

`packets_received_ok`
  Number of MySQL Client Server protocol OK packets received.
`bytes_received_eof_packet`
  Total size in bytes of MySQL Client Server protocol EOF packets received. EOF can vary in size depending on the server version. Also, EOF can transport an error message.

  > 注意: The total size in bytes includes the size of the header packet (4 bytes, see protocol overhead).

`packets_received_eof`
  Number of MySQL Client Server protocol EOF packets. Like with other packet statistics the number of packets will be increased even if PHP does not receive the expected packet but, for example, an error message.
`bytes_received_rset_header_packet`
  Total size in bytes of MySQL Client Server protocol result set header packets. The size of the packets varies depending on the payload (`LOAD LOCAL INFILE`, `INSERT`, `UPDATE`, `SELECT`, error message).

  > 注意: The total size in bytes includes the size of the header packet (4 bytes, see protocol overhead).

`packets_received_rset_header`
  Number of MySQL Client Server protocol result set header packets.
`bytes_received_rset_field_meta_packet`
  Total size in bytes of MySQL Client Server protocol result set metadata (field information) packets. Of course the size varies with the fields in the result set. The packet may also transport an error or an EOF packet in case of COM_LIST_FIELDS.

  > 注意: The total size in bytes includes the size of the header packet (4 bytes, see protocol overhead).

`packets_received_rset_field_meta`
  Number of MySQL Client Server protocol result set metadata (field information) packets.
`bytes_received_rset_row_packet`
  Total size in bytes of MySQL Client Server protocol result set row data packets. The packet may also transport an error or an EOF packet. One can compute the number of error and EOF packets by subtracting `rows_fetched_from_server_normal` and `rows_fetched_from_server_ps` from `bytes_received_rset_row_packet`.

  > 注意: The total size in bytes includes the size of the header packet (4 bytes, see protocol overhead).

`packets_received_rset_row`
  Number of MySQL Client Server protocol result set row data packets.
`bytes_received_prepare_response_packet`
  Total size in bytes of MySQL Client Server protocol OK for Prepared Statement Initialization packets (prepared statement init packets). The packet may also transport an error. The packet size depends on the MySQL version.

  > 注意: The total size in bytes includes the size of the header packet (4 bytes, see protocol overhead).

`packets_received_prepare_response`
  Number of MySQL Client Server protocol OK for Prepared Statement Initialization packets (prepared statement init packets).
`bytes_received_change_user_packet`
  Total size in bytes of MySQL Client Server protocol COM_CHANGE_USER packets. The packet may also transport an error or EOF.

  > 注意: The total size in bytes includes the size of the header packet (4 bytes, see protocol overhead).

`packets_received_change_user`
  Number of MySQL Client Server protocol COM_CHANGE_USER packets.
`packets_sent_command`
  Number of MySQL Client Server protocol commands sent from PHP to MySQL. There is no way to know which specific commands and how many of them have been sent.
`bytes_received_real_data_normal`
  Number of bytes of payload fetched by the PHP client from `mysqlnd` using the text protocol. This is the size of the actual data contained in result sets that do not originate from prepared statements and which have been fetched by the PHP client. Note that although a full result set may have been pulled from MySQL by `mysqlnd`, this statistic only counts actual data pulled from `mysqlnd` by the PHP client.

  An example of a code sequence that will increase the value is as follows:

      $mysqli = new mysqli();
      $res = $mysqli->query("SELECT 'abc'");
      $res->fetch_assoc();
      $res->close();

  Every fetch operation will increase the value.

  However, the statistic will not be increased if the result set is only buffered on the client, but not fetched, such as in the following example:

      $mysqli = new mysqli();
      $res = $mysqli->query("SELECT 'abc'");
      $res->close();

`bytes_received_real_data_ps`
  Number of bytes of the payload fetched by the PHP client from `mysqlnd` using the prepared statement protocol. This is the size of the actual data contained in result sets that originate from prepared statements and which have been fetched by the PHP client. The value will not be increased if the result set is not subsequently read by the PHP client. Note that although a full result set may have been pulled from MySQL by `mysqlnd`, this statistic only counts actual data pulled from `mysqlnd` by the PHP client. See also `bytes_received_real_data_normal`.

Result Set Related Statistics
`result_set_queries`
  Number of queries that have generated a result set. Examples of queries that generate a result set: `SELECT`, `SHOW`. The statistic will not be incremented if there is an error reading the result set header packet from the line.

  > 注意: This statistic can be used as an indirect measure for the number of queries PHP has sent to MySQL. This could help identifying a client that causes a high database load.

`non_result_set_queries`
  Number of queries that did not generate a result set. Examples of queries that do not generate a result set: `INSERT`, `UPDATE`, `LOAD DATA`. The statistic will not be incremented if there is an error reading the result set header packet from the line.

  > 注意: This statistic can be used as an indirect measure for the number of queries PHP has sent to MySQL. This could help identifying a client that causes a high database load.

`no_index_used`
  Number of queries that have generated a result set but did not use an index. (See also the mysqld start option `--log-queries-not-using-indexes`).

  > 注意: Those queries can be reported via an exception by calling `mysqli_report(MYSQLI_REPORT_INDEX);`. It is possible to have them be reported via a warning instead by calling `mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT);`.

`bad_index_used`
  Number of queries that have generated a result set and did not use a good index. (See also the mysqld start option `--log-slow-queries`).

  > 注意: Those queries can be reported via an exception by calling `mysqli_report(MYSQLI_REPORT_INDEX);`. It is possible to have them be reported via a warning instead by calling `mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT);`.

`slow_queries`
  SQL statements that took more than `long_query_time` seconds to execute and required at least `min_examined_row_limit` rows to be examined.
  警告

  Not reported through mysqli_report().

`buffered_sets`
  Number of buffered result sets returned by normal (i.e. not via a prepared statement) queries.

  Examples of API calls that will buffer result sets on the client: mysqli_query(), mysqli_store_result(), mysqli_stmt_get_result()

`unbuffered_sets`
  Number of unbuffered result sets returned by normal (i.e. not via a prepared statement) queries.

  Examples of API calls that will not buffer result sets on the client: mysqli_use_result()

`ps_buffered_sets`
  Number of buffered result sets returned by prepared statements.

  Examples of API calls that will buffer result sets on the client: mysqli_stmt_store_result()

`ps_unbuffered_sets`
  Number of unbuffered result sets returned by prepared statements. By default prepared statements are unbuffered, thus most prepared statements will be accounted in this statistic.
`flushed_normal_sets`
  Number of result sets returned by normal (i.e. not via a prepared statement) queries with unread data that have been silently flushed.

  > 注意: Flushing happens only with unbuffered result sets. Unbuffered result sets must be fetched completely before a new query can be run on the connection otherwise MySQL will throw an error. If the application does not fetch all rows from an unbuffered result set, mysqlnd does implicitly fetch the result set to clear the line. See also `rows_skipped_normal`, `rows_skipped_ps`.

  > Some possible causes for an implicit flush:

  > - Faulty client application
  > - Client stopped reading after it found what it was looking for but has made MySQL calculate more records than needed
  > - Client application has stopped unexpectedly

`flushed_ps_sets`
  Number of result sets from prepared statements with unread data that have been silently flushed.

  > 注意: Flushing happens only with unbuffered result sets. Unbuffered result sets must be fetched completely before a new query can be run on the connection otherwise MySQL will throw an error. If the application does not fetch all rows from an unbuffered result set, mysqlnd does implicitly fetch the result set to clear the line. See also `rows_skipped_normal`, `rows_skipped_ps`.

  > Some possible causes for an implicit flush:

  > - Faulty client application
  > - Client stopped reading after it found what it was looking for but has made MySQL calculate more records than needed
  > - Client application has stopped unexpectedly

`ps_prepared_never_executed`
  Number of statements prepared but never executed.
`ps_prepared_once_executed`
  Number of prepared statements executed only once.
`rows_fetched_from_server_normal`
`rows_fetched_from_server_ps`
  Total number of result set rows fetched from the server. This includes the rows which were not read by the client but had been implicitly fetched due to flushed unbuffered result sets. See also `packets_received_rset_row`.
`rows_buffered_from_client_normal`
  Total number of buffered rows originating from a normal query. This is the number of rows that have been fetched from MySQL and buffered on client.

  Examples of queries that will buffer results:

  - mysqli_query()
  - mysqli_store_result()
`rows_buffered_from_client_ps`
  Same as `rows_buffered_from_client_normal` but for prepared statements.
`rows_fetched_from_client_normal_buffered`
  Total number of rows fetched by the client from a buffered result set created by a normal query.
`rows_fetched_from_client_ps_buffered`
  Total number of rows fetched by the client from a buffered result set created by a prepared statement.
`rows_fetched_from_client_normal_unbuffered`
  Total number of rows fetched by the client from an unbuffered result set created by a normal query.
`rows_fetched_from_client_ps_unbuffered`
  Total number of rows fetched by the client from an unbuffered result set created by a prepared statement.
`rows_fetched_from_client_ps_cursor`
  Total number of rows fetch by the client from a cursor created by a prepared statement.
`rows_skipped_normal`
`rows_skipped_ps`
  Reserved for future use (currently not supported).
`copy_on_write_saved`
`copy_on_write_performed`
  This is a process level scope statistic. With mysqlnd, variables returned by the extensions point into mysqlnd internal network result buffers. If the data are not changed, the fetched data is kept only once in memory. However, any modification to the data will require mysqlnd to perform a copy-on-write operation.
`explicit_free_result`
`implicit_free_result`
  This is a connection and process level scope statistic. Total number of freed result sets.
`proto_text_fetched_null`
  Total number of columns of type `MYSQL_TYPE_NULL` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_null`
  Total number of columns of type `MYSQL_TYPE_NULL` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_bit`
  Total number of columns of type `MYSQL_TYPE_BIT` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_bit`
  Total number of columns of type `MYSQL_TYPE_BIT` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_tinyint`
  Total number of columns of type `MYSQL_TYPE_TINY` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_tinyint`
  Total number of columns of type `MYSQL_TYPE_TINY` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_short`
  Total number of columns of type `MYSQL_TYPE_SHORT` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_short`
  Total number of columns of type `MYSQL_TYPE_SHORT` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_int24`
  Total number of columns of type `MYSQL_TYPE_INT24` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_int24`
  Total number of columns of type `MYSQL_TYPE_INT24` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_int`
  Total number of columns of type `MYSQL_TYPE_LONG` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_int`
  Total number of columns of type `MYSQL_TYPE_LONG` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_bigint`
  Total number of columns of type `MYSQL_TYPE_LONGLONG` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_bigint`
  Total number of columns of type `MYSQL_TYPE_LONGLONG` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_decimal`
  Total number of columns of type `MYSQL_TYPE_DECIMAL`, or `MYSQL_TYPE_NEWDECIMAL` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_decimal`
  Total number of columns of type `MYSQL_TYPE_DECIMAL`, or `MYSQL_TYPE_NEWDECIMAL` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_float`
  Total number of columns of type `MYSQL_TYPE_FLOAT` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_float`
  Total number of columns of type `MYSQL_TYPE_FLOAT` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_double`
  Total number of columns of type `MYSQL_TYPE_DOUBLE` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_double`
  Total number of columns of type `MYSQL_TYPE_DOUBLE` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_date`
  Total number of columns of type `MYSQL_TYPE_DATE`, or `MYSQL_TYPE_NEWDATE` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_date`
  Total number of columns of type `MYSQL_TYPE_DATE`, or `MYSQL_TYPE_NEWDATE` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_year`
  Total number of columns of type `MYSQL_TYPE_YEAR` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_year`
  Total number of columns of type `MYSQL_TYPE_YEAR` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_time`
  Total number of columns of type `MYSQL_TYPE_TIME` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_time`
  Total number of columns of type `MYSQL_TYPE_TIME` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_datetime`
  Total number of columns of type `MYSQL_TYPE_DATETIME` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_datetime`
  Total number of columns of type `MYSQL_TYPE_DATETIME` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_timestamp`
  Total number of columns of type `MYSQL_TYPE_TIMESTAMP` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_timestamp`
  Total number of columns of type `MYSQL_TYPE_TIMESTAMP` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_string`
  Total number of columns of type `MYSQL_TYPE_STRING`, `MYSQL_TYPE_VARSTRING`, or `MYSQL_TYPE_VARCHAR` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_string`
  Total number of columns of type `MYSQL_TYPE_STRING`, `MYSQL_TYPE_VARSTRING`, or `MYSQL_TYPE_VARCHAR` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_blob`
  Total number of columns of type `MYSQL_TYPE_TINY_BLOB`, `MYSQL_TYPE_MEDIUM_BLOB`, `MYSQL_TYPE_LONG_BLOB`, or `MYSQL_TYPE_BLOB` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_blob`
  Total number of columns of type `MYSQL_TYPE_TINY_BLOB`, `MYSQL_TYPE_MEDIUM_BLOB`, `MYSQL_TYPE_LONG_BLOB`, or `MYSQL_TYPE_BLOB` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_enum`
  Total number of columns of type `MYSQL_TYPE_ENUM` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_enum`
  Total number of columns of type `MYSQL_TYPE_ENUM` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_set`
  Total number of columns of type `MYSQL_TYPE_SET` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_set`
  Total number of columns of type `MYSQL_TYPE_SET` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_geometry`
  Total number of columns of type `MYSQL_TYPE_GEOMETRY` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_geometry`
  Total number of columns of type `MYSQL_TYPE_GEOMETRY` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_other`
  Total number of columns of types `MYSQL_TYPE_*` not listed previously fetched from a normal query (MySQL text protocol).

  > 注意: In theory, this should always be `0`.

`proto_binary_fetched_other`
  Total number of columns of type `MYSQL_TYPE_*` not listed previously fetched from a prepared statement (MySQL binary protocol).

  > 注意: In theory, this should always be `0`.

Connection Related Statistics
`connect_success`
  Total number of successful connection attempts.

  > 注意: `connect_success` holds the sum of successful persistent and non-persistent connection attempts. Therefore, the number of successful non-persistent connection attempts is `connect_success - pconnect_success`.

`pconnect_success`
  Total number of successful persistent connection attempts.
`connect_failure`
  Total number of failed connection attempts.
`reconnect`
  This is a process level scope statistic.
`active_connections`
  This is a process level scope statistic. Total number of active persistent and non-persistent connections.

  > 注意: The total number of active non-persistent connections is `active_connections - active_persistent_connections`.

`active_persistent_connections`
  This is a process level scope statistic. Total number of active persistent connections.
`explicit_close`
  Total number of explicitly closed connections.

  示例 #1 Examples of code snippets that cause an explicit close

  -     $link = new mysqli(/* ... */);
        $link->close(/* ... */);

  -     $link = new mysqli(/* ... */);
        $link->connect(/* ... */);

`implicit_close`
  Total number of implicitly closed connections.

  示例 #2 Examples of code snippets that cause an implicit close

  -     $link = new mysqli(/* ... */);
        $link->real_connect(/* ... */);

  - `unset($link)`
  - Persistent connection: pooled connection has been created with real_connect and there may be unknown options set - close implicitly to avoid returning a connection with unknown options
  - Persistent connection: ping/change_user fails and ext/mysqli closes the connection
  - End of script execution: close connections that have not been closed by the user
`disconnect_close`
  Connection failures indicated by the C API call `mysql_real_connect` during an attempt to establish a connection.
`in_middle_of_command_close`
  This is a process level scope statistic. A connection has been closed in the middle of a command execution (outstanding result sets not fetched, after sending a query and before retrieving an answer, while fetching data, while transferring data with LOAD DATA).
  警告

  Unless asynchronous queries are used, this should only happen if the PHP application terminated unexpectedly, and PHP shuts down the connection automatically.

`init_command_executed_count`
  Total number of init command executions. For example: `mysqli_options(MYSQLI_INIT_COMMAND , $value)`. The number of successful executions is `init_command_executed_count - init_command_failed_count`.
`init_command_failed_count`
  Total number of failed init commands.

`COM_*` Command Related Statistics
`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`
  Total number of attempts to send a certain `COM_*` command from PHP to MySQL. The statistics are incremented after checking the line and immediately before sending the corresponding MySQL client server protocol packet.
  警告

  If MySQLnd fails to send the packet over the wire the statistics will not be decremented. In case of a failure MySQLnd emits a PHP warning Error while sending %s packet. PID=%d.

  示例 #3 Usage examples

  - Check if PHP sends certain commands to MySQL, for example, check if a client sends `COM_PROCESS_KILL`
  - Calculate the average number of prepared statement executions by comparing `COM_EXECUTE` with `COM_PREPARE`
  - Check if PHP has run any non-prepared SQL statements by checking if `COM_QUERY` is zero
  - Identify PHP scripts that run an excessive number of SQL statements by checking `COM_QUERY` and `COM_EXECUTE`

Miscellaneous Statistics
`explicit_stmt_close`
`implicit_stmt_close`
  This is a process level scope statistic. Total number of closed prepared statements.

  > 注意: A prepared statement is always explicitly closed. The only time it's closed implicitly is when preparing it fails.

`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`
  This is a process level scope statistic. Memory management calls.
`command_buffer_too_small`
  Number of network command buffer extensions while sending commands from PHP to MySQL. MySQLnd allocates an internal command/network buffer of mysqlnd.net_cmd_buffer_size bytes for every connection. If a MySQL Client Server protocol command, e.g. `COM_QUERY` (normal query), does not fit into the buffer, MySQLnd will grow the buffer to what is needed for sending the command. Whenever the buffer gets extended for one connection `command_buffer_too_small` will be incremented by one. If MySQLnd has to grow the buffer beyond its initial size of mysqlnd.net_cmd_buffer_size bytes for almost every connection, considerations to increase the default size should be made to avoid re-allocations.
`connection_reused`
  The total number of times a persistent connection has been reused.

# Notes

This section provides a collection of miscellaneous notes on MySQL Native Driver usage.

- Using `mysqlnd` means using PHP streams for underlying connectivity. For `mysqlnd`, the PHP streams documentation (Stream) should be consulted on such details as timeout settings, not the documentation for the MySQL Client Library.

# Memory management

Introduction

The MySQL Native Driver manages memory different than the MySQL Client Library. The libraries differ in the way memory is allocated and released, how memory is allocated in chunks while reading results from MySQL, which debug and development options exist, and how results read from MySQL are linked to PHP user variables.

The following notes are intended as an introduction and summary to users interested at understanding the MySQL Native Driver at the C code level.

Memory management functions used

All memory allocation and deallocation is done using the PHP memory management functions. Therefore, the memory consumption of mysqlnd can be tracked using PHP API calls, such as memory_get_usage(). Because memory is allocated and released using the PHP memory management, the changes may not immediately become visible at the operating system level. The PHP memory management acts as a proxy which may delay releasing memory towards the system. Due to this, comparing the memory usage of the MySQL Native Driver and the MySQL Client Library is difficult. The MySQL Client Library is using the operating system memory management calls directly, hence the effects can be observed immediately at the operating system level.

Any memory limit enforced by PHP also affects the MySQL Native Driver. This may cause out of memory errors when fetching large result sets that exceed the size of the remaining memory made available by PHP. Because the MySQL Client Library is not using PHP memory management functions, it does not comply to any PHP memory limit set. If using the MySQL Client Library, depending on the deployment model, the memory footprint of the PHP process may grow beyond the PHP memory limit. But also PHP scripts may be able to process larger result sets as parts of the memory allocated to hold the result sets are beyond the control of the PHP engine.

PHP memory management functions are invoked by the MySQL Native Driver through a lightweight wrapper. Among others, the wrapper makes debugging easier.

Handling of result sets

The various MySQL Server and the various client APIs differentiate between buffered and unbuffered result sets. Unbuffered result sets are transferred row-by-row from MySQL to the client as the client iterates over the results. Buffered results are fetched in their entirety by the client library before passing them on to the client.

The MySQL Native Driver is using PHP Streams for the network communication with the MySQL Server. Results sent by MySQL are fetched from the PHP Streams network buffers into the result buffer of mysqlnd. The result buffer is made of zvals. In a second step the results are made available to the PHP script. This final transfer from the result buffer into PHP variables impacts the memory consumption and is mostly noticeable when using buffered result sets.

By default the MySQL Native Driver tries to avoid holding buffered results twice in memory. Results are kept only once in the internal result buffers and their zvals. When results are fetched into PHP variables by the PHP script, the variables will reference the internal result buffers. Database query results are not copied and kept in memory only once. Should the user modify the contents of a variable holding the database results a copy-on-write must be performed to avoid changing the referenced internal result buffer. The contents of the buffer must not be modified because the user may decide to read the result set a second time. The copy-on-write mechanism is implemented using an additional reference management list and the use of standard zval reference counters. Copy-on-write must also be done if the user reads a result set into PHP variables and frees a result set before the variables are unset.

Generally speaking, this pattern works well for scripts that read a result set once and do not modify variables holding results. Its major drawback is the memory overhead caused by the additional reference management which comes primarily from the fact that user variables holding results cannot be entirely released until the mysqlnd reference management stops referencing them. The MySQL Native driver removes the reference to the user variables when the result set is freed or a copy-on-write is performed. An observer will see the total memory consumption grow until the result set is released. Use the statistics to check whether a script does release result sets explicitly or the driver does implicit releases and thus memory is used for a time longer than necessary. Statistics also help to see how many copy-on-write operations happened.

A PHP script reading many small rows of a buffered result set using a code snippet equal or equivalent to `while ($row = $res->fetch_assoc()) { ... }` may optimize memory consumption by requesting copies instead of references. Albeit requesting copies means keeping results twice in memory, it allows PHP to free the copy contained in `$row` as the result set is being iterated and prior to releasing the result set itself. On a loaded server optimizing peak memory usage may help improving the overall system performance although for an individual script the copy approach may be slower due to additional allocations and memory copy operations.

Monitoring and debugging

There are multiple ways of tracking the memory usage of the MySQL Native Driver. If the goal is to get a quick high level overview or to verify the memory efficiency of PHP scripts, then check the statistics collected by the library. The statistics allow you, for example, to catch SQL statements which generate more results than are processed by a PHP script.

The debug trace log can be configured to record memory management calls. This helps to see when memory is allocated or free'd. However, the size of the requested memory chunks may not be listed.

Some, recent versions of the MySQL Native Driver feature the emulation of random out of memory situations. This feature is meant to be used by the C developers of the library or mysqlnd plugin authors only. Please, search the source code for corresponding PHP configuration settings and further details. The feature is considered private and may be modified at any time without prior notice.

# MySQL Native Driver Plugin API

## 目录

- A comparison of mysqlnd plugins with MySQL Proxy
- Obtaining the mysqlnd plugin API
- MySQL Native Driver Plugin Architecture
- The mysqlnd plugin API
- Getting started building a mysqlnd plugin

The MySQL Native Driver Plugin API is a feature of MySQL Native Driver, or `mysqlnd`. `Mysqlnd` plugins operate in the layer between PHP applications and the MySQL server. This is comparable to MySQL Proxy. MySQL Proxy operates on a layer between any MySQL client application, for example, a PHP application and, the MySQL server. `Mysqlnd` plugins can undertake typical MySQL Proxy tasks such as load balancing, monitoring and performance optimizations. Due to the different architecture and location, `mysqlnd` plugins do not have some of MySQL Proxy's disadvantages. For example, with plugins, there is no single point of failure, no dedicated proxy server to deploy, and no new programming language to learn (Lua).

A `mysqlnd` plugin can be thought of as an extension to `mysqlnd`. Plugins can intercept the majority of `mysqlnd` functions. The `mysqlnd` functions are called by the PHP MySQL extensions such as `ext/mysql`, `ext/mysqli`, and `PDO_MYSQL`. As a result, it is possible for a `mysqlnd` plugin to intercept all calls made to these extensions from the client application.

Internal `mysqlnd` function calls can also be intercepted, or replaced. There are no restrictions on manipulating `mysqlnd` internal function tables. It is possible to set things up so that when certain `mysqlnd` functions are called by the extensions that use `mysqlnd`, the call is directed to the appropriate function in the `mysqlnd` plugin. The ability to manipulate `mysqlnd` internal function tables in this way allows maximum flexibility for plugins.

`Mysqlnd` plugins are in fact PHP Extensions, written in C, that use the `mysqlnd` plugin API (which is built into MySQL Native Driver, `mysqlnd`). Plugins can be made 100% transparent to PHP applications. No application changes are needed because plugins operate on a different layer. The `mysqlnd` plugin can be thought of as operating in a layer below `mysqlnd`.

The following list represents some possible applications of `mysqlnd` plugins.

- Load Balancing
  - Read/Write Splitting. An example of this is the PECL/mysqlnd_ms (Master Slave) extension. This extension splits read/write queries for a replication setup.
  - Failover
  - Round-Robin, least loaded
- Monitoring
  - Query Logging
  - Query Analysis
  - Query Auditing. An example of this is the PECL/mysqlnd_sip (SQL Injection Protection) extension. This extension inspects queries and executes only those that are allowed according to a ruleset.
- Performance
  - Caching. An example of this is the PECL/mysqlnd_qc (Query Cache) extension.
  - Throttling
  - Sharding. An example of this is the PECL/mysqlnd_mc (Multi Connect) extension. This extension will attempt to split a SELECT statement into n-parts, using SELECT ... LIMIT part_1, SELECT LIMIT part_n. It sends the queries to distinct MySQL servers and merges the result at the client.

MySQL Native Driver Plugins Available

There are a number of mysqlnd plugins already available. These include:

- PECL/mysqlnd_mc - Multi Connect plugin.
- PECL/mysqlnd_ms - Master Slave plugin.
- PECL/mysqlnd_qc - Query Cache plugin.
- PECL/mysqlnd_pscache - Prepared Statement Handle Cache plugin.
- PECL/mysqlnd_sip - SQL Injection Protection plugin.
- PECL/mysqlnd_uh - User Handler plugin.

## A comparison of mysqlnd plugins with MySQL Proxy

`Mysqlnd` plugins and MySQL Proxy are different technologies using different approaches. Both are valid tools for solving a variety of common tasks such as load balancing, monitoring, and performance enhancements. An important difference is that MySQL Proxy works with all MySQL clients, whereas `mysqlnd` plugins are specific to PHP applications.

As a PHP Extension, a `mysqlnd` plugin gets installed on the PHP application server, along with the rest of PHP. MySQL Proxy can either be run on the PHP application server or can be installed on a dedicated machine to handle multiple PHP application servers.

Deploying MySQL Proxy on the application server has two advantages:

1. No single point of failure
2. Easy to scale out (horizontal scale out, scale by client)

MySQL Proxy (and `mysqlnd` plugins) can solve problems easily which otherwise would have required changes to existing applications.

However, MySQL Proxy does have some disadvantages:

- MySQL Proxy is a new component and technology to master and deploy.
- MySQL Proxy requires knowledge of the Lua scripting language.

MySQL Proxy can be customized with C and Lua programming. Lua is the preferred scripting language of MySQL Proxy. For most PHP experts Lua is a new language to learn. A `mysqlnd` plugin can be written in C. It is also possible to write plugins in PHP using » PECL/mysqlnd_uh.

MySQL Proxy runs as a daemon - a background process. MySQL Proxy can recall earlier decisions, as all state can be retained. However, a `mysqlnd` plugin is bound to the request-based lifecycle of PHP. MySQL Proxy can also share one-time computed results among multiple application servers. A `mysqlnd` plugin would need to store data in a persistent medium to be able to do this. Another daemon would need to be used for this purpose, such as Memcache. This gives MySQL Proxy an advantage in this case.

MySQL Proxy works on top of the wire protocol. With MySQL Proxy you have to parse and reverse engineer the MySQL Client Server Protocol. Actions are limited to those that can be achieved by manipulating the communication protocol. If the wire protocol changes (which happens very rarely) MySQL Proxy scripts would need to be changed as well.

`Mysqlnd` plugins work on top of the C API, which mirrors the `libmysqlclient` client. This C API is basically a wrapper around the MySQL Client Server protocol, or wire protocol, as it is sometimes called. You can intercept all C API calls. PHP makes use of the C API, therefore you can hook all PHP calls, without the need to program at the level of the wire protocol.

`Mysqlnd` implements the wire protocol. Plugins can therefore parse, reverse engineer, manipulate and even replace the communication protocol. However, this is usually not required.

As plugins allow you to create implementations that use two levels (C API and wire protocol), they have greater flexibility than MySQL Proxy. If a `mysqlnd` plugin is implemented using the C API, any subsequent changes to the wire protocol do not require changes to the plugin itself.

## Obtaining the mysqlnd plugin API

The `mysqlnd` plugin API is simply part of the MySQL Native Driver PHP extension, `ext/mysqlnd`. Development started on the `mysqlnd` plugin API in December 2009. It is developed as part of the PHP source repository, and as such is available to the public either via Git, or through source snapshot downloads.

Plugin developers can determine the `mysqlnd` version through accessing `MYSQLND_VERSION`, which is a string of the format mysqlnd 8.3.17, or through `MYSQLND_VERSION_ID`, which is an integer such as 50007. Developers can calculate the version number as follows:

MYSQLND_VERSION_ID calculation table
Version (part) | Example
--- | ---
Major*10000 | 5*10000 = 50000
Minor*100 | 0*100 = 0
Patch | 7 = 7
MYSQLND_VERSION_ID | 50007

During development, developers should refer to the `mysqlnd` version number for compatibility and version tests, as several iterations of `mysqlnd` could occur during the lifetime of a PHP development branch with a single PHP version number.

## MySQL Native Driver Plugin Architecture

This section provides an overview of the `mysqlnd` plugin architecture.

MySQL Native Driver Overview

Before developing `mysqlnd` plugins, it is useful to know a little of how `mysqlnd` itself is organized. `Mysqlnd` consists of the following modules:

The mysqlnd organization chart, per module
Modules Statistics | mysqlnd_statistics.c
--- | ---
Connection | mysqlnd.c
Resultset | mysqlnd_result.c
Resultset Metadata | mysqlnd_result_meta.c
Statement | mysqlnd_ps.c
Network | mysqlnd_net.c
Wire protocol | mysqlnd_wireprotocol.c

C Object-Oriented Paradigm

At the code level, `mysqlnd` uses a C pattern for implementing object orientation.

In C you use a `struct` to represent an object. Members of the struct represent object properties. Struct members pointing to functions represent methods.

Unlike with other languages such as C++ or Java, there are no fixed rules on inheritance in the C object-oriented paradigm. However, there are some conventions that need to be followed that will be discussed later.

The PHP Life Cycle

When considering the PHP life cycle there are two basic cycles:

- PHP engine startup and shutdown cycle
- Request cycle

When the PHP engine starts up it will call the module initialization (MINIT) function of each registered extension. This allows each module to setup variables and allocate resources that will exist for the lifetime of the PHP engine process. When the PHP engine shuts down it will call the module shutdown (MSHUTDOWN) function of each extension.

During the lifetime of the PHP engine it will receive a number of requests. Each request constitutes another life cycle. On each request the PHP engine will call the request initialization function of each extension. The extension can perform any variable setup and resource allocation required for request processing. As the request cycle ends the engine calls the request shutdown (RSHUTDOWN) function of each extension so the extension can perform any cleanup required.

How a plugin works

A `mysqlnd` plugin works by intercepting calls made to `mysqlnd` by extensions that use `mysqlnd`. This is achieved by obtaining the `mysqlnd` function table, backing it up, and replacing it by a custom function table, which calls the functions of the plugin as required.

The following code shows how the `mysqlnd` function table is replaced:

    /* a place to store original function table */
    struct st_mysqlnd_conn_methods org_methods;

    void minit_register_hooks(TSRMLS_D) {
      /* active function table */
      struct st_mysqlnd_conn_methods * current_methods
        = mysqlnd_conn_get_methods();

      /* backup original function table */
      memcpy(&org_methods, current_methods,
        sizeof(struct st_mysqlnd_conn_methods);

      /* install new methods */
      current_methods->query = MYSQLND_METHOD(my_conn_class, query);
    }

Connection function table manipulations must be done during Module Initialization (MINIT). The function table is a global shared resource. In an multi-threaded environment, with a TSRM build, the manipulation of a global shared resource during the request processing will almost certainly result in conflicts.

> 注意: Do not use any fixed-size logic when manipulating the `mysqlnd` function table: new methods may be added at the end of the function table. The function table may change at any time in the future.

Calling parent methods

If the original function table entries are backed up, it is still possible to call the original function table entries - the parent methods.

In some cases, such as for `Connection::stmt_init()`, it is vital to call the parent method prior to any other activity in the derived method.

    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 */
    }

Extending properties

A `mysqlnd` object is represented by a C struct. It is not possible to add a member to a C struct at run time. Users of `mysqlnd` objects cannot simply add properties to the objects.

Arbitrary data (properties) can be added to a `mysqlnd` objects using an appropriate function of the `mysqlnd_plugin_get_plugin_<object>_data()` family. When allocating an object `mysqlnd` reserves space at the end of the object to hold a `void *` pointer to arbitrary data. `mysqlnd` reserves space for one `void *` pointer per plugin.

The following table shows how to calculate the position of the pointer for a specific plugin:

Pointer calculations for mysqlnd
Memory address | Contents
--- | ---
0 | Beginning of the mysqlnd object C struct
n | End of the mysqlnd object C struct
n + (m x sizeof(void*)) | void* to object data of the m-th plugin

If you plan to subclass any of the `mysqlnd` object constructors, which is allowed, you must keep this in mind!

The following code shows extending properties:

    /* any data we want to associate */
    typedef struct my_conn_properties {
      unsigned long query_counter;
    } MY_CONN_PROPERTIES;

    /* plugin id */
    unsigned int my_plugin_id;

    void minit_register_hooks(TSRMLS_D) {
      /* obtain unique plugin ID */
      my_plugin_id = mysqlnd_plugin_register();
      /* snip - see 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;
    }

The plugin developer is responsible for the management of plugin data memory.

Use of the `mysqlnd` memory allocator is recommended for plugin data. These functions are named using the convention: `mnd_*loc()`. The `mysqlnd` allocator has some useful features, such as the ability to use a debug allocator in a non-debug build.

When and how to subclass
| When to subclass? | Each instance has its own private function table? | How to subclass?
--- | --- | --- | ---
Connection (MYSQLND) | MINIT | No | mysqlnd_conn_get_methods()
Resultset (MYSQLND_RES) | MINIT or later | Yes | mysqlnd_result_get_methods() or object method function table manipulation
Resultset Meta (MYSQLND_RES_METADATA) | MINIT | No | mysqlnd_result_metadata_get_methods()
Statement (MYSQLND_STMT) | MINIT | No | mysqlnd_stmt_get_methods()
Network (MYSQLND_NET) | MINIT or later | Yes | mysqlnd_net_get_methods() or object method function table manipulation
Wire protocol (MYSQLND_PROTOCOL) | MINIT or later | Yes | mysqlnd_protocol_get_methods() or object method function table manipulation

You must not manipulate function tables at any time later than MINIT if it is not allowed according to the above table.

Some classes contain a pointer to the method function table. All instances of such a class will share the same function table. To avoid chaos, in particular in threaded environments, such function tables must only be manipulated during MINIT.

Other classes use copies of a globally shared function table. The class function table copy is created together with the object. Each object uses its own function table. This gives you two options: you can manipulate the default function table of an object at MINIT, and you can additionally refine methods of an object without impacting other instances of the same class.

The advantage of the shared function table approach is performance. There is no need to copy a function table for each and every object.

Constructor status
Type | Allocation, construction, reset | Can be modified? | Caller
--- | --- | --- | ---
Connection (MYSQLND) | mysqlnd_init() | No | mysqlnd_connect()
Resultset(MYSQLND_RES) | Allocation: Connection::result_init() Reset and re-initialized during: Result::use_result() Result::store_result | Yes, but call parent! | Connection::list_fields() Statement::get_result() Statement::prepare() (Metadata only) Statement::resultMetaData()
Resultset Meta (MYSQLND_RES_METADATA) | Connection::result_meta_init() | Yes, but call parent! | Result::read_result_metadata()
Statement (MYSQLND_STMT) | Connection::stmt_init() | Yes, but call parent! | Connection::stmt_init()
Network (MYSQLND_NET) | mysqlnd_net_init() | No | Connection::init()
Wire protocol (MYSQLND_PROTOCOL) | mysqlnd_protocol_init() | No | Connection::init()

It is strongly recommended that you do not entirely replace a constructor. The constructors perform memory allocations. The memory allocations are vital for the `mysqlnd` plugin API and the object logic of `mysqlnd`. If you do not care about warnings and insist on hooking the constructors, you should at least call the parent constructor before doing anything in your constructor.

Regardless of all warnings, it can be useful to subclass constructors. Constructors are the perfect place for modifying the function tables of objects with non-shared object tables, such as Resultset, Network, Wire Protocol.

Destruction status
Type | Derived method must call parent? | Destructor
--- | --- | ---
Connection | yes, after method execution | free_contents(), end_psession()
Resultset | yes, after method execution | free_result()
Resultset Meta | yes, after method execution | free()
Statement | yes, after method execution | dtor(), free_stmt_content()
Network | yes, after method execution | free()
Wire protocol | yes, after method execution | free()

The destructors are the appropriate place to free properties, `mysqlnd_plugin_get_plugin_<object>_data()`.

The listed destructors may not be equivalent to the actual `mysqlnd` method freeing the object itself. However, they are the best possible place for you to hook in and free your plugin data. As with constructors you may replace the methods entirely but this is not recommended. If multiple methods are listed in the above table you will need to hook all of the listed methods and free your plugin data in whichever method is called first by `mysqlnd`.

The recommended method for plugins is to simply hook the methods, free your memory and call the parent implementation immediately following this.

## The mysqlnd plugin API

The following is a list of functions provided in the `mysqlnd` plugin API:

- 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()

There is no formal definition of what a plugin is and how a plugin mechanism works.

Components often found in plugins mechanisms are:

- A plugin manager
- A plugin API
- Application services (or modules)
- Application service APIs (or module APIs)

The `mysqlnd` plugin concept employs these features, and additionally enjoys an open architecture.

No Restrictions

A plugin has full access to the inner workings of `mysqlnd`. There are no security limits or restrictions. Everything can be overwritten to implement friendly or hostile algorithms. It is recommended you only deploy plugins from a trusted source.

As discussed previously, plugins can use pointers freely. These pointers are not restricted in any way, and can point into another plugin's data. Simple offset arithmetic can be used to read another plugin's data.

It is recommended that you write cooperative plugins, and that you always call the parent method. The plugins should always cooperate with `mysqlnd` itself.

Issues: an example of chaining and cooperation
Extension | mysqlnd.query() pointer | call stack if calling parent
--- | --- | ---
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 this scenario, a cache (`ext/mysqlnd_cache`) and a monitor (`ext/mysqlnd_monitor`) plugin are loaded. Both subclass `Connection::query()`. Plugin registration happens at `MINIT` using the logic shown previously. PHP calls extensions in alphabetical order by default. Plugins are not aware of each other and do not set extension dependencies.

By default the plugins call the parent implementation of the query method in their derived version of the method.

PHP Extension Recap

This is a recap of what happens when using an example plugin, `ext/mysqlnd_plugin`, which exposes the `mysqlnd` C plugin API to PHP:

- Any PHP MySQL application tries to establish a connection to 192.168.2.29
- The PHP application will either use `ext/mysql`, `ext/mysqli` or `PDO_MYSQL`. All three PHP MySQL extensions use `mysqlnd` to establish the connection to 192.168.2.29.
- `Mysqlnd` calls its connect method, which has been subclassed by `ext/mysqlnd_plugin`.
- `ext/mysqlnd_plugin` calls the userspace hook `proxy::connect()` registered by the user.
- The userspace hook changes the connection host IP from 192.168.2.29 to 127.0.0.1 and returns the connection established by `parent::connect()`.
- `ext/mysqlnd_plugin` performs the equivalent of `parent::connect(127.0.0.1)` by calling the original `mysqlnd` method for establishing a connection.
- `ext/mysqlnd` establishes a connection and returns to `ext/mysqlnd_plugin`. `ext/mysqlnd_plugin` returns as well.
- Whatever PHP MySQL extension had been used by the application, it receives a connection to 127.0.0.1. The PHP MySQL extension itself returns to the PHP application. The circle is closed.

## Getting started building a mysqlnd plugin

It is important to remember that a `mysqlnd` plugin is itself a PHP extension.

The following code shows the basic structure of the MINIT function that will be used in the typical `mysqlnd` plugin:

    /* my_php_mysqlnd_plugin.c */

     static PHP_MINIT_FUNCTION(mysqlnd_plugin) {
      /* globals, ini entries, resources, classes */

      /* register mysqlnd plugin */
      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)(/* ... */) {
      /* ... */
    }

Task analysis: from C to userspace

     class proxy extends mysqlnd_plugin_connection {
      public function connect($host, ...) { .. }
    }
    mysqlnd_plugin_set_conn_proxy(new proxy());

Process:

1. PHP: user registers plugin callback
2. PHP: user calls any PHP MySQL API to connect to MySQL
3. C: ext/*mysql* calls mysqlnd method
4. C: mysqlnd ends up in ext/mysqlnd_plugin

5. C: ext/mysqlnd_plugin

   1. Calls userspace callback
   2. Or original `mysqlnd` method, if userspace callback not set

You need to carry out the following:

1. Write a class "mysqlnd_plugin_connection" in C
2. Accept and register proxy object through "mysqlnd_plugin_set_conn_proxy()"
3. Call userspace proxy methods from C (optimization - zend_interfaces.h)

Userspace object methods can either be called using `call_user_function()` or you can operate at a level closer to the Zend Engine and use `zend_call_method()`.

Optimization: calling methods from C using zend_call_method

The following code snippet shows the prototype for the `zend_call_method` function, taken from 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
    );

Zend API supports only two arguments. You may need more, for example:

     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
    );

To get around this problem you will need to make a copy of `zend_call_method()` and add a facility for additional parameters. You can do this by creating a set of `MY_ZEND_CALL_METHOD_WRAPPER` macros.

Calling PHP userspace

This code snippet shows the optimized method for calling a userspace function from C:

    /* 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) {
        /* call userspace proxy */
        ret = MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, host, /*...*/);
      } else {
        /* or original mysqlnd method = do nothing, be transparent */
        ret = org_methods.connect(conn, host, user, passwd,
              passwd_len, db, db_len, port,
              socket, mysql_flags TSRMLS_CC);
      }
      return ret;
    }

Calling userspace: simple arguments

    /* 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);
        /* ... */
      }
      /* ... */
    }

Calling userspace: structs as arguments

    /* 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);
        /* ... */
      }
      /* ... */
    }

The first argument of many `mysqlnd` methods is a C "object". For example, the first argument of the connect() method is a pointer to `MYSQLND`. The struct MYSQLND represents a `mysqlnd` connection object.

The `mysqlnd` connection object pointer can be compared to a standard I/O file handle. Like a standard I/O file handle a `mysqlnd` connection object shall be linked to the userspace using the PHP resource variable type.

From C to userspace and back

     class proxy extends mysqlnd_plugin_connection {
      public function connect($conn, $host, ...) {
        /* "pre" hook */
        printf("Connecting to host = '%s'\n", $host);
        debug_print_backtrace();
        return parent::connect($conn);
      }

      public function query($conn, $query) {
        /* "post" hook */
        $ret = parent::query($conn, $query);
        printf("Query = '%s'\n", $query);
        return $ret;
      }
    }
    mysqlnd_plugin_set_conn_proxy(new proxy());

PHP users must be able to call the parent implementation of an overwritten method.

As a result of subclassing it is possible to refine only selected methods and you can choose to have "pre" or "post" hooks.

Built-in class: mysqlnd_plugin_connection::connect()

    /*  my_mysqlnd_plugin_classes.c */

     PHP_METHOD("mysqlnd_plugin_connection", connect) {
      /* ... simplified! ... */
      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 Connection", le_mysqlnd_plugin_conn);
      if (PASS == org_methods.connect(conn, host, /* simplified! */ TSRMLS_CC))
        RETVAL_TRUE;
      else
        RETVAL_FALSE;
    }

- Overview
- Installation
- 运行时配置
- Incompatibilities
- Persistent Connections
- Statistics
- Notes
- Memory management
- MySQL Native Driver Plugin API
  - A comparison of mysqlnd plugins with MySQL Proxy
  - Obtaining the mysqlnd plugin API
  - MySQL Native Driver Plugin Architecture
  - The mysqlnd plugin API
  - Getting started building a mysqlnd plugin

- Overview of the MySQL PHP drivers
  - Terminology overview
  - Choosing an API
  - Choosing a library
  - Concepts
- MySQLi — MySQL增强版扩展
  - 概述
  - 快速入门指南
  - 安装/配置
  - mysqli 扩展和持久化连接
  - 预定义常量
  - Notes
  - MySQLi 扩展的函数概述
  - mysqli — mysqli 类
  - mysqli_stmt — mysqli_stmt 类
  - mysqli_result — mysqli_result 类
  - mysqli_driver — mysqli_driver 类
  - mysqli_warning — mysqli_warning 类
  - mysqli_sql_exception — mysqli_sql_exception 类
  - 别名和过时的 Mysqli 函数
  - 更新日志
- Mysql_xdevapi
  - 安装/配置
  - 预定义常量
  - 更新日志
  - 示例
  - Mysql_xdevapi 函数
  - mysql_xdevapi\BaseResult — BaseResult interface
  - mysql_xdevapi\Client — Client class
  - mysql_xdevapi\Collection — Collection class
  - mysql_xdevapi\CollectionAdd — CollectionAdd class
  - mysql_xdevapi\CollectionFind — CollectionFind class
  - mysql_xdevapi\CollectionModify — CollectionModify class
  - mysql_xdevapi\CollectionRemove — CollectionRemove class
  - mysql_xdevapi\ColumnResult — ColumnResult class
  - mysql_xdevapi\CrudOperationBindable — CrudOperationBindable interface
  - mysql_xdevapi\CrudOperationLimitable — CrudOperationLimitable interface
  - mysql_xdevapi\CrudOperationSkippable — CrudOperationSkippable interface
  - mysql_xdevapi\CrudOperationSortable — CrudOperationSortable interface
  - mysql_xdevapi\DatabaseObject — DatabaseObject interface
  - mysql_xdevapi\DocResult — DocResult class
  - mysql_xdevapi\Exception — Exception class
  - mysql_xdevapi\Executable — Executable interface
  - mysql_xdevapi\ExecutionStatus — ExecutionStatus class
  - mysql_xdevapi\Expression — Expression class
  - mysql_xdevapi\Result — Result class
  - mysql_xdevapi\RowResult — RowResult class
  - mysql_xdevapi\Schema — Schema class
  - mysql_xdevapi\SchemaObject — SchemaObject interface
  - mysql_xdevapi\Session — Session class
  - mysql_xdevapi\SqlStatement — SqlStatement class
  - mysql_xdevapi\SqlStatementResult — SqlStatementResult class
  - mysql_xdevapi\Statement — Statement class
  - mysql_xdevapi\Table — Table class
  - mysql_xdevapi\TableDelete — TableDelete class
  - mysql_xdevapi\TableInsert — TableInsert class
  - mysql_xdevapi\TableSelect — TableSelect class
  - mysql_xdevapi\TableUpdate — TableUpdate class
  - mysql_xdevapi\Warning — Warning class
- Mysql（原始） — 原始的 MySQL API
  - 安装/配置
  - 更新日志
  - 预定义常量
  - 示例
  - MySQL 函数
- Mysqlnd — MySQL Native Driver
  - Overview
  - Installation
  - 运行时配置
  - Incompatibilities
  - Persistent Connections
  - Statistics
  - Notes
  - Memory management
  - MySQL Native Driver Plugin API

# Oracle OCI8

# 简介

警告

自 PHP 8.4.0 起，此扩展不再捆绑。

这些函数允许访问 Oracle 数据库。支持 SQL 和 PL/SQL 语句。基本功能包括对事务控制、PHP 变量与 Oracle 占位符的绑定以及大对象（LOB）类型和集合的支持。还支持 Oracle 的可伸缩性特性，例如数据库驻留连接池（DRCP）和结果缓存。

# 安装/配置

## 目录

- 需求
- 安装
- Testing
- 运行时配置

## 需求

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.

> 注意:

> 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.

> 注意:

> Full OCI8 feature support is only available when using the most recent versions of the Oracle client libraries and database.

## 安装

## 使用 OCI8 配置 PHP

在配置 OCI8 之前查看前面的要求部分。

在启动 Web 服务器之前，OCI8 通常需要几个 Oracle 环境变量（见下文）来定位库、指向配置文件并设置一些基本属性，例如 Oracle 库使用的字符集。必须在 PHP 进程启动之前设置变量。

PHP 二进制文件必须链接到与其配置时相同或更高的主要 Oracle 库版本。例如，如果使用 Oracle 19 库编译 OCI8，那么 PHP 也应该使用 Oracle 19 库部署和运行。PHP 应用程序可以连接到其他版本的 Oracle 数据库，因为 Oracle 具有客户端-服务器跨版本兼容性。

## 使用 pecl 命令从 PECL 安装 OCI8

可以使用 » PECL 存储库将 OCI8 扩展添加到已安装的现有 PHP 中。

- 如果在防火墙的后面，设置 PEAR 代理，例如：

      pear config-set http_proxy http://my-proxy.example.com:80/

- 运行

      pecl install oci8

  对于 PHP 7，使用 `pecl install oci8-2.2.0`

- 出现提示时，输入 `$ORACLE_HOME` 的值或 `instantclient,/path/to/instant/client/lib`。

  注意：不要输入 `$ORACLE_HOME` 或 `$HOME` 之类的变量名，因为 `pecl` 不会展开它们。反而应该输入展开后的路径，例如 `/opt/oracle/product/19c/dbhome_1` 或 `instantclient,/Users/myname/Downloads/instantclient_19_8`

- 如果收到错误 `oci8_dtrace_gen.h: No such file or directory`，这意味着 PHP 是在启用 DTrace 动态跟踪的情况下编译的。使用如下安装：

      $ export PHP_DTRACE=yes
      $ pecl install oci8

- 编辑 php.ini 文件并添加以下行：

      extension=oci8.so

  确保 php.ini 指令 extension_dir 设置为安装 oci8.so 的目录。

## 使用 phpize 从 PECL 安装 OCI8

要在无法使用 `pecl` 命令时在已安装的现有 PHP 上安装 OCI8，请手动下载 » PECL OCI8 包，例如 oci8-3.0.0.tgz。

- 解压包：

      tar -zxf oci8-3.0.0.tgz
      cd oci8-3.0.0

- 预处理包：

      phpize

- 使用 `$ORACLE_HOME` 或 Instant Client 配置包

      ./configure -with-oci8=shared,$ORACLE_HOME

  或

      ./configure -with-oci8=shared,instantclient,/path/to/instant/client/lib

- 安装包：

      make install

- 如果收到错误 `oci8_dtrace_gen.h: No such file or directory`，这意味着 PHP 是在启用 DTrace 动态跟踪的情况下编译的。设置此环境变量后重新运行 `configure` 和 `make` 命令：

      $ export PHP_DTRACE=yes

- 编辑 php.ini 文件并添加以下行：

      extension=oci8.so

  确保 php.ini 指令 extension_dir 设置为安装 oci8.so 的目录。

## 编译 PHP 时将 OCI8 作为共享扩展安装

如果从源代码编译 PHP，则可以使用 `shared` 配置选项将 OCI8 编译为共享库，可以动态加载到 PHP。编译共享扩展可以轻松升级 OCI8 ，而不会影响 PHP 的其它部分。

使用以下任一配置选项配置 OCI8。

- 如果使用免费的 » Oracle Instant Client 库，则执行以下操作：

      ./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib

  如果 Instant Client 12.2（或更早版本）是从 ZIP 文件安装的，请首先确保创建库符号链接，例如 `ln -s libclntsh.so.12.1 libclntsh.so`。

  如果使用基于 RPM 的 Oracle Instant Client 安装，配置行将如下所示：

      ./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib

  例如：--with-oci8=shared,instantclient,/usr/lib/oracle/19.9/client/lib

- 如果使用 Oracle 数据库或完整的 Oracle 客户端安装，则执行以下操作：

      ./configure --with-oci8=shared,$ORACLE_HOME

  确保 Web 服务器用户（`nobody`、`www`）可以访问 `$ORACLE_HOME` 目录下的库、初始化文件和 tnsnames.ora（如果使用）。对于 Oracle 10gR2，可能需要运行 $ORACLE_HOME/install/changePerm.sh 实用程序来授予目录访问权限。

配置后，遵循通用的 PHP 编译过程，例如 make install。将创建 OCI8 共享扩展 oci8.so 库。可能需要手动移动到 PHP 扩展目录，由 php.ini 文件中的 extension_dir 选项指定。

要完成 OCI8 的安装，请编辑 php.ini 并添加以下行：

    extension=oci8.so

## 编译 PHP 时将 OCI8 作为静态编译扩展安装

如果从源代码编译 PHP，则可以使用以下任一配置选项，配置 PHP 为包含 OCI8 静态扩展的 PHP。

- 如果使用 Oracle Instant Client，则执行以下操作：

      ./configure --with-oci8=instantclient,/path/to/instant/client/lib

- 如果使用 Oracle 数据库或完整的 Oracle 客户端安装，则执行以下操作：

      ./configure --with-oci8=$ORACLE_HOME

配置后，遵循通用的 PHP 编译过程，例如 make install。编译成功后，不需要在 php.ini 中加入 oci8.so。不需要额外的编译步骤。

## 在 Windows 上安装 OCI8

通过使用 » PECL 存储库或函数库（library）中的 DLL，在已安装 PHP 的 `ext` 中，将 OCI8 扩展添加到现有的 PHP 安装中。

对于 Oracle 12c（或更高版本）的库，取消注释其中 php.ini 行 `extension=php_oci8_12c.dll` 或 `extension=php_oci8_11g.dll` 或 `extension=php_oci8.dll` 中的一个。一次只能启用这些 DLL 中的一个。更高版本的 DLL 可能包含更多功能。并非所有 DLL 都适用于所有版本的 PHP。确保将 extension_dir 设置为包含 PHP 扩展 DLL 的目录。

如果使用 Instant Client，请将系统 PATH 环境变量设置为 Oracle 库目录。

## 设置 Oracle 环境

在使用此扩展之前，请确保为 Web 守护程序用户正确设置了 Oracle 环境变量。 如果 Web 服务器在启动时自动启动，请确保启动时环境也已正确配置。

> 注意:

> 不要在 PHP 脚本中使用 putenv() 设置 Oracle 环境变量，因为 Oracle 库可能会在脚本运行之前加载和初始化。使用 putenv() 设置的变量可能会导致冲突、崩溃或不可预知的行为。有些函数可能有效，但其它函数可能会出现细微的错误。应在启动 Web 服务器之前设置变量。

在 Red Hat Linux 及其变体上，在 /etc/sysconfig/httpd 末尾导出变量。其他带有 Apache 2 的系统可能会使用 Apache bin 目录中的 envvars 脚本。 A third option, the Apache `SetEnv` directive in httpd.conf, may work in some systems but is known to be insufficient in others.

要检查环境变量是否设置正确，请使用 phpinfo() 并检查 Environment（不是 Apache Environment）部分是否包含预期变量。

可能需要的变量包含在下表中。有关所有可用变量的更多信息，请参阅 Oracle 文档。

常见的 Oracle 环境变量
Name | Purpose
--- | ---
ORACLE_HOME | 包含完整 Oracle 数据库软件的目录。使用 Oracle Instant Client 时不要设置它，因为它是不必要的并且可能会导致安装问题。
ORACLE_SID | 包含要连接到的本地计算机上的数据库的名称。如果使用 Oracle Instant Client 或始终将连接参数传递给 oci_connect() 时，则无需设置此项。
LD_LIBRARY_PATH | 将其（或其平台等效项，例如 `LIBPATH` 或 `SHLIB_PATH`）设置为 Oracle 库的位置，例如 $ORACLE_HOME/lib 或 /usr/lib/oracle/18.5/client/lib。请注意，对于 Linux 上的 Instant Client ZIP 文件，使用 ldconfig 更可靠，请参阅 Instant Client 安装说明。对于 Instant Client 19（或更高版本）RPM 文件，ldconfig 会自动运行。有些用户使用 `LD_PRELOAD` 而不是 `LD_LIBRARY_PATH`。
NLS_LANG | 这是设置 Oracle 库使用的字符集和国际化信息的主要变量。
ORA_SDTZ | 设置 Oracle 会话时区。
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.

不太常用的 Oracle 环境变量包括 `TWO_TASK`、`ORA_TZFILE` 和各种 Oracle 全局设置，如 `NLS*` 和 `ORA_NLS_*` 变量。

## 故障排除

安装 OCI8 最常见的问题是没有正确设置 Oracle 环境。这通常表现为使用 oci_connect() 或 oci_pconnect() 的问题。该错误可能是 PHP 错误，例如 Call to undefined function oci_connect()，Oracle 错误（例如 ORA-12705），甚至是 Apache 崩溃。检查 Apache 日志文件中的启动错误，并查看以上部分以解决此问题。

虽然 ORA-12154 或 ORA-12514 等网络错误表示是 Oracle 网络命名或配置问题，但根本原因可能是因为 PHP 环境设置不正确，Oracle 库无法找到 tnsnames.ora 配置文件。

在 Windows 上，在一台机器上安装多个版本的 Oracle 很容易导致库冲突，除非注意确保 PHP 只使用正确版本的 Oracle。

用于检查查找和加载哪些库的实用程序可以帮助解决库丢失或冲突问题，尤其是在 Windows 上。

> 注意: 如果 Web 服务器未启动或在启动时崩溃

> 检查 Apache 是否与 pthread 库链接：

>     # 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)

> 如果未列出 libpthread，则需要重新安装 Apache：

>     # cd /usr/src/apache_1.3.xx
>     # make clean
>     # LIBS=-lpthread ./config.status
>     # make
>     # make install

> 请注意，在某些系统（如 UnixWare）上，它是 libthread 而不是 libpthread PHP 和 Apache 必须配置 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

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

OCI8 Configuration Options
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
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` | Deprecated as of PHP 8.1.0.
oci8.persistent_timeout | "-1" | `INI_SYSTEM` |
oci8.ping_interval | "60" | `INI_SYSTEM` |
oci8.prefetch_lob_size | "0" | `INI_SYSTEM` | Available since PECL OCI8 3.2.
oci8.privileged_connect | Off | `INI_SYSTEM` |
oci8.statement_cache_size | "20" | `INI_SYSTEM` |

这是配置指令的简短说明。

`oci8.connection_class` string

  This user defined text should always be set when using Oracle Database Resident Connection Pooling (DRCP). It allows sub-partitioning of the DRCP connection pool, allowing OCI8 persistent connections from an application to reuse database sessions from a previous PHP script, giving better scalability. When an application uses a database pooled process previously used with a different connection class, the session settings such as the default Oracle date format are reset. This prevents accidental sharing of information between different applications.

  The value can be set at runtime with ini_set() prior to connecting.

  To use DRCP, OCI8 must be linked with Oracle 11g (or later) libraries and the database must be Oracle 11g (or later). The DRCP connection pool must be enabled in the database, the `oci8.connection_class` should be set to the same string for all web servers running the same application, and the OCI8 connection string must specify to use a pooled server. The application should use persistent connections.

`oci8.default_prefetch` int

  This option sets the default number of extra rows that will be fetched and cached automatically whenever a low-level request for data from the database is made. Setting a value of `0` turns off prefetching.

  The prefetch value does not alter the number of rows that functions like oci_fetch_array() return to the user; the prefetching and caching of rows is handled internally in OCI8.

  The value can be set per-statement with oci_set_prefetch() prior to statement execution.

  When using Oracle Database 12c (or later), the prefetch value set by PHP can be overridden by Oracle's client `oraaccess.xml` configuration file. Refer to Oracle documentation for more detail.

  > 注意: A larger prefetch can result in improved performance, at the cost of some increased memory usage. For queries that return large amounts of data, the performance benefit can be significant.

`oci8.events` bool

  Using `On` allows PHP to be notified of database Fast Application Notification (FAN) events.

  Without FAN, when a database instance or machine node fails unexpectedly, PHP applications may be blocked waiting for a database response until a TCP timeout expires. With FAN events, PHP applications are quickly notified of failures that affect their established database connections. The OCI8 extension will clean up unusable connections in the persistent connection cache.

  When using `On`, the database must also be configured to post FAN events.

  FAN support is available when OCI8 is linked with Oracle 10gR2 (or later) libraries and connected to Oracle Database 10gR2 (or later).

`oci8.max_persistent` int

  The maximum number of persistent OCI8 connections per PHP process. Setting this option to -1 means that there is no limit.

`oci8.old_oci_close_semantics` bool

  This option controls oci_close() behaviour. Enabling it means that oci_close() will do nothing; the connection will not be closed until the end of the script. This is for backward compatibility only. If you find that you need to enable this setting, you are strongly encouraged to adjust the oci_close() calls in your application instead of enabling this option.

`oci8.persistent_timeout` int

  The maximum number of seconds that a PHP process is allowed to keep an idle persistent connection open. Setting this option to -1 means that idle persistent connections will be retained until the PHP process terminates or the connection is explicitly closed with oci_close().

  > 注意: In PHP, the expiry of idle resources is not alarm-based. It occurs when PHP finishes processing a script and checks the last-used timestamp of resources. Hence there is a paradox that idle connections can only be closed when there is some activity (though not necessarily OCI8 related) in the PHP process. If there is more than one PHP process then each must individually be activated in order to trigger expiry of its idle resources. The introduction of Database Resident Connection Pooling (DRCP) in Oracle 11g resolves the memory and resource issues that `oci8.max_persistent` and `oci8.persistent_timeout` previously attempted to overcome.

`oci8.ping_interval` int

  The number of seconds that must pass before issuing a ping during oci_pconnect(). A ping ensures that the database connection is valid. When set to 0, persistent connections will be pinged every time oci_pconnect() is called. To disable pings completely, set this option to -1.

  > 注意: Disabling pings allows oci_pconnect() to operate at the highest efficiency, but PHP may not be able to detect unusable connections, such as caused by network dropout, or if the Oracle database has gone down since PHP connected, until the connection is used later in the script. Consult the oci_pconnect() documentation for more information.

`oci8.prefetch_lob_size` int

  This is a tuning parameter affecting internal buffering of LOB data. 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`.

  The value can be set per-statement with oci_set_prefetch_lob() prior to statement execution.

  > 注意: Use with Oracle Database 12.2 or later.

`oci8.privileged_connect` bool

  This option allows connections to use the privileged external credentials `OCI_SYSOPER` or `OCI_SYSDBA`.

  > 注意: Seting this `On` can allow scripts on web servers running with the appropriate OS user privileges to connect as privileged database users without requiring a database password. This can be a security risk.

`oci8.statement_cache_size` int

  This option enables statement caching, and specifies how many statements to cache. To disable statement caching just set this option to 0.

  Statement caching removes the need to transmit the statement text to the database and removes the need to transmit any meta data about the statement back to PHP. This can significantly improve overall system performance in applications which reuse statements during the lifetime of a connection. Some extra database "cursors" may be held open under the assumption that statements will be reused.

  Set this value to the size of the working set of statements used by your application. Setting too small a value can cause statements to be flushed from the cache before they are reused.

  This option is of most use with persistent connections.

  When using Oracle Database 12c (or later), this value can be overridden and automatically tuned by Oracle's client `oraaccess.xml` file. Refer to Oracle documentation for more detail.

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

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`.

常量 | 描述
--- | ---
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.

# 示例

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.

示例 #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);

    ?>

示例 #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);

    ?>

示例 #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);

    ?>

示例 #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>';

    ?>

示例 #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);

    ?>

示例 #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);

    ?>

示例 #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.

> 注意:

> 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.

> 注意:

> 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.

示例 #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,  . . .);

    ?>

## 参见

- 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.

示例 #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``.

## 参见

- 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 函数

# oci_bind_array_by_name

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL OCI8 >= 1.2.0)

oci_bind_array_by_name — Binds a PHP array to an Oracle PL/SQL array parameter

### 说明

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

Binds the PHP array `var` to the Oracle placeholder `param`, which points to an Oracle PL/SQL array. Whether it will be used for input or output will be determined at run-time.

### 参数

`statement`

  A valid OCI statement identifier.

`param`

  The Oracle placeholder.

`var`

  An array.

`max_array_length`

  Sets the maximum length both for incoming and result arrays.

`max_item_length`

  Sets maximum length for array items. If not specified or equals to -1, oci_bind_array_by_name() will find the longest element in the incoming array and will use it as the maximum length.

`type`

  Should be used to set the type of PL/SQL array items. See list of available types below:

  - `SQLT_NUM` - for arrays of NUMBER.

  - `SQLT_INT` - for arrays of INTEGER (Note: INTEGER it is actually a synonym for NUMBER(38), but `SQLT_NUM` type won't work in this case even though they are synonyms).

  - `SQLT_FLT` - for arrays of FLOAT.

  - `SQLT_AFC` - for arrays of CHAR.

  - `SQLT_CHR` - for arrays of VARCHAR2.

  - `SQLT_VCS` - for arrays of VARCHAR.

  - `SQLT_AVC` - for arrays of CHARZ.

  - `SQLT_STR` - for arrays of STRING.

  - `SQLT_LVC` - for arrays of LONG VARCHAR.

  - `SQLT_ODT` - for arrays of DATE.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 oci_bind_array_by_name() example

    <?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
        -- Bulk Insert
        FORALL i IN INDICES OF c1
          INSERT INTO bind_example VALUES (c1(i));

        -- Fetch and reverse
        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 — 绑定 PHP 变量到 Oracle 位置标志符

### 说明

function oci_bind_by_name(
resource `$statement`,
string `$param`,
mixed `&$var`,
int `$max_length` = -1,
int `$type` = 0
): bool

将 PHP 变量 `var` 绑定到 Oracle 位置占位符 `param`。绑定对 Oracle 数据库性能很重要，同时也是避免 SQL 注入安全问题的一种方式。

绑定允许数据库重用语句上下文和以前执行语句的缓存，即使另一个用户或进程最初（originally）执行它也是如此。绑定减少了 SQL 注入问题，因为与绑定变量关联的数据永远不会被视为 SQL 语句的一部分。不需要引用或转义。

已经绑定的 PHP 变量可以改变，语句重新执行，而不需要重新解析语句或重新绑定。

在 Oracle 中，绑定变量通常分为用于传递到数据库的值的 `IN` 绑定和用于返回给 PHP 的值的 `OUT` 绑定。绑定变量可以同时为 `IN` 和 `OUT`。绑定变量是用于输入还是输出是在运行时确定的。

使用 `OUT` 绑定时必须指定 `max_length` 以便 PHP 分配足够的内存来保存返回值。

对于 `IN` 绑定，如果使用不同的 PHP 变量值多次重新执行该语句，建议设置 `max_length` 长度。否则 Oracle 可能会将数据截断为初始 PHP 变量值的长度。如果不知道最大长度是多少，则在每次调用 oci_execute() 之前使用当前数据大小重新调用 oci_bind_by_name()。绑定不必要的大长度将对数据库中的进程内存产生影响。

绑定调用告诉 Oracle 从哪个内存地址读取数据。对于 `IN` 绑定，调用 oci_execute() 时地址需要包含有效数据。这意味着变量绑定必须保留在作用域内直到执行。否则，可能会出现意外结果或错误，例如“ORA-01460：未实现或不合理的转换请求”。对于 `OUT` 绑定，一个问题是没有在 PHP 变量中设置值。

对于重复执行的语句，永远不变的绑定值可能会降低 Oracle 优化器选择最佳语句执行计划的能力。很少重新执行的长时间运行的语句可能无法从绑定中获益。但是，在这两种情况下，绑定可能比将字符串连接到 SQL 语句中更安全，因为如果连接未过滤的用户文本，这可能会带来安全风险。

### 参数

`statement`

  有效的 OCI8 语句标识符。

`param`

  语句中使用以冒号为前缀的绑定变量占位符。冒号在 `param` 中是可选的。Oracle 不使用问号作为占位符。

`var`

  与 `param` 关联的 PHP 变量

`max_length`

  设置数据的最大长度。如果将其设置为 -1，则此函数将使用 `var` 的当前长度来设置最大长度。在这种情况下，`var` 必须存在并且在调用 oci_bind_by_name() 时包含数据。

`type`

  Oracle 处理数据的数据类型。使用的默认 `type` 是 `SQLT_CHR`。可能的话，Oracle 将在此类型和数据库列（或 PL/SQL 变量类型）之间转换数据。

  如果要绑定抽象数据类型（LOB/ROWID/BFILE），需要先用 oci_new_descriptor() 函数分配空间。`length` 没有用于抽象数据类型，应被设为 -1。

  `type` 的可能值为：

  - `SQLT_BFILEE` 或 `OCI_B_BFILE` 对应 BFILE；

  - `SQLT_CFILEE` 或 `OCI_B_CFILEE` 对应 CFILE；

  - `SQLT_CLOB` 或 `OCI_B_CLOB` 对应 CLOB；

  - `SQLT_BLOB` 或 `OCI_B_BLOB` 对应 BLOB；

  - `SQLT_RDD` 或 `OCI_B_ROWID` 对应 ROWID；

  - `SQLT_NTY` 或 `OCI_B_NTY` 对应命名数据类型；

  - `SQLT_INT` 或 `OCI_B_INT` 对应整型；

  - `SQLT_CHR` 对应 VARCHAR；

  - `SQLT_BIN` 或 `OCI_B_BIN` 对应 RAW 列；

  - `SQLT_LNG` 对应 LONG 列；

  - `SQLT_LBI` 对应 LONG RAW 列；

  - `SQLT_RSET` 对应使用 oci_new_cursor() 创建的游标；

  - `SQLT_BOL` 或 `OCI_B_BOL` 对应 PL/SQL BOOLEAN（需要 Oracle Database 12c）

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 使用 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     '

    ?>

示例 #2 一次绑定多次执行

    <?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);

    ?>

示例 #3 使用 `foreach` 循环绑定

    <?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);

    ?>

示例 #4 在 WHERE 子句中绑定

    <?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);

    ?>

示例 #5 使用 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 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);

    ?>

示例 #6 与 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);

    ?>

对于少量固定数量的 IN 子句条件，请使用单独的绑定变量。运行时未知的值可以设置为 NULL。这允许所有应用程序用户使用单个语句，从而最大限度地提高 Oracle 数据库缓存效率。

示例 #7 在 IN 子句中绑定多个值

    <?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);

    ?>

示例 #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);

    ?>

示例 #9 INSERT 时绑定 ROWID

    <?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);

    ?>

示例 #10 为 PL/SQL 存储函数绑定

    <?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);

    ?>

示例 #11 为 PL/SQL 存储过程绑定参数

    <?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);

    ?>

示例 #12 绑定 CLOB 列

    <?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>';

    ?>

示例 #13 绑定 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

    ?>

### 注释

警告

不要同时使用 addslashes() 和 oci_bind_by_name()，因为不需要引号。任何应用的引号都将写入数据库，因为 oci_bind_by_name() 逐字插入数据并且不会删除引号或转义字符。

> 注意:

> 如果将字符串绑定到 `WHERE` 子句中的 `CHAR` 列，请记住 Oracle 对 `CHAR` 列使用空白填充的比较语义。PHP 变量使用空格填充到与成功的 `WHERE` 子句的列相同的宽度。

> 注意:

> PHP `var` 参数是引用。某些形式的循环无法按预期工作：

>     <?php
>     foreach ($myarray as $key => $value)  {
>         oci_bind_by_name($stid, $key, $value);
>     }
>     ?>

> 这会将每个键绑定到 $value 的位置，因此所有绑定变量最终都指向最后一个循环迭代的值。应该使用以下内容：

>     <?php
>     foreach ($myarray as $key => $value) {
>         oci_bind_by_name($stid, $key, $myarray[$key]);
>     }
>     ?>

### 参见

- oci_bind_array_by_name() - Binds a PHP array to an Oracle PL/SQL array parameter
- oci_parse() - 预处理用于执行的 Oracle 语句

# oci_cancel

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_cancel — 中断游标读取数据

### 说明

function oci_cancel(resource `$statement`): bool

oci_cancel() 使一个游标无效，释放所有与之关联的资源并取消了从中读取的能力。

### 参数

`statement`

  OCI 语句。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# 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

### 说明

function oci_client_version(): string

Returns a string containing the version number of the Oracle C client library that PHP is linked with.

### 参数

None

### 返回值

Returns the version number as a string.

### 示例

示例 #1 oci_client_version() example

    <?php
        echo "Client Version: " . oci_client_version(); // Client version: 19.9.0.0.0
    ?>

### 注释

> 注意:

> 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.

### 参见

- oci_server_version() - 返回 Oracle 数据库版本

# oci_close

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_close — 关闭 Oracle 连接

### 说明

function oci_close(resource `$connection`): ?bool

取消 `connection`。如果没有其他资源正在使用底层数据库连接并且它是使用 oci_connect() 或 oci_new_connect() 创建的，则关闭底层数据库连接。

建议关闭不再需要的连接，因为这可以让其他用户使用数据库资源。

### 参数

`connection`

  oci_connect()、oci_pconnect() 或 oci_new_connect() 返回的 Oracle 连接标识符。

### 返回值

启用 oci8.old_oci_close_semantics 时返回 `null`，否则返回 `true`。

### 示例

示例 #1 关闭连接

应关闭与连接关联的资源，以确保正确终止底层数据库连接并释放数据库资源。

    <?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);

    // Free the statement identifier when closing the connection
    oci_free_statement($stid);
    oci_close($conn);

    ?>

示例 #2 在关闭所有引用之前不会关闭数据库连接

在关闭与数据库的底层连接之前，连接标识符的内部引用数必须为零。

    <?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');  // this increases the refcount on $conn
    oci_execute($stid);
    oci_fetch_all($stid, $res);
    var_dump($res);

    oci_close($conn);

    // $conn is no longer usable in the script but the underlying database
    // connection is still held open until $stid is freed.
    var_dump($conn);  // prints NULL

    // While PHP sleeps, querying the Oracle V$SESSION view in a
    // terminal window will show that the database user is still connected.
    sleep(10);

    // When $stid is freed, the database connection is physically closed
    oci_free_statement($stid);

    // While PHP sleeps, querying the Oracle V$SESSION view in a
    // terminal window will show that the database user has disconnected.
    sleep(10);

    ?>

示例 #3 关闭多次打开的连接

当重新使用数据库凭据时，必须在关闭底层数据库连接之前关闭两个连接。

    <?php

    $conn1 = oci_connect('hr', 'welcome', 'localhost/XE');

    // Using the same credentials reuses the same underlying database connection
    // Any uncommitted changes done on $conn1 will be visible in $conn2
    $conn2 = oci_connect('hr', 'welcome', 'localhost/XE');

    // While PHP sleeps, querying the Oracle V$SESSION view in a
    // terminal window will show that only one database user is connected.
    sleep(10);

    oci_close($conn1); // doesn't close the underlying database connection
    var_dump($conn1);  // prints NULL because the variable $conn1 is no longer usable
    var_dump($conn2);  // displays that $conn2 is still a valid connection resource

    ?>

示例 #4 当变量超出作用域时关闭连接

当 PHP 释放了所有超出作用域的引用连接的变量时，将发生回滚（如果需要）并关闭与数据库的底层连接。

    <?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 "Finished";
    }

    $r = myfunc();
    // At this point a rollback occurred and the underlying database connection was released.

    print $r;  // displays the function return value "Finished"

    ?>

### 注释

> 注意:

> 依赖于连接标识符的变量，例如 oci_parse() 返回的语句标识符，也必须在底层数据库连接关闭之前释放。

> 注意:

> oci_close() 函数不会关闭使用 oci_pconnect() 创建的底层数据库连接。

### 参见

- oci_connect() - 建立一个到 Oracle 服务器的连接
- oci_free_statement() - 释放关联于语句或游标的所有资源

# oci_commit

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_commit — 提交未完成的数据库事务

### 说明

function oci_commit(resource `$connection`): bool

为 Oracle `connection` 提交未完成的事务。提交结束当前事务并使所有更改永久化。释放所有持有的锁。

当使用 `OCI_NO_AUTO_COMMIT` flag 通过 oci_execute() 执行第一个更改数据的 SQL 语句时，事务开始。其他语句所做的进一步数据更改成为同一事务的一部分。在事务提交或回滚之前，事务中所做的数据更改是临时的。在提交之前，数据库的其他用户将看不到更改。

插入或更新数据时，出于关系数据一致性和性能原因，建议使用事务。

### 参数

`connection`

  oci_connect()、oci_pconnect() 或 oci_new_connect() 返回的 Oracle 连接标识符。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 oci_commit() 示例

    <?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);
    }

    ?>

### 注释

> 注意:

> 当关闭连接或脚本结束时（看哪个先）事务会自动回滚。需要明确地调用 oci_commit() 来提交事务。

> Any call to oci_execute() that uses `OCI_COMMIT_ON_SUCCESS` mode explicitly or by default will commit any previous uncommitted transaction.

> 任何 Oracle DDL 语句（例如 `CREATE` 或 `DROP`）都会自动提交任何未提交的事务。

### 参见

- oci_execute() - 执行语句
- oci_rollback() - 回滚未完成的事务

# oci_connect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_connect — 建立一个到 Oracle 服务器的连接

### 说明

function oci_connect(
string `$username`,
string `$password`,
?string `$connection_string` = `null`,
string `$encoding` = "",
int `$session_mode` = `OCI_DEFAULT`
): resource|false

返回大多数其他 OCI8 操作所需的连接标识符。

为了提高性能，大多数应用程序应该使用 oci_pconnect() 的持久连接而不是 oci_connect()。有关连接管理和连接池的基本信息，请参阅连接处理。

使用相同参数对 oci_connect() 的第二次和后续调用将返回从第一次调用返回的连接句柄。这意味着一个句柄中的事务也在其他句柄中，因为它们使用相同的底层数据库连接。如果两个句柄需要在事务上相互隔离，请改用 oci_new_connect()。

### 参数

`username`

  Oracle 用户名。

`password`

  `username` 的密码。

`connection_string`
  包含要连接的 `Oracle 实例`。可以是 » Easy Connect 串，或是 tnsnames.ora 文件中的连接名，或是本地 Oracle 实例名。 如果不指定或者为 `null`，PHP 使用环境变量来确定连接的 `Oracle 实例`，诸如 `TWO_TASK`（Linux 下）或 `LOCAL`（Windows 下）与 `ORACLE_SID` 等。 要使用 Easy Connect 命名方法，PHP 必须与 Oracle 10g 或更高版本的客户端库进行链接。Oracle 10g 的 Easy Connect 串格式：[//]host_name[:port][/service_name]。Oracle 11g 则为：[//]host_name[:port][/service_name][:server_type][/instance_name]。 在 Oracle 19c 加入类更多选项，例如 timeout 和 keep-alive 设置。 请参考 Oracle 文档。 服务名可在数据库服务器机器上运行 Oracle 实用程序 `lsnrctl status` 找到。 tnsnames.ora 文件可在 Oracle Net 查找路径中，此路径包括 /your/path/to/instantclient/network/admin、$ORACLE_HOME/network/admin 、/etc。 另一种方法是设置 `TNS_ADMIN` 以便通过 $TNS_ADMIN/tnsnames.ora 来读取。表确认 web 守护进程可读取此文件。
`encoding`
  使用 Oracle 客户端库来确定字符集。字符集不需要与数据库的字符集相匹配。如果不匹配，Oracle 会尽可能地将数据从数据库字符集进行转换。因为依赖于字符集，可能不能给出可用的结果。转换也增加一些时间开销。 如果不指定，Oracle 客户端用 `NLS_LANG` 环境变量来决定字符集。 传递此参数可减少连接时间。
`session_mode`
  此参数在 PHP 5（PECL OCI8 1.1）版本开始可用，并收受下列值：`OCI_DEFAULT`，`OCI_SYSOPER` 和 `OCI_SYSDBA`。如为 `OCI_SYSOPER` 或 `OCI_SYSDBA` 其中之一，此函数将会使用外部的证书建立有特权的连接。有特权的连接默认是禁用的。需要将 oci8.privileged_connect 设为 `On` 来启用。 PHP 5.3（PECL OCI8 1.3.4）引进了 `OCI_CRED_EXT` 模式值。使用外部或操作系统认证必需在 Oracle 数据库中进行配置。`OCI_CRED_EXT` 标志只可用于用户为 "/"，密码为空的情况。oci8.privileged_connect 可为 `On` 或 `Off`。 `OCI_CRED_EXT` 可与 `OCI_SYSOPER` 或 `OCI_SYSDBA` 模式组合使用。 `OCI_CRED_EXT` 由于安全的原因不支持 Windows 系统。

### 返回值

返回连接标识符或出错时为 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0、PECL OCI8 3.0.0 | `connection_string` 现在可为 null。

### 示例

示例 #1 使用 Easy Connect 语法的基础 oci_connect()

    <?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";

    ?>

示例 #2 使用 Network Connect 名称的基础 oci_connect()

    <?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";

    ?>

示例 #3 带有显式字符集的 oci_connect()

    <?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";

    ?>

示例 #4 多次调用 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

    ?>

### 注释

> 注意:

> 错误安装或配置的 OCI8 扩展通常会表现为连接问题或错误。有关故障排除信息，请参阅安装/配置。

### 参见

- oci_pconnect() - 使用持久连接连，连接到 Oracle 数据库
- oci_new_connect() - 使用唯一连接，连接到 Oracle 服务器
- oci_close() - 关闭 Oracle 连接

# oci_define_by_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_define_by_name — 将 PHP 变量与查询读取的列相关联

### 说明

function oci_define_by_name(
resource `$statement`,
string `$column`,
mixed `&$var`,
int `$type` = 0
): bool

使用 oci_fetch() 将 PHP 变量与查询读取的列相关联。

必须在执行 oci_execute() 之前调用 oci_define_by_name()。

### 参数

`statement`
  有效的 OCI8 报表标识符 由 oci_parse() 创建，被 oci_execute() 或 `REF CURSOR` statement 标识执行。
`column`

  查询中使用的列名。

  对 Oracle 中默认、不区分大小写的列名使用大写字母。对区分大小写的列名使用准确的列名大小写。

`var`

  将包含返回列的值的 PHP 变量。

`type`

  要返回的数据类型。一般不需要。注意不会执行 Oracle 样式的数据转换。例如将会忽略 `SQLT_INT`，返回的数据类型仍为 `SQLT_CHR`。

  可以选择使用 oci_new_descriptor() 来分配 LOB/ROWID/BFILE 描述符。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 oci_define_by_name() 示例

    <?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);

    ?>

示例 #2 oci_define_by_name() 带有区分大小写的列名

    <?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);

    ?>

示例 #3 oci_define_by_name() 带有 LOB 列

    <?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);

    ?>

示例 #4 oci_define_by_name() 带有显式类型

    <?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);

    ?>

### 参见

- oci_fetch() - 从查询中读取下一行到内部缓冲区
- oci_new_descriptor() - 初始化新的空 LOB 或 FILE 描述符

# oci_error

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_error — 返回最后发现的错误

### 说明

function oci_error(?resource `$connection_or_statement` = `null`): array|false

返回最后发现的错误。

发生错误后应立即调用该函数。错误会由成功的语句清除。

### 参数

`connection_or_statement`

  对于大多数错误，`connection_or_statement` 是传递给失败函数以供调用的资源句柄。对于 oci_connect()、oci_new_connect() 或 oci_pconnect() 的连接错误，应传递 `null`。

### 返回值

如果没有发现错误，oci_error() 返回 `false`。否则，oci_error() 将错误信息作为关联数组返回。

oci_error() 数组说明
数组键 | 类型 | 说明
--- | --- | ---
`code` | int | Oracle 错误编号。
`message` | string | Oracle 错误文本。
`offset` | int | SQL 语句中错误的字节位置。如果没有语句，则为 `0`
`sqltext` | string | SQL 语句文本。如果没有语句，则是空字符串。

### 更新日志

版本 | 说明
--- | ---
8.0.0、PECL OCI8 3.0.0 | `connection_or_statement` 现在可为 null。

### 示例

示例 #1 连接错误后显示 Oracle 错误消息

    <?php
    $conn = oci_connect("hr", "welcome", "localhost/XE");
    if (!$conn) {
        $e = oci_error();   // For oci_connect errors do not pass a handle
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }
    ?>

示例 #2 语法解析错误后显示 Oracle 错误消息

    <?php
    $stid = oci_parse($conn, "select ' from dual");  // note mismatched quote
    if (!$stid) {
        $e = oci_error($conn);  // For oci_parse errors pass the connection handle
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }
    ?>

示例 #3 显示 Oracle 错误信息、问题语句、执行错误问题所在位置

    <?php
    $stid = oci_parse($conn, "select does_not_exist from dual");
    $r = oci_execute($stid);
    if (!$r) {
        $e = oci_error($stid);  // For oci_execute errors pass the statement handle
        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 — 执行语句

### 说明

function oci_execute(resource `$statement`, int `$mode` = `OCI_COMMIT_ON_SUCCESS`): bool

执行先前从 oci_parse() 返回的 `statement`。

执行后，像 `INSERT` 这样的语句默认会将数据提交到数据库中。对于像 `SELECT` 这样的语句，执行查询的逻辑。随后可以使用 oci_fetch_array() 等函数在 PHP 中获取查询结果。

每个已解析的语句可能会执行多次，节省了重新解析的成本。当使用 oci_bind_by_name() 绑定数据时，这通常用于 `INSERT` 语句。

### 参数

`statement`

  有效的 OCI 语句标识符。

`mode`

  可选的第二个参数可以是以下常量之一：

  执行模式
  常量 | 说明
  --- | ---
  `OCI_COMMIT_ON_SUCCESS` | 当语句成功时，自动提交此连接的所有未完成更改。这是默认设置。
  `OCI_DESCRIBE_ONLY` | 使查询元数据可用于 oci_field_name() 等函数，但不创建结果集。任何后续的读取调用（例如 oci_fetch_array()）都将失败。
  `OCI_NO_AUTO_COMMIT` | 不要自动提交更改。

  使用 `OCI_NO_AUTO_COMMIT` 模式启动或继续事务。当连接关闭或脚本结束时，事务会自动回滚。显式调用 oci_commit() 来提交事务，或调用 oci_rollback() 来中止它。

  插入或更新数据时，出于关系数据一致性和性能原因，建议使用事务。

  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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 oci_execute() 用于查询

    <?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";

    ?>

示例 #2 oci_execute() 未指定模式示例

    <?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

    ?>

示例 #3 oci_execute() 和 `OCI_NO_AUTO_COMMIT` 示例

    <?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

    ?>

示例 #4 具有不同提交模式的 oci_execute() 示例

    <?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

    ?>

示例 #5 oci_execute() 与 `OCI_DESCRIBE_ONLY` 示例

    <?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";
    }

    ?>

### 注释

> 注意:

> 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.

> 注意:

> 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.

### 参见

- oci_parse() - 预处理用于执行的 Oracle 语句

# oci_fetch

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch — 从查询中读取下一行到内部缓冲区

### 说明

function oci_fetch(resource `$statement`): bool

从查询中读取下一行到内部缓冲区，可以使用 oci_result() 访问，也可以使用之前用 oci_define_by_name() 定义的变量访问。

有关读取数据的通用信息，请参阅 oci_fetch_array()。

### 参数

`statement`
  有效的 OCI8 报表标识符 由 oci_parse() 创建，被 oci_execute() 或 `REF CURSOR` statement 标识执行。

### 返回值

成功时返回 `true`，如果 `statement` 中没有更多行，则为 `false`。

### 示例

示例 #1 oci_fetch() 与已定义的变量

    <?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);

    ?>

示例 #2 oci_fetch() 和 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);

    ?>

### 注释

> 注意:

> 不会从 Oracle 数据库隐式结果集中返回行。请改用 oci_fetch_array()。

### 参见

- oci_define_by_name() - 将 PHP 变量与查询读取的列相关联
- oci_fetch_all() - 从查询中读取多行到二维数组中
- oci_fetch_array() - Returns the next row from a query as an associative or numeric array
- oci_fetch_assoc() - Returns the next row from a query as an associative array
- oci_fetch_object() - Returns the next row from a query as an object
- oci_fetch_row() - Returns the next row from a query as a numeric array
- oci_result() - 返回所取得行中字段的值

# oci_fetch_all

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_all — 从查询中读取多行到二维数组中

### 说明

function oci_fetch_all(
resource `$statement`,
array `&$output`,
int `$offset` = 0,
int `$limit` = -1,
int `$flags` = OCI_FETCHSTATEMENT_BY_COLUMN | OCI_ASSOC
): int

在查询中的读取多行到二维数组中。默认情况下，返回所有行。

对于使用 oci_execute() 执行的每个查询，此函数只能调用一次。

### 参数

`statement`
  有效的 OCI8 报表标识符 由 oci_parse() 创建，被 oci_execute() 或 `REF CURSOR` statement 标识执行。
`output`

  包含返回行的变量。

  LOB 列作为字符串返回，其中 Oracle 支持转换。

  有关如何读取数据和类型的更多信息，请参见 oci_fetch_array()。

`offset`

  读取结果时要丢弃的初始行数。默认值为 0，因此返回第一行。

`limit`

  要返回的行数。默认值为 -1，表示返回从 `offset` + 1 开始的所有行。

`flags`

  参数 `flags` 表示数组结构以及是否应使用关联数组。

  oci_fetch_all() 数组结构模式
  常量 | 说明
  --- | ---
  `OCI_FETCHSTATEMENT_BY_ROW` | 外部数组将包含每个查询行的子数组。
  `OCI_FETCHSTATEMENT_BY_COLUMN` | 外部数组将包含每个查询列的子数组。这是默认设置。

  数组可以按列标头或数字索引。只会返回一种索引模式。

  oci_fetch_all() 数组索引模式
  常量 | 说明
  --- | ---
  `OCI_NUM` | 数字索引用于每一列的数组。
  `OCI_ASSOC` | 关联索引用于每一列的数组。这是默认设置。

  使用加法运算符“+”选择数组结构和索引模式的组合。

  Oracle's default, non-case sensitive column names will have uppercase array keys. Case-sensitive column names will have array keys using the exact column case. Use var_dump() on `output` to verify the appropriate case to use for each query.

  具有多个同名列的查询应使用列别名。否则只有一列会出现在关联数组中。

### 返回值

返回 `output` 中的行数，可以是 0 或更多。

### 示例

示例 #1 oci_fetch_all() 示例

    <?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 rows fetched<br>\n";
    var_dump($res);

    // var_dump output is:
    //    2 rows fetched
    //    array(2) {
    //      ["POSTAL_CODE"]=>
    //      array(2) {
    //        [0]=>
    //        string(6) "00989x"
    //        [1]=>
    //        string(6) "10934x"
    //      }
    //      ["CITY"]=>
    //      array(2) {
    //        [0]=>
    //        string(4) "Roma"
    //        [1]=>
    //        string(6) "Venice"
    //      }
    //    }

    // Pretty-print the results
    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);

    ?>

示例 #2 带有 `OCI_FETCHSTATEMENT_BY_ROW` 的 oci_fetch_all() 示例

    <?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 rows fetched<br>\n";
    var_dump($res);

    // Output is:
    //    2 rows fetched
    //    array(2) {
    //      [0]=>
    //      array(2) {
    //        ["POSTAL_CODE"]=>
    //        string(6) "00989x"
    //        ["CITY"]=>
    //        string(4) "Roma"
    //      }
    //      [1]=>
    //      array(2) {
    //        ["POSTAL_CODE"]=>
    //        string(6) "10934x"
    //        ["CITY"]=>
    //        string(6) "Venice"
    //      }
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

示例 #3 带有 `OCI_NUM` 的 oci_fetch_all()

    <?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 rows fetched<br>\n";
    var_dump($res);

    // Output is:
    //    2 rows fetched
    //    array(2) {
    //      [0]=>
    //      array(2) {
    //        [0]=>
    //        string(6) "00989x"
    //        [1]=>
    //        string(4) "Roma"
    //      }
    //      [1]=>
    //      array(2) {
    //        [0]=>
    //        string(6) "10934x"
    //        [1]=>
    //        string(6) "Venice"
    //      }
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### 注释

> 注意:

> 使用 `offset` 非常低效。所有要跳过的行都包含在从数据库返回到 PHP 的结果集中。然后将它们丢弃。使用 SQL 限制查询中行的偏移量和范围会更高效。有关示例，请参见 oci_fetch_array()。

> 注意:

> 如果使用像 oci_fetch_array() 这样的单行读取函数，返回大量行的查询可以提高内存效率。

> 注意: 查询返回巨大数量的数据行时，通过增大 oci8.default_prefetch 值或使用 oci_set_prefetch() 可显著提高性能。

> 注意:

> 不会从 Oracle Database 12c 隐式结果集中返回行。请改用 oci_fetch_array()。

### 参见

- oci_fetch() - 从查询中读取下一行到内部缓冲区
- oci_fetch_array() - Returns the next row from a query as an associative or numeric array
- oci_fetch_assoc() - Returns the next row from a query as an associative array
- oci_fetch_object() - Returns the next row from a query as an object
- oci_fetch_row() - Returns the next row from a query as a numeric array
- oci_set_prefetch() - 设置查询预读取的行数

# oci_fetch_array

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_array — Returns the next row from a query as an associative or numeric array

### 说明

function oci_fetch_array(resource `$statement`, int `$mode` = OCI_BOTH | OCI_RETURN_NULLS): array|false

Returns an array containing the next result-set row of a query. Each array entry corresponds to a column of the row. This function is typically called in a loop until it returns `false`, indicating no more rows exist.

If `statement` corresponds to a PL/SQL block returning Oracle Database Implicit Result Sets, then rows from all sets are consecutively fetched. If `statement` is returned by oci_get_implicit_resultset(), then only the subset of rows for one child query are returned.

要获取 OCI8 扩展进行数据类型映射的细节，请参见驱动所支持的数据类型。

### 参数

`statement`
  有效的 OCI8 报表标识符 由 oci_parse() 创建，被 oci_execute() 或 `REF CURSOR` statement 标识执行。

  Can also be a statement identifier returned by oci_get_implicit_resultset().

`mode`

  An optional second parameter can be any combination of the following constants:

  oci_fetch_array() Modes
  Constant | Description
  --- | ---
  `OCI_BOTH` | Returns an array with both associative and numeric indices. This is the same as `OCI_ASSOC` + `OCI_NUM` and is the default behavior.
  `OCI_ASSOC` | Returns an associative array.
  `OCI_NUM` | Returns a numeric array.
  `OCI_RETURN_NULLS` | Creates elements for `null` fields. The element values will be a PHP `null`.
  `OCI_RETURN_LOBS` | Returns the contents of LOBs instead of the LOB descriptors.

  The default `mode` is `OCI_BOTH`.

  Use the addition operator "+" to specify more than one mode at a time.

### 返回值

Returns an array with associative and/or numeric indices. If there are no more rows in the `statement` then `false` is returned.

By default, `LOB` columns are returned as LOB descriptors.

`DATE` columns are returned as strings formatted to the current date format. The default format can be changed with Oracle environment variables such as `NLS_LANG` or by a previously executed `ALTER SESSION SET NLS_DATE_FORMAT` command.

Oracle's default, non-case sensitive column names will have uppercase associative indices in the result array. Case-sensitive column names will have array indices using the exact column case. Use var_dump() on the result array to verify the appropriate case to use for each query.

The table name is not included in the array index. If your query contains two different columns with the same name, use `OCI_NUM` or add a column alias to the query to ensure name uniqueness, see example #7. Otherwise only one column will be returned via PHP.

### 示例

示例 #1 oci_fetch_array() with `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) {
        // Use the uppercase column names for the associative array indices
        echo $row[0] . " and " . $row['DEPARTMENT_ID']   . " are the same<br>\n";
        echo $row[1] . " and " . $row['DEPARTMENT_NAME'] . " are the same<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

示例 #2 oci_fetch_array() with `OCI_NUM`

    <?php

    /*
      Before running, create the table:
          CREATE TABLE mytab (id NUMBER, description CLOB);
          INSERT INTO mytab (id, description) values (1, 'A very long string');
          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(11) . "<br>\n"; // this will output first 11 bytes from DESCRIPTION
    }

    // Output is:
    //    1
    //    A very long

    oci_free_statement($stid);
    oci_close($conn);

    ?>

示例 #3 oci_fetch_array() with `OCI_ASSOC`

    <?php

    /*
      Before running, create the table:
          CREATE TABLE mytab (id NUMBER, description CLOB);
          INSERT INTO mytab (id, description) values (1, 'A very long string');
          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(11) . "<br>\n"; // this will output first 11 bytes from DESCRIPTION
    }

    // Output is:
    //    1
    //    A very long

    oci_free_statement($stid);
    oci_close($conn);

    ?>

示例 #4 oci_fetch_array() with `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) { // Ignore NULLs
        var_dump($row);
    }

    /*
    The above code prints:
      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) { // Fetch NULLs
        var_dump($row);
    }

    /*
    The above code prints:
      array(2) {
        [1]=>
        string(1) "1"
        ["NULL"]=>
        NULL
      }
    */

    ?>

示例 #5 oci_fetch_array() with `OCI_RETURN_LOBS`

    <?php

    /*
      Before running, create the table:
          CREATE TABLE mytab (id NUMBER, description CLOB);
          INSERT INTO mytab (id, description) values (1, 'A very long string');
          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"; // this contains all of DESCRIPTION
        // In a loop, freeing the large variable before the 2nd fetch reduces PHP's peak memory usage
        unset($row);
    }

    // Output is:
    //    1
    //    A very long string

    oci_free_statement($stid);
    oci_close($conn);

    ?>

示例 #6 oci_fetch_array() with case sensitive column names

    <?php

    /*
       Before running, create the table:
          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);

    // Because 'Name' was created as a case-sensitive column, that same
    // case is used for the array index.  However uppercase 'CITY' must
    // be used for the case-insensitive column index
    print $row['Name'] . "<br>\n";   //  prints Chris
    print $row['CITY'] . "<br>\n";   //  prints Melbourne

    oci_free_statement($stid);
    oci_close($conn);

    ?>

示例 #7 oci_fetch_array() with columns having duplicate names

    <?php

    /*
      Before running, create the tables:
          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, 'Australia');
          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);

    // Output only contains one "NAME" entry:
    //    array(1) {
    //      ["NAME"]=>
    //      string(9) "Australia"
    //    }

    // To query a repeated column name, use an SQL column alias like "AS ctnm":
    $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);

    // Output now contains both columns selected:
    //    array(2) {
    //      ["CTNM"]=>
    //      string(9) "Melbourne"
    //      ["NAME"]=>
    //      string(9) "Australia"
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

示例 #8 oci_fetch_array() with `DATE` columns

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Set the date format for this connection.
    // For performance reasons, consider changing the format
    // in a trigger or with environment variables instead
    $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";  // prints 1997-06-14

    oci_free_statement($stid);
    oci_close($conn);

    ?>

示例 #9 oci_fetch_array() with `REF CURSOR`

    <?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');
    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);

    // Execute the returned REF CURSOR and fetch from it like a statement identifier
    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);

    ?>

示例 #10 Pagination with oci_fetch_array() using a `LIMIT`-like query

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Find the version of the database
    preg_match('/Release ([0-9]+)\./', oci_server_version($conn), $matches);
    $oracleversion = $matches[1];

    // This is the query you want to "page" through
    $sql = 'SELECT city, postal_code FROM locations ORDER BY city';

    if ($oracleversion >= 12) {
        // Make use of Oracle 12c OFFSET / FETCH NEXT syntax
        $sql = $sql . ' OFFSET :offset ROWS FETCH NEXT :numrows ROWS ONLY';
    } else {
        // Older Oracle versions need a nested query selecting a subset
        // from $sql.  Or, if the SQL statement is known at development
        // time, consider using a row_number() function instead of this
        // nested solution.  In production environments, be careful to
        // avoid SQL Injection issues with concatenation.
        $sql = "SELECT * FROM (SELECT a.*, ROWNUM AS my_rnum
                               FROM ($sql) a
                               WHERE ROWNUM <= :offset + :numrows)
                WHERE my_rnum > :offset";
    }

    $offset  = 0;  // skip this many rows
    $numrows = 5;  // return 5 rows
    $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";
    }

    // Output is:
    //    Beijing 190518
    //    Bern 3095
    //    Bombay 490231
    //    Geneva 1730
    //    Hiroshima 6823

    oci_free_statement($stid);
    oci_close($conn);

    ?>

示例 #11 oci_fetch_array() with Oracle Database Implicit Result Sets

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Requires OCI8 2.0 (or later) and Oracle Database 12c (or later)
    // Also see 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);

    // 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);

    ?>

### 注释

> 注意:

> Associative array indices need to be in uppercase for standard Oracle columns that were created with case insensitive names.

> 注意: 查询返回巨大数量的数据行时，通过增大 oci8.default_prefetch 值或使用 oci_set_prefetch() 可显著提高性能。

> 注意:

> The function oci_fetch_array() is insignificantly slower than oci_fetch_assoc() or oci_fetch_row(), but is more flexible.

### 参见

- oci_fetch() - 从查询中读取下一行到内部缓冲区
- oci_fetch_all() - 从查询中读取多行到二维数组中
- oci_fetch_assoc() - Returns the next row from a query as an associative array
- oci_fetch_object() - Returns the next row from a query as an object
- oci_fetch_row() - Returns the next row from a query as a numeric array
- oci_set_prefetch() - 设置查询预读取的行数

# oci_fetch_assoc

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_assoc — Returns the next row from a query as an associative array

### 说明

function oci_fetch_assoc(resource `$statement`): array|false

Returns an associative array containing the next result-set row of a query. Each array entry corresponds to a column of the row. This function is typically called in a loop until it returns `false`, indicating no more rows exist.

Calling oci_fetch_assoc() is identical to calling oci_fetch_array() with `OCI_ASSOC` + `OCI_RETURN_NULLS`.

### 参数

`statement`
  有效的 OCI8 报表标识符 由 oci_parse() 创建，被 oci_execute() 或 `REF CURSOR` statement 标识执行。

### 返回值

Returns an associative array. If there are no more rows in the `statement` then `false` is returned.

### 示例

示例 #1 oci_fetch_assoc() Example

    <?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);

    ?>

### 注释

> 注意:

> See oci_fetch_array() for more examples of fetching rows.

### 参见

- oci_fetch() - 从查询中读取下一行到内部缓冲区
- oci_fetch_all() - 从查询中读取多行到二维数组中
- oci_fetch_array() - Returns the next row from a query as an associative or numeric array
- oci_fetch_object() - Returns the next row from a query as an object
- oci_fetch_row() - Returns the next row from a query as a numeric array

# oci_fetch_object

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_object — Returns the next row from a query as an object

### 说明

function oci_fetch_object(resource `$statement`, int `$mode` = OCI_ASSOC | OCI_RETURN_NULLS): stdClass|false

Returns an object containing the next result-set row of a query. Each attribute of the object corresponds to a column of the row. This function is typically called in a loop until it returns `false`, indicating no more rows exist.

要获取 OCI8 扩展进行数据类型映射的细节，请参见驱动所支持的数据类型。

### 参数

`statement`
  有效的 OCI8 报表标识符 由 oci_parse() 创建，被 oci_execute() 或 `REF CURSOR` statement 标识执行。

### 返回值

Returns an object. Each attribute of the object corresponds to a column of the row. If there are no more rows in the `statement` then `false` is returned.

Any `LOB` columns are returned as LOB descriptors.

`DATE` columns are returned as strings formatted to the current date format. The default format can be changed with Oracle environment variables such as `NLS_LANG` or by a previously executed `ALTER SESSION SET NLS_DATE_FORMAT` command.

Oracle's default, non-case sensitive column names will have uppercase attribute names. Case-sensitive column names will have attribute names using the exact column case. Use var_dump() on the result object to verify the appropriate case for attribute access.

Attribute values will be `null` for any `NULL` data fields.

### 示例

示例 #1 oci_fetch_object() example

    <?php

    /*
      Before running, create the table:
        CREATE TABLE mytab (id NUMBER, description VARCHAR2(30));
        INSERT INTO mytab (id, description) values (1, 'Fish and Chips');
        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) {
        // Use upper case attribute names for each standard Oracle column
        echo $row->ID . "<br>\n";
        echo $row->DESCRIPTION . "<br>\n";
    }

    // Output is:
    //    1
    //    Fish and Chips

    oci_free_statement($stid);
    oci_close($conn);

    ?>

示例 #2 oci_fetch_object() 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 id, "MyDescription" FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_object($stid)) != false) {
        // Use upper case attribute names for each standard Oracle column
        echo $row->ID . "<br>\n";
        // Use the exact case for the case sensitive column name
        echo $row->MyDescription . "<br>\n";
    }

    // Output is:
    //    1
    //    Iced Coffee

    oci_free_statement($stid);
    oci_close($conn);

    ?>

示例 #3 oci_fetch_object() with LOBs

    <?php

    /*
      Before running, create the table:
        CREATE TABLE mytab (id NUMBER, description CLOB);
        INSERT INTO mytab (id, description) values (1, 'A very long string');
        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";
        // The following will output the first 11 bytes from DESCRIPTION
        echo $row->DESCRIPTION->read(11) . "<br>\n";
    }

    // Output is:
    //    1
    //    A very long

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### 参见

- oci_fetch() - 从查询中读取下一行到内部缓冲区
- oci_fetch_all() - 从查询中读取多行到二维数组中
- oci_fetch_assoc() - Returns the next row from a query as an associative array
- oci_fetch_array() - Returns the next row from a query as an associative or numeric array
- oci_fetch_row() - Returns the next row from a query as a numeric array

# oci_fetch_row

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_row — Returns the next row from a query as a numeric array

### 说明

function oci_fetch_row(resource `$statement`): array|false

Returns a numerically indexed array containing the next result-set row of a query. Each array entry corresponds to a column of the row. This function is typically called in a loop until it returns `false`, indicating no more rows exist.

Calling oci_fetch_row() is identical to calling oci_fetch_array() with `OCI_NUM` + `OCI_RETURN_NULLS`.

### 参数

`statement`
  有效的 OCI8 报表标识符 由 oci_parse() 创建，被 oci_execute() 或 `REF CURSOR` statement 标识执行。

### 返回值

Returns a numerically indexed array. If there are no more rows in the `statement` then `false` is returned.

### 示例

示例 #1 oci_fetch_row() Example

    <?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);

    ?>

### 注释

> 注意:

> See oci_fetch_array() for more examples of fetching rows.

### 参见

- oci_fetch() - 从查询中读取下一行到内部缓冲区
- oci_fetch_all() - 从查询中读取多行到二维数组中
- oci_fetch_array() - Returns the next row from a query as an associative or numeric array
- oci_fetch_assoc() - Returns the next row from a query as an associative array
- oci_fetch_object() - Returns the next row from a query as an object

# oci_field_is_null

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_is_null — 检测当前获取的行中，字段是否为 `null`

### 说明

function oci_field_is_null(resource `$statement`, string|int `$column`): bool

检测 `statement` 的当前行中的指定 `column` 是否为 `null`。

### 参数

`statement`

  有效的 OCI 语句标识符。

`column`

  字段索引（从 1 开始）或者名称。

### 返回值

如果 `column` 是 `null`，返回 `true`，否则返回 `false`。

### 示例

示例 #1 oci_field_name() 示例

    <?php

    // 创建表：
    //   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));
        }
    }

    // 输出：
    //    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 — 返回 statement 中的字段名

### 说明

function oci_field_name(resource `$statement`, string|int `$column`): string|false

返回 `column` 的名称。

### 参数

`statement`

  有效的 OCI 语句标识符。

`column`

  字段索引（从 1 开始）或者名称。

### 返回值

返回字符串形式的名称， 或者在失败时返回 `false`

### 示例

示例 #1 oci_field_name() 示例

    <?php

    // 创建表：
    //   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";

    // 输出：
    //    Name           Type
    //    NUMBER_COL    NUMBER
    //    VARCHAR2_COL  VARCHAR2
    //    CLOB_COL      CLOB
    //    DATE_COL      DATE

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### 参见

- oci_num_fields() - 返回语句中结果列的数量
- oci_field_type() - 返回字段的数据类型名称
- oci_field_size() - 返回字段大小

# oci_field_precision

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_precision — 返回字段精度

### 说明

function oci_field_precision(resource `$statement`, string|int `$column`): int|false

返回 `column` 的精度。

对于 FLOAT 字段，精度不为零且小数位数为 -127。如果精度为 0，则字段为 NUMBER。其它类型为 NUMBER(precision, scale)。

### 参数

`statement`

  有效的 OCI 语句标识符。

`column`

  字段索引（从 1 开始）或者名称。

### 返回值

返回整数形式的精度， 或者在失败时返回 `false`

### 示例

示例 #1 oci_field_precision() 示例

    <?php

    // 创建表：
    //   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";
    }

    // 输出：
    //   C1    0 -127
    //   C2  126 -127
    //   C3    4    0
    //   C4    5    3

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### 参见

- oci_field_scale() - 返回字段范围
- oci_field_type() - 返回字段的数据类型名称

# oci_field_scale

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_scale — 返回字段范围

### 说明

function oci_field_scale(resource `$statement`, string|int `$column`): int|false

返回 `column` 列索引的范围。

对于 FLOAT 列，精度为非零且范围为 -127。如果精度为 0，则列为 NUMBER。否则为 NUMBER(precision, scale)。

### 参数

`statement`

  有效的 OCI 语句标识符。

`column`

  可以是字段的索引（从1开始），也可以是名称。

### 返回值

返回 int 类型的范围， 或者在失败时返回 `false`

### 示例

示例 #1 oci_field_scale() 示例

    <?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);

    ?>

### 参见

- oci_field_precision() - 返回字段精度
- oci_field_type() - 返回字段的数据类型名称

# oci_field_size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_size — 返回字段大小

### 说明

function oci_field_size(resource `$statement`, string|int `$column`): int|false

返回 `column` 的大小。

### 参数

`statement`

  有效的 OCI 语句标识符。

`column`

  可以是字段的索引（从1开始），也可以是名称。

### 返回值

以字节为单位返回 `column` 的大小， 或者在失败时返回 `false`

### 示例

示例 #1 oci_field_size() 示例

    <?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);

    ?>

### 参见

- oci_num_fields() - 返回语句中结果列的数量
- oci_field_name() - 返回 statement 中的字段名

# oci_field_type

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_type — 返回字段的数据类型名称

### 说明

function oci_field_type(resource `$statement`, string|int `$column`): string|int|false

返回字段的数据类型名称。

### 参数

`statement`

  有效的 OCI 语句标识符。

`column`

  可以是字段的索引（从1开始），也可以是名称。

### 返回值

返回 string 或 int 类型的字段数据类型， 或者在失败时返回 `false`

### 示例

示例 #1 oci_field_type() 示例

    <?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);

    ?>

### 参见

- oci_num_fields() - 返回语句中结果列的数量
- oci_field_name() - 返回 statement 中的字段名
- oci_field_size() - 返回字段大小

# oci_field_type_raw

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_type_raw — 返回字段的原始 Oracle 数据类型

### 说明

function oci_field_type_raw(resource `$statement`, string|int `$column`): int|false

返回 `column` 的 Oracle 原始“SQLT”数据类型。

如果想要字段的类型名称，然后使用 oci_field_type() 代替。

### 参数

`statement`

  有效的 OCI 语句标识符。

`column`

  可以是字段的索引（从1开始），也可以是名称。

### 返回值

返回数字类型的 Oracle 的原始数据类型， 或者在失败时返回 `false`

### 示例

示例 #1 oci_field_type_raw() 示例

    <?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

### 说明

function oci_free_descriptor(OCILob `$lob`): bool

Frees a descriptor allocated by oci_new_descriptor().

### 参数

`lob`

  Descriptor allocated by oci_new_descriptor().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 注释

> 注意:

> This function is commonly used as a method OCILOB::free.

### 参见

- OCILOB::free

# oci_free_statement

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_free_statement — 释放关联于语句或游标的所有资源

### 说明

function oci_free_statement(resource `$statement`): bool

oci_free_statement() 释放关联于 Oracle 游标或语句的资源，该资源是作为 oci_parse() 的结果或者是从 Oracle 取得。

### 参数

`statement`

  有效的 OCI 语句。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# 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

### 说明

function oci_get_implicit_resultset(resource `$statement`): resource|false

Used to fetch consectutive 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().

### 参数

`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.

### 返回值

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().

### 示例

示例 #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);

    ?>

示例 #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);

    ?>

示例 #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);

    ?>

示例 #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);

    ?>

### 注释

> 注意: 查询返回巨大数量的数据行时，通过增大 oci8.default_prefetch 值或使用 oci_set_prefetch() 可显著提高性能。

# oci_lob_copy

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_lob_copy — Copies large object

### 说明

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.

### 参数

`to`

  The destination LOB.

`from`

  The copied LOB.

`length`

  Indicates the length of data to be copied.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | `length` is now nullable.

### 注释

> 注意:

> 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

### 说明

function oci_lob_is_equal(OCILob `$lob1`, OCILob `$lob2`): bool

Compares two LOB/FILE locators.

### 参数

`lob1`

  A LOB identifier.

`lob2`

  A LOB identifier.

### 返回值

Returns `true` if these objects are equal, `false` otherwise.

### 注释

> 注意:

> 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 — 分配新的 collection 对象

### 说明

function oci_new_collection(resource `$connection`, string `$type_name`, ?string `$schema` = `null`): OCICollection|false

分配新的 collection 对象。

### 参数

`connection`

  Oracle 连接标识符，由 oci_connect() 或 oci_pconnect() 返回。

`type_name`

  应该是有效的命名类型（大写）。

`schema`

  应该指向创建命名类型的 scheme 。当传递 `null` 时，使用当前用户名。

### 返回值

返回新 OCICollection 对象，或者当失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0、PECL OCI8 3.0.0 | `schema` 现在可为 null。

### 注释

> 注意:

> OCICollection 类在 PHP 8 和 OCI8 3.0.0 之前叫做 OCI-Collection。

# oci_new_connect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_connect — 使用唯一连接，连接到 Oracle 服务器

### 说明

function oci_new_connect(
string `$username`,
string `$password`,
?string `$connection_string` = `null`,
string `$encoding` = "",
int `$session_mode` = `OCI_DEFAULT`
): resource|false

建立与 Oracle 服务器的新连接并登录。

与 oci_connect() 和 oci_pconnect() 不同，oci_new_connect() 不缓存连接并且始终返回全新的刚打开的连接句柄。如果应用程序需要在两组查询之间进行事务隔离，这将很有用。

### 参数

`username`

  Oracle 用户名。

`password`

  `username` 的密码。

`connection_string`
  包含要连接的 `Oracle 实例`。可以是 » Easy Connect 串，或是 tnsnames.ora 文件中的连接名，或是本地 Oracle 实例名。 如果不指定或者为 `null`，PHP 使用环境变量来确定连接的 `Oracle 实例`，诸如 `TWO_TASK`（Linux 下）或 `LOCAL`（Windows 下）与 `ORACLE_SID` 等。 要使用 Easy Connect 命名方法，PHP 必须与 Oracle 10g 或更高版本的客户端库进行链接。Oracle 10g 的 Easy Connect 串格式：[//]host_name[:port][/service_name]。Oracle 11g 则为：[//]host_name[:port][/service_name][:server_type][/instance_name]。 在 Oracle 19c 加入类更多选项，例如 timeout 和 keep-alive 设置。 请参考 Oracle 文档。 服务名可在数据库服务器机器上运行 Oracle 实用程序 `lsnrctl status` 找到。 tnsnames.ora 文件可在 Oracle Net 查找路径中，此路径包括 /your/path/to/instantclient/network/admin、$ORACLE_HOME/network/admin 、/etc。 另一种方法是设置 `TNS_ADMIN` 以便通过 $TNS_ADMIN/tnsnames.ora 来读取。表确认 web 守护进程可读取此文件。
`encoding`
  使用 Oracle 客户端库来确定字符集。字符集不需要与数据库的字符集相匹配。如果不匹配，Oracle 会尽可能地将数据从数据库字符集进行转换。因为依赖于字符集，可能不能给出可用的结果。转换也增加一些时间开销。 如果不指定，Oracle 客户端用 `NLS_LANG` 环境变量来决定字符集。 传递此参数可减少连接时间。
`session_mode`
  此参数在 PHP 5（PECL OCI8 1.1）版本开始可用，并收受下列值：`OCI_DEFAULT`，`OCI_SYSOPER` 和 `OCI_SYSDBA`。如为 `OCI_SYSOPER` 或 `OCI_SYSDBA` 其中之一，此函数将会使用外部的证书建立有特权的连接。有特权的连接默认是禁用的。需要将 oci8.privileged_connect 设为 `On` 来启用。 PHP 5.3（PECL OCI8 1.3.4）引进了 `OCI_CRED_EXT` 模式值。使用外部或操作系统认证必需在 Oracle 数据库中进行配置。`OCI_CRED_EXT` 标志只可用于用户为 "/"，密码为空的情况。oci8.privileged_connect 可为 `On` 或 `Off`。 `OCI_CRED_EXT` 可与 `OCI_SYSOPER` 或 `OCI_SYSDBA` 模式组合使用。 `OCI_CRED_EXT` 由于安全的原因不支持 Windows 系统。

### 返回值

返回连接标识符或错误时为 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0、PECL OCI8 3.0.0 | `connection_string` 现在可为 null。

### 示例

下面演示了如何分离连接。

示例 #1 oci_new_connect() 示例

    <?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

    ?>

有关参数使用的更多示例，请参见 oci_connect()。

### 参见

- oci_connect() - 建立一个到 Oracle 服务器的连接
- oci_pconnect() - 使用持久连接连，连接到 Oracle 数据库

# oci_new_cursor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_cursor — 分配并返回新的游标（语句句柄）

### 说明

function oci_new_cursor(resource `$connection`): resource|false

在指定连接上分配新的语句句柄。

### 参数

`connection`

  Oracle 连接标识符，由 oci_connect() 或 oci_pconnect() 返回。

### 返回值

返回新的语句句柄，或者失败时返回 `false`。

### 示例

示例 #1 在调用 Oracle 存储过程中绑定 REF CURSOR

    <?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 — 初始化新的空 LOB 或 FILE 描述符

### 说明

function oci_new_descriptor(resource `$connection`, int `$type` = `OCI_DTYPE_LOB`): ?OCILob

分配保存描述符或 LOB 定位器的资源。

### 参数

`connection`

  Oracle 连接标识符，由 oci_connect() 或 oci_pconnect() 返回。

`type`

  `type` 的有效值是：`OCI_DTYPE_FILE`、`OCI_DTYPE_LOB` 和 `OCI_DTYPE_ROWID`。

### 返回值

成功时返回新 LOB 或 FILE 描述符，失败时为 `null`。

### 示例

示例 #1 oci_new_descriptor() 示例

    <?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);
      }
    ?>

示例 #2 oci_new_descriptor() 示例

    <?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);
    ?>

### 参见

- oci_bind_by_name() - 绑定 PHP 变量到 Oracle 位置标志符

# oci_num_fields

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_num_fields — 返回语句中结果列的数量

### 说明

function oci_num_fields(resource `$statement`): int

获取 `statement` 中的列的数量。

### 参数

`statement`

  有效的 OCI 语句标识符。

### 返回值

返回 int 类型的列的数量。

### 示例

示例 #1 oci_num_fields() 示例

    <?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 — 返回语句执行后受影响的行数

### 说明

function oci_num_rows(resource `$statement`): int|false

获取语句执行后受影响的行数。

### 参数

`statement`

  有效的 OCI 语句标识符。

### 返回值

返回 int 类型的受影响的行数， 或者在失败时返回 `false`。

### 示例

示例 #1 oci_num_rows() 示例

    <?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);

    ?>

### 注释

> 注意:

> 本函数并不返回 SELECT 查询出来的行数！对于 SELECT 语句本函数将返回用 oci_fetch*() 函数从缓冲区获取的行数。

# oci_parse

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_parse — 预处理用于执行的 Oracle 语句

### 说明

function oci_parse(resource `$connection`, string `$sql`): resource|false

使用 `connection` 预处理 `sql` 并返回语句标识符，语句标识符可跟 oci_bind_by_name()、oci_execute() 和其它函数一起使用。

语句标识符可使用 oci_free_statement() 或将变量设置为 `null` 来释放。

### 参数

`connection`

  Oracle 连接标识符，由 oci_connect()、oci_pconnect() 或 oci_new_connect() 返回。

`sql`

  SQL 或 PL/SQL 语句。

  SQL 语句不应以分号（";"）结尾。PL/SQL 语句应以分号（";"）结尾。

### 返回值

成功时返回语句句柄，错误时为 `false`。

### 示例

示例 #1 oci_parse() 的 SQL 语句示例

    <?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";

    ?>

示例 #2 oci_parse() 的 PL/SQL 语句示例

    <?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);

    ?>

### 注释

> 注意:

> 本函数并不验证 `sql`。要知道 `sql` 是否是合法的 SQL 或 PL/SQL 语句的唯一方法是执行它。

### 参见

- oci_execute() - 执行语句
- oci_free_statement() - 释放关联于语句或游标的所有资源

# oci_password_change

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_password_change — 修改 Oracle 用户的密码

### 说明

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

修改用户 `username` 的密码。

oci_password_change() 函数对于 PHP 命令行脚本或在整个 PHP 应用程序中使用非持久连接时最有用。

### 参数

`connection`

  Oracle 连接标识符，由 oci_connect() 或 oci_pconnect() 返回。

`username`

  Oracle 用户名。

`old_password`

  旧密码。

`new_password`

  要设置的新密码。

`database_name`

  数据库名。

### 返回值

提供 `database_name` 时，oci_password_change() 成功时返回 `true`， 或者在失败时返回 `false`。提供 `connection` 时，oci_password_change() 成功时返回连接资源， 或者在失败时返回 `false`。

### 示例

示例 #1 oci_password_change() 示例，更改已连接用户的密码

    <?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";

    ?>

示例 #2 oci_password_change() 示例之一步更改密码并连接

    <?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
    // ...

    ?>

### 注释

> 注意:

> 使用此函数或直接在 Oracle 中更改密码应该小心。这是因为 PHP 应用程序可能会通过使用旧密码进行身份验证来继续成功地重用持久连接。最佳做法是每当更改用户密码时重新启动所有 Web 服务器。

> 注意:

> 如果将 Oracle 客户端库或数据库从 11.2.0.3 之前的版本升级到 11.2.0.3 或更高版本，oci_password_change() 可能会给出错误“ORA-1017: invalid username/password”，除非同时升级客户端和服务器版本。

> 注意:

> 第二个 oci_password_change() 语法自 OCI8 版本 1.1 起可用。

# oci_pconnect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_pconnect — 使用持久连接连，连接到 Oracle 数据库

### 说明

function oci_pconnect(
string `$username`,
string `$password`,
?string `$connection_string` = `null`,
string `$encoding` = "",
int `$session_mode` = `OCI_DEFAULT`
): resource|false

创建到 Oracle 服务器的持久连接并登录。

持久连接会被缓冲并在请求之间重复使用，可以降低每个页面加载的消耗；一个典型的 PHP 应用程序对于每个 Apache 子进程（或者 PHP FastCGI 进程）会有打开的持久连接到 Oracle 服务器。更多信息见连接处理和连接池一节。

### 参数

`username`

  Oracle 用户名。

`password`

  `username` 的密码。

`connection_string`
  包含要连接的 `Oracle 实例`。可以是 » Easy Connect 串，或是 tnsnames.ora 文件中的连接名，或是本地 Oracle 实例名。 如果不指定或者为 `null`，PHP 使用环境变量来确定连接的 `Oracle 实例`，诸如 `TWO_TASK`（Linux 下）或 `LOCAL`（Windows 下）与 `ORACLE_SID` 等。 要使用 Easy Connect 命名方法，PHP 必须与 Oracle 10g 或更高版本的客户端库进行链接。Oracle 10g 的 Easy Connect 串格式：[//]host_name[:port][/service_name]。Oracle 11g 则为：[//]host_name[:port][/service_name][:server_type][/instance_name]。 在 Oracle 19c 加入类更多选项，例如 timeout 和 keep-alive 设置。 请参考 Oracle 文档。 服务名可在数据库服务器机器上运行 Oracle 实用程序 `lsnrctl status` 找到。 tnsnames.ora 文件可在 Oracle Net 查找路径中，此路径包括 /your/path/to/instantclient/network/admin、$ORACLE_HOME/network/admin 、/etc。 另一种方法是设置 `TNS_ADMIN` 以便通过 $TNS_ADMIN/tnsnames.ora 来读取。表确认 web 守护进程可读取此文件。
`encoding`
  使用 Oracle 客户端库来确定字符集。字符集不需要与数据库的字符集相匹配。如果不匹配，Oracle 会尽可能地将数据从数据库字符集进行转换。因为依赖于字符集，可能不能给出可用的结果。转换也增加一些时间开销。 如果不指定，Oracle 客户端用 `NLS_LANG` 环境变量来决定字符集。 传递此参数可减少连接时间。
`session_mode`
  此参数在 PHP 5（PECL OCI8 1.1）版本开始可用，并收受下列值：`OCI_DEFAULT`，`OCI_SYSOPER` 和 `OCI_SYSDBA`。如为 `OCI_SYSOPER` 或 `OCI_SYSDBA` 其中之一，此函数将会使用外部的证书建立有特权的连接。有特权的连接默认是禁用的。需要将 oci8.privileged_connect 设为 `On` 来启用。 PHP 5.3（PECL OCI8 1.3.4）引进了 `OCI_CRED_EXT` 模式值。使用外部或操作系统认证必需在 Oracle 数据库中进行配置。`OCI_CRED_EXT` 标志只可用于用户为 "/"，密码为空的情况。oci8.privileged_connect 可为 `On` 或 `Off`。 `OCI_CRED_EXT` 可与 `OCI_SYSOPER` 或 `OCI_SYSDBA` 模式组合使用。 `OCI_CRED_EXT` 由于安全的原因不支持 Windows 系统。

### 返回值

返回连接标识符或错误时为 `false`。

### 示例

示例 #1 基础 oci_pconnect() 示例，使用 Easy Connect 语法

    <?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";

    ?>

有关参数使用的更多示例，请参见 oci_connect()。

### 注释

> 注意: 每个 PHP 进程的持久 Oracle 连接的生命周期和最大数目可以通过以下配置选项来调整：oci8.persistent_timeout，oci8.ping_interval 和 oci8.max_persistent。

### 参见

- oci_connect() - 建立一个到 Oracle 服务器的连接
- oci_new_connect() - 使用唯一连接，连接到 Oracle 服务器

# 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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 — 返回所取得行中字段的值

### 说明

function oci_result(resource `$statement`, string|int `$column`): mixed

返回由 oci_fetch() 所读取的当前行中 `column` 的数据。

要获取 OCI8 扩展进行数据类型映射的细节，请参见驱动所支持的数据类型。

### 参数

`statement`

`column`

  可以使用列号（从 1 开始）或列名。列名的大小写必须是 Oracle 元数据描述该列的大小写，对于创建的不区分大小写的列来说是大写。

### 返回值

以字符串形式返回除抽象类型（ROWID、LOB 和 FILE）之外的所有内容。在出错时返回 `false`。

### 示例

示例 #1 oci_fetch() 和 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);

    ?>

### 参见

- oci_fetch_array() - Returns the next row from a query as an associative or numeric array
- oci_fetch_assoc() - Returns the next row from a query as an associative array
- oci_fetch_object() - Returns the next row from a query as an object
- oci_fetch_row() - Returns the next row from a query as a numeric array
- oci_fetch_all() - 从查询中读取多行到二维数组中

# oci_rollback

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_rollback — 回滚未完成的事务

### 说明

function oci_rollback(resource `$connection`): bool

恢复 Oracle `connection` 的所有未提交更改并结束事务。释放所有持有的锁。所有 Oracle `SAVEPOINTS` 都被擦除。

当使用 `OCI_NO_AUTO_COMMIT` flag 通过 oci_execute() 执行第一个更改数据的 SQL 语句时，事务开始。其他语句所做的后续数据更改成为同一事务的一部分。在事务提交或回滚之前，事务中所做的数据更改是临时的。在提交之前，数据库的其他用户将看不到更改。

插入或更新数据时，出于关系数据一致性和性能原因，建议使用事务。

### 参数

`connection`

  oci_connect()、oci_pconnect() 或 oci_new_connect() 返回的 Oracle 连接标识符。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 oci_rollback() 示例

    <?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);
    }

    ?>

示例 #2 回滚到 `SAVEPOINT` 示例

    <?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
    ?>

### 注释

> 注意:

> 当关闭连接或脚本结束时，事务会自动回滚。需要显式调用 oci_commit() 提交事务。

> Any call to oci_execute() that uses `OCI_COMMIT_ON_SUCCESS` mode explicitly or by default will commit any previous uncommitted transaction.

> 任何 Oracle DDL 语句（例如 `CREATE` 或 `DROP`）都会自动提交任何未提交的事务。

### 参见

- oci_commit() - 提交未完成的数据库事务
- oci_execute() - 执行语句

# oci_server_version

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_server_version — 返回 Oracle 数据库版本

### 说明

function oci_server_version(resource `$connection`): string|false

以字符串返回 Oracle 数据库版本和可用选项。

### 参数

`connection`

### 返回值

以字符串返回版本信息，错误时为 `false`。

### 示例

示例 #1 oci_server_version() 示例

    <?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);

    ?>

### 参见

- 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

### 说明

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.

### 参数

`connection`
  Oracle 连接标识，由 oci_connect()，oci_pconnect()，或 oci_new_connect() 返回。
`action`

  User chosen string up to 32 bytes long.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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;

### 注释

> 注意: Oracle 版本需求
> 当 PHP 是与 Oracle 数据库 10g 及更新版本的 扩展库链接时，此函数可用。

小技巧

# 性能

使用旧版的 OCI8 或 ORACLE 数据库，可使用 Oracle `DBMS_APPLICATION_INFO` 包来设置客户端信息。这比使用 oci_set_client_info() 较低效。

警告

# Roundtrip Gotcha

一些 OCI8 函数会导致 Roundtrips. 对数据库来说当启用结果缓存时，查询可能不产生 Roundtrips。

### 参见

- 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

### 说明

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.

### 参数

`connection`
  Oracle 连接标识，由 oci_connect()，oci_pconnect()，或 oci_new_connect() 返回。
`timeout`

  The maximum time in milliseconds that any single round-trip between PHP and Oracle Database may take.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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

### 说明

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.

### 参数

`connection`
  Oracle 连接标识，由 oci_connect()，oci_pconnect()，或 oci_new_connect() 返回。
`client_id`

  User chosen string up to 64 bytes long.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);

    // ...

    ?>

### 注释

警告

# Roundtrip Gotcha

一些 OCI8 函数会导致 Roundtrips. 对数据库来说当启用结果缓存时，查询可能不产生 Roundtrips。

### 参见

- 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

### 说明

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.

### 参数

`connection`
  Oracle 连接标识，由 oci_connect()，oci_pconnect()，或 oci_new_connect() 返回。
`client_info`

  User chosen string up to 64 bytes long.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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;

### 注释

> 注意: Oracle 版本需求
> 当 PHP 是与 Oracle 数据库 10g 及更新版本的 扩展库链接时，此函数可用。

小技巧

# 性能

使用旧版的 OCI8 或 ORACLE 数据库，可使用 Oracle `DBMS_APPLICATION_INFO` 包来设置客户端信息。这比使用 oci_set_client_info() 较低效。

警告

# Roundtrip Gotcha

一些 OCI8 函数会导致 Roundtrips. 对数据库来说当启用结果缓存时，查询可能不产生 Roundtrips。

### 参见

- 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

### 说明

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).

### 参数

`connection`
  Oracle 连接标识，由 oci_connect()，oci_pconnect()，或 oci_new_connect() 返回。
`action`

  User chosen string.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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;

### 注释

警告

# Roundtrip Gotcha

一些 OCI8 函数会导致 Roundtrips. 对数据库来说当启用结果缓存时，查询可能不产生 Roundtrips。

### 参见

- 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

### 说明

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

### 参数

`edition`

  Oracle Database edition name previously created with the SQL "`CREATE EDITION`" command.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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";

    ?>

### 注释

> 注意: Oracle version requirement

> This function is available from Oracle 11gR2 onwards.

警告

# Persistent connections

To avoid inconsistencies and unexpected errors, do not use ALTER SESSION SET EDITION to change the edition on persistent connections.

警告

# 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

### 说明

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.

### 参数

`connection`
  Oracle 连接标识，由 oci_connect()，oci_pconnect()，或 oci_new_connect() 返回。
`name`

  User chosen string up to 48 bytes long.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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;

### 注释

> 注意: Oracle 版本需求
> 当 PHP 是与 Oracle 数据库 10g 及更新版本的 扩展库链接时，此函数可用。

小技巧

# 性能

使用旧版的 OCI8 或 ORACLE 数据库，可使用 Oracle `DBMS_APPLICATION_INFO` 包来设置客户端信息。这比使用 oci_set_client_info() 较低效。

警告

# Roundtrip Gotcha

一些 OCI8 函数会导致 Roundtrips. 对数据库来说当启用结果缓存时，查询可能不产生 Roundtrips。

### 参见

- 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 — 设置查询预读取的行数

### 说明

function oci_set_prefetch(resource `$statement`, int `$rows`): bool

在调用 oci_execute() 成功查询以及对数据库的每个后续内部读取请求之后，设置 Oracle 客户端库缓冲的行数。对于返回大量行的查询，可以通过在默认 oci8.default_prefetch 值上增加预读取数来显着提高性能。

预读取是 Oracle 在每个网络请求中从数据库返回多个数据行的有效方式。这可以提高网络和 CPU 利用率。行缓冲是 OCI8 的内部操作，无论预取数如何，OCI8 提取函数的行为都不会改变。例如，oci_fetch_row() 将始终返回一行。预读取缓冲区是针对单个语句的，不会被重新执行的语句或其他连接使用。

在调用 oci_execute() 之前调用 oci_set_prefetch()。

调整目标是将预读取值设置为网络和数据库要处理的合理大小。对于返回大量行的查询，如果以多个块的形式从数据库中检索行（即设置预读取值小于行数），则整体系统效率可能会更好。这允许数据库在 PHP 脚本处理行的当前集合的同时处理其他用户的语句。

Oracle 8i 中引入了查询预读取。REF CURSOR 预读取是在 Oracle 11gR2 中引入的，当 PHP 与 Oracle 11gR2（或更高版本）客户端库链接时发生。嵌套游标预读取是在 Oracle 11gR2 中引入的，它要求 Oracle Client 库和数据库都是 11gR2 或更高版本。

当查询包含 LONG 或 LOB 列时，不支持预读取。预读取值将会忽略，并且在不支持预读取的所有情况下都将使用单行获取。

使用 Oracle Database 12c 时，PHP 设置的预读取值可以被 Oracle 的客户端 `oraaccess.xml` 配置文件覆盖。有关详细信息，请参阅 Oracle 文档。

### 参数

`statement`
  有效的 OCI8 报表标识符 由 oci_parse() 创建，被 oci_execute() 或 `REF CURSOR` statement 标识执行。
`rows`

  要预读取的行数，>= 0

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 更改查询的默认预读取值

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT * FROM myverybigtable');
    oci_set_prefetch($stid, 300);  // 调用 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);

    ?>

示例 #2 更改 REF CURSOR 获取的默认预获取值

    <?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);

    ?>

如果 PHP OCI8 从 REF CURSOR 获取数据，然后将 REF CURSOR 传回给第二个 PL/SQL 过程进行进一步处理，则将 REF CURSOR 预读取值设置为 `0`，以避免结果集中的行被“丢失”。预读取值是每个 OCI8 内部请求到数据库中获取的额外行数，因此将其设置为 `0` 意味着每次只获取一行。

示例 #3 将 REF CURSOR 传回 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().
    // A prefetch value of 0 is allowed in PHP 5.3.2 and PECL OCI8 1.4
    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);

    ?>

### 参见

- oci8.default_prefetch ini 选项

# 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.

### 说明

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.

### 参数

`statement`
  有效的 OCI8 报表标识符 由 oci_parse() 创建，被 oci_execute() 或 `REF CURSOR` statement 标识执行。
`prefetch_lob_size`

  The number of bytes of each LOB to be prefetched, >= 0

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);

    ?>

### 参见

- oci8.prefetch_lob_size ini option

# oci_statement_type

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_statement_type — 返回语句的类型

### 说明

function oci_statement_type(resource `$statement`): string|false

返回关键字，标识 OCI8 `statement` 的类型。

### 参数

`statement`

  来自 oci_parse() 的有效 OCI8 语句标识符。

### 返回值

返回 `statement` 类型，可能为以下字符串之一。

语句类型
返回字符串 | 说明
--- | ---
`ALTER` |
`BEGIN` |
`CALL` |
`CREATE` |
`DECLARE` |
`DELETE` |
`DROP` |
`INSERT` |
`SELECT` |
`UPDATE` |
`UNKNOWN` |

错误时返回 `false`。

### 示例

示例 #1 oci_statement_type() 示例

    <?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

### 说明

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.

### 参数

`connection`

  An Oracle connection identifier.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- oci_register_taf_callback() - Register a user-defined callback function for Oracle Database TAF

## 目录

- oci_bind_array_by_name — Binds a PHP array to an Oracle PL/SQL array parameter
- oci_bind_by_name — 绑定 PHP 变量到 Oracle 位置标志符
- oci_cancel — 中断游标读取数据
- oci_client_version — Returns the Oracle client library version
- oci_close — 关闭 Oracle 连接
- oci_commit — 提交未完成的数据库事务
- oci_connect — 建立一个到 Oracle 服务器的连接
- oci_define_by_name — 将 PHP 变量与查询读取的列相关联
- oci_error — 返回最后发现的错误
- oci_execute — 执行语句
- oci_fetch — 从查询中读取下一行到内部缓冲区
- oci_fetch_all — 从查询中读取多行到二维数组中
- oci_fetch_array — Returns the next row from a query as an associative or numeric array
- oci_fetch_assoc — Returns the next row from a query as an associative array
- oci_fetch_object — Returns the next row from a query as an object
- oci_fetch_row — Returns the next row from a query as a numeric array
- oci_field_is_null — 检测当前获取的行中，字段是否为 null
- oci_field_name — 返回 statement 中的字段名
- oci_field_precision — 返回字段精度
- oci_field_scale — 返回字段范围
- oci_field_size — 返回字段大小
- oci_field_type — 返回字段的数据类型名称
- oci_field_type_raw — 返回字段的原始 Oracle 数据类型
- oci_free_descriptor — Frees a descriptor
- oci_free_statement — 释放关联于语句或游标的所有资源
- 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 — 分配新的 collection 对象
- oci_new_connect — 使用唯一连接，连接到 Oracle 服务器
- oci_new_cursor — 分配并返回新的游标（语句句柄）
- oci_new_descriptor — 初始化新的空 LOB 或 FILE 描述符
- oci_num_fields — 返回语句中结果列的数量
- oci_num_rows — 返回语句执行后受影响的行数
- oci_parse — 预处理用于执行的 Oracle 语句
- oci_password_change — 修改 Oracle 用户的密码
- oci_pconnect — 使用持久连接连，连接到 Oracle 数据库
- oci_register_taf_callback — Register a user-defined callback function for Oracle Database TAF
- oci_result — 返回所取得行中字段的值
- oci_rollback — 回滚未完成的事务
- oci_server_version — 返回 Oracle 数据库版本
- 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 — 设置查询预读取的行数
- oci_set_prefetch_lob — Sets the amount of data prefetched for each CLOB or BLOB.
- oci_statement_type — 返回语句的类型
- 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)

## 简介

OCI8 Collection functionality.

> 注意:

> The OCI-Collection class was renamed to OCICollection in PHP 8 OCI8 3.0.0 to align with PHP naming standards.

## 类摘要

class OCICollection {
/* 方法 */
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 — Appends element to the collection

### 说明

public function OCICollection::append(string `$value`): bool

Appends element to the end of the collection.

### 参数

`value`

  The value to be added to the collection.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Collection class was renamed to OCICollection to align with PHP naming standards.

### 参见

- OCICollection::assign

# OCICollection::assign

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::assign — Assigns a value to the collection from another existing collection

### 说明

public function OCICollection::assign(OCICollection `$from`): bool

Assigns a value to the collection from another, previously created collection. Both collections must be created with oci_new_collection() prior to using them.

### 参数

`from`

  An instance of OCICollection.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Collection class was renamed to OCICollection to align with PHP naming standards.

### 参见

- OCICollection::append

# OCICollection::assignElem

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::assignElem — Assigns a value to the element of the collection

### 说明

public function OCICollection::assignElem(int `$index`, string `$value`): bool

Assigns a value to the element with index `index`.

### 参数

`index`

  The element index. First index is 0.

`value`

  Can be a string or a number.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Collection class was renamed to OCICollection to align with PHP naming standards.

### 参见

- OCICollection::getElem

# OCICollection::free

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::free — Frees the resources associated with the collection object

### 说明

public function OCICollection::free(): bool

Frees the resources associated with the collection object.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Collection class was renamed to OCICollection to align with PHP naming standards.

### 参见

- oci_new_collection

# OCICollection::getElem

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::getElem — Returns value of the element

### 说明

public function OCICollection::getElem(int `$index`): string|float|null|false

Returns element's value with the index `index` (0-based).

### 参数

`index`

  The element index. First index is 0.

### 返回值

Returns `false` if such element doesn't exist; `null` if element is `null`; string if element is column of a string datatype or number if element is numeric field.

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Collection class was renamed to OCICollection to align with PHP naming standards.

### 参见

- OCICollection::assignElem

# OCICollection::max

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::max — Returns the maximum number of elements in the collection

### 说明

public function OCICollection::max(): int|false

Returns the maximum number of elements in the collection.

### 参数

此函数没有参数。

### 返回值

Returns the maximum number as an integer, or `false` on errors.

If the returned value is 0, then the number of elements is not limited.

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Collection class was renamed to OCICollection to align with PHP naming standards.

### 参见

- OCICollection::size

# OCICollection::size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::size — Returns size of the collection

### 说明

public function OCICollection::size(): int|false

Returns the size of the collection.

### 参数

此函数没有参数。

### 返回值

Returns the number of elements in the collection or `false` on error.

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Collection class was renamed to OCICollection to align with PHP naming standards.

### 参见

- OCICollection::max

# OCICollection::trim

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::trim — Trims elements from the end of the collection

### 说明

public function OCICollection::trim(int `$num`): bool

Trims `num` of elements from the end of the collection.

### 参数

`num`

  The number of elements to be trimmed.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Collection class was renamed to OCICollection to align with PHP naming standards.

### 参见

- OCICollection::size

## 目录

- OCICollection::append — Appends element to the collection
- OCICollection::assign — Assigns a value to the collection from another existing collection
- OCICollection::assignElem — Assigns a value to the element of the collection
- OCICollection::free — Frees the resources associated with the collection object
- OCICollection::getElem — Returns value of the element
- OCICollection::max — Returns the maximum number of elements in the collection
- OCICollection::size — Returns size of the collection
- OCICollection::trim — Trims elements from the end of the collection

# The OCILob class

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

## 简介

OCI8 LOB functionality for large binary (BLOB) and character (CLOB) objects.

> 注意:

> The OCI-Lob class was renamed to OCILob in PHP 8 and PECL OCI8 3.0.0 to align with PHP naming standards.

## 类摘要

class OCILob {
/* 方法 */
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

### 说明

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.

### 参数

`from`

  The copied LOB.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### 参见

- OCILob::flush
- OCILob::setBuffering
- OCILob::getBuffering

# OCILob::close

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::close — Closes LOB descriptor

### 说明

public function OCILob::close(): bool

Closes descriptor of LOB or FILE. This function should be used only with OCILob::writeTemporary.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### 参见

- 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

### 说明

public function OCILob::eof(): bool

Tells whether the internal pointer of large object is at the end of LOB.

### 参数

此函数没有参数。

### 返回值

Returns `true` if internal pointer of large object is at the end of LOB. Otherwise returns `false`.

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### 注释

> 注意:

> This function will return an Oracle error if OCILob::setBuffering is enabled on the LOB.

### 参见

- 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

### 说明

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.

### 参数

`offset`

`length`

### 返回值

Returns the actual number of characters/bytes erased 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
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.

### 参见

- OCILob::truncate

# OCILob::export

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::export — Exports LOB's contents to a file

### 说明

public function OCILob::export(string `$filename`, ?int `$offset` = `null`, ?int `$length` = `null`): bool

Exports LOB contents to a file.

### 参数

`filename`

  Path to the file.

`offset`

  Indicates from where to start exporting.

`length`

  Indicates the length of data to be exported.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
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.

### 参见

- 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

### 说明

public function OCILob::flush(int `$flag` = 0): bool

OCILob::flush() actually writes data to the server.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

Returns `false` if buffering was not enabled or an error occurred.

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### 参见

- 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

### 说明

public function OCILob::free(): bool

Frees resources associated with the descriptor, previously allocated with oci_new_descriptor().

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
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

### 说明

public function OCILob::getBuffering(): bool

Tells whether the buffering for the large object is on or off.

### 参数

此函数没有参数。

### 返回值

Returns `false` if buffering for the large object is off and `true` if buffering is used.

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### 参见

- OCILob::setBuffering

# OCILob::import

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::import — Imports file data to the LOB

### 说明

public function OCILob::import(string `$filename`): bool

Writes data from the `filename` in to the current position of large object.

### 参数

`filename`

  Path to the file.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### 参见

- OCILob::export
- OCILob::write

# OCILob::load

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::load — Returns large object's contents

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the contents of the object, or `false` on errors.

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### 参见

- OCILob::read

# OCILob::read

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::read — Reads part of the large object

### 说明

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.

### 参数

`length`

  The length of data to read, in bytes (BLOB) or characters (CLOB). Large values will be rounded down to 1 MB.

### 返回值

Returns the contents as a string, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### 参见

- 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

### 说明

public function OCILob::rewind(): bool

Sets the internal pointer to the beginning of the large object.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### 参见

- 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

### 说明

public function OCILob::save(string `$data`, int `$offset` = 0): bool

Saves `data` to the large object.

### 参数

`data`

  The data to be saved.

`offset`

  Can be used to indicate offset from the beginning of the large object.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### 参见

- OCILob::write
- OCILob::import

# OCILob::saveFile

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::saveFile — 别名 OCILob::import()

### 说明

此函数是该函数的别名： OCILob::import().

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

# OCILob::seek

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::seek — Sets the internal pointer of the large object

### 说明

public function OCILob::seek(int `$offset`, int `$whence` = `OCI_SEEK_SET`): bool

Sets the internal pointer of the large object.

### 参数

`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)

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### 参见

- 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

### 说明

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.

### 参数

`mode`

  `true` for on and `false` for off.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。 Repeated calls to this method with the same flag will return `true`.

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### 参见

- OCILob::getBuffering

# OCILob::size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::size — Returns size of large object

### 说明

public function OCILob::size(): int|false

Gets the size of the large object.

### 参数

此函数没有参数。

### 返回值

Returns length of large object value 或者在失败时返回 `false`. Empty objects have zero length.

### 更新日志

版本 | 说明
--- | ---
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

### 说明

public function OCILob::tell(): int|false

Gets the current position of a LOB's internal pointer.

### 参数

此函数没有参数。

### 返回值

Returns current position of a LOB's internal pointer or `false` if an error occurred.

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### 参见

- OCILob::rewind
- OCILob::size
- OCILob::eof

# OCILob::truncate

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::truncate — Truncates large object

### 说明

public function OCILob::truncate(int `$length` = 0): bool

Truncates the LOB.

### 参数

`length`

  If provided, this method will truncate the LOB to `length` bytes. Otherwise, it will completely purge the LOB.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### 参见

- OCILob::erase

# OCILob::write

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::write — Writes data to the large object

### 说明

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.

### 参数

`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.

### 返回值

Returns the number of bytes written 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
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.

### 参见

- OCILob::read

# OCILob::writeTemporary

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::writeTemporary — Writes a temporary large object

### 说明

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.

### 参数

`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

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### 参见

- OCILob::close

# OCILob::writeToFile

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::writeToFile — 别名 OCILob::export()

### 说明

此函数是该函数的别名： OCILob::export().

### 更新日志

版本 | 说明
--- | ---
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.

## 目录

- 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 — 别名 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 — 别名 OCILob::export

# OCI8 Obsolete Aliases and Functions

# 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

### 说明

function oci_internal_debug(bool `$onoff`): void

Enables or disables internal debug output.

### 参数

`onoff`

  Set this to `false` to turn debug output off or `true` to turn it on.

### 返回值

没有返回值。

### 注释

> 注意:

> 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 — 别名 oci_bind_by_name()

### 说明

别名 oci_bind_by_name()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocicancel

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicancel — 别名 oci_cancel()

### 说明

别名 oci_cancel()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocicloselob

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 1.0)

ocicloselob — 别名 OCILob::close()

### 说明

别名 OCILob::close()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocicollappend

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollappend — 别名 OCICollection::append()

### 说明

别名 OCICollection::append()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocicollassign

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 >= 1.0.0)

ocicollassign — 别名 OCICollection::assign()

### 说明

别名 OCICollection::assign()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocicollassignelem

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollassignelem — 别名 OCICollection::assignElem()

### 说明

别名 OCICollection::assignElem()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocicollgetelem

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollgetelem — 别名 OCICollection::getElem()

### 说明

别名 OCICollection::getElem()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocicollmax

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollmax — 别名 OCICollection::max()

### 说明

别名 OCICollection::max()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocicollsize

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollsize — 别名 OCICollection::size()

### 说明

别名 OCICollection::size()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocicolltrim

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolltrim — 别名 OCICollection::trim()

### 说明

别名 OCICollection::trim()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocicolumnisnull

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnisnull — 别名 oci_field_is_null()

### 说明

别名 oci_field_is_null()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocicolumnname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnname — 别名 oci_field_name()

### 说明

别名 oci_field_name()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocicolumnprecision

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnprecision — 别名 oci_field_precision()

### 说明

别名 oci_field_precision()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocicolumnscale

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnscale — 别名 oci_field_scale()

### 说明

别名 oci_field_scale()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocicolumnsize

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnsize — 别名 oci_field_size()

### 说明

别名 oci_field_size()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocicolumntype

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumntype — 别名 oci_field_type()

### 说明

别名 oci_field_type()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocicolumntyperaw

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumntyperaw — 别名 oci_field_type_raw()

### 说明

别名 oci_field_type_raw()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocicommit

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicommit — 别名 oci_commit()

### 说明

别名 oci_commit()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocidefinebyname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocidefinebyname — 别名 oci_define_by_name()

### 说明

别名 oci_define_by_name()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocierror

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocierror — 别名 oci_error()

### 说明

别名 oci_error()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ociexecute

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociexecute — 别名 oci_execute()

### 说明

别名 oci_execute()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocifetch

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetch — 别名 oci_fetch()

### 说明

别名 oci_fetch()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocifetchinto

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetchinto — Obsolete variant of oci_fetch_array(), oci_fetch_object(), oci_fetch_assoc() and oci_fetch_row()

### 说明

Obsolete variant of oci_fetch_array(), oci_fetch_object(), oci_fetch_assoc() and oci_fetch_row()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocifetchstatement

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetchstatement — 别名 oci_fetch_all()

### 说明

别名 oci_fetch_all()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocifreecollection

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreecollection — 别名 OCICollection::free()

### 说明

别名 OCICollection::free()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocifreecursor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreecursor — 别名 oci_free_statement()

### 说明

别名 oci_free_statement()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocifreedesc

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreedesc — 别名 OCILob::free()

### 说明

别名 OCILob::free()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocifreestatement

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreestatement — 别名 oci_free_statement()

### 说明

别名 oci_free_statement()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ociinternaldebug

(PHP 4, PHP 5, PHP 7, PECL OCI8 >= 1.0.0, PECL OCI8 <= 2.2.0)

ociinternaldebug — 别名 oci_internal_debug()

### 说明

别名 oci_internal_debug()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ociloadlob

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociloadlob — 别名 OCILob::load()

### 说明

别名 OCILob::load()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocilogoff

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocilogoff — 别名 oci_close()

### 说明

别名 oci_close()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocilogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocilogon — 别名 oci_connect()

### 说明

别名 oci_connect()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocinewcollection

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewcollection — 别名 oci_new_collection()

### 说明

别名 oci_new_collection()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocinewcursor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewcursor — 别名 oci_new_cursor()

### 说明

别名 oci_new_cursor()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocinewdescriptor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewdescriptor — 别名 oci_new_descriptor()

### 说明

别名 oci_new_descriptor()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocinlogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinlogon — 别名 oci_new_connect()

### 说明

别名 oci_new_connect()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocinumcols

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinumcols — 别名 oci_num_fields()

### 说明

别名 oci_num_fields()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ociparse

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociparse — 别名 oci_parse()

### 说明

别名 oci_parse()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ociplogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociplogon — 别名 oci_pconnect()

### 说明

别名 oci_pconnect()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ociresult

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociresult — 别名 oci_result()

### 说明

别名 oci_result()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocirollback

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocirollback — 别名 oci_rollback()

### 说明

别名 oci_rollback()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocirowcount

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocirowcount — 别名 oci_num_rows()

### 说明

别名 oci_num_rows()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocisavelob

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisavelob — 别名 OCILob::save()

### 说明

别名 OCILob::save()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocisavelobfile

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisavelobfile — 别名 OCILob::import()

### 说明

别名 OCILob::import()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ociserverversion

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociserverversion — 别名 oci_server_version()

### 说明

别名 oci_server_version()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocisetprefetch

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisetprefetch — 别名 oci_set_prefetch()

### 说明

别名 oci_set_prefetch()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ocistatementtype

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocistatementtype — 别名 oci_statement_type()

### 说明

别名 oci_statement_type()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ociwritelobtofile

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociwritelobtofile — 别名 OCILob::export()

### 说明

别名 OCILob::export()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

# ociwritetemporarylob

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 1.0)

ociwritetemporarylob — 别名 OCILob::writeTemporary()

### 说明

别名 OCILob::writeTemporary()

警告

自 PHP 5.4.0 起，已经废弃此别名。强烈建议不要应用此别名。

## 目录

- oci_internal_debug — Enables or disables internal debug output
- ocibindbyname — 别名 oci_bind_by_name
- ocicancel — 别名 oci_cancel
- ocicloselob — 别名 OCILob::close
- ocicollappend — 别名 OCICollection::append
- ocicollassign — 别名 OCICollection::assign
- ocicollassignelem — 别名 OCICollection::assignElem
- ocicollgetelem — 别名 OCICollection::getElem
- ocicollmax — 别名 OCICollection::max
- ocicollsize — 别名 OCICollection::size
- ocicolltrim — 别名 OCICollection::trim
- ocicolumnisnull — 别名 oci_field_is_null
- ocicolumnname — 别名 oci_field_name
- ocicolumnprecision — 别名 oci_field_precision
- ocicolumnscale — 别名 oci_field_scale
- ocicolumnsize — 别名 oci_field_size
- ocicolumntype — 别名 oci_field_type
- ocicolumntyperaw — 别名 oci_field_type_raw
- ocicommit — 别名 oci_commit
- ocidefinebyname — 别名 oci_define_by_name
- ocierror — 别名 oci_error
- ociexecute — 别名 oci_execute
- ocifetch — 别名 oci_fetch
- ocifetchinto — Obsolete variant of oci_fetch_array, oci_fetch_object, oci_fetch_assoc and oci_fetch_row
- ocifetchstatement — 别名 oci_fetch_all
- ocifreecollection — 别名 OCICollection::free
- ocifreecursor — 别名 oci_free_statement
- ocifreedesc — 别名 OCILob::free
- ocifreestatement — 别名 oci_free_statement
- ociinternaldebug — 别名 oci_internal_debug
- ociloadlob — 别名 OCILob::load
- ocilogoff — 别名 oci_close
- ocilogon — 别名 oci_connect
- ocinewcollection — 别名 oci_new_collection
- ocinewcursor — 别名 oci_new_cursor
- ocinewdescriptor — 别名 oci_new_descriptor
- ocinlogon — 别名 oci_new_connect
- ocinumcols — 别名 oci_num_fields
- ociparse — 别名 oci_parse
- ociplogon — 别名 oci_pconnect
- ociresult — 别名 oci_result
- ocirollback — 别名 oci_rollback
- ocirowcount — 别名 oci_num_rows
- ocisavelob — 别名 OCILob::save
- ocisavelobfile — 别名 OCILob::import
- ociserverversion — 别名 oci_server_version
- ocisetprefetch — 别名 oci_set_prefetch
- ocistatementtype — 别名 oci_statement_type
- ociwritelobtofile — 别名 OCILob::export
- ociwritetemporarylob — 别名 OCILob::writeTemporary

- 安装/配置
  - 需求
  - 安装
  - Testing
  - 运行时配置
- 预定义常量
- 示例
- 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 函数
  - oci_bind_array_by_name — Binds a PHP array to an Oracle PL/SQL array parameter
  - oci_bind_by_name — 绑定 PHP 变量到 Oracle 位置标志符
  - oci_cancel — 中断游标读取数据
  - oci_client_version — Returns the Oracle client library version
  - oci_close — 关闭 Oracle 连接
  - oci_commit — 提交未完成的数据库事务
  - oci_connect — 建立一个到 Oracle 服务器的连接
  - oci_define_by_name — 将 PHP 变量与查询读取的列相关联
  - oci_error — 返回最后发现的错误
  - oci_execute — 执行语句
  - oci_fetch — 从查询中读取下一行到内部缓冲区
  - oci_fetch_all — 从查询中读取多行到二维数组中
  - oci_fetch_array — Returns the next row from a query as an associative or numeric array
  - oci_fetch_assoc — Returns the next row from a query as an associative array
  - oci_fetch_object — Returns the next row from a query as an object
  - oci_fetch_row — Returns the next row from a query as a numeric array
  - oci_field_is_null — 检测当前获取的行中，字段是否为 null
  - oci_field_name — 返回 statement 中的字段名
  - oci_field_precision — 返回字段精度
  - oci_field_scale — 返回字段范围
  - oci_field_size — 返回字段大小
  - oci_field_type — 返回字段的数据类型名称
  - oci_field_type_raw — 返回字段的原始 Oracle 数据类型
  - oci_free_descriptor — Frees a descriptor
  - oci_free_statement — 释放关联于语句或游标的所有资源
  - 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 — 分配新的 collection 对象
  - oci_new_connect — 使用唯一连接，连接到 Oracle 服务器
  - oci_new_cursor — 分配并返回新的游标（语句句柄）
  - oci_new_descriptor — 初始化新的空 LOB 或 FILE 描述符
  - oci_num_fields — 返回语句中结果列的数量
  - oci_num_rows — 返回语句执行后受影响的行数
  - oci_parse — 预处理用于执行的 Oracle 语句
  - oci_password_change — 修改 Oracle 用户的密码
  - oci_pconnect — 使用持久连接连，连接到 Oracle 数据库
  - oci_register_taf_callback — Register a user-defined callback function for Oracle Database TAF
  - oci_result — 返回所取得行中字段的值
  - oci_rollback — 回滚未完成的事务
  - oci_server_version — 返回 Oracle 数据库版本
  - 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 — 设置查询预读取的行数
  - oci_set_prefetch_lob — Sets the amount of data prefetched for each CLOB or BLOB.
  - oci_statement_type — 返回语句的类型
  - oci_unregister_taf_callback — Unregister a user-defined callback function for Oracle Database TAF
- OCICollection — The OCICollection class
  - OCICollection::append — Appends element to the collection
  - OCICollection::assign — Assigns a value to the collection from another existing collection
  - OCICollection::assignElem — Assigns a value to the element of the collection
  - OCICollection::free — Frees the resources associated with the collection object
  - OCICollection::getElem — Returns value of the element
  - OCICollection::max — Returns the maximum number of elements in the collection
  - OCICollection::size — Returns size of the collection
  - OCICollection::trim — Trims elements from the end of the collection
- 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 — 别名 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 — 别名 OCILob::export
- OCI8 Obsolete Aliases and Functions
  - oci_internal_debug — Enables or disables internal debug output
  - ocibindbyname — 别名 oci_bind_by_name
  - ocicancel — 别名 oci_cancel
  - ocicloselob — 别名 OCILob::close
  - ocicollappend — 别名 OCICollection::append
  - ocicollassign — 别名 OCICollection::assign
  - ocicollassignelem — 别名 OCICollection::assignElem
  - ocicollgetelem — 别名 OCICollection::getElem
  - ocicollmax — 别名 OCICollection::max
  - ocicollsize — 别名 OCICollection::size
  - ocicolltrim — 别名 OCICollection::trim
  - ocicolumnisnull — 别名 oci_field_is_null
  - ocicolumnname — 别名 oci_field_name
  - ocicolumnprecision — 别名 oci_field_precision
  - ocicolumnscale — 别名 oci_field_scale
  - ocicolumnsize — 别名 oci_field_size
  - ocicolumntype — 别名 oci_field_type
  - ocicolumntyperaw — 别名 oci_field_type_raw
  - ocicommit — 别名 oci_commit
  - ocidefinebyname — 别名 oci_define_by_name
  - ocierror — 别名 oci_error
  - ociexecute — 别名 oci_execute
  - ocifetch — 别名 oci_fetch
  - ocifetchinto — Obsolete variant of oci_fetch_array, oci_fetch_object, oci_fetch_assoc and oci_fetch_row
  - ocifetchstatement — 别名 oci_fetch_all
  - ocifreecollection — 别名 OCICollection::free
  - ocifreecursor — 别名 oci_free_statement
  - ocifreedesc — 别名 OCILob::free
  - ocifreestatement — 别名 oci_free_statement
  - ociinternaldebug — 别名 oci_internal_debug
  - ociloadlob — 别名 OCILob::load
  - ocilogoff — 别名 oci_close
  - ocilogon — 别名 oci_connect
  - ocinewcollection — 别名 oci_new_collection
  - ocinewcursor — 别名 oci_new_cursor
  - ocinewdescriptor — 别名 oci_new_descriptor
  - ocinlogon — 别名 oci_new_connect
  - ocinumcols — 别名 oci_num_fields
  - ociparse — 别名 oci_parse
  - ociplogon — 别名 oci_pconnect
  - ociresult — 别名 oci_result
  - ocirollback — 别名 oci_rollback
  - ocirowcount — 别名 oci_num_rows
  - ocisavelob — 别名 OCILob::save
  - ocisavelobfile — 别名 OCILob::import
  - ociserverversion — 别名 oci_server_version
  - ocisetprefetch — 别名 oci_set_prefetch
  - ocistatementtype — 别名 oci_statement_type
  - ociwritelobtofile — 别名 OCILob::export
  - ociwritetemporarylob — 别名 OCILob::writeTemporary

# PostgreSQL

# 简介

PostgreSQL 数据库是开源产品，免费提供。Postgres 最初由加州大学伯克利分校计算机科学系开发，首创了许多对象关系概念，现在可以在一些商业数据库中使用。它提供 SQL92/SQL99 语言支持、事务、参照完整性、存储过程和可扩展类型（type extensibility）。PostgreSQL 是这个原始伯克利代码的开源后代。

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置
- 资源类型

## 需求

要使用 PostgreSQL 支持，你需要 libpq（PostgreSQL C 客户端库）。 从 PHP 8.0.0 开始，需要 libpq 9.1 或更高版本。 从 PHP 8.4.0 开始，需要 libpq 10.0 或更高版本。 PostgreSQL 支持包含多字节字符编码的多种字符编码。有关 PostgreSQL 的当前版本和更多信息，请访问 » http://www.postgresql.org/ 和 » PostgreSQL 文档。

## 安装

为启用 PostgreSQL 支持，编译 PHP 时需要 --with-pgsql[=DIR]。`DIR` 是 PostgreSQL 的基本安装目录，默认是 /usr/local/pgsql。如果共享对象模块可用，可以使用 php.ini 中的 extension 指令或者 dl() 函数加载 PostgreSQL 模块。

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

PostgreSQL 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
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` |

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`pgsql.allow_persistent` bool

  是否允许持久的 Postgres 连接。

`pgsql.max_persistent` int

  每个进程所能有的持久 Postgres 连接数目。

`pgsql.max_links` int

  每个进程所能有的 Postgres 连接数目，包括持久连接。

`pgsql.auto_reset_persistent` int

  检测用在 pg_pconnect() 上的中断了的持久连接。需要一些损耗。

`pgsql.ignore_notice` int

  是否忽略 PostgreSQL 后端的通告。

`pgsql.log_notice` int

  是否记录 PostgreSQL 后端的通告消息。要记录通告消息日志，PHP 指令 pgsql.ignore_notice 必须为 off。

## 资源类型

在 PHP 8.1.0 之前，PostgreSQL 模块中使用了两种资源类型。第一个是数据库连接的链接标识符，第二个是保存查询结果的资源。

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`PGSQL_LIBPQ_VERSION` (string)
  仅包含数字和小数点的简短 libpq 版本号。
`PGSQL_LIBPQ_VERSION_STR` (string)
  PHP 8.0.0 之前为包含编译信息的长 libpq 版本号。自 PHP 8.0.0 起，此值与 `PGSQL_LIBPQ_VERSION` 相同，并且弃用 `PGSQL_LIBPQ_VERSION_STR`。
`PGSQL_ASSOC` (int)
  传递给 pg_fetch_array()。返回字段名和值的关联数组。
`PGSQL_NUM` (int)
  传递给 pg_fetch_array()。返回字段编号和值的数字索引数组。
`PGSQL_BOTH` (int)
  传递给 pg_fetch_array()。返回字段值数组，这些字段值既有数字索引（按字段编号）也有关联索引（按字段名称）。
`PGSQL_CONNECT_FORCE_NEW` (int)
  传递给 pg_connect() 以强制创建新连接，而不是重新使用现有的相同连接。
`PGSQL_CONNECT_ASYNC` (int)
  传递给 pg_connect() 以创建异步连接。
`PGSQL_CONNECTION_AUTH_OK` (int)
`PGSQL_CONNECTION_AWAITING_RESPONSE` (int)
`PGSQL_CONNECTION_BAD` (int)
  由 pg_connection_status() 返回，表示数据库连接处于无效状态。
`PGSQL_CONNECTION_MADE` (int)
`PGSQL_CONNECTION_OK` (int)
  由 pg_connection_status() 返回，表示数据库连接处于有效状态。
`PGSQL_CONNECTION_SETENV` (int)
`PGSQL_CONNECTION_SSL_STARTUP` (int)
`PGSQL_CONNECTION_STARTED` (int)
`PGSQL_SEEK_SET` (int)
  传递给 pg_lo_seek()。寻找操作是从对象的开头开始的。
`PGSQL_SEEK_CUR` (int)
  传递给 pg_lo_seek()。寻找操作是从当前位置开始的。
`PGSQL_SEEK_END` (int)
  传递给 pg_lo_seek()。寻找操作是从对象的末尾开始。
`PGSQL_EMPTY_QUERY` (int)
  由 pg_result_status() 返回。发送到服务器的字符串为空。
`PGSQL_COMMAND_OK` (int)
  由 pg_result_status() 返回。成功完成命令不返回任何数据。
`PGSQL_TUPLES_OK` (int)
  由 pg_result_status() 返回。成功完成一个返回数据的命令（例如 `SELECT` 或 `SHOW`）。
`PGSQL_TUPLES_CHUNK` (int)
  由 pg_result_status() 返回。表示命令执行完毕，以分块模式返回数据。当设置了 pg_set_chunked_rows_size() 时，将返回 `SELECT` 命令。结果集分为多个块，每个块包含预定义的行数。自 PHP 8.4.0 和 libpq 17 起可用。
`PGSQL_COPY_OUT` (int)
  由 pg_result_status() 返回。开始复制（从服务器）数据传输。
`PGSQL_COPY_IN` (int)
  由 pg_result_status() 返回。开始复制（到服务器）数据传输。
`PGSQL_BAD_RESPONSE` (int)
  由 pg_result_status() 返回。无法理解服务器的响应。
`PGSQL_NONFATAL_ERROR` (int)
  由 pg_result_status() 返回。发生非致命错误（通知或警告）。
`PGSQL_FATAL_ERROR` (int)
  由 pg_result_status() 返回。发生致命错误。
`PGSQL_TRANSACTION_IDLE` (int)
  由 pg_transaction_status() 返回。当前连接处于空闲状态，不在事务中。
`PGSQL_TRANSACTION_ACTIVE` (int)
  由 pg_transaction_status() 返回。连接正在执行命令。查询（query）已通过连接发送但尚未完成。
`PGSQL_TRANSACTION_INTRANS` (int)
  由 pg_transaction_status() 返回。连接处于空闲状态且处于事务块中。
`PGSQL_TRANSACTION_INERROR` (int)
  由 pg_transaction_status() 返回。连接处于空闲状态且处于失败的事务块中。
`PGSQL_TRANSACTION_UNKNOWN` (int)
  由 pg_transaction_status() 返回。连接损坏。
`PGSQL_DIAG_SEVERITY` (int)
  传递给 pg_result_error_field()。严重程度；字段内容是 `ERROR`、`FATAL` 或 `PANIC`（在 error 消息中）或 `WARNING`、`NOTICE`、`DEBUG`、`INFO` 或 `LOG`（在 notice 消息中），或其中之一的本地化翻译。始终存在。
`PGSQL_DIAG_SQLSTATE` (int)
  传递给 pg_result_error_field()。error 的 SQLSTATE 代码。SQLSTATE 代码标识已发生的错误类型；前端应用程序可以使用它来执行特定操作（例如错误处理）以响应特定的数据库错误。该字段不可本地化，并且始终存在。
`PGSQL_DIAG_MESSAGE_PRIMARY` (int)
  传递给 pg_result_error_field()。 人可读的主要错误消息（通常是一行）。始终存在。
`PGSQL_DIAG_MESSAGE_DETAIL` (int)
  传递给 pg_result_error_field()。 详细信息：可选的次要错误消息，其中包含有关该问题的更多详细信息。可能会有多行。
`PGSQL_DIAG_MESSAGE_HINT` (int)
  传递给 pg_result_error_field()。 提示：关于如何处理该问题的可选建议。这与细节不同，因为它提供建议（可能不合适）而不是确凿的事实。可能会有多行。
`PGSQL_DIAG_STATEMENT_POSITION` (int)
  传递给 pg_result_error_field()。 包含十进制整数的字符串，指示错误游标位置作为原始语句字符串的索引。第一个字符的索引为 1，位置以字符而不是字节为单位进行测量。
`PGSQL_DIAG_INTERNAL_POSITION` (int)
  传递给 pg_result_error_field()。该字段的定义与 `PG_DIAG_STATEMENT_POSITION` 字段相同，但当光标位置引用内部生成的命令（而不是客户端提交的命令）时，会使用该常量。 当此字段出现时，`PG_DIAG_INTERNAL_QUERY` 字段将始终出现。
`PGSQL_DIAG_INTERNAL_QUERY` (int)
  传递给 pg_result_error_field()。 失败的内部生成命令的文本。例如，这可能是由 PL/pgSQL 函数发出的 SQL 查询。
`PGSQL_DIAG_CONTEXT` (int)
  传递给 pg_result_error_field()。 错误发生时的上下文指示。目前包括活动过程语言函数和内部生成的查询调用堆栈回溯。跟踪是每行一个条目，最近的条目在前。
`PGSQL_DIAG_SOURCE_FILE` (int)
  传递给 pg_result_error_field()。 报告错误的 PostgreSQL 源代码位置的文件名。
`PGSQL_DIAG_SOURCE_LINE` (int)
  传递给 pg_result_error_field()。 报告错误的 PostgreSQL 源代码位置的行号。
`PGSQL_DIAG_SOURCE_FUNCTION` (int)
  传递给 pg_result_error_field()。 报告错误的 PostgreSQL 源代码函数的名称。
`PGSQL_DIAG_SCHEMA_NAME` (int)
  自 PHP 7.3.0 起可用。
`PGSQL_DIAG_TABLE_NAME` (int)
  自 PHP 7.3.0 起可用。
`PGSQL_DIAG_COLUMN_NAME` (int)
  自 PHP 7.3.0 起可用。
`PGSQL_DIAG_DATATYPE_NAME` (int)
  自 PHP 7.3.0 起可用。
`PGSQL_DIAG_CONSTRAINT_NAME` (int)
  自 PHP 7.3.0 起可用。
`PGSQL_ERRORS_TERSE` (int)
  传递给 pg_set_error_verbosity()。指定返回的消息，仅包括严重性、主要文本和位置；通常适合单行。
`PGSQL_ERRORS_DEFAULT` (int)
  传递给 pg_set_error_verbosity()。默认模式生成的消息包括上述内容以及所有的详细信息、提示或上下文字段（这些可能会有多行）。
`PGSQL_ERRORS_VERBOSE` (int)
  传递给 pg_set_error_verbosity()。详细模式包括所有可用字段。
`PGSQL_ERRORS_SQLSTATE` (int)
  传递给 pg_set_error_verbosity()。仅包括错误严重性和 `SQLSTATE` 错误代码。如果没有可用的错误代码，则输出类似于 `PGSQL_ERRORS_TERSE` 模式。在 PostgreSQL 11.1 之前，输出始终与 `PGSQL_ERRORS_TERSE` 模式相同。
`PGSQL_NOTICE_LAST` (int)
  用于 pg_last_notice()。自 PHP 7.1.0 起可用。
`PGSQL_NOTICE_ALL` (int)
  用于 pg_last_notice()。自 PHP 7.1.0 起可用。
`PGSQL_NOTICE_CLEAR` (int)
  用于 pg_last_notice()。自 PHP 7.1.0 起可用。
`PGSQL_STATUS_LONG` (int)
  传递给 pg_result_status()。表示需要的数字结果代码。
`PGSQL_STATUS_STRING` (int)
  传递给 pg_result_status()。表示需要的文本结果命令标记。
`PGSQL_CONV_IGNORE_DEFAULT` (int)
  传递给 pg_convert()。转换期间忽略表中的默认值。
`PGSQL_CONV_FORCE_NULL` (int)
  传递给 pg_convert()。使用 SQL `NULL` 代替空 string。
`PGSQL_CONV_IGNORE_NOT_NULL` (int)
  传递给 pg_convert()。不会将 `null` 转换为 SQL `NOT NULL` 列。
`PGSQL_DML_NO_CONV` (int)
  传递给 pg_insert()、pg_select()、pg_update() 和 pg_delete()。所有参数按原样传递。如果参数包含用户提供的数据，则需要使用 pg_escape_string() 手动转义。
`PGSQL_DML_EXEC` (int)
  传递给 pg_insert()、pg_select()、pg_update() 和 pg_delete()。通过这些函数执行查询。
`PGSQL_DML_ASYNC` (int)
  传递给 pg_insert()、pg_select()、pg_update() 和 pg_delete()。通过这些函数执行异步查询。
`PGSQL_DML_STRING` (int)
  传递给 pg_insert()、pg_select()、pg_update() 和 pg_delete()。返回执行的查询字符串。
`PGSQL_DML_ESCAPE` (int)
  传递给 pg_insert()、pg_select()、pg_update() 和 pg_delete()。将转义应用于所有参数，而不是在内部调用 pg_convert()。此选项省略元数据查找。查询可能与 pg_query() 和 pg_send_query() 一样快。
`PGSQL_POLLING_FAILED` (int)
  由 pg_connect_poll() 返回，表示尝试连接失败。
`PGSQL_POLLING_READING` (int)
  由 pg_connect_poll() 返回，表示该连接正在等待 PostgreSQL 套接字可读。
`PGSQL_POLLING_WRITING` (int)
  由 pg_connect_poll() 返回，表示该连接正在等待 PostgreSQL 套接字可写。
`PGSQL_POLLING_OK` (int)
  由 pg_connect_poll() 返回，表示连接已准备就绪，可以使用。
`PGSQL_POLLING_ACTIVE` (int)
  由 pg_connect_poll() 返回，表示该连接当前处于活动状态。
`PGSQL_DIAG_SEVERITY_NONLOCALIZED` (int)
  严重程度；字段内容是 ERROR、FATAL 或 PANIC（在错误消息中）或 WARNING、NOTICE、DEBUG、INFO 或 LOG（在通知消息中）。这与 PG_DIAG_SEVERITY 字段相同，只是内容从未本地化。这仅存在于 9.6 及更高版本/PHP 7.3.0 及更高版本中。
`PGSQL_SHOW_CONTEXT_NEVER` (int)
  跟 pg_set_error_context_visibility() 一起使用，上下文永远不会显示。自 PHP 8.3.0 起可用。
`PGSQL_SHOW_CONTEXT_ERRORS` (int)
  跟 pg_set_error_context_visibility() 一起使用，上下文字段仅包含在错误消息中。这是默认行为。自 PHP 8.3.0 起可用。
`PGSQL_SHOW_CONTEXT_ALWAYS` (int)
  跟 pg_set_error_context_visibility() 一起使用，上下文字段包含在 error、notice 和 warning 消息中。自 PHP 8.3.0 起可用。
`PGSQL_TRACE_SUPPRESS_TIMESTAMPS` (int)
  跟 pg_trace() 一起使用，时间戳不包含在跟踪消息中。自 PHP 8.4.20 起可用。
`PGSQL_TRACE_REGRESS_MODE` (int)
  跟 pg_trace() 一起使用，比如 OID 等字段包含在跟踪消息中。自 PHP 8.3.0 起可用。

# 示例

## 目录

- Basic usage
- Basic usage

## Basic usage

This simple example shows how to connect, execute a query, print resulting rows and disconnect from a PostgreSQL database.

示例 #1 PostgreSQL extension overview example

    <?php

    // Connecting, selecting database
    $dbconn = pg_connect("host=localhost dbname=publishing user=www password=foo")
        or die('Could not connect: ' . pg_last_error());

    // Performing SQL query
    $query = 'SELECT * FROM authors';
    $result = pg_query($dbconn, $query) or die('Query failed: ' . pg_last_error());

    // Printing results in HTML
    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";

    // Free resultset
    pg_free_result($result);

    // Closing connection
    pg_close($dbconn);

    ?>

## Basic usage

These examples contain user defined functions similar to legacy MySQL functions.

示例 #1 PostgreSQL user defined functions example

    <?php
    // This function should be needed, since PostgreSQL connection binds database.
    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);
    }

    // List tables.
    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);
    }

    // See also pg_meta_data(). It returns field definition as array.
    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 函数

## 注释

> 注意:

> Not all functions are supported by all builds. It depends on your libpq (The PostgreSQL C client library) version and how libpq is compiled. If PHP PostgreSQL extensions are missing, then it is because your libpq version does not support them.

> 注意:

> Most PostgreSQL functions accept `connection` as the optional first parameter. If it is not provided, the last opened connection is used. If it doesn't exist, functions return `false`.

> 注意:

> PostgreSQL automatically folds all identifiers (e.g. table/column names) to lower-case values at object creation time and at query time. To force the use of mixed or upper case identifiers, you must escape the identifier using double quotes ("").

> 注意:

> PostgreSQL does not have special commands for fetching database schema information (eg. all the tables in the current database). Instead, there is a standard schema named `information_schema` containing system views with all the necessary information, in an easily queryable form. See the » PostgreSQL Documentation for full details.

# pg_affected_rows

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_affected_rows — 返回受影响的记录数（元组）

### 说明

function pg_affected_rows(PgSql\Result `$result`): int

pg_affected_rows() 返回受 `INSERT`、`UPDATE` 和 `DELETE` 查询影响的元组数（实例/记录/行）。

服务器返回 SELECT 的行数。

> 注意:

> 此函数过去称为 pg_cmdtuples()。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。

### 返回值

受查询影响的行数。如果没有元组受到影响，它将返回 `0`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 pg_affected_rows() 示例

    <?php
    $result = pg_query($conn, "INSERT INTO authors VALUES ('Orwell', 2002, 'Animal Farm')");

    $cmdtuples = pg_affected_rows($result);

    echo $cmdtuples . " tuples are affected.\n";
    ?>

以上示例会输出：

    1 tuples are affected.

### 参见

- pg_query() - 执行查询
- pg_query_params() - Submits a command to the server and waits for the result, with the ability to pass parameters separately from the SQL command text
- pg_execute() - Sends a request to execute a prepared statement with given parameters, and waits for the result
- pg_num_rows() - 返回结果中行的数量

# pg_cancel_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_cancel_query — 取消异步查询

### 说明

function pg_cancel_query(PgSql\Connection `$connection`): bool

pg_cancel_query() 取消由 pg_send_query()、pg_send_query_params() 或 pg_send_execute() 发送的异步查询。不能取消使用 pg_query() 执行的查询。

### 参数

`connection`
  PgSql\Connection 实例。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_cancel_query() 示例

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from authors; select count(*) from authors;");
      }

      $res1 = pg_get_result($dbconn);
      echo "First call to pg_get_result(): $res1\n";
      $rows1 = pg_num_rows($res1);
      echo "$res1 has $rows1 records\n\n";

      // Cancel the currently running query.  Will be the second query if it is
      // still running.
      pg_cancel_query($dbconn);
    ?>

以上示例会输出：

    First call to pg_get_result(): Resource id #3
    Resource id #3 has 3 records

### 参见

- pg_send_query() - 发送异步查询
- pg_connection_busy() - 获取连接是否繁忙

# pg_change_password

(PHP 8 >= 8.4.0)

pg_change_password — Change a PostgreSQL user's password

### 说明

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.

### 参数

`connection`
  PgSql\Connection 实例。
`user`
  The name of the PostgreSQL user whose password to change.
`password`
  The new password.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- pg_connect() - 打开 PostgreSQL 连接

# pg_client_encoding

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_client_encoding — 获取客户端编码

### 说明

function pg_client_encoding(?PgSql\Connection `$connection` = `null`): string

PostgreSQL 支持某些字符集在服务器和客户端之间自动进行字符集转换。pg_client_encoding() 以字符串形式返回客户端编码。返回的字符串将是标准的 PostgreSQL 编码标识符之一。

> 注意:

> 如果 libpq 在没有多字节编码支持的情况下编译，pg_client_encoding() 总是返回 `SQL_ASCII`。支持的编码取决于 PostgreSQL 版本。请参阅 PostgreSQL 文档支持的编码。

> 此函数过去称为 pg_clientencoding()。

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is `null`, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

### 返回值

客户端编码。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。
8.0.0 | `connection` 现在可以为 null。

### 示例

示例 #1 pg_client_encoding() 示例

    <?php
    // Assume $conn is a connection to a ISO-8859-1 database
    $encoding = pg_client_encoding($conn);

    echo "Client encoding is: ", $encoding, "\n";
    ?>

以上示例会输出：

    Client encoding is: ISO-8859-1

### 参见

- pg_set_client_encoding() - 设定客户端编码

# pg_close

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_close — 关闭 PostgreSQL 连接

### 说明

function pg_close(?PgSql\Connection `$connection` = `null`): true

pg_close() 关闭与指定 `connection` 实例关联的 PostgreSQL 数据库的非持久连接。

> 注意:

> 通常不需要使用 pg_close()，因为打开的非持久连接会在脚本结束时自动关闭。

如果连接上有打开的 PgSql\Lob 实例，请不要在关闭所有 PgSql\Lob 实例之前关闭连接。

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is `null`, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.2.0 | 现在返回类型为 `true`；之前是 bool。
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。
8.0.0 | `connection` 现在可以为 null。

### 示例

示例 #1 pg_close() 示例

    <?php
    $dbconn = pg_connect("host=localhost port=5432 dbname=mary")
       or die("Could not connect");
    echo "Connected successfully";
    pg_close($dbconn);
    ?>

以上示例会输出：

    Connected successfully

### 参见

- pg_connect() - 打开 PostgreSQL 连接

# pg_connect

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_connect — 打开 PostgreSQL 连接

### 说明

function pg_connect(string `$connection_string`, int `$flags` = 0): PgSql\Connection|false

pg_connect() 打开通过 `connection_string` 指定的 PostgreSQL 数据库的连接。

如果使用与现有连接相同的 `connection_string` 对 pg_connect() 进行第二次调用，将返回现有连接，除非将 `PGSQL_CONNECT_FORCE_NEW` 作为 `flags` 传递。

弃用有多个参数的旧语法 $conn = pg_connect("host", "port", "options", "tty", "dbname")。

### 参数

`connection_string`

  `connection_string` 可以为空以使用所有默认参数，或者可以包含一个或多个由空格分隔的参数设置。 每个参数设置的形式为 `keyword = value`。等号两旁的空格是可选的。写入空值或包含空格的值，请用单引号将其括起来，例如 `keyword = 'a value'`。值中的单引号和反斜线必须使用反斜线转义，即 \' 和 \\。

  当前可识别的参数关键字有 `host`、`hostaddr`、`port`、`dbname`（默认为 `user` 的值）、`user`、`password`、`connect_timeout`、`options`、`tty`（忽略）、`sslmode`、`requiressl`（弃用 `sslmode`）和 `service`。存在哪些参数取决于 PostgreSQL 版本。

  The `options` parameter can be used to set command line parameters to be invoked by the server.

`flags`

  如果传递 `PGSQL_CONNECT_FORCE_NEW`，将会创建新连接，即使 `connection_string` 与现有连接相同。

  如果指定 `PGSQL_CONNECT_ASYNC`，然后连接是异步创建。连接状态可以通过 pg_connect_poll() 或 pg_connection_status() 检测。

### 返回值

成功时返回 PgSql\Connection 实例， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在返回 PgSql\Connection 实例；之前返回 resource。

### 示例

示例 #1 使用 pg_connect()

    <?php
    $dbconn = pg_connect("dbname=mary");
    //connect to a database named "mary"

    $dbconn2 = pg_connect("host=localhost port=5432 dbname=mary");
    // connect to a database named "mary" on "localhost" at port "5432"

    $dbconn3 = pg_connect("host=sheep port=5432 dbname=mary user=lamb password=foo");
    //connect to a database named "mary" on the host "sheep" with a username and password

    $conn_string = "host=sheep port=5432 dbname=test user=lamb password=bar";
    $dbconn4 = pg_connect($conn_string);
    //connect to a database named "test" on the host "sheep" with a username and password

    $dbconn5 = pg_connect("host=localhost options='--client_encoding=UTF8'");
    //connect to a database on "localhost" and set the command line parameter which tells the encoding is in UTF-8
    ?>

### 参见

- pg_pconnect() - 打开一个持久的 PostgreSQL 连接
- pg_close() - 关闭 PostgreSQL 连接
- pg_host() - 返回和某连接关联的主机名
- pg_port() - 返回 connection 相关的端口号
- pg_tty() - 返回跟连接相关的 tty 名
- pg_options() - 获得和 connection 相关的选项
- pg_dbname() - 获取数据库名称

# pg_connect_poll

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_connect_poll — 对正在进行尝试进行异步的 PostgreSQL 连接轮询其状态。

### 说明

function pg_connect_poll(PgSql\Connection `$connection`): int

pg_connect_poll() 轮询通过 `PGSQL_CONNECT_ASYNC` 选项调用 pg_connect() 创建的 PostgreSQL 连接的状态。

### 参数

`connection`
  PgSql\Connection 实例。

### 返回值

返回 `PGSQL_POLLING_FAILED`、`PGSQL_POLLING_READING`、`PGSQL_POLLING_WRITING`、`PGSQL_POLLING_OK` 或 `PGSQL_POLLING_ACTIVE`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

# pg_connection_busy

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_busy — 获取连接是否繁忙

### 说明

function pg_connection_busy(PgSql\Connection `$connection`): bool

pg_connection_busy() 确定连接是否繁忙。如果繁忙，则之前的查询仍在执行。如果在连接上使用 pg_get_result()，将被阻塞。

### 参数

`connection`
  PgSql\Connection 实例。

### 返回值

如果连接繁忙返回 `true`，否则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_connection_busy() 示例

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");
      $bs = pg_connection_busy($dbconn);
      if ($bs) {
          echo 'connection is busy';
      } else {
         echo 'connection is not busy';
      }
    ?>

### 参见

- pg_connection_status() - 获取连接状态
- pg_get_result() - 取得异步查询结果

# pg_connection_reset

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_reset — 重置连接（再次连接）

### 说明

function pg_connection_reset(PgSql\Connection `$connection`): bool

pg_connection_reset() 重置连接。用于错误恢复。

### 参数

`connection`
  PgSql\Connection 实例。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_connection_reset() 示例

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");
      $dbconn2 = pg_connection_reset($dbconn);
      if ($dbconn2) {
          echo "reset successful\n";
      } else {
          echo "reset failed\n";
      }
    ?>

### 参见

- pg_connect() - 打开 PostgreSQL 连接
- pg_pconnect() - 打开一个持久的 PostgreSQL 连接
- pg_connection_status() - 获取连接状态

# pg_connection_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_status — 获取连接状态

### 说明

function pg_connection_status(PgSql\Connection `$connection`): int

pg_connection_status() 返回指定 `connection` 的状态。

### 参数

`connection`
  PgSql\Connection 实例。

### 返回值

`PGSQL_CONNECTION_OK` 或 `PGSQL_CONNECTION_BAD`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_connection_status() 示例

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");
      $stat = pg_connection_status($dbconn);
      if ($stat === PGSQL_CONNECTION_OK) {
          echo 'Connection status ok';
      } else {
          echo 'Connection status bad';
      }
    ?>

### 参见

- pg_connection_busy() - 获取连接是否繁忙

# pg_consume_input

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_consume_input — Reads input on the connection

### 说明

function pg_consume_input(PgSql\Connection `$connection`): bool

pg_consume_input() consumes any input waiting to be read from the database server.

### 参数

`connection`
  PgSql\Connection 实例。

### 返回值

`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.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

# pg_convert

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_convert — 将关联的数组值转换为适合 SQL 语句的格式

### 说明

function pg_convert(
PgSql\Connection `$connection`,
string `$table_name`,
array `$values`,
int `$flags` = 0
): array|false

pg_convert() 检查 `values` 中的值并将其转换为为适用于 SQL 语句的值。pg_convert() 的前提条件是现有的表 `table_name` 中具有的列至少有 `values` 中的单元那么多。`table_name` 中的字段名以及字段值必须匹配 `values` 中的索引，并且相应的数据类型必须兼容。成功时返回包含转换后的值的数组，否则返回 `false`。

> 注意:

> 接受 bool 值并转换为 PostgreSQL boolean 值。还支持 bool 值的字符串表示。`null` 转换为 PostgreSQL NULL。

### 参数

`connection`
  PgSql\Connection 实例。
`table_name`

  要转换类型的表名。

`values`

  要转换的数据。

`flags`

  `PGSQL_CONV_IGNORE_DEFAULT`、`PGSQL_CONV_FORCE_NULL` 或 `PGSQL_CONV_IGNORE_NOT_NULL` 的任意数量组合。

### 返回值

转换值后的 array， 或者在失败时返回 `false`。

### 错误／异常

当字段的值或类型不能正确匹配 PostgreSQL 的类型时，会抛出 ValueError 或 TypeError。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | 当字段的值或类型不能正确匹配 PostgreSQL 的类型时，现在会抛出 ValueError 或 TypeError 错误；之前触发 `E_WARNING`。
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_convert() 示例

    <?php
      $dbconn = pg_connect('dbname=foo');

      $tmp = array(
          'author' => 'Joe Thackery',
          'year' => 2005,
          'title' => 'My Life, by Joe Thackery'
      );

      $vals = pg_convert($dbconn, 'authors', $tmp);
    ?>

### 参见

- pg_meta_data() - 获得表的元数据
- pg_insert() - 将数组插入到表中
- pg_select() - 选择记录
- pg_update() - 更新表
- pg_delete() - 删除记录

# pg_copy_from

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_copy_from — 将数组中的记录插入到表

### 说明

function pg_copy_from(
PgSql\Connection `$connection`,
string `$table_name`,
array|Traversable `$rows`,
string `$separator` = "\t",
string `$null_as` = "\\\\N"
): bool

pg_copy_from() 将 `rows` 插入记录到表中。在内部发出 `COPY FROM` 命令以插入记录。

### 参数

`connection`
  PgSql\Connection 实例。
`table_name`

  复制 `rows` 到其中的表名。

`rows`

  要复制 iterable 中的数据到 `table_name`。`rows` 中的每个值都成为 `table_name` 中的一行。`rows` 中的每个值都应该用字符串分割以插入到每个字段。值应该换行终止。

`separator`

  `rows` 的每个元素分割为每个字段的值的标记。默认为 `\t`。

`null_as`

  SQL `NULL` 值在 `rows` 中的表示方式。默认为 `\\N`（`"\\\\N"`）。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.5.0 | `rows` 现在是 iterable 类型。 之前是 array 类型。
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_copy_from() 示例

    <?php
       $db = pg_connect("dbname=publisher") or die("Could not connect");

       $rows = pg_copy_to($db, $table_name);

       pg_query($db, "DELETE FROM $table_name");

       pg_copy_from($db, $table_name, $rows);
    ?>

### 参见

- pg_copy_to() - 将表复制到数组

# pg_copy_to

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_copy_to — 将表复制到数组

### 说明

function pg_copy_to(
PgSql\Connection `$connection`,
string `$table_name`,
string `$separator` = "\t",
string `$null_as` = "\\\\N"
): array|false

pg_copy_to() 将表复制到数组。在内部发出 `COPY TO` 命令来检索记录。

### 参数

`connection`
  PgSql\Connection 实例。
`table_name`

  从表中将数据复制到 `rows` 中的表名。

`separator`

  `rows` 的每个元素分割为每个字段的值的标记。默认为 `\t`。

`null_as`

  SQL `NULL` 值在 `rows` 中的表示方式。默认为 `\\N`（`"\\\\N"`）。

### 返回值

`COPY` 数据的每一行都作为一个元素组成的 array， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_copy_to() 示例

    <?php
       $db = pg_connect("dbname=publisher") or die("Could not connect");

       $rows = pg_copy_to($db, $table_name);

       pg_query($db, "DELETE FROM $table_name");

       pg_copy_from($db, $table_name, $rows);
    ?>

### 参见

- pg_copy_from() - 将数组中的记录插入到表

# pg_dbname

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_dbname — 获取数据库名称

### 说明

function pg_dbname(?PgSql\Connection `$connection` = `null`): string

pg_dbname() 返回指定 PostgreSQL `connection` 实例的数据库名称。

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is `null`, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

### 返回值

包含 `connection` 到的数据库名称的 string。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。
8.0.0 | `connection` 可以为 null。

### 示例

示例 #1 pg_dbname() 示例

    <?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 — 删除记录

### 说明

function pg_delete(
PgSql\Connection `$connection`,
string `$table_name`,
array `$conditions`,
int `$flags` = `PGSQL_DML_EXEC`
): string|bool

pg_delete() 从 `conditions` 中的键和值指定的表中删除记录。

如果指定 `flags`，则 pg_convert() 应用于具有指定 flag 的 `conditions`。

默认 pg_delete() 传递原始值。值必须转义或者 `flags` 必须指定 `PGSQL_DML_ESCAPE` flag。`PGSQL_DML_ESCAPE` 引用并转义参数/标识符。因此，table/column 名称变为区分大小写。

注意转义和预处理查询都不能保护 LIKE 查询、JSON、Array、Regex 等，这些参数要根据上下文来处理。即转义/验证值。

### 参数

`connection`
  PgSql\Connection 实例。
`table_name`

  要从中删除行的表名。

`conditions`

  array，其键为表 `table_name` 中的字段名，其值为要删除的那些字段的值。

`flags`

  任意数量 `PGSQL_CONV_FORCE_NULL`、`PGSQL_DML_NO_CONV`、`PGSQL_DML_ESCAPE`、`PGSQL_DML_EXEC`、`PGSQL_DML_ASYNC` 或 `PGSQL_DML_STRING` 的组合。如果 `PGSQL_DML_STRING` 是 `flags` 的一部分，则返回查询字符串。当设置 `PGSQL_DML_NO_CONV` 或 `PGSQL_DML_ESCAPE` 时，不会在内部调用 pg_convert()。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。如果通过 `flags` 传递 `PGSQL_DML_STRING`，则返回 string。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_delete() 示例

    <?php
      $db = pg_connect('dbname=foo');
      // 因为转义了所有的值，所以在某种程度上是安全的。
      // 然而 PostgreSQL 支持
      // JSON/Array。无论是转义还是预处理都不安全。
      $res = pg_delete($db, 'post_log', $_POST, PG_DML_ESCAPE);
      if ($res) {
          echo "POST data is deleted: $res\n";
      } else {
          echo "User must have sent wrong inputs\n";
      }
    ?>

### 参见

- pg_convert() - 将关联的数组值转换为适合 SQL 语句的格式

# pg_end_copy

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_end_copy — 与 PostgreSQL 后端同步

### 说明

function pg_end_copy(?PgSql\Connection `$connection` = `null`): bool

pg_end_copy() 在处理完 pg_put_line() 所执行的拷贝操作之后将 PostgreSQL 前端（通常为 web server 进程）与 PostgreSQL 服务器进行同步。pg_end_copy() 必须被调用，否则 PostgreSQL 服务器可能会和前端失去同步并报错。

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is `null`, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。
8.0.0 | `connection` 现在可以为 null。

### 示例

示例 #1 pg_end_copy() 示例

    <?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);
    ?>

### 参见

- pg_put_line() - 向 PostgreSQL 后端发送以 NULL 字符结尾的字符串

# pg_escape_bytea

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_escape_bytea — 转义字符串以插入到 bytea 字段

### 说明

function pg_escape_bytea(PgSql\Connection `$connection` = ?, string `$string`): string

pg_escape_bytea() 转义 bytea 数据类型的字符串。返回转义后的字符串。

> 注意:

> 当 `SELECT` bytea 类型时，PostgreSQL 返回前缀为“\”的八进制字节值（例如 \032）。用户需要手动转换为二进制格式。

> 本函数需要 PostgreSQL 7.2 及其更高版本。在 PostgreSQL 7.2.0 和 7.2.1 版中，如果使用了多字节支持，必须强制转换 bytea 类型。即 `INSERT INTO test_table (image) VALUES ('$image_escaped'::bytea);`，在 PostgreSQL 7.2.2 及其更高版本不需要强制转换。异常情况是当客户端和后端字符编码不匹配时，可能会有多字节流错误。然后用户必须强制转换 bytea 以避免此错误。

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is unspecified, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

`string`

  包含要插入到 bytea 列中的文本或二进制数据的 string。

### 返回值

包含转义数据的 string。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_escape_bytea() 示例

    <?php
      // 连接到数据库
      $dbconn = pg_connect('dbname=foo');

      // 读入二进制文件
      $data = file_get_contents('image1.jpg');

      // 转义二进制数据
      $escaped = pg_escape_bytea($data);

      // 将其插入数据库
      pg_query("INSERT INTO gallery (name, data) VALUES ('Pine trees', '{$escaped}')");
    ?>

### 参见

- pg_unescape_bytea() - 反转义 bytea 类型的二进制数据
- pg_escape_string() - 转义字符串以供查询

# pg_escape_identifier

(PHP 5 >= 5.4.4, PHP 7, PHP 8)

pg_escape_identifier — Escape an identifier for insertion into a text field

### 说明

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.

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is unspecified, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

`string`

  A string containing text to be escaped.

### 返回值

A string containing the escaped data, or `false` on failure.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #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};");
    ?>

### 参见

- pg_escape_literal() - Escape a literal for insertion into a text field
- pg_escape_bytea() - 转义字符串以插入到 bytea 字段
- pg_escape_string() - 转义字符串以供查询

# pg_escape_literal

(PHP 5 >= 5.4.4, PHP 7, PHP 8)

pg_escape_literal — Escape a literal for insertion into a text field

### 说明

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.

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is unspecified, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

`string`

  A string containing text to be escaped.

### 返回值

A string containing the escaped data, or `false` on failure.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #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})");
    ?>

### 参见

- pg_escape_identifier() - Escape an identifier for insertion into a text field
- pg_escape_bytea() - 转义字符串以插入到 bytea 字段
- pg_escape_string() - 转义字符串以供查询

# pg_escape_string

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_escape_string — 转义字符串以供查询

### 说明

function pg_escape_string(PgSql\Connection `$connection` = ?, string `$string`): string

pg_escape_string() 转义用于查询数据库的字符串。它返回不带引号的 PostgreSQL 格式的转义字符串。pg_escape_literal() 是为 PostgreSQL 转义 SQL 参数的首选方法。addslashes() 不得与 PostgreSQL 一起使用。如果列的类型是 bytea，则必须改用 pg_escape_bytea()。pg_escape_identifier() 必须用于转义标识符（例如表名、字段名）

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is unspecified, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

`string`

  包含要转义的 string。

### 返回值

包含转义数据的 string。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_escape_string() 示例

    <?php
      // 连接到数据库
      $dbconn = pg_connect('dbname=foo');

      // 读入文本文件（包含撇号和反斜线）
      $data = file_get_contents('letter.txt');

      // 转义文本数据
      $escaped = pg_escape_string($data);

      // 将其插入数据库
      pg_query("INSERT INTO correspondence (name, data) VALUES ('My letter', '{$escaped}')");
    ?>

### 参见

- pg_escape_bytea() - 转义字符串以插入到 bytea 字段

# pg_execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_execute — Sends a request to execute a prepared statement with given parameters, and waits for the result

### 说明

function pg_execute(PgSql\Connection `$connection` = ?, string `$statement_name`, array `$params`): PgSql\Result|false

Sends a request to execute a prepared statement with given parameters, and waits for the result.

pg_execute() is like pg_query_params(), but the command to be executed is specified by naming a previously-prepared statement, instead of giving a query string. This feature allows commands that will be used repeatedly to be parsed and planned just once, rather than each time they are executed. The statement must have been prepared previously in the current session.

The parameters are identical to pg_query_params(), except that the name of a prepared statement is given instead of a query string.

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is unspecified, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

`statement_name`

  The name of the prepared statement to execute. if "" is specified, then the unnamed statement is executed. The name must have been previously prepared using pg_prepare(), pg_send_prepare() or a `PREPARE` SQL command.

`params`

  An array of parameter values to substitute for the $1, $2, etc. placeholders in the original prepared query string. The number of elements in the array must match the number of placeholders.

  警告

  Elements are converted to strings by calling this function.

### 返回值

An PgSql\Result instance on success, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在返回 PgSql\Result 实例，之前返回 resource
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 Using pg_execute()

    <?php
    // Connect to a database named "mary"
    $dbconn = pg_connect("dbname=mary");

    // Prepare a query for execution
    $result = pg_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');

    // Execute the prepared query.  Note that it is not necessary to escape
    // the string "Joe's Widgets" in any way
    $result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));

    // Execute the same prepared query, this time with a different parameter
    $result = pg_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));

    ?>

### 参见

- pg_prepare() - Submits a request to the server to create a prepared statement with the given parameters, and waits for completion
- pg_send_prepare() - Sends a request to create a prepared statement with the given parameters, without waiting for completion
- pg_query_params() - Submits a command to the server and waits for the result, with the ability to pass parameters separately from the SQL command text

# pg_fetch_all

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_fetch_all — 从结果中获取所有行作为数组

### 说明

function pg_fetch_all(PgSql\Result `$result`, int `$mode` = `PGSQL_ASSOC`): array

pg_fetch_all() 返回包含 PgSql\Result 实例中所有行（记录）的数组。

> 注意: 此函数将 NULL 字段设置为 PHP `null` 值。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。
`mode`
  An optional parameter that controls how the returned array is indexed. `mode` is a constant and can take the following values: `PGSQL_ASSOC`, `PGSQL_NUM` and `PGSQL_BOTH`. Using `PGSQL_NUM`, the function will return an array with numerical indices, using `PGSQL_ASSOC` it will return only associative indices while `PGSQL_BOTH` will return both numerical and associative indices.

### 返回值

包含结果中所有行的 array。每行都是一个由字段名作为索引的字段值数组。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。
8.0.0 | 对于零行的结果集，pg_fetch_all() 现在将返回一个空数组而不是 array。
7.1.0 | 新增 `mode` 参数。

### 示例

示例 #1 PostgreSQL 获取全部

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
        echo "An error occurred.\n";
        exit;
    }

    $result = pg_query($conn, "SELECT * FROM authors");
    if (!$result) {
        echo "An error occurred.\n";
        exit;
    }

    $arr = pg_fetch_all($result);

    print_r($arr);

    ?>

以上示例的输出类似于：

    Array
    (
        [0] => Array
            (
                [id] => 1
                [name] => Fred
            )

        [1] => Array
            (
                [id] => 2
                [name] => Bob
            )

    )

### 参见

- pg_fetch_row() - 提取一行作为枚举数组
- pg_fetch_array() - 获取一行作为数组
- pg_fetch_object() - 获取一行作为对象
- pg_fetch_result() - 从结果实例返回值

# pg_fetch_all_columns

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_fetch_all_columns — Fetches all rows in a particular result column as an array

### 说明

function pg_fetch_all_columns(PgSql\Result `$result`, int `$field` = 0): array

pg_fetch_all_columns() returns an array that contains all rows (records) in a particular column of the PgSql\Result instance.

> 注意: 此函数将 NULL 字段设置为 PHP `null` 值。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。
`field`

  Column number. Defaults to the first column if not specified.

### 返回值

An array with all values in the result column.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 pg_fetch_all_columns() example

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "An error occurred.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT title, name, address FROM authors");
    if (!$result) {
      echo "An error occurred.\n";
      exit;
    }

    // Get an array of all author names
    $arr = pg_fetch_all_columns($result, 1);

    var_dump($arr);

    ?>

### 参见

- pg_fetch_all() - 从结果中获取所有行作为数组

# pg_fetch_array

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_array — 获取一行作为数组

### 说明

function pg_fetch_array(PgSql\Result `$result`, ?int `$row` = `null`, int `$mode` = `PGSQL_BOTH`): array|false

pg_fetch_array() 返回与所提取的行（元组/记录）相一致的数组。

pg_fetch_array() 是 pg_fetch_row() 的扩展版本。在结果数组中不仅以数字索引（字段编号）方式存放数据，还用关联索引（字段名）存储数据。它默认存储两个索引。

> 注意: 此函数将 NULL 字段设置为 PHP `null` 值。

使用 pg_fetch_array() 并不比 pg_fetch_row() 慢的明显，而且在使用中提供了更大的方便。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。
`row`

  要获取的结果中的行号。行从 0 向上编号。如果省略或为 `null`，则获取下一行。

`mode`
  An optional parameter that controls how the returned array is indexed. `mode` is a constant and can take the following values: `PGSQL_ASSOC`, `PGSQL_NUM` and `PGSQL_BOTH`. Using `PGSQL_NUM`, the function will return an array with numerical indices, using `PGSQL_ASSOC` it will return only associative indices while `PGSQL_BOTH` will return both numerical and associative indices.

### 返回值

数字方式（从 0 开始）或关联方式（按字段名索引）或两者共同索引的 array。array 中的每个值都表示为 string。数据库 `NULL` 值作为 `null` 返回。

如果 `row` 超过集合中的行数、没有更多行或任何其他错误，则返回 `false`。从 SELECT 以外的查询结果中获取也将返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 pg_fetch_array() 示例

    <?php

    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "An error occurred.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT author, email FROM authors");
    if (!$result) {
      echo "An error occurred.\n";
      exit;
    }

    $arr = pg_fetch_array($result, 0, PGSQL_NUM);
    echo $arr[0] . " <- Row 1 Author\n";
    echo $arr[1] . " <- Row 1 E-mail\n";

    // The row parameter is optional; NULL can be passed instead,
    // to pass a result_type.  Successive calls to pg_fetch_array
    // will return the next row.
    $arr = pg_fetch_array($result, NULL, PGSQL_ASSOC);
    echo $arr["author"] . " <- Row 2 Author\n";
    echo $arr["email"] . " <- Row 2 E-mail\n";

    $arr = pg_fetch_array($result);
    echo $arr["author"] . " <- Row 3 Author\n";
    echo $arr[1] . " <- Row 3 E-mail\n";

    ?>

### 参见

- pg_fetch_row() - 提取一行作为枚举数组
- pg_fetch_object() - 获取一行作为对象
- pg_fetch_result() - 从结果实例返回值

# pg_fetch_assoc

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_fetch_assoc — 获取一行作为关联数组

### 说明

function pg_fetch_assoc(PgSql\Result `$result`, ?int `$row` = `null`): array|false

pg_fetch_assoc() 返回与所提取的行（元组/记录）相一致的关联数组。

pg_fetch_assoc() 等同于调用 `PGSQL_ASSOC` 作为第三个参数的 pg_fetch_array()。其仅返回关联数组。如果需要数字索引，使用 pg_fetch_row()。

> 注意: 此函数将 NULL 字段设置为 PHP `null` 值。

使用 pg_fetch_assoc() 并不比 pg_fetch_row() 慢的明显，而且在使用中提供了更大的方便。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。
`row`

  要获取的结果中的行号。行从 0 向上编号。如果省略或为 `null`，则获取下一行。

### 返回值

关联方式（按字段名）的 array。array 中的每个值都表示为 string。数据库 `NULL` 值作为 `null` 返回。

如果 `row` 超过集合中的行数、没有更多行或任何其他错误，则返回 `false`。从 SELECT 以外的查询结果中获取也将返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 pg_fetch_assoc() 示例

    <?php
    $conn = pg_connect("dbname=publisher");
    if (!$conn) {
      echo "An error occurred.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT id, author, email FROM authors");
    if (!$result) {
      echo "An error occurred.\n";
      exit;
    }

    while ($row = pg_fetch_assoc($result)) {
      echo $row['id'];
      echo $row['author'];
      echo $row['email'];
    }
    ?>

### 参见

- pg_fetch_row() - 提取一行作为枚举数组
- pg_fetch_array() - 获取一行作为数组
- pg_fetch_object() - 获取一行作为对象
- pg_fetch_result() - 从结果实例返回值

# pg_fetch_object

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_object — 获取一行作为对象

### 说明

function pg_fetch_object(
PgSql\Result `$result`,
?int `$row` = `null`,
string `$class` = "stdClass",
array `$constructor_args` = []
): object|false

pg_fetch_object() 返回对象，该对象的属性对应于获取的行的字段名称。它可以选择实例化特定类的对象，并将参数传递给该类的构造方法。

> 注意: 此函数将 NULL 字段设置为 PHP `null` 值。

在速度方面，该函数与 pg_fetch_array() 相同，并且几乎与 pg_fetch_row() 一样快（差别不大）。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。
`row`

  要获取的结果中的行号。行从 0 向上编号。如果省略或为 `null`，则获取下一行。

`class`

  要实例化、设置属性并返回的类的名称。如果未指定，则返回 stdClass 对象。

`constructor_args`

  要传递给 `class` 对象的构造方法的可选参数 array。

### 返回值

结果中的每个字段名称都有在 object 中对应的属性。数据库 `NULL` 值作为 `null` 返回。

如果 `row` 超过集合中的行数、没有更多行或任何其他错误，则返回 `false`。

### 错误／异常

当 `constructor_args` 非空而类没有构造方法时，会抛出 ValueError。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | 当 `constructor_args` 非空而类没有构造方法时，现在会抛出 ValueError 异常；之前抛出 Exception。
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 pg_fetch_object() 示例

    <?php

    $database = "store";

    $db_conn = pg_connect("host=localhost port=5432 dbname=$database");
    if (!$db_conn) {
      echo "Failed connecting to postgres database $database\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);

    ?>

### 参见

- pg_query() - 执行查询
- pg_fetch_array() - 获取一行作为数组
- pg_fetch_assoc() - 获取一行作为关联数组
- pg_fetch_row() - 提取一行作为枚举数组
- pg_fetch_result() - 从结果实例返回值

# pg_fetch_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_fetch_result — 从结果实例返回值

### 说明

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() 返回 PgSql\Result 实例中特定行和字段（列）的值。

> 注意:

> 此函数过去称为 pg_result()。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。
`row`

  要获取的结果中的行号。行从 0 向上编号。如果省略，则获取下一行。

`field`

  表示要获取的字段（列）名的 string，否则为表示要获取的字段编号的 int。字段从 0 向上编号。

### 返回值

布尔值返回为 "t" 或 "f"。所有其它类型，包括数组，都以字符串形式返回，其格式与 psql 程序中的 PostgreSQL 默认方式相同。数据库 `NULL` 值作为 `null` 返回。

如果 `row` 超过集合中的行数或任何其他错误，则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | `row` 现在可为 null。
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 pg_fetch_result() 示例

    <?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 "First field in the second row is: ", $val, "\n";
    ?>

以上示例会输出：

    First field in the second row is: 2

### 参见

- pg_query() - 执行查询
- pg_fetch_array() - 获取一行作为数组

# pg_fetch_row

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_row — 提取一行作为枚举数组

### 说明

function pg_fetch_row(PgSql\Result `$result`, ?int `$row` = `null`, int `$mode` = `PGSQL_NUM`): array|false

pg_fetch_row() 根据指定 `result` 实例提取一行数据（记录）作为数组返回。每个得到的列依次存放在数组中，偏移量从 0 开始。

> 注意: 此函数将 NULL 字段设置为 PHP `null` 值。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。
`row`

  要获取的结果中的行号。行从 0 向上编号。如果省略或为 `null`，则获取下一行。

`mode`
  An optional parameter that controls how the returned array is indexed. `mode` is a constant and can take the following values: `PGSQL_ASSOC`, `PGSQL_NUM` and `PGSQL_BOTH`. Using `PGSQL_NUM`, the function will return an array with numerical indices, using `PGSQL_ASSOC` it will return only associative indices while `PGSQL_BOTH` will return both numerical and associative indices.

### 返回值

array，从 0 向上索引，每个值表示为一个 string。数据库 `NULL` 值作为 `null` 返回。

返回的数组和提取的行相一致。如果没有更多行 `row` 可提取，则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 pg_fetch_row() 示例

    <?php

    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "An error occurred.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT author, email FROM authors");
    if (!$result) {
      echo "An error occurred.\n";
      exit;
    }

    while ($row = pg_fetch_row($result)) {
      echo "Author: $row[0]  E-mail: $row[1]";
      echo "<br />\n";
    }

    ?>

### 参见

- pg_query() - 执行查询
- pg_fetch_array() - 获取一行作为数组
- pg_fetch_object() - 获取一行作为对象
- pg_fetch_result() - 从结果实例返回值

# pg_field_is_null

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_is_null — 测试字段是否为 SQL `NULL`

### 说明

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() 测试 PgSql\Result 实例中的字段是否为 SQL `NULL`。

> 注意:

> 此函数过去称为 pg_fieldisnull()。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。
`row`

  要获取的结果中的行号。行从 0 向上编号。如果省略或，则获取当前行。

`field`

  作为 int 的字段编号（从 0 开始）或作为 string 的字段名。

### 返回值

如果指定行中的字段为 SQL `NULL`，则返回 `1`，否则返回 `0`。如果该行超出范围或发生任何其他错误，则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | `row` 现在可为 null。
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 pg_field_is_null() 示例

    <?php
      $dbconn = pg_connect("dbname=publisher") or die ("Could not connect");
      $res = pg_query($dbconn, "select * from authors where author = 'Orwell'");
      if ($res) {
          if (pg_field_is_null($res, 0, "year") == 1) {
              echo "The value of the field year is null.\n";
          }
          if (pg_field_is_null($res, 0, "year") == 0) {
              echo "The value of the field year is not null.\n";
        }
     }
    ?>

# pg_field_name

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_name — 返回字段名

### 说明

function pg_field_name(PgSql\Result `$result`, int `$field`): string

pg_field_name() 返回在指定 `result` 实例中占据 `field` 字段的字段名。字段编号从 0 开始。

> 注意:

> 此函数过去称为 pg_fieldname()。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。
`field`

  字段编号，从 0 开始。

### 返回值

字段名。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 获取字段信息

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      $res = pg_query($dbconn, "select * from authors where author = 'Orwell'");
      $i = pg_num_fields($res);
      for ($j = 0; $j < $i; $j++) {
          echo "column $j\n";
          $fieldname = pg_field_name($res, $j);
          echo "fieldname: $fieldname\n";
          echo "printed length: " . pg_field_prtlen($res, $fieldname) . " characters\n";
          echo "storage length: " . pg_field_size($res, $j) . " bytes\n";
          echo "field type: " . pg_field_type($res, $j) . " \n\n";
      }
    ?>

以上示例会输出：

    column 0
    fieldname: author
    printed length: 6 characters
    storage length: -1 bytes
    field type: varchar

    column 1
    fieldname: year
    printed length: 4 characters
    storage length: 2 bytes
    field type: int2

    column 2
    fieldname: title
    printed length: 24 characters
    storage length: -1 bytes
    field type: varchar

### 参见

- pg_field_num() - 返回名为 field 的字段编号

# pg_field_num

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_num — 返回名为 field 的字段编号

### 说明

function pg_field_num(PgSql\Result `$result`, string `$field`): int

pg_field_num() 将返回与指定 `result` 实例中的 `field` 对应的字段编号。

> 注意:

> 本函数以前的名字为 pg_fieldnum()。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。
`field`

  字段名。 指定的名称被视为 SQL 命令中的标识符，也就是说，除非用双引号引起来，否则它将是大写（downcased）。

### 返回值

字段编号（从 0 开始），错误时为 -1。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 获取字段信息

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      $res = pg_query($dbconn, "select author, year, title from authors where author = 'Orwell'");

      echo "Column 'title' is field number: ", pg_field_num($res, 'title');
    ?>

以上示例会输出：

    Column 'title' is field number: 2

### 参见

- pg_field_name() - 返回字段名

# pg_field_prtlen

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_prtlen — 返回打印的长度

### 说明

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() 返回 PostgreSQL `result` 中特定值的实际打印长度（字符数）。行编号从 0 开始。此函数将在出错时返回 `false`。

`field_name_or_number` 可以传递 int 或 string。如果它作为 int 传递，PHP 将其视为字段号，否则视为字段名。

请参阅 pg_field_name() 页面中给出的示例。

> 注意:

> 本函数以前的名字为 pg_fieldprtlen()。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。
`row`

  结果中的行号。行从 0 向上编号。如果省略，则获取当前行。

### 返回值

字段打印的长度。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | `row` 现在可为 null。
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 获取字段的信息

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      $res = pg_query($dbconn, "select * from authors where author = 'Orwell'");
      $i = pg_num_fields($res);
      for ($j = 0; $j < $i; $j++) {
          echo "column $j\n";
          $fieldname = pg_field_name($res, $j);
          echo "fieldname: $fieldname\n";
          echo "printed length: " . pg_field_prtlen($res, $fieldname) . " characters\n";
          echo "storage length: " . pg_field_size($res, $j) . " bytes\n";
          echo "field type: " . pg_field_type($res, $j) . " \n\n";
      }
    ?>

以上示例会输出：

    column 0
    fieldname: author
    printed length: 6 characters
    storage length: -1 bytes
    field type: varchar

    column 1
    fieldname: year
    printed length: 4 characters
    storage length: 2 bytes
    field type: int2

    column 2
    fieldname: title
    printed length: 24 characters
    storage length: -1 bytes
    field type: varchar

### 参见

- pg_field_size() - 返回指定字段的内部存储大小

# pg_field_size

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_size — 返回指定字段的内部存储大小

### 说明

function pg_field_size(PgSql\Result `$result`, int `$field`): int

pg_field_size() 返回指定 PostgreSQL `result` 中字段编号的内部存储大小（以字节为单位）。

> 注意:

> 本函数以前的名字为 pg_fieldsize()。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。
`field`

  字段编号，从 0 开始。

### 返回值

内部字段存储大小（以字节为单位）。-1 表示可变长度字段。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 获取字段信息

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      $res = pg_query($dbconn, "select * from authors where author = 'Orwell'");
      $i = pg_num_fields($res);
      for ($j = 0; $j < $i; $j++) {
          echo "column $j\n";
          $fieldname = pg_field_name($res, $j);
          echo "fieldname: $fieldname\n";
          echo "printed length: " . pg_field_prtlen($res, $fieldname) . " characters\n";
          echo "storage length: " . pg_field_size($res, $j) . " bytes\n";
          echo "field type: " . pg_field_type($res, $j) . " \n\n";
      }
    ?>

以上示例会输出：

    column 0
    fieldname: author
    printed length: 6 characters
    storage length: -1 bytes
    field type: varchar

    column 1
    fieldname: year
    printed length: 4 characters
    storage length: 2 bytes
    field type: int2

    column 2
    fieldname: title
    printed length: 24 characters
    storage length: -1 bytes
    field type: varchar

### 参见

- pg_field_prtlen() - 返回打印的长度
- pg_field_type() - 返回相应字段编号的类型名称

# pg_field_table

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

pg_field_table — Returns the name or oid of the tables field

### 说明

function pg_field_table(PgSql\Result `$result`, int `$field`, bool `$oid_only` = `false`): string|int|false

pg_field_table() returns the name of the table that field belongs to, or the table's oid if `oid_only` is `true`.

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。
`field`

  Field number, starting from 0.

`oid_only`

  By default the tables name that field belongs to is returned but if `oid_only` is set to `true`, then the oid will instead be returned.

### 返回值

On success either the fields table name or oid, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 Getting table information about a field

    <?php
    $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

    $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));
    ?>

以上示例的输出类似于：

    foo
    14379580

    bool(false)

### 注释

> 注意:

> Returning the oid is much faster than returning the table name because fetching the table name requires a query to the database system table.

### 参见

- pg_field_name() - 返回字段名
- pg_field_type() - 返回相应字段编号的类型名称

# pg_field_type

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_type — 返回相应字段编号的类型名称

### 说明

function pg_field_type(PgSql\Result `$result`, int `$field`): string

pg_field_type() 返回字符串，其中包含指定 `result` 实例中指定 `field` 的基本类型名称。

> 注意:

> 如果字段使用 PostgreSQL domain（而不是基本类型），则返回的是 domain 的底层类型名称，而不是 domain 本身的名称。

> 注意:

> 本函数以前的名字为 pg_fieldtype()。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。
`field`

  字段编号，从 0 开始。

### 返回值

包含字段类型的基本名称的 string。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 获取字段信息

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      // 假设 'title' 是 varchar 类型
      $res = pg_query($dbconn, "select title from authors where author = 'Orwell'");

      echo "Title field type: ", pg_field_type($res, 0);
    ?>

以上示例会输出：

    Title field type: varchar

### 参见

- pg_field_prtlen() - 返回打印的长度
- pg_field_name() - 返回字段名
- pg_field_type_oid() - Returns the type ID (OID) for the corresponding field number

# pg_field_type_oid

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_field_type_oid — Returns the type ID (OID) for the corresponding field number

### 说明

function pg_field_type_oid(PgSql\Result `$result`, int `$field`): string|int

pg_field_type_oid() returns an integer containing the OID of the base type of the given `field` in the given `result` instance.

You can get more information about the field type by querying PostgreSQL's `pg_type` system table using the OID obtained with this function. The PostgreSQL format_type() function will convert a type OID into an SQL standard type name.

> 注意:

> If the field uses a PostgreSQL domain (rather than a basic type), it is the OID of the domain's underlying type that is returned, rather than the OID of the domain itself.

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。
`field`

  Field number, starting from 0.

### 返回值

The OID of the field's base type.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 Getting information about fields

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      // Assume 'title' is a varchar type
      $res = pg_query($dbconn, "select title from authors where author = 'Orwell'");

      echo "Title field type OID: ", pg_field_type_oid($res, 0);
    ?>

以上示例会输出：

    Title field type OID: 1043

### 参见

- pg_field_type() - 返回相应字段编号的类型名称
- pg_field_prtlen() - 返回打印的长度
- pg_field_name() - 返回字段名

# pg_flush

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_flush — 刷新链接中已处理的数据查询

### 说明

function pg_flush(PgSql\Connection `$connection`): int|bool

pg_flush() 刷新任何已经处理的等待发送到链接的数据查询。

### 参数

`connection`
  PgSql\Connection 实例。

### 返回值

如果刷新成功或者没有数据等待刷新返回 `true` ， 如果返回 `0` 为部分刷新或者更多未被刷新,刷新失败为 `false`

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

# pg_free_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_free_result — 释放查询结果占用的内存

### 说明

function pg_free_result(PgSql\Result `$result`): bool

pg_free_result() 释放与指定 PgSql\Result 实例关联的内存和数据。

仅当脚本执行期间的内存消耗成为问题时才需要调用此函数。否则，所有结果内存将在脚本结束时自动释放。

> 注意:

> 本函数以前的名字为 pg_freeresult()。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 pg_free_result() 示例

    <?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 "First field in the second row is: ", $val, "\n";

    pg_free_result($res);
    ?>

以上示例会输出：

    First field in the second row is: 2

### 参见

- pg_query() - 执行查询
- pg_query_params() - Submits a command to the server and waits for the result, with the ability to pass parameters separately from the SQL command text
- pg_execute() - Sends a request to execute a prepared statement with given parameters, and waits for the result
- 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 — 获取 SQL NOTIFY 消息

### 说明

function pg_get_notify(PgSql\Connection `$connection`, int `$mode` = `PGSQL_ASSOC`): array|false

pg_get_notify() 取得 SQL 命令 `NOTIFY` 生成的消息。要接收通知，必须发送 SQL 命令 `LISTEN`。

### 参数

`connection`
  PgSql\Connection 实例。
`mode`
  An optional parameter that controls how the returned array is indexed. `mode` is a constant and can take the following values: `PGSQL_ASSOC`, `PGSQL_NUM` and `PGSQL_BOTH`. Using `PGSQL_NUM`, the function will return an array with numerical indices, using `PGSQL_ASSOC` it will return only associative indices while `PGSQL_BOTH` will return both numerical and associative indices.

### 返回值

包含 `NOTIFY` 消息名称和后端 PID 的 array。如果服务器支持，该数组还包含服务器版本和有效负载。否则，如果没有 `NOTIFY` 正在等待，则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 PostgreSQL NOTIFY 消息

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "An error occurred.\n";
      exit;
    }

    // 从其它进程监听 'author_updated' 消息
    pg_query($conn, 'LISTEN author_updated;');
    $notify = pg_get_notify($conn);
    if (!$notify) {
      echo "No messages\n";
    } else {
      print_r($notify);
    }
    ?>

### 参见

- pg_get_pid() - 获取后端的进程 ID

# pg_get_pid

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_get_pid — 获取后端的进程 ID

### 说明

function pg_get_pid(PgSql\Connection `$connection`): int

pg_get_pid() 取得后端（数据库服务器进程）的 PID。PID 用来确定通过 pg_get_notify() 接收到的 `NOTIFY` 消息，是否是其它进程发送的。

### 参数

`connection`
  PgSql\Connection 实例。

### 返回值

后端数据库进程 ID。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 PostgreSQL 后端 PID

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "An error occurred.\n";
      exit;
    }

    // Backend process PID. Use PID with pg_get_notify()
    $pid = pg_get_pid($conn);
    ?>

### 参见

- pg_get_notify() - 获取 SQL NOTIFY 消息

# pg_get_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_get_result — 取得异步查询结果

### 说明

function pg_get_result(PgSql\Connection `$connection`): PgSql\Result|false

pg_get_result() 从由 pg_send_query()、pg_send_query_params() 或 pg_send_execute() 执行的异步查询中获取 PgSql\Result 实例。

pg_send_query() 和其它异步查询函数可以向 PostgreSQL 服务器发送多个查询，而 pg_get_result() 则用来逐个获取查询结果。

### 参数

`connection`
  PgSql\Connection 实例。

### 返回值

PgSql\Result 实例，或者没有更多查询结果，则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在返回 PgSql\Result 实例，之前返回 resource
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_get_result() 示例

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from authors; select count(*) from authors;");
      }

      $res1 = pg_get_result($dbconn);
      echo "First call to pg_get_result(): $res1\n";
      $rows1 = pg_num_rows($res1);
      echo "$res1 has $rows1 records\n\n";

      $res2 = pg_get_result($dbconn);
      echo "Second call to pg_get_result(): $res2\n";
      $rows2 = pg_num_rows($res2);
      echo "$res2 has $rows2 records\n";
    ?>

以上示例会输出：

    First call to pg_get_result(): Resource id #3
    Resource id #3 has 3 records

    Second call to pg_get_result(): Resource id #4
    Resource id #4 has 1 records

### 参见

- pg_send_query() - 发送异步查询

# pg_host

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_host — 返回和某连接关联的主机名

### 说明

function pg_host(?PgSql\Connection `$connection` = `null`): string

pg_host() 返回指定的 PostgreSQL `connection` 实例所连接到的主机名称。

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is `null`, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

### 返回值

string, 包含 `connection` 的主机名，或错误时为空字符串。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。
8.0.0 | `connection` 现在可为 null。

### 示例

示例 #1 pg_host() 示例

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       print "Successfully connected to: " . pg_host($pgsql_conn) . "<br/>\n";
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

### 参见

- pg_connect() - 打开 PostgreSQL 连接
- pg_pconnect() - 打开一个持久的 PostgreSQL 连接

# pg_insert

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_insert — 将数组插入到表中

### 说明

function pg_insert(
PgSql\Connection `$connection`,
string `$table_name`,
array `$values`,
int `$flags` = `PGSQL_DML_EXEC`
): PgSql\Result|string|bool

pg_insert() 将 `values` 中的值插入到由 `table_name` 指定的表中。

如果指定 `flags`，则 pg_convert() 使用指定 flag 应用于 `values`。

默认情况下 pg_insert() 传递原始值。值必须转义或必须在 `flags` 中指定 `PGSQL_DML_ESCAPE` flag。`PGSQL_DML_ESCAPE` 引用并转义参数/标识符。因此，表/列名称变得区分大小写。

注意转义和预处理查询都不能保护 LIKE 查询、JSON、Array、Regex 等，这些参数要根据上下文来处理。即转义/验证值。

### 参数

`connection`
  PgSql\Connection 实例。
`table_name`

  要插入记录的表名。表 `table_name` 中的列必须至少要有 `values` 中的单元那么多。

`values`

  array，其键是表 `table_name` 中的字段名称，其值是要插入的匹配行。

`flags`

  任意数量的 `PGSQL_CONV_OPTS`、`PGSQL_DML_NO_CONV`、`PGSQL_DML_ESCAPE`、`PGSQL_DML_EXEC`、`PGSQL_DML_ASYNC` 或 `PGSQL_DML_STRING` 的组合。当 `PGSQL_DML_STRING` 是 `flags` 的一部分，然后将返回查询字符串。当设置了 `PGSQL_DML_NO_CONV` 或 `PGSQL_DML_ESCAPE` 时，不会在内部调用 pg_convert()。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。如果通过 `flags` 传递 `PGSQL_DML_STRING`，成功时返回 string。

### 错误／异常

当指定的表无效时，会抛出 ValueError。

当字段的值或类型不能正确匹配 PostgreSQL的类型时，会抛出 ValueError 或 TypeError。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | 当指定的表无效时，现在会抛出 ValueError 错误；之前触发 `E_WARNING`。
8.3.0 | 当字段的值或类型不能正确匹配 PostgreSQL 的类型时，现在会抛出 ValueError 或 TypeError 错误；之前触发 `E_WARNING`。
8.1.0 | 现在返回 PgSql\Result 实例，之前返回 resource
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_insert() 示例

    <?php
      $dbconn = pg_connect('dbname=foo');
      // 在某种程度上安全，因为所有值都转义了。
      // 然而 PostgreSQL 支持 JSON/Array。无论是
      // 转义还是预处理都不安全。
      $res = pg_insert($dbconn, 'post_log', $_POST, PGSQL_DML_ESCAPE);
      if ($res) {
          echo "POST data is successfully logged\n";
      } else {
          echo "User must have sent wrong inputs\n";
      }
    ?>

### 参见

- pg_convert() - 将关联的数组值转换为适合 SQL 语句的格式

# pg_jit

(PHP 8 >= 8.4.0)

pg_jit — Returns the JIT information of the server

### 说明

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.

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is `null`, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

### 返回值

Returns an array containing the JIT information of the server.

### 参见

- pg_version() - Returns an array with client, protocol and server version (when available)

# pg_last_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_last_error — 得到某连接的最后一条错误信息

### 说明

function pg_last_error(?PgSql\Connection `$connection` = `null`): string

pg_last_error() 返回指定 `connection` 的最后一条错误信息。

错误信息可能会被调用的 PostgreSQL(libpq) 内部函数覆盖。如果 PostgreSQL 的内部模块函数产生了多个错误，则可能不能返回适当的错误信息。

使用 pg_result_error()、pg_result_error_field()、pg_result_status() 和 pg_connection_status() 用于更好的错误处理。

> 注意:

> 本函数以前的名字为 pg_errormessage()。

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is `null`, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

### 返回值

string，包含指定 `connection` 的最后一条错误消息。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。
8.0.0 | `connection` 现在可为 null。

### 示例

示例 #1 pg_last_error() 示例

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      // 查询失败
      $res = pg_query($dbconn, "select * from doesnotexist");

      echo pg_last_error($dbconn);
    ?>

### 参见

- pg_result_error() - 获得跟 result 相关的错误信息
- pg_result_error_field() - Returns an individual field of an error report

# pg_last_notice

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

pg_last_notice — 返回 PostgreSQL 服务器最新一条公告信息

### 说明

function pg_last_notice(PgSql\Connection `$connection`, int `$mode` = `PGSQL_NOTICE_LAST`): array|string|bool

pg_last_notice() 返回由 `connection` 指定的 PostgreSQL 服务器最新的一条 notice 信息。PostgreSQL 服务器在某些情况下会发送 notice 信息，例如在表里创建 `SERIAL` 列。

使用 pg_last_notice()，只要检查 notice 是否和该事务有关，就可以避免提交无用的查询。

可以通过在 php.ini 中把 `pgsql.ignore_notice` 置为 1 来使 notice 信息追踪成为可选项。

可以通过在 php.ini 中把 `pgsql.log_notice` 置为 0 来使 notice 信息日志成为可选项。 除非 `pgsql.ignore_notice` 为 0，否则 notice 信息不能被日志记录。

### 参数

`connection`
  PgSql\Connection 实例。
`mode`

  `PGSQL_NOTICE_LAST`（返回最后的 notice）、`PGSQL_NOTICE_ALL`（返回所有 notice）或 `PGSQL_NOTICE_CLEAR`（清除 notice）之一。

### 返回值

在指定 `connection` 使用 `PGSQL_NOTICE_LAST`，返回包含最后一条 notice 的 string，使用 `PGSQL_NOTICE_ALL` 时为 array，使用 `PGSQL_NOTICE_CLEAR` 时为 bool。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。
7.1.0 | 新增 `mode` 参数。

### 示例

示例 #1 pg_last_notice() 示例

    <?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;
    ?>

以上示例会输出：

    CREATE TABLE will create implicit sequence "test_id_seq" for "serial" column "test.id"

### 参见

- pg_query() - 执行查询
- pg_last_error() - 得到某连接的最后一条错误信息

# pg_last_oid

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_last_oid — 返回上一条记录的 oid

### 说明

function pg_last_oid(PgSql\Result `$result`): string|int|false

pg_last_oid() 用于检索分配给插入行的 OID。

从 PostgreSQL 7.2 开始 OID 字段成为可选项，在 PostgreSQL 8.1 中默认不存在。如果表中没有定义 OID 字段，程序员必须用 pg_result_status() 检查记录是否成功插入。

要在插入的行中获取 `SERIAL` 字段的值，必须使用 PostgreSQL `CURRVAL` 函数，命名需要最后一个值的序列。如果序列名称未知，则需要 `pg_get_serial_sequence` PostgreSQL 8.0 函数。

PostgreSQL 8.1 有一个函数 `LASTVAL`，它返回会话中最近使用的序列的值。这避免了对序列、表或列的命名需求。

> 注意:

> 本函数以前的名字为 pg_getlastoid()。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。

### 返回值

int 或 string，包含分配给指定 `connection` 中最近插入的行的 OID，如果出错或没有可用的 OID，则为 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 pg_last_oid() 示例

    <?php
      // 连接到数据库
      pg_connect("dbname=mark host=localhost");

      // 创建示例表
      pg_query("CREATE TABLE test (a INTEGER) WITH OIDS");

      // 插入一些数据
      $res = pg_query("INSERT INTO test VALUES (1)");

      $oid = pg_last_oid($res);
    ?>

### 参见

- pg_query() - 执行查询
- pg_result_status() - 获得查询结果的状态

# pg_lo_close

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_close — 关闭大对象

### 说明

function pg_lo_close(PgSql\Lob `$lob`): bool

pg_lo_close() 关闭大对象。

要使用大对象接口，必须将其封装在事务块中。

> 注意:

> 本函数以前的名字为 pg_loclose()。

### 参数

`lob`
  通过 pg_lo_open() 返回的 PgSql\Lob 实例。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `lob` 接受 PgSql\Lob 实例，之前接受 resource。

### 示例

示例 #1 pg_lo_close() 示例

    <?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, "large object data");
       pg_lo_close($handle);
       pg_query($database, "commit");
    ?>

### 参见

- pg_lo_open() - 打开大对象
- pg_lo_create() - 新建大对象
- pg_lo_import() - 将文件导入为大型对象

# pg_lo_create

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_create — 新建大对象

### 说明

function pg_lo_create(PgSql\Connection `$connection` = ?, mixed `$object_id` = ?): int
function pg_lo_create(mixed `$object_id`): int

pg_lo_create() 新建大对象并返回大对象的 oid。不支持 PostgreSQL 访问模式 `INV_READ` 和 `INV_WRITE`。 创建的对象始终以读写方式访问。

要使用大对象接口，必须将其封装在一个事务块中。

不使用大对象接口（没有访问控制，使用起来很麻烦），试试 PostgreSQL 的 bytea 列类型和 pg_escape_bytea()。

> 注意:

> 本函数以前的名字为 pg_locreate()。

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is unspecified, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

`object_id`

  如果指定 `object_id`，该函数将尝试使用此 id 创建大对象，否则服务器将分配一个空闲对象 id。

### 返回值

大对象 OID， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_lo_create() 示例

    <?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, "large object data");
       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 — 将大型对象导出到文件

### 说明

function pg_lo_export(PgSql\Connection `$connection` = ?, int `$oid`, string `$filename`): bool

pg_lo_export() 在 PostgreSQL 数据库中获取一个大对象并将其内容保存到本地文件系统上的文件中。

要使用大型对象（lo）接口，需要将其放置在事务块中。

> 注意:

> 本函数以前的名字为 pg_loexport()。

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is unspecified, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

`oid`

  要导出的数据库里的大型对象的 OID。

`filename`

  要导出的数据库里的大型对象的文件在客户端上完整路径和文件名。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_lo_export() 示例

    <?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, "large object data");
       pg_lo_close($handle);
       pg_lo_export($database, $oid, '/tmp/lob.dat');
       pg_query($database, "commit");
    ?>

### 参见

- pg_lo_import() - 将文件导入为大型对象

# pg_lo_import

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_import — 将文件导入为大型对象

### 说明

function pg_lo_import(PgSql\Connection `$connection` = ?, string `$filename`, int|string `$oid` = ?): int|string|false

pg_lo_import() 使用文件系统上的文件作为其数据源从而在数据库中创建新的大对象。

要使用大型对象接口，需要将其放置在事务块中。

> 注意:

> 本函数以前的名字为 pg_loimport()。

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is unspecified, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

`filename`

  在客户端文件系统上读取大对象数据的文件的完整路径和文件名。

`oid`

  如果指定了 `oid`，该函数将使用此 id 尝试创建大对象，否则服务器将分配空闲对象 id。该参数依赖于 PostgreSQL 8.1 中首次出现的功能。

### 返回值

新创建大对象的 OID， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_lo_import() 示例

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_import($database, '/tmp/lob.dat');
       pg_query($database, "commit");
    ?>

### 参见

- pg_lo_export() - 将大型对象导出到文件
- pg_lo_open() - 打开大对象

# pg_lo_open

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_open — 打开大对象

### 说明

function pg_lo_open(PgSql\Connection `$connection`, int `$oid`, string `$mode`): PgSql\Lob|false

pg_lo_open() 打开数据库中的大对象并返回 PgSql\Lob 实例，以便对其进行操作。

警告

在关闭 PgSql\Lob 实例之前不要关闭数据库连接。

要使用大对象接口，必须将其封装在一个事务块中。

> 注意:

> 本函数以前的名字为 pg_loopen()。

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is unspecified, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

`oid`

  数据库中大对象的 OID。

`mode`

  可以是只读的“r”、只写的“w”或读写的“rw”。

### 返回值

PgSql\Lob 实例， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在返回 PgSql\Lob 实例；之前返回 resource。
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_lo_open() 示例

    <?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, "large object data");
       pg_lo_close($handle);
       pg_query($database, "commit");
    ?>

### 参见

- pg_lo_close() - 关闭大对象
- pg_lo_create() - 新建大对象

# pg_lo_read

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_read — 读取大对象

### 说明

function pg_lo_read(PgSql\Lob `$lob`, int `$length` = 8192): string|false

pg_lo_read() 从大对象中读取最多 `length` 字节的数据并以 string 返回。

要使用大对象接口，必须将其封装在一个事务块中。

> 注意:

> 本函数以前的名字为 pg_loread()。

### 参数

`lob`
  通过 pg_lo_open() 返回的 PgSql\Lob 实例。
`length`

  可选的要返回的最大字节数。

### 返回值

包含来自大对象的 `length` 字节的 string，或错误时为 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `lob` 接受 PgSql\Lob 实例，之前接受 resource。

### 示例

示例 #1 pg_lo_read() 示例

    <?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;
    ?>

### 参见

- pg_lo_read_all() - 读取整个大对象并直接发送到浏览器

# pg_lo_read_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_read_all — 读取整个大对象并直接发送到浏览器

### 说明

function pg_lo_read_all(PgSql\Lob `$lob`): int

pg_lo_read_all() 读取大对象并在发送完所有待发的 header 之后将其直接发送给浏览器。主要用于发送图片或声音等二进制数据。

要使用大对象接口，必须将其封装在一个事务块中。

> 注意:

> 本函数以前的名字为 pg_loreadall()。

### 参数

`lob`
  通过 pg_lo_open() 返回的 PgSql\Lob 实例。

### 返回值

读取的字节数。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `lob` 接受 PgSql\Lob 实例，之前接受 resource。

### 示例

示例 #1 pg_lo_read_all() 示例

    <?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");
    ?>

### 参见

- pg_lo_read() - 读取大对象

# pg_lo_seek

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_seek — 在大对象中寻找位置

### 说明

function pg_lo_seek(PgSql\Lob `$lob`, int `$offset`, int `$whence` = `SEEK_CUR`): bool

pg_lo_seek() 在 PgSql\Lob 实例中寻找位置。

要使用大对象接口，必须将其封装在一个事务块中。

### 参数

`lob`
  通过 pg_lo_open() 返回的 PgSql\Lob 实例。
`offset`

  要寻找的字节数。

`whence`

  常量 `PGSQL_SEEK_SET`（从对象开始处寻找）、 `PGSQL_SEEK_CUR`（从当前位置寻找） 或 `PGSQL_SEEK_END`（从对象结尾处寻找）之一。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `lob` 接受 PgSql\Lob 实例，之前接受 resource。

### 示例

示例 #1 pg_lo_seek() 示例

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       // 忽略开始的 50000 字节
       pg_lo_seek($handle, 50000, PGSQL_SEEK_SET);
       // 读取接下来的 10000 字节
       $data = pg_lo_read($handle, 10000);
       pg_query($database, "commit");
       echo $data;
    ?>

### 参见

- pg_lo_tell() - 返回当前大型对象的指针位置

# pg_lo_tell

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_tell — 返回当前大型对象的指针位置

### 说明

function pg_lo_tell(PgSql\Lob `$lob`): int

pg_lo_tell() 返回当前大对象的指针位置（从头开始的偏移量）。

要使用大对象接口，必须将其封装在一个事务块中。

### 参数

`lob`
  通过 pg_lo_open() 返回的 PgSql\Lob 实例。

### 返回值

当前查找距离大对象开头的偏移量（字节数）。如果有错误，返回值为负。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `lob` 接受 PgSql\Lob 实例，之前接受 resource。

### 示例

示例 #1 pg_lo_tell() 示例

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       // 忽略开始的 50000 字节
       pg_lo_seek($handle, 50000, PGSQL_SEEK_SET);
       // 查看忽略了多少
       $offset = pg_lo_tell($handle);
       echo "Seek position is: $offset";
       pg_query($database, "commit");
    ?>

以上示例会输出：

    Seek position is: 50000

### 参见

- pg_lo_seek() - 在大对象中寻找位置

# pg_lo_truncate

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_lo_truncate — Truncates a large object

### 说明

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.

### 参数

`lob`
  通过 pg_lo_open() 返回的 PgSql\Lob 实例。
`size`

  The number of bytes to truncate.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `lob` 接受 PgSql\Lob 实例，之前接受 resource。

### 示例

示例 #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;
    ?>

### 参见

- pg_lo_tell() - 返回当前大型对象的指针位置

# pg_lo_unlink

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_unlink — 删除一个大型对象

### 说明

function pg_lo_unlink(PgSql\Connection `$connection`, int `$oid`): bool

pg_lo_unlink() 删除由 `oid` 指定的大型对象。成功时返回 `true`， 或者在失败时返回 `false`。

要使用大型对象（lo）接口，需要将其放置在事务块中。

> 注意:

> 本函数以前的名字为 pg_lounlink()。

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is unspecified, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

`oid`

  数据库中大对象的 OID。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_lo_unlink() 示例

    <?php
       // 要删除的大对象的 OID
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       pg_lo_unlink($database, $doc_oid);
       pg_query($database, "commit");
    ?>

### 参见

- pg_lo_create() - 新建大对象
- pg_lo_import() - 将文件导入为大型对象

# pg_lo_write

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_write — 向大对象写入数据

### 说明

function pg_lo_write(PgSql\Lob `$lob`, string `$data`, ?int `$length` = `null`): int|false

pg_lo_write() 在大对象的当前位置写入数据。

要使用大对象接口，必须将其封装在一个事务块中。

> 注意:

> 本函数以前的名字为 pg_lowrite()。

### 参数

`lob`
  通过 pg_lo_open() 返回的 PgSql\Lob 实例。
`data`

  写入到大对象中的数据。如果 `length` 是 int 并且少于 `data` 的长度，仅会写入 `length` 个字节。

`length`

  可选的最大写入字节数。必须大于零且不大于 `data` 的长度。默认为 `data` 的长度。

### 返回值

写入到大对象的字节数，或出错时为 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `lob` 接受 PgSql\Lob 实例，之前接受 resource。
8.0.0 | `length` 现在可为 null。

### 示例

示例 #1 pg_lo_write() 示例

    <?php
       $doc_oid = 189762345;
       $data = "This will overwrite the start of the large object.";
       $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");
    ?>

### 参见

- pg_lo_create() - 新建大对象
- pg_lo_open() - 打开大对象

# pg_meta_data

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_meta_data — 获得表的元数据

### 说明

function pg_meta_data(PgSql\Connection `$connection`, string `$table_name`, bool `$extended` = `false`): array|false

pg_metadata() 以数组形式返回 `table_name` 的表定义。

### 参数

`connection`
  PgSql\Connection 实例。
`table_name`

  表名。

`extended`

  用于返回扩展元数据的 flag。默认为 `false`。

### 返回值

以 array 形式返回表定义， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 取得表的元数据

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      $meta = pg_meta_data($dbconn, 'authors');
      if (is_array($meta)) {
          echo '<pre>';
          var_dump($meta);
          echo '</pre>';
      }
    ?>

以上示例会输出：

    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)
    }
    }

### 参见

- pg_convert() - 将关联的数组值转换为适合 SQL 语句的格式

# pg_num_fields

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_num_fields — 返回结果中字段的数量

### 说明

function pg_num_fields(PgSql\Result `$result`): int

pg_num_fields() 返回 PgSql\Result 实例中字段（列）的数量。

> 注意:

> 本函数以前的名字为 pg_numfields()。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。

### 返回值

结果中的字段（列）的数量。错误时返回 -1。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 pg_num_fields() 示例

    <?php
    $result = pg_query($conn, "SELECT 1, 2");

    $num = pg_num_fields($result);

    echo $num . " field(s) returned.\n";
    ?>

以上示例会输出：

    2 field(s) returned.

### 参见

- pg_num_rows() - 返回结果中行的数量
- pg_affected_rows() - 返回受影响的记录数（元组）

# pg_num_rows

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_num_rows — 返回结果中行的数量

### 说明

function pg_num_rows(PgSql\Result `$result`): int

pg_num_rows() 返回 PgSql\Result 实例中的行的数量。

> 注意:

> 本函数以前的名字为 pg_numrows()。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。

### 返回值

结果中行的数量。错误时返回 `-1`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 pg_num_rows() 示例

    <?php
    $result = pg_query($conn, "SELECT 1");

    $rows = pg_num_rows($result);

    echo $rows . " row(s) returned.\n";
    ?>

以上示例会输出：

    1 row(s) returned.

### 参见

- pg_num_fields() - 返回结果中字段的数量
- pg_affected_rows() - 返回受影响的记录数（元组）

# pg_options

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_options — 获得和 connection 相关的选项

### 说明

function pg_options(?PgSql\Connection `$connection` = `null`): string

pg_options() 将返回字符串，包含指定 PostgreSQL `connection` 实例的特定选项。

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is `null`, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

### 返回值

包含 `connection` 选项的 string。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。
8.0.0 | `connection` 现在可为 null。

### 示例

示例 #1 pg_options() 示例

    <?php
       $pgsql_conn = pg_connect("dbname=mark host=localhost");
       echo pg_options($pgsql_conn);
    ?>

### 参见

- pg_connect() - 打开 PostgreSQL 连接

# pg_parameter_status

(PHP 5, PHP 7, PHP 8)

pg_parameter_status — Looks up a current parameter setting of the server

### 说明

function pg_parameter_status(PgSql\Connection `$connection` = ?, string `$name`): string|false

Looks up a current parameter setting of the server.

Certain parameter values are reported by the server automatically at connection startup or whenever their values change. pg_parameter_status() can be used to interrogate these settings. It returns the current value of a parameter if known, or `false` if the parameter is not known.

Parameters reported by the server include `server_version`, `server_encoding`, `client_encoding`, `is_superuser`, `session_authorization`, `DateStyle`, `TimeZone`, and `integer_datetimes`. Note that `server_version`, `server_encoding` and `integer_datetimes` cannot change after PostgreSQL startup.

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is unspecified, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

`name`

  Possible `name` values include `server_version`, `server_encoding`, `client_encoding`, `is_superuser`, `session_authorization`, `DateStyle`, `TimeZone`, and `integer_datetimes`. Note that this value is case-sensitive.

### 返回值

A string containing the value of the parameter, `false` on failure or invalid `name`.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_parameter_status() example

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      echo "Server encoding: ", pg_parameter_status($dbconn, "server_encoding");
    ?>

以上示例会输出：

    Server encoding: SQL_ASCII

# pg_pconnect

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_pconnect — 打开一个持久的 PostgreSQL 连接

### 说明

function pg_pconnect(string `$connection_string`, int `$flags` = 0): PgSql\Connection|false

pg_pconnect() 打开一个到 PostgreSQL 数据库的持久连接。返回其它 PostgreSQL 函数所需要的 PgSql\Connection 实例。

如果使用与已有连接相同的 `connection_string` 对 pg_pconnect() 进行第二次调用，则将返回已有连接，除非将 `PGSQL_CONNECT_FORCE_NEW` 传递给 `flags`。

要打开持久连接，php.ini 中的 pgsql.allow_persistent 参数必须为 `"On"`（也是默认值）。最大持久连接数由 php.ini 中的 pgsql.max_persistent 参数定义（默认为 `-1` 表示没有限制）。所有连接的数量可由 php.ini 中的 pgsql.max_links 参数设置。

pg_close() 不能关闭由 pg_pconnect() 打开的持久连接。

### 参数

`connection_string`

  `connection_string` 可以为空以使用所有默认参数，也可以包含一个或多个由空格分隔的参数设置。每个参数设置的形式为 `keyword = value`。等号旁边的空格是可选的。要写入空值或包含空格的值，请用单引号将其括起来，例如，`keyword = 'a value'`。值中的单引号和反斜线必须用反斜线转义，即 `\'` 和 `\\`。

  当前可识别的参数关键字是：`host`、`hostaddr`、`port`、`dbname`、`user`、`password`、`connect_timeout`、`options`、`tty`（已忽略）、`sslmode`、`requiressl`（已弃用以支持 `sslmode`）和 `service`。存在哪些参数取决于 PostgreSQL 版本。

`flags`

  如果传递了 `PGSQL_CONNECT_FORCE_NEW`，则会创建新连接，即使 `connection_string` 与现有连接相同。

### 返回值

成功时返回 PgSql\Connection 实例， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在返回 PgSql\Connection 实例；之前返回 resource。

### 示例

示例 #1 使用 pg_pconnect()

    <?php
    // 连接到名为 "mary" 的数据库
    $dbconn = pg_pconnect("dbname=mary");

    // 连接到主机为 "localhost"，端口为 "5432"， 名为 "mary" 的水库
    $dbconn2 = pg_pconnect("host=localhost port=5432 dbname=mary");

    // 使用用户名和密码连接到主机为 "sheep"，名为 "mary" 的数据库
    $dbconn3 = pg_pconnect("host=sheep port=5432 dbname=mary user=lamb password=foo");

    // 使用用户名和密码连接到主机为 "sheep"，名为 "test" 的数据库
    $conn_string = "host=sheep port=5432 dbname=test user=lamb password=bar";
    $dbconn4 = pg_pconnect($conn_string);
    ?>

### 参见

- pg_connect() - 打开 PostgreSQL 连接
- 持久数据库连接

# pg_ping

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_ping — Ping 数据库连接

### 说明

function pg_ping(?PgSql\Connection `$connection` = `null`): bool

pg_ping() ping 数据库连接，如果中断则尝试重新连接。

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is `null`, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。
8.0.0 | `connection` 现在可为 null。

### 示例

示例 #1 pg_ping() 示例

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "An error occurred.\n";
      exit;
    }

    if (!pg_ping($conn))
      die("Connection is broken\n");
    ?>

### 参见

- pg_connection_status() - 获取连接状态
- pg_connection_reset() - 重置连接（再次连接）

# pg_port

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_port — 返回 connection 相关的端口号

### 说明

function pg_port(?PgSql\Connection `$connection` = `null`): string

pg_port() 返回连接指定 PostgreSQL `connection` 实例的端口号。

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is `null`, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

### 返回值

string，包含 `connection` 连接到的数据库服务器的端口号，错误时为空字符串。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。
8.0.0 | `connection` 现在可为 null。

### 示例

示例 #1 pg_port() 示例

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       print "Successfully connected to port: " . pg_port($pgsql_conn) . "<br/>\n";
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

# pg_prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_prepare — Submits a request to the server to create a prepared statement with the given parameters, and waits for completion

### 说明

function pg_prepare(PgSql\Connection `$connection` = ?, string `$statement_name`, string `$query`): PgSql\Result|false

pg_prepare() creates a prepared statement for later execution with pg_execute() or pg_send_execute(). This feature allows commands that will be used repeatedly to be parsed and planned just once, rather than each time they are executed.

The function creates a prepared statement named `statement_name` from the `query` string, which must contain a single SQL command. `statement_name` may be `""` to create an unnamed statement, in which case any pre-existing unnamed statement is automatically replaced; otherwise it is an error if the statement name is already defined in the current session. If any parameters are used, they are referred to in the `query` as `$1`, `$2`, etc.

Prepared statements for use with pg_prepare() can also be created by executing SQL `PREPARE` statements. (But pg_prepare() is more flexible since it does not require parameter types to be pre-specified.) Also, although there is no PHP function for deleting a prepared statement, the SQL `DEALLOCATE` statement can be used for that purpose.

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is unspecified, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

`statement_name`

  The name to give the prepared statement. Must be unique per-connection. If `""` is specified, then an unnamed statement is created, overwriting any previously defined unnamed statement.

`query`

  The parameterized SQL statement. Must contain only a single statement (multiple statements separated by semi-colons are not allowed). If any parameters are used, they are referred to as `$1`, `$2`, etc.

### 返回值

An PgSql\Result instance on success, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在返回 PgSql\Result 实例，之前返回 resource
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 Using pg_prepare()

    <?php

    // Connect to a database named "mary"
    $dbconn = pg_connect("dbname=mary");

    // Prepare a query for execution
    $result = pg_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');

    // Execute the prepared query.  Note that it is not necessary to escape
    // the string "Joe's Widgets" in any way
    $result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));

    // Execute the same prepared query, this time with a different parameter
    $result = pg_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));

    ?>

### 参见

- pg_execute() - Sends a request to execute a prepared statement with given parameters, and waits for the result
- pg_send_execute() - Sends a request to execute a prepared statement with given parameters, without waiting for the result(s)

# pg_put_copy_data

(PHP 8 >= 8.4.0)

pg_put_copy_data — Send data to the server during a COPY operation

### 说明

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.

### 参数

`connection`
  PgSql\Connection 实例。
`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.

### 返回值

Returns `1` on success, `0` if the data could not be queued (only in non-blocking mode), or `-1` on error.

### 参见

- pg_put_copy_end() - Signal the completion of a COPY operation to the server
- pg_query() - 执行查询

# pg_put_copy_end

(PHP 8 >= 8.4.0)

pg_put_copy_end — Signal the completion of a COPY operation to the server

### 说明

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.

### 参数

`connection`
  PgSql\Connection 实例。
`error`
  If not `null`, the `COPY` operation is forced to fail with the given error message.

### 返回值

Returns `1` on success, `0` if the data could not be queued (only in non-blocking mode), or `-1` on error.

### 参见

- pg_put_copy_data() - Send data to the server during a COPY operation
- pg_query() - 执行查询

# pg_put_line

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_put_line — 向 PostgreSQL 后端发送以 NULL 字符结尾的字符串

### 说明

function pg_put_line(PgSql\Connection `$connection` = ?, string `$query`): bool

pg_put_line() 向 PostgreSQL 后端服务器发送以 NULL 字符结尾的字符串。这需要与 PostgreSQL 的 `COPY FROM` 命令结合使用。

`COPY` 是 PostgreSQL 支持的高速数据加载接口。数据在传入时不会解析且在单个事务中。

使用原生 pg_put_line() 命令的替代方法是使用 pg_copy_from()。这是一个简单得多的接口。

> 注意:

> 应用程序必须明确地在 pg_end_copy() 之前最后一行发送两个字符“\.”来向后端表明发送数据结束。

警告

Use of the pg_put_line() causes most large object operations, including pg_lo_read() and pg_lo_tell(), to subsequently fail. You can use pg_copy_from() and pg_copy_to() instead.

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is unspecified, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

`query`

  要直接发送到 PostgreSQL 后端的一行文本。自动添加 `NULL` 终止符。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_put_line() 示例

    <?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);
    ?>

### 参见

- pg_end_copy() - 与 PostgreSQL 后端同步

# pg_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_query — 执行查询

### 说明

function pg_query(PgSql\Connection `$connection` = ?, string `$query`): PgSql\Result|false

pg_query() 在特定数据库 `connection` 上执行 `query`。pg_query_params() 在大多数情况下应该是首选。

如果发生错误并返回 `false`，那么在连接有效时可以使用 pg_last_error() 函数检索错误的详细信息。

> 注意: 尽管可以省略 `connection`，但不建议这样做，因为可能会导致脚本中的错误难以发现。

> 注意:

> 本函数以前的名字为 pg_exec()。pg_exec() 因为兼容性原因仍可使用，但鼓励用户使用新名称。

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is unspecified, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

`query`

  要执行的 SQL 语句。当多个语句传递给函数时，将作为一个事务自动执行，除非查询字符串中包含明确的 BEGIN/COMMIT 命令。但是，不建议在一个函数调用中使用多个事务。

  警告

  用户提供的数据作为字符串插入值非常危险，很可能导致 SQL 注入漏洞。在大多数情况下，应该首选 pg_query_params()，将用户提供的值作为参数传递，而不是将它们替换为查询字符串。

  任何用户提供的数据，都应该正确转义，然后直接替换为查询字符串。

### 返回值

成功时为 PgSql\Result 实例， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在返回 PgSql\Result 实例，之前返回 resource
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_query() 示例

    <?php

    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "An error occurred.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT author, email FROM authors");
    if (!$result) {
      echo "An error occurred.\n";
      exit;
    }

    while ($row = pg_fetch_row($result)) {
      echo "Author: $row[0]  E-mail: $row[1]";
      echo "<br />\n";
    }

    ?>

示例 #2 使用多条语句的 pg_query()

    <?php

    $conn = pg_pconnect("dbname=publisher");

    // 这些语句将作为一个事务执行

    $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);

    ?>

### 参见

- pg_connect() - 打开 PostgreSQL 连接
- pg_pconnect() - 打开一个持久的 PostgreSQL 连接
- pg_fetch_array() - 获取一行作为数组
- pg_fetch_object() - 获取一行作为对象
- pg_num_rows() - 返回结果中行的数量
- pg_affected_rows() - 返回受影响的记录数（元组）

# pg_query_params

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_query_params — Submits a command to the server and waits for the result, with the ability to pass parameters separately from the SQL command text

### 说明

function pg_query_params(PgSql\Connection `$connection` = ?, string `$query`, array `$params`): PgSql\Result|false

Submits a command to the server and waits for the result, with the ability to pass parameters separately from the SQL command text.

pg_query_params() is like pg_query(), but offers additional functionality: parameter values can be specified separately from the command string proper.

If parameters are used, they are referred to in the `query` string as $1, $2, etc. The same parameter may appear more than once in the `query`; the same value will be used in that case. `params` specifies the actual values of the parameters. A `null` value in this array means the corresponding parameter is SQL `NULL`.

The primary advantage of pg_query_params() over pg_query() is that parameter values may be separated from the `query` string, thus avoiding the need for tedious and error-prone quoting and escaping. Unlike pg_query(), pg_query_params() allows at most one SQL command in the given string. (There can be semicolons in it, but not more than one nonempty command.)

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is unspecified, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

`query`

  The parameterized SQL statement. Must contain only a single statement. (multiple statements separated by semi-colons are not allowed.) If any parameters are used, they are referred to as $1, $2, etc.

  User-supplied values should always be passed as parameters, not interpolated into the query string, where they form possible SQL injection attack vectors and introduce bugs when handling data containing quotes. If for some reason you cannot use a parameter, ensure that interpolated values are properly escaped.

`params`

  An array of parameter values to substitute for the $1, $2, etc. placeholders in the original prepared query string. The number of elements in the array must match the number of placeholders.

  Values intended for `bytea` fields are not supported as parameters. Use pg_escape_bytea() instead, or use the large object functions.

### 返回值

An PgSql\Result instance on success, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在返回 PgSql\Result 实例，之前返回 resource
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 Using pg_query_params()

    <?php
    // Connect to a database named "mary"
    $dbconn = pg_connect("dbname=mary");

    // Find all shops named Joe's Widgets.  Note that it is not necessary to
    // escape "Joe's Widgets"
    $result = pg_query_params($dbconn, 'SELECT * FROM shops WHERE name = $1', array("Joe's Widgets"));

    // Compare against just using pg_query
    $str = pg_escape_string("Joe's Widgets");
    $result = pg_query($dbconn, "SELECT * FROM shops WHERE name = '{$str}'");

    ?>

### 参见

- pg_query() - 执行查询

# pg_result_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_result_error — 获得跟 result 相关的错误信息

### 说明

function pg_result_error(PgSql\Result `$result`): string|false

pg_result_error() 返回和 `result` 实例关联的错误信息。因此用户更有机会可以得到比 pg_last_error() 更好的错误信息。

函数 pg_result_error_field() 可以比 pg_result_error() 给出更多关于 result 错误的细节。

因为如果查询失败 pg_query() 返回 `false`，必须使用 pg_send_query() 和 pg_get_result() 来获取 result 句柄。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。

### 返回值

返回 string。如果没有错误返回空字符串。如果有跟 `result` 参数相关的错误，则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 pg_result_error() 示例

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from doesnotexist;");
      }

      $res1 = pg_get_result($dbconn);
      echo pg_result_error($res1);
    ?>

### 参见

- pg_result_error_field() - Returns an individual field of an error report
- pg_query() - 执行查询
- pg_send_query() - 发送异步查询
- pg_get_result() - 取得异步查询结果
- pg_last_error() - 得到某连接的最后一条错误信息
- pg_last_notice() - 返回 PostgreSQL 服务器最新一条公告信息

# pg_result_error_field

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_result_error_field — Returns an individual field of an error report

### 说明

function pg_result_error_field(PgSql\Result `$result`, int `$field_code`): string|false|null

pg_result_error_field() returns one of the detailed error message fields associated with `result` instance. The error field is specified by the `field_code`.

Because pg_query() and pg_query_params() return `false` if the query fails, you must use pg_send_query() and pg_get_result() to get the result handle.

If you need to get additional error information from failed pg_query() queries, use pg_set_error_verbosity() and pg_last_error() and then parse the result.

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。
`field_code`

  Possible `field_code` values are: `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` or `PGSQL_DIAG_SOURCE_FUNCTION`.

### 返回值

A string containing the contents of the error field, `null` if the field does not exist or `false` on failure.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 pg_result_error_field() example

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      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);
    ?>

### 参见

- pg_result_error() - 获得跟 result 相关的错误信息

# pg_result_memory_size

(PHP 8 >= 8.4.0)

pg_result_memory_size — Returns the amount of memory allocated for a query result

### 说明

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().

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。

### 返回值

Returns the memory amount in bytes.

### 示例

示例 #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);
    ?>

以上示例的输出类似于：

    int(3288)

### 参见

- pg_free_result() - 释放查询结果占用的内存

# pg_result_seek

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_result_seek — 在 result 实例中设定内部行偏移量

### 说明

function pg_result_seek(PgSql\Result `$result`, int `$row`): bool

pg_result_seek() 在 `result` 实例中设定内部行偏移量。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。
`row`

  在 PgSql\Result 实例中将内部偏移量移动到的行。行号从零开始。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 pg_result_seek() 示例

    <?php

    // 连接到数据库
    $conn = pg_pconnect("dbname=publisher");

    // 执行查询
    $result = pg_query($conn, "SELECT author, email FROM authors");

    // 寻找第三行（假设有 3 行）
    pg_result_seek($result, 2);

    // 获取第三行记录
    $row = pg_fetch_row($result);

    ?>

### 参见

- pg_fetch_row() - 提取一行作为枚举数组
- pg_fetch_assoc() - 获取一行作为关联数组
- pg_fetch_array() - 获取一行作为数组
- pg_fetch_object() - 获取一行作为对象
- pg_fetch_result() - 从结果实例返回值

# pg_result_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_result_status — 获得查询结果的状态

### 说明

function pg_result_status(PgSql\Result `$result`, int `$mode` = `PGSQL_STATUS_LONG`): string|int

pg_result_status() 返回 PgSql\Result 实例的状态，或者与 result 相关的 PostgreSQL 命令完成标记。

### 参数

`result`
  PgSql\Result 实例，由 pg_query()、pg_query_params() 或者 pg_execute()（等）返回。
`mode`

  要么指定 `PGSQL_STATUS_LONG` 返回 `result` 的数字状态，要么指定 `PGSQL_STATUS_STRING` 返回 `result` 的命令标记。如果未指定，默认是 `PGSQL_STATUS_LONG`。

### 返回值

如果指定 `PGSQL_STATUS_LONG`，可能返回的值是 `PGSQL_EMPTY_QUERY`、`PGSQL_COMMAND_OK`、`PGSQL_TUPLES_OK`、`PGSQL_TUPLES_CHUNK`、`PGSQL_COPY_OUT`、`PGSQL_COPY_IN`、`PGSQL_BAD_RESPONSE`、`PGSQL_NONFATAL_ERROR` 和 `PGSQL_FATAL_ERROR`。否则，返回包含 PostgreSQL 命令标记的 string。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `result` 参数接受 PgSql\Result 实例，之前接受 resource。

### 示例

示例 #1 pg_result_status() 示例

    <?php

    // Connect to the database
    $conn = pg_pconnect("dbname=publisher");

    // Execute a COPY
    $result = pg_query($conn, "COPY authors FROM STDIN;");

    // Get the result status
    $status = pg_result_status($result);

    // Determine status
    if ($status == PGSQL_COPY_IN)
       echo "Copy began.";
    else
       echo "Copy failed.";

    ?>

以上示例会输出：

    Copy began.

### 参见

- pg_connection_status() - 获取连接状态

# pg_select

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_select — 选择记录

### 说明

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() 根据 `conditions` 数组中的 `field=>value` 值来选择记录。成功的查询返回和 `conditions` 指定的条件相匹配的包括记录和字段的数组。

如果设置了 `flags`，pg_convert() 会按照指定 flag 作用于 `conditions` 上。

如果设置了 `mode`，返回值将以数组形式返回，其中使用 `PGSQL_NUM` 表示索引数组，使用 `PGSQL_ASSOC` 表示关联数组（默认），或者同时使用 `PGSQL_BOTH` 表示两者。

默认情况下 pg_select() 传递原始值。值必须转义或指定 PGSQL_DML_ESCAPE。PGSQL_DML_ESCAPE 引用并转义参数/标识符。因此，表/列名称变得区分大小写。

注意转义和预处理查询都不能保护 LIKE 查询、JSON、Array、Regex 等，这些参数要根据上下文来处理。即转义/验证值。

### 参数

`connection`
  PgSql\Connection 实例。
`table_name`

  要选择记录的表名。

`conditions`

  array，其键是表 `table_name` 中的字段名称，其值是检索记录必须满足的条件。 自 PHP 8.4.0 起，当提供空数组时，不会应用任何条件。 以前，当 `conditions` 参数为空时，函数失败。

`flags`

  任意数量的 `PGSQL_CONV_FORCE_NULL`、`PGSQL_DML_NO_CONV`、`PGSQL_DML_ESCAPE`、`PGSQL_DML_EXEC`、`PGSQL_DML_ASYNC` 或 `PGSQL_DML_STRING` 的组合。当 `PGSQL_DML_STRING` 是 `flags` 的一部分，然后将返回查询字符串。当设置了 `PGSQL_DML_NO_CONV` 或 `PGSQL_DML_ESCAPE` 时，不会在内部调用 pg_convert()。

`mode`

  `PGSQL_ASSOC`、`PGSQL_NUM` 或 `PGSQL_BOTH` 中的一个。 如果设置了 `PGSQL_ASSOC`，返回值将是关联 array；如果设置了 `PGSQL_NUM`，返回值将是索引 array；如果设置了 `PGSQL_BOTH`，返回值将是同时包含关联和索引的 array。

### 返回值

成功时，如果通过 `flags` 传递 `PGSQL_DML_STRING`，返回 string，否则返回 array， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `conditions` 现在是可选的。
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。
7.1.0 | 新增 `mode` 参数。

### 示例

示例 #1 pg_select() 示例

    <?php
      $db = pg_connect('dbname=foo');
      // 在某种程度上安全，因为所有值都转义了。
      // 然而 PostgreSQL 支持 JSON/Array。无论是
      // 转义还是预处理都不安全。
      $rec = pg_select($db, 'post_log', $_POST, PG_DML_ESCAPE);
      if ($rec) {
          echo "Records selected\n";
          var_dump($rec);
      } else {
          echo "User must have sent wrong inputs\n";
      }
    ?>

### 参见

- pg_convert() - 将关联的数组值转换为适合 SQL 语句的格式

# pg_send_execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_execute — Sends a request to execute a prepared statement with given parameters, without waiting for the result(s)

### 说明

function pg_send_execute(PgSql\Connection `$connection`, string `$statement_name`, array `$params`): int|bool

Sends a request to execute a prepared statement with given parameters, without waiting for the result(s).

This is similar to pg_send_query_params(), but the command to be executed is specified by naming a previously-prepared statement, instead of giving a query string. The function's parameters are handled identically to pg_execute(). Like pg_execute(), it will not work on pre-7.4 versions of PostgreSQL.

### 参数

`connection`
  PgSql\Connection 实例。
`statement_name`

  The name of the prepared statement to execute. If "" is specified, then the unnamed statement is executed. The name must have been previously prepared using pg_prepare(), pg_send_prepare() or a `PREPARE` SQL command.

`params`

  An array of parameter values to substitute for the $1, $2, etc. placeholders in the original prepared query string. The number of elements in the array must match the number of placeholders.

### 返回值

Returns `true` on success, `false` or `0` on failure. Use pg_get_result() to determine the query result.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 Using pg_send_execute()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      // Prepare a query for execution
      if (!pg_connection_busy($dbconn)) {
        pg_send_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');
        $res1 = pg_get_result($dbconn);
      }

      // Execute the prepared query.  Note that it is not necessary to escape
      // the string "Joe's Widgets" in any way
      if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Joe's Widgets"));
        $res2 = pg_get_result($dbconn);
      }

      // Execute the same prepared query, this time with a different parameter
      if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));
        $res3 = pg_get_result($dbconn);
      }

    ?>

### 参见

- pg_prepare() - Submits a request to the server to create a prepared statement with the given parameters, and waits for completion
- pg_send_prepare() - Sends a request to create a prepared statement with the given parameters, without waiting for completion
- pg_execute() - Sends a request to execute a prepared statement with given parameters, and waits for the result

# pg_send_prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_prepare — Sends a request to create a prepared statement with the given parameters, without waiting for completion

### 说明

function pg_send_prepare(PgSql\Connection `$connection`, string `$statement_name`, string `$query`): int|bool

Sends a request to create a prepared statement with the given parameters, without waiting for completion.

This is an asynchronous version of pg_prepare(): it returns `true` if it was able to dispatch the request, and `false` if not. After a successful call, call pg_get_result() to determine whether the server successfully created the prepared statement. The function's parameters are handled identically to pg_prepare(). Like pg_prepare(), it will not work on pre-7.4 versions of PostgreSQL.

### 参数

`connection`
  PgSql\Connection 实例。
`statement_name`

  The name to give the prepared statement. Must be unique per-connection. If "" is specified, then an unnamed statement is created, overwriting any previously defined unnamed statement.

`query`

  The parameterized SQL statement. Must contain only a single statement. (multiple statements separated by semi-colons are not allowed.) If any parameters are used, they are referred to as $1, $2, etc.

### 返回值

Returns `true` on success, `false` or `0` on failure. Use pg_get_result() to determine the query result.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 Using pg_send_prepare()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      // Prepare a query for execution
      if (!pg_connection_busy($dbconn)) {
        pg_send_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');
        $res1 = pg_get_result($dbconn);
      }

      // Execute the prepared query.  Note that it is not necessary to escape
      // the string "Joe's Widgets" in any way
      if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Joe's Widgets"));
        $res2 = pg_get_result($dbconn);
      }

      // Execute the same prepared query, this time with a different parameter
      if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));
        $res3 = pg_get_result($dbconn);
      }

    ?>

### 参见

- pg_connect() - 打开 PostgreSQL 连接
- pg_pconnect() - 打开一个持久的 PostgreSQL 连接
- pg_execute() - Sends a request to execute a prepared statement with given parameters, and waits for the result
- pg_send_execute() - Sends a request to execute a prepared statement with given parameters, without waiting for the result(s)
- pg_send_query_params() - Submits a command and separate parameters to the server without waiting for the result(s)

# pg_send_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_send_query — 发送异步查询

### 说明

function pg_send_query(PgSql\Connection `$connection`, string `$query`): int|bool

pg_send_query() 向 `connection` 发送异步查询。跟 pg_query() 不同，它可以一次性向 PostgreSQL 发送多个查询并用 pg_get_result() 依次得到结果。

当执行查询时不会阻塞脚本执行。用 pg_connection_busy() 来检查连接是否繁忙（即查询正在执行中）。可以使用 pg_cancel_query() 取消查询。

尽管用户可以同时发送多个查询，但连接繁忙的情况下无法发送多个查询。如果连接繁忙时发送了查询，则会等待上一个查询结束，并且丢弃上个查询的所有结果。

### 参数

`connection`
  PgSql\Connection 实例。
`query`

  要执行的 SQL 语句或者语句集合。

  应该正确转义查询中的数据。

### 返回值

成功时返回 `true`，失败时返回 `false` 或 `0`。使用 pg_get_result() 来确定查询结果。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_send_query() 示例

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from authors; select count(*) from authors;");
      }

      $res1 = pg_get_result($dbconn);
      echo "First call to pg_get_result(): $res1\n";
      $rows1 = pg_num_rows($res1);
      echo "$res1 has $rows1 records\n\n";

      $res2 = pg_get_result($dbconn);
      echo "Second call to pg_get_result(): $res2\n";
      $rows2 = pg_num_rows($res2);
      echo "$res2 has $rows2 records\n";
    ?>

以上示例会输出：

    First call to pg_get_result(): Resource id #3
    Resource id #3 has 3 records

    Second call to pg_get_result(): Resource id #4
    Resource id #4 has 1 records

### 参见

- pg_query() - 执行查询
- pg_cancel_query() - 取消异步查询
- pg_get_result() - 取得异步查询结果
- pg_connection_busy() - 获取连接是否繁忙

# pg_send_query_params

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_query_params — Submits a command and separate parameters to the server without waiting for the result(s)

### 说明

function pg_send_query_params(PgSql\Connection `$connection`, string `$query`, array `$params`): int|bool

Submits a command and separate parameters to the server without waiting for the result(s).

This is equivalent to pg_send_query() except that query parameters can be specified separately from the `query` string. The function's parameters are handled identically to pg_query_params(). Like pg_query_params(), it will not work on pre-7.4 PostgreSQL connections, and it allows only one command in the query string.

### 参数

`connection`
  PgSql\Connection 实例。
`query`

  The parameterized SQL statement. Must contain only a single statement. (multiple statements separated by semi-colons are not allowed.) If any parameters are used, they are referred to as $1, $2, etc.

`params`

  An array of parameter values to substitute for the $1, $2, etc. placeholders in the original prepared query string. The number of elements in the array must match the number of placeholders.

### 返回值

Returns `true` on success, `false` or `0` on failure. Use pg_get_result() to determine the query result.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 Using pg_send_query_params()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      // Using parameters.  Note that it is not necessary to quote or escape
      // the parameter.
      pg_send_query_params($dbconn, 'select count(*) from authors where city = $1', array('Perth'));

      // Compare against basic pg_send_query usage
      $str = pg_escape_string('Perth');
      pg_send_query($dbconn, "select count(*) from authors where city = '{$str}'");
    ?>

### 参见

- pg_send_query() - 发送异步查询

# 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

### 说明

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.

### 参数

`connection`
  PgSql\Connection 实例。
`size`
  The number of rows to be retrieved in each chunk.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

If `size` is less than `1`, a ValueError will be thrown.

### 示例

示例 #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));

以上示例会输出：

    int(1)
    bool(false)

### 参见

- pg_get_result() - 取得异步查询结果
- pg_result_status() - 获得查询结果的状态

# pg_set_client_encoding

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_set_client_encoding — 设定客户端编码

### 说明

function pg_set_client_encoding(PgSql\Connection `$connection` = ?, string `$encoding`): int

pg_set_client_encoding() 设定客户端编码，成功返回 0，出错返回 -1。

PostgreSQL 会自动将后端数据库编码中的数据转换成前端编码。

> 注意:

> 本函数以前的名字为 pg_setclientencoding()。

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is unspecified, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

`encoding`

  必需的客户端编码。`SQL_ASCII`、`EUC_JP`、`EUC_CN`、`EUC_KR`、`EUC_TW`、`UNICODE`、`MULE_INTERNAL`、`LATINX` (X=1...9)、`KOI8`、`WIN`、`ALT`、`SJIS`、`BIG5` 或 `WIN1250` 中的一个。

  确切有效的编码列表取决于 PostgreSQL 版本，因此查阅 PostgreSQL 手册获取更具体的列表。

### 返回值

成功时返回 `0` 失败时返回 `-1`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_set_client_encoding() 示例

    <?php

    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "An error occurred.\n";
      exit;
    }

    // Set the client encoding to UNICODE.  Data will be automatically
    // converted from the backend encoding to the frontend.
    pg_set_client_encoding($conn, "UNICODE");

    $result = pg_query($conn, "SELECT author, email FROM authors");
    if (!$result) {
      echo "An error occurred.\n";
      exit;
    }

    // Write out UTF-8 data
    while ($row = pg_fetch_row($result)) {
      echo "Author: $row[0]  E-mail: $row[1]";
      echo "<br />\n";
    }

    ?>

### 参见

- pg_client_encoding() - 获取客户端编码

# 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()

### 说明

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()

### 参数

`connection`
  PgSql\Connection 实例。
`visibility`

  The required visibility: `PGSQL_SHOW_CONTEXT_NEVER`, `PGSQL_SHOW_CONTEXT_ERRORS` or `PGSQL_SHOW_CONTEXT_ALWAYS`.

### 返回值

The previous visibility level: `PGSQL_SHOW_CONTEXT_NEVER`, `PGSQL_SHOW_CONTEXT_ERRORS` or `PGSQL_SHOW_CONTEXT_ALWAYS`.

### 示例

示例 #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);
    ?>

### 参见

- pg_last_error() - 得到某连接的最后一条错误信息
- pg_result_error() - 获得跟 result 相关的错误信息

# pg_set_error_verbosity

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_set_error_verbosity — Determines the verbosity of messages returned by pg_last_error() and pg_result_error()

### 说明

function pg_set_error_verbosity(PgSql\Connection `$connection` = ?, int `$verbosity`): int|false

Determines the verbosity of messages returned by pg_last_error() and pg_result_error().

pg_set_error_verbosity() sets the verbosity mode, returning the connection's previous setting. In `PGSQL_ERRORS_TERSE` mode, returned messages include severity, primary text, and position only; this will normally fit on a single line. The default mode (`PGSQL_ERRORS_DEFAULT`) produces messages that include the above plus any detail, hint, or context fields (these may span multiple lines). The `PGSQL_ERRORS_VERBOSE` mode includes all available fields. Changing the verbosity does not affect the messages available from already-existing result objects, only subsequently-created ones.

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is unspecified, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

`verbosity`

  The required verbosity: `PGSQL_ERRORS_TERSE`, `PGSQL_ERRORS_DEFAULT` or `PGSQL_ERRORS_VERBOSE`.

### 返回值

The previous verbosity level: `PGSQL_ERRORS_TERSE`, `PGSQL_ERRORS_DEFAULT` or `PGSQL_ERRORS_VERBOSE`, or `false` on failure.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_set_error_verbosity() 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_verbosity($dbconn, PGSQL_ERRORS_VERBOSE);
      $res1 = pg_get_result($dbconn);
      echo pg_result_error($res1);
    ?>

### 参见

- pg_last_error() - 得到某连接的最后一条错误信息
- pg_result_error() - 获得跟 result 相关的错误信息

# 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

### 说明

function pg_socket(PgSql\Connection `$connection`): resource|false

pg_socket() returns a read only resource corresponding to the socket underlying the given PostgreSQL connection.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`connection`
  PgSql\Connection 实例。

### 返回值

A socket resource on success 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

# pg_socket_poll

(PHP 8 >= 8.4.0)

pg_socket_poll — Poll a PostgreSQL connection socket for read/write readiness

### 说明

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.

### 参数

`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.

### 返回值

Returns a positive value if the socket is ready, `0` if the timeout was reached, or `-1` on error.

### 参见

- 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() - 发送异步查询

# pg_trace

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

pg_trace — 启用 PostgreSQL 连接的追踪

### 说明

function pg_trace(
string `$filename`,
string `$mode` = "w",
?PgSql\Connection `$connection` = `null`,
int `$trace_mode` = 0
): bool

pg_trace() 启用 PostgreSQL 前后端通讯的追踪并记录到文件。要完全理解结果，需要熟悉 PostgreSQL 通讯协议的内部工作原理。

对不熟悉的人来说，追踪发送到服务器的查询错误依然有用，例如可以用 grep '^To backend' trace.log 来查看实际发送到 PostgreSQL 服务器的查询。更多信息参考 » PostgreSQL 手册。

### 参数

`filename`

  写入追踪日志的文件完整路径和文件名，与 fopen() 一致。

`mode`

  可选的文件访问模式，同 fopen()。

`connection`

  An PgSql\Connection instance. When `connection` is `null`, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

`trace_mode`

  可选的 trace 模式，使用下列常量 `PGSQL_TRACE_SUPPRESS_TIMESTAMPS` 和 `PGSQL_TRACE_REGRESS_MODE`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | 新增 `trace_mode`。
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。
8.0.0 | `connection` 现在可为 null。

### 示例

示例 #1 pg_trace() 示例

    <?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);
       // Now /tmp/trace.log will contain backend communication
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

### 参见

- fopen() - 打开文件或者 URL
- pg_untrace() - 禁用 PostgreSQL 连接的追踪

# pg_transaction_status

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_transaction_status — Returns the current in-transaction status of the server

### 说明

function pg_transaction_status(PgSql\Connection `$connection`): int

Returns the current in-transaction status of the server.

警告

pg_transaction_status() will give incorrect results when using a PostgreSQL 7.3 server that has the parameter `autocommit` set to off. The server-side autocommit feature has been deprecated and does not exist in later server versions.

### 参数

`connection`
  PgSql\Connection 实例。

### 返回值

The status can be `PGSQL_TRANSACTION_IDLE` (currently idle), `PGSQL_TRANSACTION_ACTIVE` (a command is in progress), `PGSQL_TRANSACTION_INTRANS` (idle, in a valid transaction block), or `PGSQL_TRANSACTION_INERROR` (idle, in a failed transaction block). `PGSQL_TRANSACTION_UNKNOWN` is reported if the connection is bad. `PGSQL_TRANSACTION_ACTIVE` is reported only when a query has been sent to the server and not yet completed.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_transaction_status() example

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");
      $stat = pg_transaction_status($dbconn);
      if ($stat === PGSQL_TRANSACTION_UNKNOWN) {
          echo 'Connection is bad';
      } else if ($stat === PGSQL_TRANSACTION_IDLE) {
          echo 'Connection is currently idle';
      } else {
          echo 'Connection is in a transaction state';
      }
    ?>

# pg_tty

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_tty — 返回跟连接相关的 tty 名

### 说明

function pg_tty(?PgSql\Connection `$connection` = `null`): string

pg_tty() 返回指定 PostgreSQL `connection` 实例在服务器端调试输出发送的 tty 名。

> 注意:

> pg_tty() 已经过时，因为服务器不再关注 TTY 设置，但为了向后兼容性，该函数仍然保留。

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is `null`, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

### 返回值

string，包含 `connection` 的调试 TTY。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。
8.0.0 | `connection` 现在可为 null。

### 示例

示例 #1 pg_tty() 示例

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       print "Server debug TTY is: " . 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 — 反转义 bytea 类型的二进制数据

### 说明

function pg_unescape_bytea(string `$string`): string

pg_unescape_bytea() 反转义 PostgreSQL bytea 数据值。返回反转义后的字符串，可能包含二进制数据。

> 注意:

> 当 `SELECT` bytea 类型时，PostgreSQL 返回前缀为“\”的八进制字节值（例如 \032）。用户需要手动将其转换回二进制格式。

### 参数

`string`

  string，包含 PostgreSQL bytea 数据，需要转换为 PHP 二进制字符串。

### 返回值

包含反转义数据的 string。

### 示例

示例 #1 pg_unescape_bytea() 示例

    <?php
      // Connect to the database
      $dbconn = pg_connect('dbname=foo');

      // Get the bytea data
      $res = pg_query("SELECT data FROM gallery WHERE name='Pine trees'");
      $raw = pg_fetch_result($res, 'data');

      // Convert to binary and send to the browser
      header('Content-type: image/jpeg');
      echo pg_unescape_bytea($raw);
    ?>

### 参见

- pg_escape_bytea() - 转义字符串以插入到 bytea 字段
- pg_escape_string() - 转义字符串以供查询

# pg_untrace

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

pg_untrace — 禁用 PostgreSQL 连接的追踪

### 说明

function pg_untrace(?PgSql\Connection `$connection` = `null`): true

停止由 pg_trace() 启用的追踪。

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is `null`, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.2.0 | 现在返回类型为 `true`；之前是 bool。
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。
8.0.0 | `connection` 现在可为 null。

### 示例

示例 #1 pg_untrace() 示例

    <?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);
       // Now tracing of backend communication is disabled
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

### 参见

- pg_trace() - 启用 PostgreSQL 连接的追踪

# pg_update

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_update — 更新表

### 说明

function pg_update(
PgSql\Connection `$connection`,
string `$table_name`,
array `$values`,
array `$conditions`,
int `$flags` = `PGSQL_DML_EXEC`
): string|bool

pg_update() 更新匹配 `conditions` 和 `values` 的记录。

如果指定 `flags`，则 pg_convert() 使用指定 flag 应用于 `values`。

默认情况下 pg_update() 传递原始值。值必须转义或必须在 `flags` 中指定 `PGSQL_DML_ESCAPE` flag。`PGSQL_DML_ESCAPE` 引用并转义参数/标识符。因此，表/列名称变得区分大小写。

注意转义和预处理查询都不能保护 LIKE 查询、JSON、Array、Regex 等，这些参数要根据上下文来处理。即转义/验证值。

### 参数

`connection`
  PgSql\Connection 实例。
`table_name`

  要更新记录的表名。

`values`

  array，其键是表 `table_name` 中的字段名称，其值是要更新的匹配行。

`conditions`

  array，其键是表 `table_name` 中的字段名称，其值是更新行必须满足的条件。

`flags`

  任意数量的 `PGSQL_CONV_FORCE_NULL`、`PGSQL_DML_NO_CONV`、`PGSQL_DML_ESCAPE`、`PGSQL_DML_EXEC`、`PGSQL_DML_ASYNC` 或 `PGSQL_DML_STRING` 的组合。当 `PGSQL_DML_STRING` 是 `flags` 的一部分，然后将返回查询字符串。当设置了 `PGSQL_DML_NO_CONV` 或 `PGSQL_DML_ESCAPE` 时，不会在内部调用 pg_convert()。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。如果通过 `flags` 传递 `PGSQL_DML_STRING`，成功时返回 string。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。

### 示例

示例 #1 pg_update() 示例

    <?php
      $db = pg_connect('dbname=foo');
      $data = array('field1'=>'AA', 'field2'=>'BB');
      // 在某种程度上安全，因为所有值都转义了。
      // 然而 PostgreSQL 支持 JSON/Array。无论是
      // 转义还是预处理都不安全。
      $res = pg_update($db, 'post_log', $_POST, $data);
      if ($res) {
          echo "Data is updated: $res\n";
      } else {
          echo "User must have sent wrong inputs\n";
      }
    ?>

### 参见

- pg_convert() - 将关联的数组值转换为适合 SQL 语句的格式

# pg_version

(PHP 5, PHP 7, PHP 8)

pg_version — Returns an array with client, protocol and server version (when available)

### 说明

function pg_version(?PgSql\Connection `$connection` = `null`): array

pg_version() returns an array with the client, protocol and server version.

For more detailed server information, use pg_parameter_status().

### 参数

`connection`

  An PgSql\Connection instance. When `connection` is `null`, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

  警告

  As of PHP 8.1.0, using the default connection is deprecated.

### 返回值

Returns an array with `client`, `protocol` and `server` keys and values (if available).

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `connection` 参数接受 PgSql\Connection 实例，之前接受 resource。
8.0.0 | `connection` is now nullable.

### 示例

示例 #1 pg_version() example

    <?php
      $dbconn = pg_connect("host=localhost port=5432 dbname=mary")
         or die("Could not connect");

      $v = pg_version($dbconn);

      echo $v['client'];
    ?>

以上示例会输出：

    7.4

### 参见

- pg_parameter_status() - Looks up a current parameter setting of the server

## 目录

- pg_affected_rows — 返回受影响的记录数（元组）
- pg_cancel_query — 取消异步查询
- pg_change_password — Change a PostgreSQL user's password
- pg_client_encoding — 获取客户端编码
- pg_close — 关闭 PostgreSQL 连接
- pg_connect — 打开 PostgreSQL 连接
- pg_connect_poll — 对正在进行尝试进行异步的 PostgreSQL 连接轮询其状态。
- pg_connection_busy — 获取连接是否繁忙
- pg_connection_reset — 重置连接（再次连接）
- pg_connection_status — 获取连接状态
- pg_consume_input — Reads input on the connection
- pg_convert — 将关联的数组值转换为适合 SQL 语句的格式
- pg_copy_from — 将数组中的记录插入到表
- pg_copy_to — 将表复制到数组
- pg_dbname — 获取数据库名称
- pg_delete — 删除记录
- pg_end_copy — 与 PostgreSQL 后端同步
- pg_escape_bytea — 转义字符串以插入到 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 — 转义字符串以供查询
- pg_execute — Sends a request to execute a prepared statement with given parameters, and waits for the result
- pg_fetch_all — 从结果中获取所有行作为数组
- pg_fetch_all_columns — Fetches all rows in a particular result column as an array
- pg_fetch_array — 获取一行作为数组
- pg_fetch_assoc — 获取一行作为关联数组
- pg_fetch_object — 获取一行作为对象
- pg_fetch_result — 从结果实例返回值
- pg_fetch_row — 提取一行作为枚举数组
- pg_field_is_null — 测试字段是否为 SQL NULL
- pg_field_name — 返回字段名
- pg_field_num — 返回名为 field 的字段编号
- pg_field_prtlen — 返回打印的长度
- pg_field_size — 返回指定字段的内部存储大小
- pg_field_table — Returns the name or oid of the tables field
- pg_field_type — 返回相应字段编号的类型名称
- pg_field_type_oid — Returns the type ID (OID) for the corresponding field number
- pg_flush — 刷新链接中已处理的数据查询
- pg_free_result — 释放查询结果占用的内存
- pg_get_notify — 获取 SQL NOTIFY 消息
- pg_get_pid — 获取后端的进程 ID
- pg_get_result — 取得异步查询结果
- pg_host — 返回和某连接关联的主机名
- pg_insert — 将数组插入到表中
- pg_jit — Returns the JIT information of the server
- pg_last_error — 得到某连接的最后一条错误信息
- pg_last_notice — 返回 PostgreSQL 服务器最新一条公告信息
- pg_last_oid — 返回上一条记录的 oid
- pg_lo_close — 关闭大对象
- pg_lo_create — 新建大对象
- pg_lo_export — 将大型对象导出到文件
- pg_lo_import — 将文件导入为大型对象
- pg_lo_open — 打开大对象
- pg_lo_read — 读取大对象
- pg_lo_read_all — 读取整个大对象并直接发送到浏览器
- pg_lo_seek — 在大对象中寻找位置
- pg_lo_tell — 返回当前大型对象的指针位置
- pg_lo_truncate — Truncates a large object
- pg_lo_unlink — 删除一个大型对象
- pg_lo_write — 向大对象写入数据
- pg_meta_data — 获得表的元数据
- pg_num_fields — 返回结果中字段的数量
- pg_num_rows — 返回结果中行的数量
- pg_options — 获得和 connection 相关的选项
- pg_parameter_status — Looks up a current parameter setting of the server
- pg_pconnect — 打开一个持久的 PostgreSQL 连接
- pg_ping — Ping 数据库连接
- pg_port — 返回 connection 相关的端口号
- pg_prepare — Submits a request to the server to create a prepared statement with the given parameters, and waits for completion
- 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 — 向 PostgreSQL 后端发送以 NULL 字符结尾的字符串
- pg_query — 执行查询
- pg_query_params — Submits a command to the server and waits for the result, with the ability to pass parameters separately from the SQL command text
- pg_result_error — 获得跟 result 相关的错误信息
- pg_result_error_field — Returns an individual field of an error report
- pg_result_memory_size — Returns the amount of memory allocated for a query result
- pg_result_seek — 在 result 实例中设定内部行偏移量
- pg_result_status — 获得查询结果的状态
- pg_select — 选择记录
- pg_send_execute — Sends a request to execute a prepared statement with given parameters, without waiting for the result(s)
- pg_send_prepare — Sends a request to create a prepared statement with the given parameters, without waiting for completion
- pg_send_query — 发送异步查询
- pg_send_query_params — Submits a command and separate parameters to the server without waiting for the result(s)
- pg_set_chunked_rows_size — Set the query results to be retrieved in chunk mode
- pg_set_client_encoding — 设定客户端编码
- 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 — Determines the verbosity of messages returned by pg_last_error and pg_result_error
- 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 — 启用 PostgreSQL 连接的追踪
- pg_transaction_status — Returns the current in-transaction status of the server
- pg_tty — 返回跟连接相关的 tty 名
- pg_unescape_bytea — 反转义 bytea 类型的二进制数据
- pg_untrace — 禁用 PostgreSQL 连接的追踪
- pg_update — 更新表
- pg_version — Returns an array with client, protocol and server version (when available)

# The PgSql\Connection class

(PHP 8 >= 8.1.0)

## 简介

A fully opaque class which replaces a `pgsql link` resource as of PHP 8.1.0.

## 类摘要

namespace PgSql;
final class Connection {
}

# The PgSql\Result class

(PHP 8 >= 8.1.0)

## 简介

A fully opaque class which replaces a `pgsql result` resource as of PHP 8.1.0.

## 类摘要

namespace PgSql;
final class Result {
}

# The PgSql\Lob class

(PHP 8 >= 8.1.0)

## 简介

A fully opaque class which replaces a `pgsql large object` resource as of PHP 8.1.0.

## 类摘要

namespace PgSql;
final class Lob {
}

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
  - 资源类型
- 预定义常量
- 示例
  - Basic usage
  - Basic usage
- PostgreSQL 函数
  - pg_affected_rows — 返回受影响的记录数（元组）
  - pg_cancel_query — 取消异步查询
  - pg_change_password — Change a PostgreSQL user's password
  - pg_client_encoding — 获取客户端编码
  - pg_close — 关闭 PostgreSQL 连接
  - pg_connect — 打开 PostgreSQL 连接
  - pg_connect_poll — 对正在进行尝试进行异步的 PostgreSQL 连接轮询其状态。
  - pg_connection_busy — 获取连接是否繁忙
  - pg_connection_reset — 重置连接（再次连接）
  - pg_connection_status — 获取连接状态
  - pg_consume_input — Reads input on the connection
  - pg_convert — 将关联的数组值转换为适合 SQL 语句的格式
  - pg_copy_from — 将数组中的记录插入到表
  - pg_copy_to — 将表复制到数组
  - pg_dbname — 获取数据库名称
  - pg_delete — 删除记录
  - pg_end_copy — 与 PostgreSQL 后端同步
  - pg_escape_bytea — 转义字符串以插入到 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 — 转义字符串以供查询
  - pg_execute — Sends a request to execute a prepared statement with given parameters, and waits for the result
  - pg_fetch_all — 从结果中获取所有行作为数组
  - pg_fetch_all_columns — Fetches all rows in a particular result column as an array
  - pg_fetch_array — 获取一行作为数组
  - pg_fetch_assoc — 获取一行作为关联数组
  - pg_fetch_object — 获取一行作为对象
  - pg_fetch_result — 从结果实例返回值
  - pg_fetch_row — 提取一行作为枚举数组
  - pg_field_is_null — 测试字段是否为 SQL NULL
  - pg_field_name — 返回字段名
  - pg_field_num — 返回名为 field 的字段编号
  - pg_field_prtlen — 返回打印的长度
  - pg_field_size — 返回指定字段的内部存储大小
  - pg_field_table — Returns the name or oid of the tables field
  - pg_field_type — 返回相应字段编号的类型名称
  - pg_field_type_oid — Returns the type ID (OID) for the corresponding field number
  - pg_flush — 刷新链接中已处理的数据查询
  - pg_free_result — 释放查询结果占用的内存
  - pg_get_notify — 获取 SQL NOTIFY 消息
  - pg_get_pid — 获取后端的进程 ID
  - pg_get_result — 取得异步查询结果
  - pg_host — 返回和某连接关联的主机名
  - pg_insert — 将数组插入到表中
  - pg_jit — Returns the JIT information of the server
  - pg_last_error — 得到某连接的最后一条错误信息
  - pg_last_notice — 返回 PostgreSQL 服务器最新一条公告信息
  - pg_last_oid — 返回上一条记录的 oid
  - pg_lo_close — 关闭大对象
  - pg_lo_create — 新建大对象
  - pg_lo_export — 将大型对象导出到文件
  - pg_lo_import — 将文件导入为大型对象
  - pg_lo_open — 打开大对象
  - pg_lo_read — 读取大对象
  - pg_lo_read_all — 读取整个大对象并直接发送到浏览器
  - pg_lo_seek — 在大对象中寻找位置
  - pg_lo_tell — 返回当前大型对象的指针位置
  - pg_lo_truncate — Truncates a large object
  - pg_lo_unlink — 删除一个大型对象
  - pg_lo_write — 向大对象写入数据
  - pg_meta_data — 获得表的元数据
  - pg_num_fields — 返回结果中字段的数量
  - pg_num_rows — 返回结果中行的数量
  - pg_options — 获得和 connection 相关的选项
  - pg_parameter_status — Looks up a current parameter setting of the server
  - pg_pconnect — 打开一个持久的 PostgreSQL 连接
  - pg_ping — Ping 数据库连接
  - pg_port — 返回 connection 相关的端口号
  - pg_prepare — Submits a request to the server to create a prepared statement with the given parameters, and waits for completion
  - 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 — 向 PostgreSQL 后端发送以 NULL 字符结尾的字符串
  - pg_query — 执行查询
  - pg_query_params — Submits a command to the server and waits for the result, with the ability to pass parameters separately from the SQL command text
  - pg_result_error — 获得跟 result 相关的错误信息
  - pg_result_error_field — Returns an individual field of an error report
  - pg_result_memory_size — Returns the amount of memory allocated for a query result
  - pg_result_seek — 在 result 实例中设定内部行偏移量
  - pg_result_status — 获得查询结果的状态
  - pg_select — 选择记录
  - pg_send_execute — Sends a request to execute a prepared statement with given parameters, without waiting for the result(s)
  - pg_send_prepare — Sends a request to create a prepared statement with the given parameters, without waiting for completion
  - pg_send_query — 发送异步查询
  - pg_send_query_params — Submits a command and separate parameters to the server without waiting for the result(s)
  - pg_set_chunked_rows_size — Set the query results to be retrieved in chunk mode
  - pg_set_client_encoding — 设定客户端编码
  - 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 — Determines the verbosity of messages returned by pg_last_error and pg_result_error
  - 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 — 启用 PostgreSQL 连接的追踪
  - pg_transaction_status — Returns the current in-transaction status of the server
  - pg_tty — 返回跟连接相关的 tty 名
  - pg_unescape_bytea — 反转义 bytea 类型的二进制数据
  - pg_untrace — 禁用 PostgreSQL 连接的追踪
  - pg_update — 更新表
  - pg_version — Returns an array with client, protocol and server version (when available)
- PgSql\Connection — The PgSql\Connection class
- PgSql\Result — The PgSql\Result class
- PgSql\Lob — The PgSql\Lob class

# SQLite3

# 简介

支持 SQLite v3 数据库。

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置

## 需求

从 PHP 7.4.0 开始，需要 » libsqlite ≥ 3.7.4。以前，可以使用捆绑的 libsqlite。

## 安装

SQLite3 扩展默认启用。 允许在编译时使用 `--without-sqlite3` 禁用之。

Windows 用户必须启用 php_sqlite3.dll 方可使用该扩展。此扩展的 DLL 文件 包含于 Windows 版的 PHP 发行包中。

> 注意: 自 PHP 7.4.0 起在 Windows 上的附加设置

> 为了使此扩展生效， DLL 文件必须能在 Windows 系统的 PATH 指示的路径下找到。如何操作的信息，请参见题为“如何在 Windows 中将 PHP 目录加到 PATH 中”的FAQ。虽然将 DLL 文件从 PHP 文件夹复制到 Windows 系统目录也行，但不建议这样做。 此扩展需要下列文件在 PATH 路径中： libsqlite3.dll.

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

SQLite3 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
sqlite3.extension_dir | "" | `INI_SYSTEM` |
sqlite3.defensive | 1 | `INI_USER` | 自 PHP 7.2.17 和 7.3.4 起适用于 libsqlite ≥ 3.26.0。在 PHP 8.2.0 之前，此设置只能更改为 `INI_SYSTEM`。

这是配置指令的简短说明。

`sqlite3.extension_dir` string

  SQLite 的可加载扩展所在目录的路径。

`sqlite3.defensive` bool

  启用 defensive flag 后，将禁用普通 SQL 故意损坏数据库文件的语言功能。这禁止直接写入模式（schema）、影子表（例如 FTS 数据表）或 sqlite_dbpage 虚拟表。此 php.ini 设置仅对 libsqlite ≥ 3.26.0 有效。

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`SQLITE3_ASSOC` (int)
  指定 Sqlite3Result::fetchArray() 方法返回按列名称索引的数组，其中列名即相应结果集返回的列名。
`SQLITE3_NUM` (int)
  指定 Sqlite3Result::fetchArray() 方法返回按列序号索引的数组，其中列号即相应结果集返回的列号，从第 0 列开始计数。
`SQLITE3_BOTH` (int)
  指定 Sqlite3Result::fetchArray() 方法返回同时按列名称与列序号索引的数组，其中列名即相应结果集返回的列名，列号即相应结果集返回的列号，从第 0 列开始计数。
`SQLITE3_INTEGER` (int)
  表示 SQLite3 INTEGER (整型) 存储类。
`SQLITE3_FLOAT` (int)
  表示 SQLite3 REAL (FLOAT) (实型) 存储类。
`SQLITE3_TEXT` (int)
  表示 SQLite3 TEXT (文本) 存储类。
`SQLITE3_BLOB` (int)
  表示 SQLite3 BLOB (二进制对象) 存储类。
`SQLITE3_NULL` (int)
  表示 SQLite3 NULL 存储类。
`SQLITE3_OPEN_READONLY` (int)
  指定 SQLite3 数据库以只读模式打开。
`SQLITE3_OPEN_READWRITE` (int)
  指定 SQLite3 数据库以读写模式打开。
`SQLITE3_OPEN_CREATE` (int)
  指定 SQLite3 数据库若不存在，则创建并打开。
`SQLITE3_DETERMINISTIC` (int)
  使用 SQLite3::createFunction() 创建的指定函数是确定性的，即它始终在单个 SQL 语句中指定的相同输入返回相同结果。（自 PHP 7.1.4 起可用。）

# SQLite3 类

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## 简介

连接 SQLite 3 数据库的类。

## 类摘要

class SQLite3 {
/* 常量 */
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;
/* 方法 */
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
}

## 预定义常量

`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

### 说明

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.

小技巧

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.

### 参数

`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`.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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

### 说明

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.

### 参数

`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.

### 返回值

Returns `true` on success, 或者在失败时返回 `false`.

# SQLite3::changes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::changes — Returns the number of database rows that were changed (or inserted or deleted) by the most recent SQL statement

### 说明

public function SQLite3::changes(): int

Returns the number of database rows that were changed (or inserted or deleted) by the most recent SQL statement.

### 参数

此函数没有参数。

### 返回值

Returns an int value corresponding to the number of database rows changed (or inserted or deleted) by the most recent SQL statement.

### 示例

示例 #1 SQLite3::changes() example

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $query = $db->exec('UPDATE counter SET views=0 WHERE page="test"');
    if ($query) {
        echo 'Number of rows modified: ', $db->changes();
    }
    ?>

# SQLite3::close

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::close — Closes the database connection

### 说明

public function SQLite3::close(): bool

Closes the database connection.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 SQLite3::close() example

    <?php
    $db = new SQLite3('mysqlitedb.db');
    $db->close();
    ?>

# SQLite3::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::__construct — 实例化 SQLite3 对象并打开 SQLite 3 数据库

### 说明

public function SQLite3::__construct(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = "")

实例化 SQLite3 对象并打开连接到 SQLite 3 数据库的连接。如果构建包括加密，那么将尝试使用密钥。

### 参数

`filename`

  SQLite 数据库的路径，或 `:memory:` 使用内存数据库。如果 `filename` 是空字符串，那么将创建私有的临时磁盘数据库。一旦数据库连接关闭，这个私有数据库就会自动删除。

`flags`

  可选的 flag，用于确定如何打开 SQLite 数据库。默认使用 `SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE` 打开。

  - `SQLITE3_OPEN_READONLY`：以只读方式打开数据库。

  - `SQLITE3_OPEN_READWRITE`：以读写方式打开数据库。

  - `SQLITE3_OPEN_CREATE`：如果数据库不存在，则创建数据库。

`encryptionKey`

  加密和解密 SQLite 数据库时使用的可选加密密钥。如果未安装 SQLite 加密模块，则此参数无效。

### 错误／异常

失败时抛出 Exception。

### 更新日志

版本 | 说明
--- | ---
7.0.10 | `filename` 可以为空，以使用私有的临时磁盘数据库。

### 示例

示例 #1 SQLite3::__construct() 示例

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $db->exec('CREATE TABLE foo (bar TEXT)');
    $db->exec("INSERT INTO foo (bar) VALUES ('This is a 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 — Registers a PHP function for use as an SQL aggregate function

### 说明

public function SQLite3::createAggregate(
string `$name`,
callable `$stepCallback`,
callable `$finalCallback`,
int `$argCount` = -1
): bool

Registers a PHP function or user-defined function for use as an SQL aggregate function for use within SQL statements.

### 参数

`name`

  Name of the SQL aggregate to be created or redefined.

`stepCallback`

  Callback function called for each row of the result set. Your PHP function should accumulate the result and store it in the aggregation context.

  This function need to be defined as:

  function step(
  mixed `$context`,
  int `$rownumber`,
  mixed `$value`,
  mixed `...$values`
  ): mixed
  `context`

    `null` for the first row; on subsequent rows it will have the value that was previously returned from the step function; you should use this to maintain the aggregate state.

  `rownumber`

    The current row number.

  `value`

    The first argument passed to the aggregate.

  `values`

    Further arguments passed to the aggregate.

  The return value of this function will be used as the `context` argument in the next call of the step or finalize functions.
`finalCallback`

  Callback function to aggregate the "stepped" data from each row. Once all the rows have been processed, this function will be called and it should then take the data from the aggregation context and return the result. This callback function should return a type understood by SQLite (i.e. scalar type).

  This function need to be defined as:

  function fini(mixed `$context`, int `$rownumber`): mixed
  `context`

    Holds the return value from the very last call to the step function.

  `rownumber`

    Always `0`.

  The return value of this function will be used as the return value for the aggregate.
`argCount`

  The number of arguments that the SQL aggregate takes. If this parameter is negative, then the SQL aggregate may take any number of arguments.

### 返回值

Returns `true` upon successful creation of the aggregate, 或者在失败时返回 `false`.

### 示例

示例 #1 max_length aggregation function example

    <?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'));
    ?>

以上示例会输出：

    int(5)

In this example, we are creating an aggregating function that will calculate the length of the longest string in one of the columns of the table. For each row, the `max_len_step` function is called and passed a `$context` parameter. The context parameter is just like any other PHP variable and be set to hold an array or even an object value. In this example, we are simply using it to hold the maximum length we have seen so far; if the `$string` has a length longer than the current maximum, we update the context to hold this new maximum length.

After all of the rows have been processed, SQLite calls the `max_len_finalize` function to determine the aggregate result. Here, we could perform some kind of calculation based on the data found in the `$context`. In our simple example though, we have been calculating the result as the query progressed, so we simply need to return the context value.

小技巧

It is NOT recommended for you to store a copy of the values in the context and then process them at the end, as you would cause SQLite to use a lot of memory to process the query - just think of how much memory you would need if a million rows were stored in memory, each containing a string 32 bytes in length.

小技巧

You can use SQLite3::createAggregate() to override SQLite native SQL functions.

# SQLite3::createCollation

(PHP 5 >= 5.3.11, PHP 7, PHP 8)

SQLite3::createCollation — Registers a PHP function for use as an SQL collating function

### 说明

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.

### 参数

`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

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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();

    ?>

以上示例会输出：

    default:
    a1
    a10
    a2

    natural:
    a1
    a2
    a10

### 参见

- The SQLite collation documentation: » http://sqlite.org/datatype3.html#collation

# SQLite3::createFunction

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::createFunction — Registers a PHP function for use as an SQL scalar function

### 说明

public function SQLite3::createFunction(
string `$name`,
callable `$callback`,
int `$argCount` = -1,
int `$flags` = 0
): bool

Registers a PHP function or user-defined function for use as an SQL scalar function for use within SQL statements.

### 参数

`name`

  Name of the SQL 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 SQL function.

  This function need to be defined as:

  function callback(mixed `$value`, mixed `...$values`): mixed
  `value`

    The first argument passed to the SQL function.

  `values`

    Further arguments passed to the SQL function.

`argCount`

  The number of arguments that the SQL function takes. If this parameter is `-1`, then the SQL function may take any number of arguments.

`flags`

  A bitwise conjunction of flags. Currently, only `SQLITE3_DETERMINISTIC` is supported, which specifies that the function always returns the same result given the same inputs within a single SQL statement.

### 返回值

Returns `true` upon successful creation of the function, `false` on failure.

### 更新日志

版本 | 说明
--- | ---
7.1.4 | The `flags` parameter has been added.

### 示例

示例 #1 SQLite3::createFunction() example

    <?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")'));
    ?>

以上示例的输出类似于：

    string(32) "098f6bcd4621d373cade4e832627b4f6"

# SQLite3::enableExceptions

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::enableExceptions — Enable throwing exceptions

### 说明

public function SQLite3::enableExceptions(bool `$enable` = `false`): bool

Controls whether the SQLite3 instance will throw exceptions or warnings on error.

### 参数

`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.

### 返回值

Returns the old value; `true` if exceptions were enabled, `false` otherwise.

### 更新日志

版本 | 说明
--- | ---
8.3.0 | Calling SQLite3::enableExceptions() with `enable` as `false` will trigger a `E_DEPRECATED` warning.

### 示例

示例 #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();
    }
    ?>

以上示例的输出类似于：

    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 — Returns a string that has been properly escaped

### 说明

public static function SQLite3::escapeString(string `$string`): string

Returns a string that has been properly escaped for safe inclusion in an SQL statement.

警告

此函数（还）不能安全地适用于二进制对象！

To properly handle BLOB fields which may contain NUL characters, use SQLite3Stmt::bindParam() instead.

### 参数

`string`

  The string to be escaped.

### 返回值

Returns a properly escaped string that may be used safely in an SQL statement.

### 注释

警告

addslashes() should NOT be used to quote your strings for SQLite queries; it will lead to strange results when retrieving your data.

# SQLite3::exec

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::exec — Executes a result-less query against a given database

### 说明

public function SQLite3::exec(string `$query`): bool

Executes a result-less query against a given database.

> 注意: SQLite3 may need to create » temporary files during the execution of queries, so the respective directories may have to be writable.

### 参数

`query`

  The SQL query to execute (typically an INSERT, UPDATE, or DELETE query).

### 返回值

Returns `true` if the query succeeded, `false` on failure.

### 示例

示例 #1 SQLite3::exec() example

    <?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 — Returns the numeric result code of the most recent failed SQLite request

### 说明

public function SQLite3::lastErrorCode(): int

Returns the numeric result code of the most recent failed SQLite request.

### 参数

此函数没有参数。

### 返回值

Returns an integer value representing the numeric result code of the most recent failed SQLite request.

# SQLite3::lastErrorMsg

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastErrorMsg — Returns English text describing the most recent failed SQLite request

### 说明

public function SQLite3::lastErrorMsg(): string

Returns English text describing the most recent failed SQLite request.

### 参数

此函数没有参数。

### 返回值

Returns an English string describing the most recent failed SQLite request.

# SQLite3::lastInsertRowID

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastInsertRowID — Returns the row ID of the most recent INSERT into the database

### 说明

public function SQLite3::lastInsertRowID(): int

Returns the row ID of the most recent INSERT into the database.

### 参数

此函数没有参数。

### 返回值

Returns the row ID of the most recent INSERT into the database. If no successful INSERTs into rowid tables have ever occurred on this database connection, then SQLite3::lastInsertRowID() returns `0`.

# SQLite3::loadExtension

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::loadExtension — Attempts to load an SQLite extension library

### 说明

public function SQLite3::loadExtension(string `$name`): bool

Attempts to load an SQLite extension library.

### 参数

`name`

  The name of the library to load. The library must be located in the directory specified in the configure option sqlite3.extension_dir.

### 返回值

Returns `true` if the extension is successfully loaded, `false` on failure.

### 示例

示例 #1 SQLite3::loadExtension() example

    <?php
    $db = new SQLite3('mysqlitedb.db');
    $db->loadExtension('libagg.so');
    ?>

# SQLite3::open

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::open — Opens an SQLite database

### 说明

public function SQLite3::open(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = ""): void

Opens an SQLite 3 Database. If the build includes encryption, then it will attempt to use the key.

### 参数

`filename`

  Path to the SQLite database, or `:memory:` to use in-memory database.

`flags`

  Optional flags used to determine how to open the SQLite database. By default, open uses `SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE`.

  - `SQLITE3_OPEN_READONLY`: Open the database for reading only.

  - `SQLITE3_OPEN_READWRITE`: Open the database for reading and writing.

  - `SQLITE3_OPEN_CREATE`: Create the database if it does not exist.

`encryptionKey`

  An optional encryption key used when encrypting and decrypting an SQLite database. If the SQLite encryption module is not installed, this parameter will have no effect.

### 返回值

没有返回值。

### 示例

示例 #1 SQLite3::open() example

    <?php
    /**
     * Simple example of extending the SQLite3 class and changing the __construct
     * parameters, then using the open method to initialize the DB.
     */
    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

### 说明

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`

> 注意: 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.

### 参数

`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.

### 返回值

Returns a stream resource, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
7.2.0 | The `flags` parameter has been added, allowing to write BLOBs; formerly only reading was supported.

### 示例

示例 #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();
    ?>

以上示例会输出：

    Lorem ipsum

示例 #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();
    ?>

以上示例会输出：

    Lorem ipsum
    Lorem ipsum
    Lorem ipsum

# SQLite3::prepare

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::prepare — Prepares an SQL statement for execution

### 说明

public function SQLite3::prepare(string `$query`): SQLite3Stmt|false

Prepares an SQL statement for execution and returns an SQLite3Stmt object.

### 参数

`query`

  The SQL query to prepare.

### 返回值

Returns an SQLite3Stmt object on success 或者在失败时返回 `false`.

### 示例

示例 #1 SQLite3::prepare() example

    <?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());
    ?>

### 参见

- 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 — Executes an SQL query

### 说明

public function SQLite3::query(string `$query`): SQLite3Result|false

Executes an SQL query, returning an SQLite3Result object. If the query does not yield a result (such as DML statements) the returned SQLite3Result object is not really usable. Use SQLite3::exec() for such queries instead.

### 参数

`query`

  The SQL query to execute.

### 返回值

Returns an SQLite3Result object, 或者在失败时返回 `false`.

### 示例

示例 #1 SQLite3::query() example

    <?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

### 说明

public function SQLite3::querySingle(string `$query`, bool `$entireRow` = `false`): mixed

Executes a query and returns a single result.

### 参数

`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.

### 返回值

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`.

### 示例

示例 #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));
    ?>

以上示例的输出类似于：

    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

### 说明

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.

### 参数

`callback`

  The callable to be called.

  If `null` is passed instead, this will disable the current authorizer callback.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

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).

### 示例

示例 #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;'));

以上示例会输出：

    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

### 说明

public static function SQLite3::version(): array

Returns the SQLite3 library version as a string constant and as a number.

### 参数

此函数没有参数。

### 返回值

Returns an associative array with the keys "versionString" and "versionNumber".

### 示例

示例 #1 SQLite3::version() example

    <?php
    print_r(SQLite3::version());
    ?>

以上示例的输出类似于：

    Array
    (
        [versionString] => 3.5.9
        [versionNumber] => 3005009
    )

## 目录

- SQLite3::backup — Backup one database to another database
- SQLite3::busyTimeout — Sets the busy connection handler
- SQLite3::changes — Returns the number of database rows that were changed (or inserted or deleted) by the most recent SQL statement
- SQLite3::close — Closes the database connection
- SQLite3::__construct — 实例化 SQLite3 对象并打开 SQLite 3 数据库
- SQLite3::createAggregate — Registers a PHP function for use as an SQL aggregate function
- SQLite3::createCollation — Registers a PHP function for use as an SQL collating function
- SQLite3::createFunction — Registers a PHP function for use as an SQL scalar function
- SQLite3::enableExceptions — Enable throwing exceptions
- SQLite3::escapeString — Returns a string that has been properly escaped
- SQLite3::exec — Executes a result-less query against a given database
- SQLite3::lastErrorCode — Returns the numeric result code of the most recent failed SQLite request
- SQLite3::lastErrorMsg — Returns English text describing the most recent failed SQLite request
- SQLite3::lastInsertRowID — Returns the row ID of the most recent INSERT into the database
- SQLite3::loadExtension — Attempts to load an SQLite extension library
- SQLite3::open — Opens an SQLite database
- SQLite3::openBlob — Opens a stream resource to read a BLOB
- SQLite3::prepare — Prepares an SQL statement for execution
- SQLite3::query — Executes an SQL query
- 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)

## 简介

Represents a SQLite3 specific exception.

## 类摘要

class SQLite3Exception extends Exception {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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
}

# SQLite3Stmt 类

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## 简介

处理 SQLite 3 扩展语句模板的类。

## 类摘要

class SQLite3Stmt {
/* 方法 */
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

### 说明

public function SQLite3Stmt::bindParam(string|int `$param`, mixed `&$var`, int `$type` = `SQLITE3_TEXT`): bool

Binds a parameter to a statement variable.

警告

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.

### 参数

`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`.

  > 注意:

  > If `var` is `null`, it is always treated as `SQLITE3_NULL`, regardless of the given `type`.

### 返回值

Returns `true` if the parameter is bound to the statement variable, `false` on failure.

### 更新日志

版本 | 说明
--- | ---
7.4.0 | `param` now also supports the `@param` notation.

### 示例

示例 #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);
    }
    ?>

以上示例会输出：

    array(1) {
      ["bar"]=>
      string(3) "baz"
    }
    array(1) {
      ["bar"]=>
      string(2) "42"
    }

### 参见

- SQLite3Stmt::bindValue() - Binds the value of a parameter to a statement variable
- SQLite3::prepare() - Prepares an SQL statement for execution

# SQLite3Stmt::bindValue

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::bindValue — Binds the value of a parameter to a statement variable

### 说明

public function SQLite3Stmt::bindValue(string|int `$param`, mixed `$value`, int `$type` = `SQLITE3_TEXT`): bool

Binds the value of a parameter to a statement variable.

警告

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.

### 参数

`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`.

  > 注意:

  > If `value` is `null`, it is always treated as `SQLITE3_NULL`, regardless of the given `type`.

### 返回值

Returns `true` if the value is bound to the statement variable, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
7.4.0 | `param` now also supports the `@param` notation.

### 示例

示例 #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));
    ?>

以上示例会输出：

    array(1) {
      ["bar"]=>
      string(14) "This is a test"
    }

### 参见

- SQLite3Stmt::bindParam() - Binds a parameter to a statement variable
- SQLite3::prepare() - Prepares an SQL statement for execution

# SQLite3Stmt::clear

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::clear — Clears all current bound parameters

### 说明

public function SQLite3Stmt::clear(): bool

Clears all current bound parameters (sets them to `null`).

警告

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.

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function SQLite3Stmt::close(): true

Closes the prepared statement.

> 注意: Note that all SQLite3Results that have been retrieved by executing this statement will be invalidated when the statement is closed.

### 参数

此函数没有参数。

### 返回值

总是返回 `true`。

### 错误／异常

An Error is thrown if the method is called on an uninitialized object.

### 更新日志

版本 | 说明
--- | ---
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

### 说明

private function SQLite3Stmt::__construct(SQLite3 `$sqlite3`, string `$query`)

SQLite3Stmt instances are created by SQLite3::prepare().

### 参数

`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

### 说明

public function SQLite3Stmt::execute(): SQLite3Result|false

Executes a prepared statement and returns a result set object.

警告

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.

### 参数

此函数没有参数。

### 返回值

Returns an SQLite3Result object on successful execution of the prepared statement, `false` on failure.

### 参见

- SQLite3::prepare() - Prepares an SQL statement for execution
- 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

### 说明

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.

### 参数

`expand`

  Whether to retrieve the expanded SQL. Passing `true` is only supported as of libsqlite 3.14.

### 返回值

Returns the SQL of the prepared statement, 或者在失败时返回 `false`.

### 错误／异常

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().

### 示例

示例 #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));
    ?>

以上示例的输出类似于：

    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

### 说明

public function SQLite3Stmt::paramCount(): int

Returns the number of parameters within the prepared statement.

### 参数

此函数没有参数。

### 返回值

Returns the number of parameters within the prepared statement.

### 参见

- SQLite3::prepare() - Prepares an SQL statement for execution

# SQLite3Stmt::readOnly

(PHP 5 >= 5.3.6, PHP 7, PHP 8)

SQLite3Stmt::readOnly — Returns whether a statement is definitely read only

### 说明

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.

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function SQLite3Stmt::reset(): bool

Resets the prepared statement to its state prior to execution. All bindings remain intact after reset.

### 参数

此函数没有参数。

### 返回值

Returns `true` if the statement is successfully reset, 或者在失败时返回 `false`.

## 目录

- 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 类

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## 简介

处理 SQLite 3 扩展返回结果集的类。

## 类摘要

class SQLite3Result {
/* 方法 */
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

### 说明

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.

### 参数

`column`

  The numeric zero-based index of the column.

### 返回值

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

### 说明

public function SQLite3Result::columnType(int `$column`): int|false

Returns the type of the column identified by `column`.

### 参数

`column`

  The numeric zero-based index of the column.

### 返回值

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

### 说明

private function SQLite3Result::__construct()

SQLite3Result instances are created by SQLite3::query() and SQLite3Stmt::execute().

### 参数

此函数没有参数。

# 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

### 说明

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.

### 参数

`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

### 返回值

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

### 说明

public function SQLite3Result::finalize(): true

Closes the result set.

### 参数

此函数没有参数。

### 返回值

总是返回 `true`。

### 错误／异常

An Error is thrown if the method is called on an uninitialized object.

### 更新日志

版本 | 说明
--- | ---
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

### 说明

public function SQLite3Result::numColumns(): int

Returns the number of columns in the result set.

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function SQLite3Result::reset(): bool

Resets the result set back to the first row.

### 参数

此函数没有参数。

### 返回值

Returns `true` if the result set is successfully reset back to the first row, `false` on failure.

## 目录

- 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

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
- 预定义常量
- SQLite3 — SQLite3 类
  - SQLite3::backup — Backup one database to another database
  - SQLite3::busyTimeout — Sets the busy connection handler
  - SQLite3::changes — Returns the number of database rows that were changed (or inserted or deleted) by the most recent SQL statement
  - SQLite3::close — Closes the database connection
  - SQLite3::__construct — 实例化 SQLite3 对象并打开 SQLite 3 数据库
  - SQLite3::createAggregate — Registers a PHP function for use as an SQL aggregate function
  - SQLite3::createCollation — Registers a PHP function for use as an SQL collating function
  - SQLite3::createFunction — Registers a PHP function for use as an SQL scalar function
  - SQLite3::enableExceptions — Enable throwing exceptions
  - SQLite3::escapeString — Returns a string that has been properly escaped
  - SQLite3::exec — Executes a result-less query against a given database
  - SQLite3::lastErrorCode — Returns the numeric result code of the most recent failed SQLite request
  - SQLite3::lastErrorMsg — Returns English text describing the most recent failed SQLite request
  - SQLite3::lastInsertRowID — Returns the row ID of the most recent INSERT into the database
  - SQLite3::loadExtension — Attempts to load an SQLite extension library
  - SQLite3::open — Opens an SQLite database
  - SQLite3::openBlob — Opens a stream resource to read a BLOB
  - SQLite3::prepare — Prepares an SQL statement for execution
  - SQLite3::query — Executes an SQL query
  - 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 — 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 — 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

# 简介

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.

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置
- 资源类型

## 需求

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.

## 安装

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.

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

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 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
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

## 资源类型

## Connection resource

A connection resource returned by sqlsrv_connect().

## Statement resource

A statement resource returned by sqlsrv_query() or by sqlsrv_prepare().

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`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 warings 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 函数

# sqlsrv_begin_transaction

(No version information available, might only be in Git)

sqlsrv_begin_transaction — Begins a database transaction

### 说明

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.

### 参数

`conn`
  The connection resource returned by a call to sqlsrv_connect().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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 />";
    }
    ?>

以上示例的输出类似于：

### 参见

- 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

### 说明

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.

### 参数

`stmt`
  The statement resource to be cancelled.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

### 注释

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.

### 参见

- 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

### 说明

function sqlsrv_client_info(resource `$conn`): array

Returns information about the client and specified connection

### 参数

`conn`
  The connection about which information is returned.

### 返回值

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)

### 示例

示例 #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 />";
    }
    ?>

### 参见

- 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 resourses associated with the connection

### 说明

function sqlsrv_close(resource `$conn`): bool

Closes an open connection and releases resourses associated with the connection.

### 参数

`conn`
  The connection to be closed.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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 );
    ?>

### 参见

- 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()

### 说明

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.

### 参数

`conn`
  The connection on which the transaction is to be committed.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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 />";
    }
    ?>

### 参见

- 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

### 说明

function sqlsrv_configure(string `$setting`, mixed `$value`): bool

Changes the driver error handling and logging configurations.

### 参数

`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)

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- » 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

### 说明

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.

### 参数

`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.

### 返回值

A connection resource. If a connection cannot be successfully opened, `false` is returned.

### 示例

示例 #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));
    }
    ?>

示例 #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));
    }
    ?>

示例 #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));
    }
    ?>

### 注释

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")).

### 参见

- sqlsrv_close() - Closes an open connection and releases resourses 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

### 说明

function sqlsrv_errors(int `$errorsOrWarnings` = ?): mixed

Returns error and warning information about the last SQLSRV operation performed.

### 参数

`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.

### 返回值

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.

### 示例

示例 #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 />";
            }
        }
    }
    ?>

### 注释

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.

### 参见

- 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()

### 说明

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.

### 参数

`stmt`
  A statement resource returned by sqlsrv_prepare().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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));
        }
    }
    ?>

### 注释

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().

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 示例

示例 #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;
    ?>

### 参见

- 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

### 说明

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).

### 参数

`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.

### 返回值

Returns an array on success, `null` if there are no more rows to return, and `false` if an error occurs.

### 示例

示例 #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);
    ?>

示例 #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);
    ?>

### 注释

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 ("").

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 示例

示例 #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 />";
    }
    ?>

### 注释

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().

### 参见

- 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()

### 说明

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.

### 参数

`stmt`
  The statement resource for which metadata is returned.

### 返回值

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.

### 示例

示例 #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 />";
    }
    ?>

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);

    ?>

### 注释

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.

### 参见

- 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

### 说明

function sqlsrv_get_config(string `$setting`): mixed

Returns the value of the specified configuration setting.

### 参数

`setting`
  The name of the setting for which the value is returned. For a list of configurable settings, see sqlsrv_configure().

### 返回值

Returns the value of the specified setting. If an invalid setting is specified, `false` is returned.

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

Returns data from the specified field on success. Returns `false` otherwise.

### 示例

示例 #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;
    ?>

### 参见

- 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

### 说明

function sqlsrv_has_rows(resource `$stmt`): bool

Indicates whether the specified statement has rows.

### 参数

`stmt`
  A statement resource returned by sqlsrv_query() or sqlsrv_execute().

### 返回值

Returns `true` if the specified statement has rows and `false` if the statement does not have rows or if an error occurred.

### 示例

示例 #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 />";
    }
    ?>

### 参见

- 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

### 说明

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.

### 参数

`stmt`
  The statement on which the next result is being called.

### 返回值

Returns `true` if the next result was successfully retrieved, `false` if an error occurred, and `null` if there are no more results to retrieve.

### 示例

示例 #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));
    }
    ?>

### 参见

- 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

### 说明

function sqlsrv_num_fields(resource `$stmt`): mixed

Retrieves the number of fields (columns) on a statement.

### 参数

`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.

### 返回值

Returns the number of fields on success. Returns `false` otherwise.

### 示例

示例 #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 />";
    }
    ?>

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 示例

示例 #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 retrieveing row count.";
    else
       echo $row_count;
    ?>

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

Returns a statement resource on success and `false` if an error occurred.

### 示例

示例 #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));
        }
    }
    ?>

### 注释

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().

### 参见

- 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

### 说明

function sqlsrv_query(
resource `$conn`,
string `$sql`,
array `$params` = ?,
array `$options` = ?
): mixed

Prepares and executes a query.

### 参数

`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.

### 返回值

Returns a statement resource on success and `false` if an error occurred.

### 示例

示例 #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));
    }
    ?>

### 注释

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().

### 参见

- 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()

### 说明

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.

### 参数

`conn`
  The connection resource returned by a call to sqlsrv_connect().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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 />";
    }
    ?>

### 参见

- 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

### 说明

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().

### 参数

`stmt`
  The executed statement resource for which the number of affected rows is returned.

### 返回值

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.

### 示例

示例 #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 />";
    }
    ?>

### 参见

- 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

### 说明

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.

### 参数

`stmt`
  A statement resource returned by sqlsrv_query() or sqlsrv_execute().

### 返回值

Returns `true` if there is more data to send and `false` if there is not.

### 示例

示例 #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.";
    ?>

### 参见

- 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

### 说明

function sqlsrv_server_info(resource `$conn`): array

Returns information about the server.

### 参数

`conn`
  The connection resource that connects the client and the server.

### 返回值

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.

### 示例

示例 #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));
    }
    ?>

### 参见

- sqlsrv_client_info() - Returns information about the client and specified connection

## 目录

- 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 resourses 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

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
  - 资源类型
- 预定义常量
- SQLSRV 函数
  - 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 resourses 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
  - 安装/配置
  - 预定义常量
  - 示例
  - CUBRID 函数
  - CUBRID MySQL 兼容性函数
  - CUBRID 过时的别名和函数
- dBase
  - 安装/配置
  - 预定义常量
  - dBase 函数
- Firebird/InterBase
  - 安装/配置
  - 预定义常量
  - Firebird/InterBase 函数
- IBM DB2 — IBM DB2, Cloudscape and Apache Derby
  - 安装/配置
  - 预定义常量
  - IBM DB2 函数
- MongoDB — MongoDB Extension
  - 安装/配置
  - 预定义常量
  - Tutorials
  - Driver Architecture and Internals — Explains the driver architecture, and special features
  - Security
  - MongoDB\Driver — MongoDB 扩展类
  - MongoDB\BSON — MongoDB BSON Classes and Functions
  - MongoDB\Driver\Monitoring — Monitoring classes and subscriber functions
  - MongoDB\Driver\Exception — Exception 类
- MySQL — MySQL Drivers and Plugins
  - Overview of the MySQL PHP drivers
  - MySQLi — MySQL增强版扩展
  - Mysql_xdevapi
  - Mysql（原始） — 原始的 MySQL API
  - Mysqlnd — MySQL Native Driver
- OCI8 — Oracle OCI8
  - 安装/配置
  - 预定义常量
  - 示例
  - 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 函数
  - OCICollection — The OCICollection class
  - OCILob — The OCILob class
  - OCI8 Obsolete Aliases and Functions
- PostgreSQL
  - 安装/配置
  - 预定义常量
  - 示例
  - PostgreSQL 函数
  - PgSql\Connection — The PgSql\Connection class
  - PgSql\Result — The PgSql\Result class
  - PgSql\Lob — The PgSql\Lob class
- SQLite3
  - 安装/配置
  - 预定义常量
  - SQLite3 — SQLite3 类
  - SQLite3Exception — The SQLite3Exception class
  - SQLite3Stmt — SQLite3Stmt 类
  - SQLite3Result — SQLite3Result 类
- SQLSRV — Microsoft SQL Server Driver for PHP
  - 安装/配置
  - 预定义常量
  - SQLSRV 函数

- 数据库抽象层
  - DBA — Database (dbm-style) Abstraction Layer
  - ODBC — ODBC (Unified)
  - PDO — PHP 数据对象
- 针对各数据库系统对应的扩展
  - CUBRID
  - dBase
  - Firebird/InterBase
  - IBM DB2 — IBM DB2, Cloudscape and Apache Derby
  - MongoDB — MongoDB Extension
  - MySQL — MySQL Drivers and Plugins
  - OCI8 — Oracle OCI8
  - PostgreSQL
  - SQLite3
  - SQLSRV — Microsoft SQL Server Driver for PHP

# 日期与时间相关扩展

# Calendar

# 简介

Calendar 扩展提供了一系列用于简化不同历法间格式转换的函数，它是以儒略日数为中介或标准来进行的。儒略日数是以公元前 4713 年 1 月 1 日为起点的计数法。为了在不同历法系统间进行转换，需要先转换成儒略日数，然后再转换为所需的历法系统。儒略日数和儒略历是非常不同的！儒略日数的更多信息可以参考 » http://www.hermetic.ch/cal_stud/jdn.htm，历法系统的更多信息可以参考 » http://www.fourmilab.ch/documents/calendar/。本页中的引用包括在相应的文章中并用引号引起来。

# 安装/配置

## 目录

- 安装

## 安装

要使用本类函数，需要在编译 PHP 时加上 --enable-calendar。

PHP 的 Windows 版本已内建对此扩展的支持。不需要载入额外的扩展来使用这些函数。

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`CAL_EASTER_DEFAULT` (int)
  easter_days()：根据儒略历计算 1753 年之前的复活节，并根据公历计算之后的复活节。
`CAL_EASTER_ROMAN` (int)
  easter_days()：根据儒略历计算 1583 年之前的复活节，并根据公历计算之后的复活节。
`CAL_EASTER_ALWAYS_GREGORIAN` (int)
  easter_days()：根据公历计算复活节。
`CAL_EASTER_ALWAYS_JULIAN` (int)
  easter_days()：根据儒略历计算复活节。
`CAL_GREGORIAN` (int)
  cal_days_in_month()、cal_from_jd()、cal_info() 和 cal_to_jd()：使用前公历。
`CAL_JULIAN` (int)
  cal_days_in_month()、cal_from_jd()、cal_info() 和 cal_to_jd()：使用儒略历。
`CAL_JEWISH` (int)
  cal_days_in_month()、cal_from_jd()、cal_info() 和 cal_to_jd()：使用犹太历。
`CAL_FRENCH` (int)
  cal_days_in_month()、cal_from_jd()、cal_info() 和 cal_to_jd()：使用法国共和历。
`CAL_NUM_CALS` (int)
  可用历法的数量。
`CAL_JEWISH_ADD_ALAFIM_GERESH` (int)
  jdtojewish()：在年份中添加 geresh 符号（类似单引号）作为千位分隔符。
`CAL_JEWISH_ADD_ALAFIM` (int)
  jdtojewish()：在年份中添加单词 alafim 作为千位分隔符。
`CAL_JEWISH_ADD_GERESHAYIM` (int)
  For jdtojewish(): add a gershayim symbol (which resembles a double-quote mark) before the final letter of the day and year numbers.
`CAL_DOW_DAYNO` (int)
  jddayofweek()：用 int 表示星期几，`0` 表示星期日，`6` 表示星期六。
`CAL_DOW_SHORT` (int)
  jddayofweek()：星期几的英文名称缩写。
`CAL_DOW_LONG` (int)
  jddayofweek()：星期几的英文名称。
`CAL_MONTH_GREGORIAN_SHORT` (int)
  jdmonthname()：公历月份名称缩写。
`CAL_MONTH_GREGORIAN_LONG` (int)
  jdmonthname()：公历月份名称。
`CAL_MONTH_JULIAN_SHORT` (int)
  jdmonthname()：儒略历月份名称缩写。
`CAL_MONTH_JULIAN_LONG` (int)
  jdmonthname()：儒略历月份名称。
`CAL_MONTH_JEWISH` (int)
  jdmonthname()：犹太历月份名称。
`CAL_MONTH_FRENCH` (int)
  jdmonthname()：法国共和历月份名称。

# Calendar 函数

# cal_days_in_month

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_days_in_month — 返回指定历法中某年某月的天数

### 说明

function cal_days_in_month(int `$calendar`, int `$month`, int `$year`): int

此函数返回指定 `calendar` 中的某 `year` 中的某 `month` 的天数。

### 参数

`calendar`

  用来计算的历法

`month`

  指定历法中的某月

`year`

  指定历法中的某年

### 返回值

指定历法中所选月份的天数

### 示例

示例 #1 cal_days_in_month() 示例

    <?php
    $number = cal_days_in_month(CAL_GREGORIAN, 8, 2003); // 31
    echo "There were {$number} days in August 2003";
    ?>

# cal_from_jd

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_from_jd — 从儒略日数转换为支持的历法

### 说明

function cal_from_jd(int `$julian_day`, int `$calendar`): array

cal_from_jd() 根据 `julian_day` 指定的儒略日 转换为指定 `calendar` 中的日期。`calendar` 支持的值有 `CAL_GREGORIAN`、`CAL_JULIAN`、`CAL_JEWISH` 和 `CAL_FRENCH`。

### 参数

`julian_day`

  int 类型的儒略日

`calendar`

  要转换为的历法

### 返回值

返回包含的历法信息的数组，例如月、日、年、星期几（`dow` ）、星期和月份的缩写和全称、日期的 string 形式是“月/日/年”。 星期几的范围是从 `0` （星期天）到 `6`（星期六）。

### 示例

示例 #1 cal_from_jd() 示例

    <?php
    $today = unixtojd(mktime(0, 0, 0, 8, 16, 2003));
    print_r(cal_from_jd($today, CAL_GREGORIAN));
    ?>

以上示例会输出：

    Array
    (
        [date] => 8/16/2003
        [month] => 8
        [day] => 16
        [year] => 2003
        [dow] => 6
        [abbrevdayname] => Sat
        [dayname] => Saturday
        [abbrevmonth] => Aug
        [monthname] => August
    )

### 参见

- cal_to_jd() - 从支持的历法转换为儒略日数
- jdtofrench() - 从儒略日数转换为法国共和历
- jdtogregorian() - 将儒略日数转换为公历日期
- jdtojewish() - 将儒略日数转换为犹太历日期
- jdtojulian() - 将儒略日数转换为儒略历日期
- jdtounix() - 将儒略日数转换为 Unix 时间戳

# cal_info

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_info — 返回选定历法的信息

### 说明

function cal_info(int `$calendar` = -1): array

cal_info() 返回选定 `calendar` 的信息。

以数组的形式返回历法信息，包含的元素有 `calname`（历法名称）、`calsymbol`（历法代码）、`month` （月份）、`abbrevmonth`（月份的缩写）和 `maxdaysinmonth`（单月的最多天数）。`calendar` 参数可以使用下列值指定不同历法的名称：

- 0 或者 `CAL_GREGORIAN` - 公历
- 1 或者 `CAL_JULIAN` - 儒略历
- 2 或者 `CAL_JEWISH` - 犹太历
- 3 或者 `CAL_FRENCH` - 法国共和历

如果没有指定参数 `calendar`，所支持的所有历法将以数组形式返回。

### 参数

`calendar`

  返回指定历法的信息，如果没有指定，将返回所有历法信息。

### 返回值

### 示例

示例 #1 cal_info() 示例

    <?php
    $info = cal_info(0);
    print_r($info);
    ?>

以上示例会输出：

    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 — 从支持的历法转换为儒略日数

### 说明

function cal_to_jd(
int `$calendar`,
int `$month`,
int `$day`,
int `$year`
): int

cal_to_jd() 计算指定 `calendar` 中某个日期的儒略日数。支持的历法有 `CAL_GREGORIAN`、`CAL_JULIAN`、`CAL_JEWISH` 和 `CAL_FRENCH`。

### 参数

`calendar`

  要转换的历法，可以是 `CAL_GREGORIAN`、`CAL_JULIAN`、`CAL_JEWISH`、`CAL_FRENCH` 中的一个。

`month`

  数字类型的月份，根据 `calendar` 来确定有效范围。

`day`

  数字类型的日期，根据选定的 `calendar` 来确定有效范围。

`year`

  数字类型的年份，根据选定的 `calendar` 来确定有效范围。

### 返回值

儒略日数。

### 参见

- cal_from_jd() - 从儒略日数转换为支持的历法
- frenchtojd() - 从法国共和历日期转换为儒略日数
- gregoriantojd() - 将公历日期转为儒略日数
- jewishtojd() - 将犹太历日期转换为儒略日数
- juliantojd() - 儒略日期转为儒略日数
- unixtojd() - 将 Unix 时间戳转换为儒略日数

# easter_date

(PHP 4, PHP 5, PHP 7, PHP 8)

easter_date — 得到指定年份的复活节当地午夜时的 Unix 时间戳

### 说明

function easter_date(?int `$year` = `null`, int `$mode` = `CAL_EASTER_DEFAULT`): int

返回指定年份的复活节午夜时的 Unix 时间戳。

复活节的日期是由尼西亚议会在公元 325 年确定的为每年春分月圆后的第一个星期日。春分一般是在 3 月 21 日，这就简化为只要计算满月的日期和紧挨的星期日的日期。这里所用的算法是在 532 年由 Dionysius Exiguus 引入。在 1753 年以前用儒略历计算，一个简单的 19 年周期用于追踪月相。在 1753 年之后公历（由 Clavius 和 Lilius 设计，1582 年 10 月由教皇 Gregory 十三世引入，并于 1752 年 9 月进入英国及其当时的殖民地）添加了两个校正因子以使周期更准确。

### 参数

`year`

  对于 32 位系统，年份必须是 1970 至 2037 之间的数字，对于 64 位系统，年份必须是 1970 到 2,000,000,000 之间的数字。如果省略或者为 `null`，则根据本地时间默认为当前年份。

`mode`

  当设置为 `CAL_EASTER_ALWAYS_JULIAN` 时，允许基于儒略历计算复活节时间。参见 calendar 常量。

### 返回值

复活节日期的 Unix 时间戳。

### 错误／异常

如果年份早于 1970，或者晚于 32 位系统的 2037 以及 64 位系统上的 2,000,000,000 时会抛出 ValueError。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | 在 64 位系统上，`year` 参数现在接受范围在 1970 到 2,000,000,000 的值。
8.0.0 | `year` 现在可为空（nullable）。
8.0.0 | 当 `year` 超出允许的范围现在抛出 ValueError。之前函数会返回 `false` 会触发 `E_WARNING`。

### 示例

示例 #1 easter_date() 示例

    <?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

    ?>

示例 #2 使用带 DateTime 的 easter_date()

    <?php

    $timestamp = easter_date(2023);

    $datetime = new \DateTime();
    $datetime->setTimestamp($timestamp);

    echo $datetime->format('M-d-Y'); // Apr-09-2023

    ?>

### 注释

> 注意:

> easter_date() 依赖于系统的 C 库 time 函数，而不是使用 PHP 内置的 date 和 time 函数。因此 easter_date() 使用 `TZ` 环境变量来确定应该运行的时区，而不是使用 PHP 默认时区 ，此函数与 PHP 其他 date 函数一起使用时会出现意外行为。

> 有一种解决方案，可以使用带 DateTime 和 DateInterval 的 easter_days() 来计算 PHP 时区中的复活节开始时间，如下所示：

>     <?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("Easter in %d is on %s\n",
>                $year,
>                get_easter_datetime($year)->format('F j'));
>     }
>     ?>

> 以上示例会输出：

>     Easter in 2012 is on April 8
>     Easter in 2013 is on March 31
>     Easter in 2014 is on April 20
>     Easter in 2015 is on April 5

### 参见

- easter_days() - 得到指定年份的 3 月 21 日到复活节之间的天数 用于计算 1970 年之前或 2037 年之后的复活节。

# easter_days

(PHP 4, PHP 5, PHP 7, PHP 8)

easter_days — 得到指定年份的 3 月 21 日到复活节之间的天数

### 说明

function easter_days(?int `$year` = `null`, int `$mode` = `CAL_EASTER_DEFAULT`): int

返回指定年份的 3 月 21 日到复活节之间的天数，如果没有指定年份，默认是当年。

此函数可以用来代替 easter_date() 来计算超出 Unix 时间戳范围（比如 1970 年以前或 2037 年以后）的年份的复活节日期。

复活节的日期是由尼西亚议会在公元 325 年确定的为每年春分月圆后的第一个星期日。春分一般是在 3 月 21 日，这就简化为只要计算满月的日期和紧挨的星期日的日期。这里所用的算法是在 532 年由 Dionysius Exiguus 引入。在 1753 年以前用儒略历计算，一个简单的 19 年周期用于追踪月相。在 1753 年之后公历（由 Clavius 和 Lilius 设计，1582 年 10 月由教皇 Gregory 十三世引入，并于 1752 年 9 月进入英国及其当时的殖民地）添加了两个校正因子以使周期更准确。

### 参数

`year`

  年份为正整数。如果省略或为 `null`, 默认为本地时间的当前年份。

`mode`

  当设置为 `CAL_EASTER_ROMAN` 时，允许用公历来计算 1582 年至 1752 年之间的复活节日期。更多有效常量参考 calendar 常量。

### 返回值

根据指定参数 `year` 而返回 3 月 21 日至复活节的天数。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `year` 现在可为空（nullable）。

### 示例

示例 #1 easter_days() 示例

    <?php

    echo easter_days(1999);        // 14, i.e. April 4
    echo easter_days(1492);        // 32, i.e. April 22
    echo easter_days(1913);        //  2, i.e. March 23

    ?>

### 参见

- easter_date() - 得到指定年份的复活节当地午夜时的 Unix 时间戳

# frenchtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

frenchtojd — 从法国共和历日期转换为儒略日数

### 说明

function frenchtojd(int `$month`, int `$day`, int `$year`): int

从法国历日期转换为儒略日数。

该函数仅转换第 1 年到第 14 年之间的日期（公历 1792 年 9 月 22 日到 1806 年 9 月 22 日）。 这涵盖并且超出了这个历法实际上采用的时间。

### 参数

`month`

  月份的范围是 1 （Vendémiaire）到 13（每年年底的 5 到 6 天）之间的数字。

`day`

  天的范围是 1 到 30 之间的数字

`year`

  年份的范围是 1 到 14 之间的数字

### 返回值

指定法国共和历日期的 int 类型儒略日数。

### 参见

- jdtofrench() - 从儒略日数转换为法国共和历
- cal_to_jd() - 从支持的历法转换为儒略日数

# gregoriantojd

(PHP 4, PHP 5, PHP 7, PHP 8)

gregoriantojd — 将公历日期转为儒略日数

### 说明

function gregoriantojd(int `$month`, int `$day`, int `$year`): int

公历的有效范围是从公元前 4714 年 11 月 25 日开始。至少到公元 9999 年 12 月 31 日

虽然这个函数可以处理追溯到公元前 4714 年以前的日期，但这样做可能没有意义。公历直到 1582 年 10 年 15 日（或是儒略历 1582 年 10 月 5 日）才被发明，一些国家直到很久以后才接受它。比如，英国是在 1752 年开始使用公历，苏联是在 1918 年，希腊是在 1923 年，大部分的欧洲国家在公历前使用儒略历。

### 参数

`month`

  月份的范围是 1（January）到 12（December）之间的数字。

`day`

  天的范围是 1 到 31 之间的数字。如果该月的天数小于指定的天数， 则会发生溢出。请参考下面的示例。

`year`

  年份的范围是 -4714 到 9999 之间的数字。负数表示公元前，正数表示公元。注意没有公元 `0` 年，公元前 1 年 12 月 31 日紧跟其后的是公元 1 年 1 月 1 日。

### 返回值

int 类型的指定公历日期的儒略日。日期超出范围值返回 `0`。

### 示例

示例 #1 历法函数

    <?php
    $jd = gregoriantojd(10, 11, 1970);
    echo "$jd\n";
    $gregorian = jdtogregorian($jd);
    echo "$gregorian\n";
    ?>

以上示例会输出：

    2440871
    10/11/1970

示例 #2 溢出行为

    <?php
    echo gregoriantojd(2, 31, 2018), PHP_EOL,
         gregoriantojd(3,  3, 2018), PHP_EOL;
    ?>

以上示例会输出：

    2458181
    2458181

### 参见

- jdtogregorian() - 将儒略日数转换为公历日期
- cal_to_jd() - 从支持的历法转换为儒略日数

# jddayofweek

(PHP 4, PHP 5, PHP 7, PHP 8)

jddayofweek — 返回星期几

### 说明

function jddayofweek(int `$julian_day`, int `$mode` = `CAL_DOW_DAYNO`): int|string

返回星期几，根据模式不同返回 string 或 int。

### 参数

`julian_day`

  int 类型的儒略日数

`mode`

  历法星期模式
  模式 | 含义
  --- | ---
  0 (默认) | 返回 int 类型的星期几（0 = Sunday， 1 = Monday，等等）
  1 | 以英文返回公历形式的 string 类型的星期几
  2 | 以英文返回公历形式的 string 类型的星期几缩写

### 返回值

int 或 string 类型的公历星期几。

# jdmonthname

(PHP 4, PHP 5, PHP 7, PHP 8)

jdmonthname — 返回月份名称

### 说明

function jdmonthname(int `$julian_day`, int `$mode`): string

返回 string 类型的月份名称，`mode` 告诉此函数要将儒略历转化为哪个历法以及哪个类型的月份名称。

历法模式
模式 | 含义 | 值
--- | --- | ---
`CAL_MONTH_GREGORIAN_SHORT` | 公历 - 缩写 | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
`CAL_MONTH_GREGORIAN_LONG` | 公历 | January, February, March, April, May, June, July, August, September, October, November, December
`CAL_MONTH_JULIAN_SHORT` | 儒略历 - 缩写 | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
`CAL_MONTH_JULIAN_LONG` | 儒略历 | January, February, March, April, May, June, July, August, September, October, November, December
`CAL_MONTH_JEWISH` | 犹太历 | Tishri, Heshvan, Kislev, Tevet, Shevat, Adar, Adar I, Adar II, Nisan, Iyyar, Sivan, Tammuz, Av, Elul
`CAL_MONTH_FRENCH` | 法国历 | Vendemiaire, Brumaire, Frimaire, Nivose, Pluviose, Ventose, Germinal, Floreal, Prairial, Messidor, Thermidor, Fructidor, Extra

### 参数

`julian_day`

  用来计算的儒略日

`mode`

  历法模式（见上表）。

### 返回值

指定的儒略日和 `mode` 的月份的名称。

# jdtofrench

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtofrench — 从儒略日数转换为法国共和历

### 说明

function jdtofrench(int `$julian_day`): string

从儒略日数转换为法国共和历。

### 参数

`julian_day`

  int 类型的儒略日数

### 返回值

string 类型，“月/日/年”格式的法国共和历日期

### 参见

- frenchtojd() - 从法国共和历日期转换为儒略日数
- cal_from_jd() - 从儒略日数转换为支持的历法

# jdtogregorian

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtogregorian — 将儒略日数转换为公历日期

### 说明

function jdtogregorian(int `$julian_day`): string

将儒略日数转换为“月/日/年”格式，string 类型的公历日期。

### 参数

`julian_day`

  int 类型的儒略日数

### 返回值

格式为 “月/日/年”，string 类型的公历日期

### 参见

- gregoriantojd() - 将公历日期转为儒略日数
- cal_from_jd() - 从儒略日数转换为支持的历法

# jdtojewish

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtojewish — 将儒略日数转换为犹太历日期

### 说明

function jdtojewish(int `$julian_day`, bool `$hebrew` = `false`, int `$flags` = 0): string

儒略日数转为犹太历日期。

### 参数

`julian_day`

  int 类型的儒略日数。

`hebrew`

  如果参数 `hebrew` 设置为 `true`，参数 `flags` 可用于希伯莱语、基于 ISO-8859-8 字符串编码格式的输出。

`flags`

  可能由 `CAL_JEWISH_ADD_ALAFIM_GERESH`、 `CAL_JEWISH_ADD_ALAFIM`、 `CAL_JEWISH_ADD_GERESHAYIM` 组成的位掩码。

### 返回值

根据 `hebrew` 参数返回格式为“月/日/年”的犹太日期或者 ISO-8859-8 编码的希伯来日期字符串。

### 示例

示例 #1 jdtojewish() 示例

    <?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;

以上示例会输出：

    ב חשון התשסג
    ב' חשון התשס"ג
    ב חשון ה אלפים תשסג
    ב חשון ה'תשסג

### 参见

- jewishtojd() - 将犹太历日期转换为儒略日数
- cal_from_jd() - 从儒略日数转换为支持的历法

# jdtojulian

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtojulian — 将儒略日数转换为儒略历日期

### 说明

function jdtojulian(int `$julian_day`): string

将儒略日数转换成格式为“月/日/年”，string 类型的儒略历日期。

### 参数

`julian_day`

  int 类型的儒略日数

### 返回值

“月/日/年”格式，string 类型的儒略日期

### 参见

- juliantojd() - 儒略日期转为儒略日数
- cal_from_jd() - 从儒略日数转换为支持的历法

# jdtounix

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtounix — 将儒略日数转换为 Unix 时间戳

### 说明

function jdtounix(int `$julian_day`): int

这个函数将返回与 `julian_day` 给出的儒略日相对应的 Unix 时间戳。返回的时间是 UTC。

### 参数

`julian_day`

  儒略日数在 64 位系统上是 `2440588` 到 `106751993607888` 之间的数字，在 32 位系统上是 `2440588` 到 `2465443` 之间的数字。

### 返回值

指定儒略日的开始时（午夜，而非中午）的 unix 时间戳。

### 错误／异常

`julian_day` 超出允许的范围值，抛出 ValueError。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 此函数在失败时不再返回 `false`，而是引发 ValueError。
7.3.24, 7.4.12 | 扩充了 `julian_day` 的上限。以前无论计算机体系结构如何，都是 `2465342`。

### 参见

- unixtojd() - 将 Unix 时间戳转换为儒略日数

# jewishtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

jewishtojd — 将犹太历日期转换为儒略日数

### 说明

function jewishtojd(int `$month`, int `$day`, int `$year`): int

尽管这个函数可以处理元年（公元前 3761 年）以前的年份，但这样做可能没有意义。 犹太历被用了几千年，但早期的时候一个月的开始没有固定的准则，通常是观察到一个新月后定为一个月份的开始。

### 参数

`month`

  月份为 `1` 到 `13` 之间的数字， `1` 代表 `Tishri`， `13` 代表 `Elul`， `6` 和 `7` 代表平年中的 `Adar`，但在闰年则分别代表 `Adar I` 和 `Adar II`。

`day`

  天数为 `1` 到 `30` 之间的数字。如果这个月只有 29 天，则假设第 30 天为下个月的第一天。

`year`

  年份为 1 到 9999 之间的数字

### 返回值

指定犹太历日期所对应的 int 类型的儒略日。

### 参见

- jdtojewish() - 将儒略日数转换为犹太历日期
- cal_to_jd() - 从支持的历法转换为儒略日数

# juliantojd

(PHP 4, PHP 5, PHP 7, PHP 8)

juliantojd — 儒略日期转为儒略日数

### 说明

function juliantojd(int `$month`, int `$day`, int `$year`): int

儒略历的有效年份为公元前 4713 年到公元 9999 年。

尽管这个函数也可以处理追溯到公元前 4713 年以前的日期，但这样做可能没有意义。此历法是在公元前 46 年创建，但是到了公元 8 年细节才稳定，也有可能是 4 晚期。此外，每年的开始也因为文化的不同，不是所有人都接受 January 为第一个月份。

警告

记住，当今世界最广泛使用的历法系统是公历，函数 gregoriantojd() 可用于转换此类日期为儒略日数。

### 参数

`month`

  月的范围是 1 (January) 到 12 ( December) 之间的数字。

`day`

  天的范围是 1 到 31 之间的数字

`year`

  年的范围是 -4713 到 9999 之间的数字

### 返回值

指定儒略日期所对应的 int 类型的儒略日。

### 参见

- jdtojulian() - 将儒略日数转换为儒略历日期
- cal_to_jd() - 从支持的历法转换为儒略日数

# unixtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

unixtojd — 将 Unix 时间戳转换为儒略日数

### 说明

function unixtojd(?int `$timestamp` = `null`): int|false

根据指定的 Unix `timestamp` （自 1970 年 1 月 1 日以来的秒数）返回儒略日数。如果没有指定时间戳则返回当前日期的儒略日数。 无论哪种方式，时间都被视为当地时间（不是 UTC）。

### 参数

`timestamp`

  用于转换的 unix 时间戳。

### 返回值

int 类型的儒略日数， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `timestamp` 现在可以为 null。

### 参见

- jdtounix() - 将儒略日数转换为 Unix 时间戳

## 目录

- cal_days_in_month — 返回指定历法中某年某月的天数
- cal_from_jd — 从儒略日数转换为支持的历法
- cal_info — 返回选定历法的信息
- cal_to_jd — 从支持的历法转换为儒略日数
- easter_date — 得到指定年份的复活节当地午夜时的 Unix 时间戳
- easter_days — 得到指定年份的 3 月 21 日到复活节之间的天数
- frenchtojd — 从法国共和历日期转换为儒略日数
- gregoriantojd — 将公历日期转为儒略日数
- jddayofweek — 返回星期几
- jdmonthname — 返回月份名称
- jdtofrench — 从儒略日数转换为法国共和历
- jdtogregorian — 将儒略日数转换为公历日期
- jdtojewish — 将儒略日数转换为犹太历日期
- jdtojulian — 将儒略日数转换为儒略历日期
- jdtounix — 将儒略日数转换为 Unix 时间戳
- jewishtojd — 将犹太历日期转换为儒略日数
- juliantojd — 儒略日期转为儒略日数
- unixtojd — 将 Unix 时间戳转换为儒略日数

- 安装/配置
  - 安装
- 预定义常量
- Calendar 函数
  - cal_days_in_month — 返回指定历法中某年某月的天数
  - cal_from_jd — 从儒略日数转换为支持的历法
  - cal_info — 返回选定历法的信息
  - cal_to_jd — 从支持的历法转换为儒略日数
  - easter_date — 得到指定年份的复活节当地午夜时的 Unix 时间戳
  - easter_days — 得到指定年份的 3 月 21 日到复活节之间的天数
  - frenchtojd — 从法国共和历日期转换为儒略日数
  - gregoriantojd — 将公历日期转为儒略日数
  - jddayofweek — 返回星期几
  - jdmonthname — 返回月份名称
  - jdtofrench — 从儒略日数转换为法国共和历
  - jdtogregorian — 将儒略日数转换为公历日期
  - jdtojewish — 将儒略日数转换为犹太历日期
  - jdtojulian — 将儒略日数转换为儒略历日期
  - jdtounix — 将儒略日数转换为 Unix 时间戳
  - jewishtojd — 将犹太历日期转换为儒略日数
  - juliantojd — 儒略日期转为儒略日数
  - unixtojd — 将 Unix 时间戳转换为儒略日数

# 日期和时间

# 简介

DateTimeImmutable 和关联类允许表示日期/时间信息。通过传递字符串表述的日期/时间信息或从当前系统时间来创建这些对象。

还提供了丰富的方法来修改和格式化这些信息，包括处理时区和 DST（夏令时）转换。

PHP 中的日期/时间功能实现了 ISO 8601 历法，这是» 前公历，实现了公历之前的当前闰日规则，并且还包括 `0` 年作为介于两者之间的年份——`公元前 1 年`和`公元 1 年`。不支持闰秒。

日期和时间信息在内部是以 64 位数字存储的，所以支持所有可能有用的日期（包括负数年份）。其范围覆盖当前时间前后 2920 亿年的时间。

> 注意: 本节中用到的时区可以从所支持的时区列表获取。

# 安装/配置

## 目录

- 安装
- 运行时配置

## 安装

使用这些函数不需要安装，它们是 PHP 核心的一部分。

> 注意: 获取最新版的时区数据

> 可以通过安装 PECL 的 » timezonedb 获取最新的时区数据。

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

日期/时间配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
date.default_latitude | "31.7667" | `INI_ALL` |
date.default_longitude | "35.2333" | `INI_ALL` |
date.sunrise_zenith | "90.833333" | `INI_ALL` | 在 PHP 8.0.0 之前，默认值是“90.583333”
date.sunset_zenith | "90.833333" | `INI_ALL` | 在 PHP 8.0.0 之前，默认值是“90.583333”
date.timezone | "UTC" | `INI_ALL` | 自 PHP 8.2.0 起，将其设置为无效值或者空字符串时将发出警告。

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`date.default_latitude` float

  默认纬度范围从赤道的 `0` 到向北 `+90` 和向南 `-90`。

`date.default_longitude` float

  默认经度范围从本初子午线的 `0` 到向东 `+180` 和向西 `−180`。

`date.sunrise_zenith` float

  日出时默认天顶。

  默认值是 90°50'。额外的 50' 是因为两个部分：太阳半径（即 16'）及大气折射（即 34'）。

`date.sunset_zenith` float

  日落时默认天顶。

`date.timezone` string

  所有日期/时间函数使用的默认时区。date_default_timezone_get() 页面中描述了在没有明确提及时区的情况下使用时区的优先顺序。参见所支持的时区列表以获得支持的时区列表。

> 注意: 前四个配置选项目前仅用于 date_sunrise() 和 date_sunset()。

# 预定义常量

已定义的 `DATE_*` 常量提供了一些标准的日期时间的表达，可以用在日期时间格式化的函数中（例如 date()）。

date_sunrise() 和 date_sunset() 的有效 `returnFormat`
警告

自 PHP 8.4.0 起，已弃用这些常量。相应的 date_sunrise() 和 date_sunset() 函数自 PHP 8.1.0 起已弃用。

`SUNFUNCS_RET_TIMESTAMP` （int）
  时间戳
`SUNFUNCS_RET_STRING` （int）
  小时:分钟（例如：`08:02`）
`SUNFUNCS_RET_DOUBLE` （int）
  浮点数表示的小时（例如：`8.75`）

`DATE_*` constants
`DATE_ATOM` (string)
  Atom（示例：`2005-08-15T15:52:01+00:00`）；兼容 ISO-8601、RFC 3339 和 XML Schema
`DATE_COOKIE` (string)
  HTTP Cookie（示例：`Monday, 15-Aug-2005 15:52:01 UTC`）
`DATE_ISO8601` (string)
  类似 ISO-8601 格式（示例：`2005-08-15T15:52:01+0000`）

  > 注意: 此格式与 ISO-8601 不兼容，但出于向后兼容的原因，保留了这种格式。使用 `DATE_ISO8601_EXPANDED`、`DATE_ATOM` 来兼容 ISO-8601（参考 ISO8601:2004 第 4.3.3 节第 d 条）。

`DATE_ISO8601_EXPANDED` (string)
  ISO-8601 扩充（示例：`+10191-07-26T08:59:52+01:00`）

  > 注意: 此格式允许使用 ISO-8601 正常范围（`0000`-`9999`）之外的年份范围，只需包含一个字符即可。还确保时区部分 (`+01:00`) 与 ISO-8601 兼容。

`DATE_RFC822` (string)
  RFC 822（示例：`Mon, 15 Aug 05 15:52:01 +0000`）
`DATE_RFC850` (string)
  RFC 850（示例：`Monday, 15-Aug-05 15:52:01 UTC`）
`DATE_RFC1036` (string)
  RFC 1036（示例：`Mon, 15 Aug 05 15:52:01 +0000`）
`DATE_RFC1123` (string)
  RFC 1123（示例：`Mon, 15 Aug 2005 15:52:01 +0000`）
`DATE_RFC7231` (string)
  RFC 7231（自 PHP 7.0.19 和 7.1.5 起）（示例：`Sat, 30 Apr 2016 17:52:13 GMT`）
`DATE_RFC2822` (string)
  RFC 2822（示例：`Mon, 15 Aug 2005 15:52:01 +0000`）
`DATE_RFC3339` (string)
  与 `DATE_ATOM` 相同。
`DATE_RFC3339_EXTENDED` (string)
  RFC 3339 EXTENDED 格式（示例：`2005-08-15T15:52:01.000+00:00`）
`DATE_RSS` (string)
  RSS（示例：`Mon, 15 Aug 2005 15:52:01 +0000`）. 别名 `DATE_RFC1123`.
`DATE_W3C` (string)
  万维网联盟（示例：`2005-08-15T15:52:01+00:00`）。别名 `DATE_RFC3339`。

# 示例

## 目录

- 日期/时间算法

## 日期/时间算法

以下示例展示了有关 DST 转换和具有不同天数的月份的日期/时间算法的一些缺陷。

示例 #1 DateTimeImmutable::add/sub 添加包含经过时间的间隔

在 DST 转换上添加 PT24H 似乎会增加 23/25 小时（大多数时区）。

    <?php
    $dt = new DateTimeImmutable("2015-11-01 00:00:00", new DateTimeZone("America/New_York"));
    echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->add(new DateInterval("PT3H"));
    echo "End:   ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

以上示例会输出：

    Start: 2015-11-01 00:00:00 -04:00
    End:   2015-11-01 02:00:00 -05:00

示例 #2 DateTimeImmutable::modify 和 strtotime 递增/减单个组件值

在 DST 转换上添加 +24 小时将准确添加 24 小时，如日期/时间字符串中所示（除非开始/结束时间位于转换点）。

    <?php
    $dt = new DateTimeImmutable("2015-11-01 00:00:00", new DateTimeZone("America/New_York"));
    echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("+24 hours");
    echo "End:   ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

以上示例会输出：

    Start: 2015-11-01 00:00:00 -04:00
    End:   2015-11-02 00:00:00 -05:00

示例 #3 新增/减去时间可能会溢出/下溢日期

就像 1 月 31 日 + 1 月会导致 3 月 2 日（闰年）或 3 月 3 日（平年）。

    <?php
    echo "Normal year:\n"; // 2 月有 28 天
    $dt = new DateTimeImmutable("2015-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("+1 month");
    echo "End:   ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

    echo "Leap year:\n"; // 2 月有 29 天
    $dt = new DateTimeImmutable("2016-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("+1 month");
    echo "End:   ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

以上示例会输出：

    Normal year:
    Start: 2015-01-31 00:00:00 -05:00
    End:   2015-03-03 00:00:00 -05:00
    Leap year:
    Start: 2016-01-31 00:00:00 -05:00
    End:   2016-03-02 00:00:00 -05:00

要获取下个月的最后一天（例如防止溢出），可以使用 `last day of` 格式。

    <?php
    echo "Normal year:\n"; // 2 月有 28 天
    $dt = new DateTimeImmutable("2015-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("last day of next month");
    echo "End:   ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

    echo "Leap year:\n"; // 2 月有 29 天
    $dt = new DateTimeImmutable("2016-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("last day of next month");
    echo "End:   ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

以上示例会输出：

    Normal year:
    Start: 2015-01-31 00:00:00 -05:00
    End:   2015-02-28 00:00:00 -05:00
    Leap year:
    Start: 2016-01-31 00:00:00 -05:00
    End:   2016-02-29 00:00:00 -05:00

# DateTime 类

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

## 简介

日期和时间表示。

此类与 DateTimeImmutable 行为相同。区别就是调用有修改行为的方法（比如 DateTime::modify()）时，会修改对象本身。

警告

在 DateTime 类的对象上调用方法会改变对象中封装的信息，如果想要避免这种情况，就得使用 `clone` 操作符创建新的对象。推荐使用 DateTimeImmutable 代替 DateTime 来获得这个默认行为。

## 类摘要

class DateTime implements DateTimeInterface {
/* 继承的常量 */
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";
/* 方法 */
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
}

## 更新日志

版本 | 说明
--- | ---
8.4.0 | 类常量现已类型化。
7.2.0 | DateTime 的类常量现在定义在 DateTimeInterface 上。
7.1.0 | 现在 DateTime 构造器在构造值中包含了当前微秒。在此之前，微秒会一直初始化为 `0`。

# DateTime::add

# date_add

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::add -- date_add — 修改 DateTime 对象，增加天、月、年、小时、分钟以及秒的数量。

### 说明

面向对象风格

public function DateTime::add(DateInterval `$interval`): DateTime

过程化风格

function date_add(DateTime `$object`, DateInterval `$interval`): DateTime

将指定的 DateInterval 对象到 DateTime 对象。

跟 DateTimeImmutable::add()一样，但适用于 DateTime。

过程化版本将 DateTime 对象作为它的第一个参数。

### 参数

`object`
  仅过程化风格：由 date_create() 返回的 DateTime 类型的对象。此函数会修改这个对象。
`interval`

  DateInterval 对象。

### 返回值

返回方法链修改后的 DateTime 对象。

### 参见

- DateTimeImmutable::add() - Returns a new object, with added amount of days, months, years, hours, minutes and seconds

# DateTime::__construct

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::__construct — 返回新的 DateTime 对象

### 说明

public function DateTime::__construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)

跟 DateTimeImmutable::__construct() 一样，但适用于 DateTime。Consider using the DateTimeImmutable and features instead.

返回新的 DateTime 对象。

### 参数

`datetime`

  日期/时间字符串。正确格式的说明详见 日期与时间格式。

  如果这个参数为字符串 `"now"` 表示获取当前时间。 如果同时指定了 `$timezone` 参数，那么获取指定时区的当前时间。

`timezone`

  DateTimeZone 对象表示 `$datetime` 的时区。

  如果省略了 `$timezone` 参数或者传递 `null`， 那么会使用当前时区。

  > 注意:

  > 当 `$datetime` 参数是 UNIX 时间戳（例如 `@946684800`），或者已经包含时区信息（例如 `2010-01-28T15:00:00+02:00`）的时候，`$timezone` 参数和当前时区都将被忽略。

### 返回值

返回一个新的 DateTime 对象实例，或者在发生错误的时候返回

### 错误／异常

如果传递无效的日期/时间字符串，将会抛出 DateMalformedStringException，在 PHP 8.3 之前，将抛出 Exception。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | 传递无效的字符串现在抛出 DateMalformedStringException 而不是 Exception。

### 参见

- DateTimeImmutable::__construct() - Returns new DateTimeImmutable object

# DateTime::createFromFormat

# date_create_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::createFromFormat -- date_create_from_format — 根据指定格式解析时间字符串

### 说明

面向对象风格

public static function DateTime::createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTime|false

过程化风格

function date_create_from_format(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTime|false

返回新的 DateTime 对象，该对象是通过指定 `format` 将表示日期和时间的 `datetime` 格式化生成。

类似于 DateTimeImmutable::createFromFormat() 和 date_create_immutable_from_format()，但创建的是 DateTime 对象。

此方法（包括参数、示例和注意事项）记录在 DateTimeImmutable::createFromFormat 页面上。

### 参数

参阅 DateTimeImmutable::createFromFormat。

### 返回值

返回 DateTime 对象 或者在失败时返回 `false`。

### 错误／异常

当 `datetime` 包含 NULL 字节时，此方法抛出 ValueError。

### 更新日志

版本 | 说明
--- | ---
8.0.21、8.1.8、8.2.0 | 现在，当将 NULL 字节传递到 `datetime` 时，会引发 ValueError，而之前会默默忽略该错误。

### 示例

有关大量示例，请参阅 DateTimeImmutable::createFromFormat。

### 参见

- DateTimeImmutable::createFromFormat() - Parses a time string according to a specified format

# DateTime::createFromImmutable

(PHP 7 >= 7.3.0, PHP 8)

DateTime::createFromImmutable — Returns new DateTime instance encapsulating the given DateTimeImmutable object

### 说明

public static function DateTime::createFromImmutable(DateTimeImmutable `$object`): static

### 参数

`object`

  The immutable DateTimeImmutable object that needs to be converted to a mutable version. This object is not modified, but instead a new DateTime instance is created containing the same date, time, and timezone information.

### 返回值

Returns a new DateTime instance.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | The method returns an instance of the currently invoked class now. Previously, it created a new instance of DateTime.

### 示例

示例 #1 Creating a mutable date time object

    <?php
    $date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");
    $mutable = DateTime::createFromImmutable( $date );

# DateTime::createFromInterface

(PHP 8)

DateTime::createFromInterface — Returns new DateTime object encapsulating the given DateTimeInterface object

### 说明

public static function DateTime::createFromInterface(DateTimeInterface `$object`): DateTime

### 参数

`object`

  The DateTimeInterface object that needs to be converted to a mutable version. This object is not modified, but instead a new DateTime object is created containing the same date, time, and timezone information.

### 返回值

Returns a new DateTime instance.

### 示例

示例 #1 Creating a mutable date time object

    <?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

### 说明

public static function DateTime::createFromTimestamp(int|float `$timestamp`): static

Creates an instance from a Unix timestamp.

### 参数

`timestamp`
  Unix timestamp representing the date. A float value is also accepted which allows for microsecond precision.

### 返回值

Returns a new DateTime instance.

### 错误／异常

If the `timestamp` is outside the range [`PHP_INT_MIN`, `PHP_INT_MAX`], a DateRangeError is thrown.

### 示例

示例 #1 DateTime::createFromTimestamp() example

    <?php
    $date = DateTime::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u');
    ?>

以上示例会输出：

    1970-01-01 00:02:03.456789

# DateTime::getLastErrors

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::getLastErrors — 别名 DateTimeImmutable::getLastErrors()

### 说明

此函数是该函数的别名： DateTimeImmutable::getLastErrors()

# DateTime::modify

# date_modify

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::modify -- date_modify — 修改日期时间对象的值

### 说明

面向对象风格

public function DateTime::modify(string `$modifier`): DateTime

过程化风格

function date_modify(DateTime `$object`, string `$modifier`): DateTime|false

通过 DateTimeImmutable::__construct() 能够接受的格式，对 Datetime 对象的时间戳进行修改（自增或者自减）。

### 参数

`object`
  仅过程化风格：由 date_create() 返回的 DateTime 类型的对象。此函数会修改这个对象。
`modifier`

  日期/时间字符串。正确格式的说明详见 日期与时间格式。

### 返回值

成功时返回 DateTime。过程化风格在失败时返回 `false`。

### 错误／异常

仅限于面向对象的 API：如果传递了无效的日期/时间字符串，将抛出 DateMalformedStringException。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | 如果传递了无效的字符串，DateTime::modify() 现在将抛出 DateMalformedStringException 。之前返回 `false` 并且发出警告。date_modify() 尚未更改。

### 示例

示例 #1 DateTime::modify() 示例

面向对象风格

    <?php
    $date = new DateTime('2006-12-12');
    $date->modify('+1 day');
    echo $date->format('Y-m-d');

以上示例会输出：

    2006-12-13

过程化风格

    <?php
    $date = date_create('2006-12-12');
    date_modify($date, '+1 day');
    echo date_format($date, 'Y-m-d');

以上示例会输出：

    2006-12-13

示例 #2 增加或者减少月份的时候需要当心

    <?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";

以上示例会输出：

    2001-01-31
    2001-03-03

示例 #3 支持所有日期和时间格式

    <?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";

以上示例会输出：

    2023-07-01 00:00
    2023-07-03 00:00
    2023-07-03 17:30

### 参见

- strtotime() - 将任何英文文本日期时间描述解析为 Unix 时间戳
- DateTimeImmutable::modify() - Creates a new object with modified timestamp
- DateTime::add() - 修改 DateTime 对象，增加天、月、年、小时、分钟以及秒的数量。
- DateTime::sub() - 对 DateTime 对象减去一定量的日、月、年、小时、分钟和秒。
- DateTime::setDate() - 设置日期
- DateTime::setISODate() - 设置 ISO 日期
- DateTime::setTime() - 设置时间
- DateTime::setTimestamp() - 以 Unix 时间戳的方式设置日期和时间

# DateTime::__set_state

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::__set_state — __set_state 处理程序

### 说明

public static function DateTime::__set_state(array `$array`): DateTime

__set_state() 处理程序。

跟 DateTimeImmutable::__set_state() 一样，但适用于 DateTime。

### 参数

`array`

  数组初始化。

### 返回值

返回 DateTime 对象实例。

# DateTime::setDate

# date_date_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setDate -- date_date_set — 设置日期

### 说明

面向对象风格

public function DateTime::setDate(int `$year`, int `$month`, int `$day`): DateTime

过程化风格

function date_date_set(
DateTime `$object`,
int `$year`,
int `$month`,
int `$day`
): DateTime

将 DateTime 对象的当前日期重置为其它日期。

跟 DateTimeImmutable::setDate() 一样，但适用于 DateTime，且更改现有对象。

过程化版本将 DateTime 对象作为第一个参数。

### 参数

`object`
  仅过程化风格：由 date_create() 返回的 DateTime 类型的对象。此函数会修改这个对象。
`year`

  年份。

`month`

  月份。

`day`

  日。

### 返回值

返回方法链修改后的 DateTime 对象。

### 参见

- DateTimeImmutable::setDate() - Sets the date

# DateTime::setISODate

# date_isodate_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setISODate -- date_isodate_set — 设置 ISO 日期

### 说明

面向对象风格

public function DateTime::setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTime

过程化风格

function date_isodate_set(
DateTime `$object`,
int `$year`,
int `$week`,
int `$dayOfWeek` = 1
): DateTime

根据 ISO 8601 规范设置日期，使用周和日的偏移量，而不是使用指定日期。

跟 DateTimeImmutable::setISODate() 一样，但适用于 DateTime。

过程化版本将 DateTime 对象作为第一个参数。

### 参数

`object`
  仅过程化风格：由 date_create() 返回的 DateTime 类型的对象。此函数会修改这个对象。
`year`

  年份。

`week`

  周。

`dayOfWeek`

  从周的第一天计算，日在一周内的偏移量。

### 返回值

返回方法链修改后的 DateTime 对象。

### 参见

- DateTimeImmutable::setISODate() - Sets the ISO date

# DateTime::setMicrosecond

(PHP 8 >= 8.4.0)

DateTime::setMicrosecond — Sets microsecond part of the time

### 说明

public function DateTime::setMicrosecond(int `$microsecond`): static

Sets microsecond part of the time.

Like DateTimeImmutable::setMicrosecond() but works with DateTime.

### 参数

`microsecond`
  The microsecond value to set (`0` to `999999`).

### 返回值

返回方法链修改后的 DateTime 对象。

### 错误／异常

If the `microsecond` is outside the range [`0`, `999999`], a DateRangeError is thrown.

### 示例

示例 #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;
    ?>

以上示例会输出：

    1970-01-01 00:02:03.456789
    1970-01-01 00:02:03.987654

### 参见

- 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 — 设置时间

### 说明

面向对象风格

public function DateTime::setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTime

过程化风格

function date_time_set(
DateTime `$object`,
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTime

将 DateTime 的当前时间重置为不同的时间。

跟 DateTimeImmutable::setTime() 一样，但适用于 DateTime。

过程化版本将 DateTime 对象作为第一个参数。

### 参数

`object`
  仅过程化风格：由 date_create() 返回的 DateTime 类型的对象。此函数会修改这个对象。
`hour`

  时间中的小时。

`minute`

  时间中的分钟。

`second`

  时间中的秒。

`microsecond`

  时间中的微秒。

### 返回值

返回方法链修改后的 DateTime 对象。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The behaviour with double existing hours (during the fall-back DST transition) changed. Previously PHP would pick the second occurrence (after the DST transition), instead of the first occurrence (before DST transition).
7.1.0 | 新增 `microsecond` 参数。

### 参见

- DateTimeImmutable::setTime() - Sets the time

# DateTime::setTimestamp

# date_timestamp_set

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::setTimestamp -- date_timestamp_set — 以 Unix 时间戳的方式设置日期和时间

### 说明

面向对象风格

public function DateTime::setTimestamp(int `$timestamp`): DateTime

过程化风格

function date_timestamp_set(DateTime `$object`, int `$timestamp`): DateTime

以 Unix 时间戳的方式设置日期和时间。

跟 DateTimeImmutable::setTimestamp() 一样，但适用于 DateTime。

过程化版本将 DateTime 对象作为第一个参数。

### 参数

`object`
  仅过程化风格：由 date_create() 返回的 DateTime 类型的对象。此函数会修改这个对象。
`timestamp`

  代表日期的 Unix 时间戳。DateTimeImmutable::modify() 使用 `@` 格式可以设置范围超过 int 的时间戳。

### 返回值

返回方法链修改后的 DateTime 对象。

### 参见

- DateTimeImmutable::setTimestamp() - Sets the date and time based on a Unix timestamp

# DateTime::setTimezone

# date_timezone_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setTimezone -- date_timezone_set — 设置 DateTime 对象的时区

### 说明

面向对象风格

public function DateTime::setTimezone(DateTimeZone `$timezone`): DateTime

过程化风格

function date_timezone_set(DateTime `$object`, DateTimeZone `$timezone`): DateTime

为 DateTime object 设置新时区。

跟 DateTimeImmutable::setTimezone() 一样，但适用于 DateTime。

过程化版本将 DateTime 对象作为第一个参数。

### 参数

`object`
  仅过程化风格：由 date_create() 返回的 DateTime 类型的对象。此函数会修改这个对象。
`timezone`

  代表所需时区的 DateTimeZone 对象。

### 返回值

返回链式调用的 DateTime 对象。调用此方法时，底层的时间点不会更改。

### 示例

示例 #1 DateTime::setTimeZone() 示例

面向对象风格

    <?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";

以上示例会输出：

    2000-01-01 00:00:00+12:00
    2000-01-01 01:45:00+13:45

过程化风格

    <?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";

以上示例会输出：

    2000-01-01 00:00:00+12:00
    2000-01-01 01:45:00+13:45

### 参见

- DateTimeImmutable::setTimezone() - Sets the time zone
- DateTime::getTimezone() - 返回相对于指定 DateTime 的时区
- DateTimeZone::__construct() - 创建新的DateTimeZone对象

# DateTime::sub

# date_sub

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::sub -- date_sub — 对 DateTime 对象减去一定量的日、月、年、小时、分钟和秒。

### 说明

面向对象风格

public function DateTime::sub(DateInterval `$interval`): DateTime

过程化风格

function date_sub(DateTime `$object`, DateInterval `$interval`): DateTime

对指定 DateTime 对象，减去指定 DateInterval 对象。

跟 DateTimeImmutable::sub() 一样，但适用于 DateTime。

过程化版本将 DateTime 对象作为第一个参数。

### 参数

`object`
  仅过程化风格：由 date_create() 返回的 DateTime 类型的对象。此函数会修改这个对象。
`interval`

  DateInterval 对象

### 返回值

返回方法链修改后的 DateTime 对象。

### 错误／异常

仅限于面向对象的API：如果尝试不受支持的操作，比如使用 DateInterval 对象表示相对时间规格（如 `next weekday`）的，将会抛出 DateInvalidOperationException。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | 当尝试执行不受支持的操作时，DateTime::sub() 现在会抛出 DateInvalidOperationException，而不是警告。date_sub() 尚未更改。

### 参见

- DateTimeImmutable::sub() - Subtracts an amount of days, months, years, hours, minutes and seconds

## 目录

- DateTime::add — 修改 DateTime 对象，增加天、月、年、小时、分钟以及秒的数量。
- DateTime::__construct — 返回新的 DateTime 对象
- DateTime::createFromFormat — 根据指定格式解析时间字符串
- DateTime::createFromImmutable — Returns new DateTime instance encapsulating the given DateTimeImmutable object
- DateTime::createFromInterface — Returns new DateTime object encapsulating the given DateTimeInterface object
- DateTime::createFromTimestamp — Creates an instance from a Unix timestamp
- DateTime::getLastErrors — 别名 DateTimeImmutable::getLastErrors
- DateTime::modify — 修改日期时间对象的值
- DateTime::__set_state — __set_state 处理程序
- DateTime::setDate — 设置日期
- DateTime::setISODate — 设置 ISO 日期
- DateTime::setMicrosecond — Sets microsecond part of the time
- DateTime::setTime — 设置时间
- DateTime::setTimestamp — 以 Unix 时间戳的方式设置日期和时间
- DateTime::setTimezone — 设置 DateTime 对象的时区
- DateTime::sub — 对 DateTime 对象减去一定量的日、月、年、小时、分钟和秒。

# The DateTimeImmutable class

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## 简介

Representation of date and time.

This class behaves the same as DateTime except new objects are returned when modification methods such as DateTime::modify() are called.

## 类摘要

class DateTimeImmutable implements DateTimeInterface {
/* 继承的常量 */
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";
/* 方法 */
public function __construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)
#[\NoDiscard(message: "as DateTimeImmutable::add() does not modify the object itself")]
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(message: "as DateTimeImmutable::modify() does not modify the object itself")]
public function modify(string `$modifier`): DateTimeImmutable
public static function __set_state(array `$array`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setDate() does not modify the object itself")]
public function setDate(int `$year`, int `$month`, int `$day`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setISODate() does not modify the object itself")]
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(message: "as DateTimeImmutable::setTime() does not modify the object itself")]
public function setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setTimestamp() does not modify the object itself")]
public function setTimestamp(int `$timestamp`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setTimezone() does not modify the object itself")]
public function setTimezone(DateTimeZone `$timezone`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::sub() does not modify the object itself")]
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
}

## 更新日志

版本 | 说明
--- | ---
8.4.0 | The class constants are now typed.
7.1.0 | The DateTimeImmutable constructor now includes the current microseconds in the constructed value. Before this, it would always initialise the microseconds to `0`.

# DateTimeImmutable::add

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::add — Returns a new object, with added amount of days, months, years, hours, minutes and seconds

### 说明

#[\NoDiscard(message: "as DateTimeImmutable::add() does not modify the object itself")]
public function DateTimeImmutable::add(DateInterval `$interval`): DateTimeImmutable

Creates a new DateTimeImmutable object, and adds the specified DateInterval object to this, to represent the new value.

### 参数

`interval`

  A DateInterval object

### 返回值

返回带有修改数据的新 DateTimeImmutable 对象。

### 示例

示例 #1 DateTimeImmutable::add() example

面向对象风格

    <?php
    $date = new DateTimeImmutable('2000-01-01');
    $newDate = $date->add(new DateInterval('P10D'));
    echo $newDate->format('Y-m-d') . "\n";
    ?>

示例 #2 Further DateTimeImmutable::add() examples

    <?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";
    ?>

以上示例会输出：

    2000-01-01 10:00:30
    2007-06-05 04:03:02

示例 #3 Beware when adding months

    <?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";
    ?>

以上示例会输出：

    2001-01-31
    2001-03-03

### 参见

- DateTimeImmutable::sub() - Subtracts an amount of days, months, years, hours, minutes and seconds
- DateTimeImmutable::diff() - 返回两个 DateTime 之间的差值
- DateTimeImmutable::modify() - Creates a new object with modified timestamp

# DateTimeImmutable::__construct

# date_create_immutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::__construct -- date_create_immutable — Returns new DateTimeImmutable object

### 说明

面向对象风格

public function DateTimeImmutable::__construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)

过程化风格

function date_create_immutable(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Returns new a DateTimeImmutable object.

### 参数

`datetime`

  日期/时间字符串。正确格式的说明详见 日期与时间格式。

  Enter `"now"` here to obtain the current time when using the `$timezone` parameter.

`timezone`

  A DateTimeZone object representing the timezone of `$datetime`.

  If `$timezone` is omitted or `null`, the current timezone will be used.

  > 注意:

  > The `$timezone` parameter and the current timezone are ignored when the `$datetime` parameter either is a UNIX timestamp (e.g. `@946684800`) or specifies a timezone (e.g. `2010-01-28T15:00:00+02:00`, or `2010-07-05T06:00:00Z`).

### 返回值

Returns a new DateTimeImmutable instance.

### 错误／异常

If an invalid Date/Time string is passed, DateMalformedStringException is thrown. Previous to PHP 8.3, this was Exception.

### 更新日志

版本 | 说明
--- | ---
8.3.0 | Now throws DateMalformedStringException if an invalid string is passed, instead of Exception.
7.1.0 | From now on microseconds are filled with actual value. Not with '00000'.

### 示例

示例 #1 DateTimeImmutable::__construct() example

面向对象风格

    <?php
    try {
        $date = new DateTimeImmutable('2000-01-01');
    } catch (Exception $e) {
        echo $e->getMessage();
        exit(1);
    }

    echo $date->format('Y-m-d');

以上示例会输出：

    2000-01-01

过程化风格

    <?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');

以上示例会输出：

    2000-01-01

示例 #2 Intricacies of DateTimeImmutable::__construct()

    <?php
    date_default_timezone_set('America/Jamaica');

    // Specified date/time in PHP's default time zone.
    $date = new DateTimeImmutable('2000-01-01');
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Specified date/time in the specified time zone.
    $date = new DateTimeImmutable('2000-01-01', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Current date/time in your PHP's default time zone.
    $date = new DateTimeImmutable();
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Current date/time in the specified time zone.
    $date = new DateTimeImmutable('now', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Using a UNIX timestamp.  Notice the result is in the UTC time zone.
    $date = new DateTimeImmutable('@946684800');
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Non-existent values roll over.
    $date = new DateTimeImmutable('2000-02-30');
    echo $date->format('Y-m-d H:i:sP') . "\n";

以上示例的输出类似于：

    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

> 注意:

> Rolled over dates can be detected by checking for warnings using DateTimeImmutable::getLastErrors().

示例 #3 Changing the associated timezone

    <?php
    $timeZone = new \DateTimeZone('Asia/Tokyo');

    $time = new \DateTimeImmutable();
    $time = $time->setTimezone($timeZone);

    echo $time->format('Y/m/d H:i:s e'), "\n";

以上示例的输出类似于：

    2022/08/12 23:49:23 Asia/Tokyo

示例 #4 Using a relative date/time string

    <?php
    $time = new \DateTimeImmutable("-1 year");

    echo $time->format('Y/m/d H:i:s'), "\n";

以上示例的输出类似于：

    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 — Parses a time string according to a specified format

### 说明

面向对象风格

public static function DateTimeImmutable::createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

过程化风格

function date_create_immutable_from_format(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Returns a new DateTimeImmutable object representing the date and time specified by the `datetime` string, which was formatted in the given `format`.

### 参数

`format`

  The format that the passed in string should be in. See the formatting options below. In most cases, the same letters as for the date() can be used.

  All fields are initialised with the current date/time. In most cases you would want to reset these to "zero" (the Unix epoch, `1970-01-01 00:00:00 UTC`). You do that by including the `!` character as first character in your `format`, or `|` as your last. Please see the documentation for each character below for more information.

  The format is parsed from left to right, which means that in some situations the order in which the format characters are present affects the result. In the case of `z` (the day of the year), it is required that a year has already been parsed, for example through the `Y` or `y` characters.

  Letters that are used for parsing numbers allow a wide range of values, outside of what the logical range would be. For example, the `d` (day of the month) accepts values in the range from `00` to `99`. The only constraint is on the amount of digits. The date/time parser's overflow mechanism is used when out-of-range values are given. The examples below show some of this behaviour.

  This also means that the data parsed for a format letter is greedy, and will read up to the amount of digits its format allows for. That can then also mean that there are no longer enough characters in the `datetime` string for following format characters. An example on this page also illustrates this issue.

  The following characters are recognized in the `format` parameter string
  `format` character | Description | Example parsable values
  --- | --- | ---
  Day | --- | ---
  `d` and `j` | Day of the month, 2 digits with or without leading zeros | `01` to `31` or `1` to `31`. (2 digit numbers higher than the number of days in the month are accepted, in which case they will make the month overflow. For example using 33 with January, means February 2nd)
  `D` and `l` | A textual representation of a day | `Mon` through `Sun` or `Sunday` through `Saturday`. If the day name given is different than the day name belonging to a parsed (or default) date is different, then an overflow occurs to the next date with the given day name. See the examples below for an explanation.
  `S` | English ordinal suffix for the day of the month, 2 characters. It's ignored while processing. | `st`, `nd`, `rd` or `th`.
  `z` | The day of the year (starting from 0); must be preceded by `Y` or `y`. | `0` through `365`. (3 digit numbers higher than the numbers in a year are accepted, in which case they will make the year overflow. For example using 366 with 2022, means January 2nd, 2023)
  Month | --- | ---
  `F` and `M` | A textual representation of a month, such as January or Sept | `January` through `December` or `Jan` through `Dec`
  `m` and `n` | Numeric representation of a month, with or without leading zeros | `01` through `12` or `1` through `12`. (2 digit numbers higher than 12 are accepted, in which case they will make the year overflow. For example using 13 means January in the next year)
  Year | --- | ---
  `X` and `x` | A full numeric representation of a year, up to 19 digits, optionally prefixed by `+` or `-` | Examples: `0055`, `787`, `1999`, `-2003`, `+10191`
  `Y` | A full numeric representation of a year, up to 4 digits | Examples: `25` (same as `0025`), `787`, `1999`, `2003`
  `y` | A two digit representation of a year (which is assumed to be in the range 1970-2069, inclusive) | Examples: `99` or `03` (which will be interpreted as `1999` and `2003`, respectively)
  Time | --- | ---
  `a` and `A` | Ante meridiem and Post meridiem | `am` or `pm`
  `g` and `h` | 12-hour format of an hour with or without leading zero | `1` through `12` or `01` through `12` (2 digit numbers higher than 12 are accepted, in which case they will make the day overflow. For example using `14` means `02` in the next AM/PM period)
  `G` and `H` | 24-hour format of an hour with or without leading zeros | `0` through `23` or `00` through `23` (2 digit numbers higher than 24 are accepted, in which case they will make the day overflow. For example using `26` means `02:00` the next day)
  `i` | Minutes with leading zeros | `00` to `59`. (2 digit numbers higher than 59 are accepted, in which case they will make the hour overflow. For example using `66` means `:06` the next hour)
  `s` | Seconds, with leading zeros | `00` through `59` (2 digit numbers higher than 59 are accepted, in which case they will make the minute overflow. For example using `90` means `:30` the next minute)
  `v` | Fraction in milliseconds (up to three digits) | Example: `12` (`0.12` seconds), `345` (`0.345` seconds)
  `u` | Fraction in microseconds (up to six digits) | Example: `45` (`0.45` seconds), `654321` (`0.654321` seconds)
  Timezone | --- | ---
  `e`, `O`, `p`, `P` and `T` | Timezone identifier, or difference to UTC in hours, or difference to UTC with colon between hours and minutes, or timezone abbreviation | Examples: `UTC`, `GMT`, `Atlantic/Azores` or `+0200` or `+02:00` or `EST`, `MDT`
  Full Date/Time | --- | ---
  `U` | Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT) | Example: `1292177455`
  Whitespace and Separators | --- | ---
  `` (space) | Zero or more spaces, tabs, NBSP (U+A0), or NNBSP (U+202F) characters | Example: `"\t"`, `" "`
  `#` | One of the following separation symbol: `;`, `:`, `/`, `.`, `,`, `-`, `(` or `)` | Example: `/`
  `;`, `:`, `/`, `.`, `,`, `-`, `(` or `)` | The specified character. | Example: `-`
  `?` | A random byte | Example: `^` (Be aware that for UTF-8 characters you might need more than one `?`. In this case, using `*` is probably what you want instead)
  `*` | Random bytes until the next separator or digit | Example: `*` in `Y-*-d` with the string `2009-aWord-08` will match `aWord`
  `!` | Resets all fields (year, month, day, hour, minute, second, fraction and timezone information) to zero-like values ( `0` for hour, minute, second and fraction, `1` for month and day, `1970` for year and the default timezone) | Without `!,` all fields will be set to the current date and time.
  `|` | Resets all fields (year, month, day, hour, minute, second, fraction and timezone information) to zero-like values if they have not been parsed yet | `Y-m-d|` will set the year, month and day to the information found in the string to parse, and sets the hour, minute and second to 0.
  `+` | If this format specifier is present, trailing data in the string will not cause an error, but a warning instead | Use DateTimeImmutable::getLastErrors() to find out whether trailing data was present.

  Unrecognized characters in the format string will cause the parsing to fail and an error message is appended to the returned structure. You can query error messages with DateTimeImmutable::getLastErrors().

  To include literal characters in `format`, you have to escape them with a backslash (`\`).

  If `format` does not contain the character `!` then portions of the generated date/time which are not specified in `format` will be set to the current system time.

  If `format` contains the character `!`, then portions of the generated date/time not provided in `format`, as well as values to the left-hand side of the `!`, will be set to corresponding values from the Unix epoch.

  If any time character is parsed, then all other time-related fields are set to "0", unless also parsed.

  The Unix epoch is 1970-01-01 00:00:00 UTC.

`datetime`

  String representing the time.

`timezone`

  A DateTimeZone object representing the desired time zone.

  If `timezone` is omitted or `null` and `datetime` contains no timezone, the current timezone will be used.

  > 注意:

  > The `timezone` parameter and the current timezone are ignored when the `datetime` parameter either contains a UNIX timestamp (e.g. `946684800`) or specifies a timezone (e.g. `2010-01-28T15:00:00+02:00`).

### 返回值

Returns a new DateTimeImmutable instance 或者在失败时返回 `false`.

### 错误／异常

This method throws ValueError when the `datetime` contains NULL-bytes.

### 更新日志

版本 | 说明
--- | ---
8.2.9 | The `` (space) specifier now also supports NBSP (U+A0) and NNBSP (U+202F) characters.
8.2.0 | The `X` and `x` `format` specifiers have been added.
8.0.21, 8.1.8, 8.2.0 | Now throws ValueError when NULL-bytes are passed into `datetime`, which previously was silently ignored.
7.3.0 | The `v` `format` specifier has been added.

### 示例

示例 #1 DateTimeImmutable::createFromFormat() example

面向对象风格

    <?php
    $date = DateTimeImmutable::createFromFormat('j-M-Y', '15-Feb-2009');
    echo $date->format('Y-m-d');

示例 #2 Using predefined format constants with DateTimeImmutable::createFromFormat()

面向对象风格

    <?php
    $date = DateTimeImmutable::createFromFormat(
        DateTimeInterface::ISO8601,
        '2004-02-12T15:19:21+00:00'
    );
    echo $date->format('c e') . "\n";

    $date = DateTimeImmutable::createFromFormat(
        DateTimeInterface::RFC3339_EXTENDED,
        '2013-10-14T09:00:00.000+02:00'
    );
    echo $date->format('c e') . "\n";

The formatting constants as used in this example consist of a string of characters for formatting a DateTimeImmutable object. In most cases, these letters match with the same elements of date/time information as the ones defined in the parameters section above, but they tend to be more lenient.

示例 #3 Intricacies of DateTimeImmutable::createFromFormat()

    <?php
    echo 'Current time: ' . 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";

以上示例的输出类似于：

    Current time: 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

示例 #4 Format string with literal characters

    <?php
    echo DateTimeImmutable::createFromFormat('H\h i\m s\s','23h 15m 03s')->format('H:i:s');

以上示例的输出类似于：

    23:15:03

示例 #5 Overflow behaviour

    <?php
    echo DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2021-17-35 16:60:97')->format(DateTimeImmutable::RFC2822);

以上示例的输出类似于：

    Sat, 04 Jun 2022 17:01:37 +0000

Although the result looks odd, it is correct, as the following overflows happen:

1. `97` seconds overflows to `1` minute, leaving `37` seconds.
2. `61` minutes overflows to `1` hour, leaving `1` minutes.
3. `35` days overflows to `1` month, leaving `4` days. The amount of days that are left over depends on the month, as not every month has the same amount of days.
4. `18` months overflows to `1` year, leaving `6` months.

示例 #6 Overflowing day name behaviour

    <?php
    $d = DateTime::createFromFormat(DateTimeInterface::RFC1123, 'Mon, 3 Aug 2020 25:00:00 +0000');
    echo $d->format(DateTime::RFC1123), "\n";

以上示例的输出类似于：

    Mon, 10 Aug 2020 01:00:00 +0000

Although the result looks odd, it is correct, as the following overflows happen:

1. `3 Aug 2020 25:00:00` overflows to `(Tue) 4 Aug 2020 01:00`.
2. `Mon` gets applied, which advances the date to `Mon, 10 Aug 2020 01:00:00`. The explanation of relative keywords such as `Mon` is explained in the section on relative formats.

In order to detect overflows in dates, you can use DateTimeImmutable::getLastErrors(), which will include a warning if an overflow occurred.

示例 #7 Detecting overflown dates

    <?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());

以上示例的输出类似于：

    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) {
      }
    }

示例 #8 Greedy parsing behaviour

    <?php
    print_r(date_parse_from_format('Gis', '60101'));

以上示例的输出类似于：

    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] =>
    )

The `G` format is to parse 24 hour clock hours, with or without leading zero. This requires to parse 1 or 2 digits. Because there are two following digits, it greedily reads this as `60`.

The following `i` and `s` format characters both require two digits. This means that `10` is passed as minute (`i`), and that there are then not enough digits left to parse for as second (`s`).

The `errors` array indicates this problem.

Additionally, an hour of `60` is outside the range `0`-`24`, which causes the `warnings` array to include a warning that the time is invalid.

### 参见

- DateTimeImmutable::__construct() - Returns new DateTimeImmutable object
- DateTimeImmutable::getLastErrors() - Returns the warnings and errors
- checkdate() - 验证一个格里高里日期
- strptime() - 解析由 strftime 生成的日期／时间

# DateTimeImmutable::createFromInterface

(PHP 8)

DateTimeImmutable::createFromInterface — Returns new DateTimeImmutable object encapsulating the given DateTimeInterface object

### 说明

public static function DateTimeImmutable::createFromInterface(DateTimeInterface `$object`): DateTimeImmutable

### 参数

`object`

  The DateTimeInterface object that needs to be converted to an immutable version. This object is not modified, but instead a new DateTimeImmutable object is created containing the same date, time, and timezone information.

### 返回值

Returns a new DateTimeImmutable instance.

### 示例

示例 #1 Creating an immutable date time object

    <?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 — Returns new DateTimeImmutable instance encapsulating the given DateTime object

### 说明

public static function DateTimeImmutable::createFromMutable(DateTime `$object`): static

### 参数

`object`

  The mutable DateTime object that you want to convert to an immutable version. This object is not modified, but instead a new DateTimeImmutable instance is created containing the same date time and timezone information.

### 返回值

Returns a new DateTimeImmutable instance.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | The method returns an instance of the currently invoked class now. Previously, it created a new instance of DateTimeImmutable.

### 示例

示例 #1 Creating an immutable date time object

    <?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

### 说明

public static function DateTimeImmutable::createFromTimestamp(int|float `$timestamp`): static

Creates an instance from a Unix timestamp.

### 参数

`timestamp`
  Unix timestamp representing the date. A float value is also accepted which allows for microsecond precision.

### 返回值

Returns a new DateTimeImmutable instance.

### 错误／异常

If the `timestamp` is outside the range [`PHP_INT_MIN`, `PHP_INT_MAX`], a DateRangeError is thrown.

### 示例

示例 #1 DateTimeImmutable::createFromTimestamp() example

    <?php
    $date = DateTimeImmutable::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u');
    ?>

以上示例会输出：

    1970-01-01 00:02:03.456789

# DateTimeImmutable::getLastErrors

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::getLastErrors — Returns the warnings and errors

### 说明

public static function DateTimeImmutable::getLastErrors(): array|false

Returns an array of warnings and errors found while parsing a date/time string.

### 参数

此函数没有参数。

### 返回值

Returns array containing info about warnings and errors, or `false` if there are neither warnings nor errors.

### 更新日志

版本 | 说明
--- | ---
8.2.0 | Before PHP 8.2.0, this function did not return `false` when there were no warnings or errors. Instead, it would always return the documented array structure.

### 示例

示例 #1 DateTimeImmutable::getLastErrors() example

    <?php
    try {
        $date = new DateTimeImmutable('asdfasdf');
    } catch (Exception $e) {
        // For demonstration purposes only...
        print_r(DateTimeImmutable::getLastErrors());

        // The real object-oriented way to do this is
        echo $e->getMessage();
    }
    ?>

以上示例会输出：

    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
            )
    )
    Failed to parse time string (asdfasdf) at position 0 (a): The timezone could not be found in the database

The indexes 6, and 0 in the example output refer to the character index in the string where the error occurred.

示例 #2 Detecting rolled over dates

    <?php
    $date = DateTimeImmutable::createFromFormat('!Y-m-d', '2020-02-30');
    print_r(DateTimeImmutable::getLastErrors());

以上示例会输出：

    Array
    (
        [warning_count] => 1
        [warnings] => Array
            (
                [10] => The parsed date was invalid
            )

        [error_count] => 0
        [errors] => Array
            (
            )
    )

# DateTimeImmutable::modify

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::modify — Creates a new object with modified timestamp

### 说明

#[\NoDiscard(message: "as DateTimeImmutable::modify() does not modify the object itself")]
public function DateTimeImmutable::modify(string `$modifier`): DateTimeImmutable

Creates a new DateTimeImmutable object with modified timestamp. The original object is not modified.

### 参数

`modifier`

  日期/时间字符串。正确格式的说明详见 日期与时间格式。

### 返回值

Returns DateTimeImmutable on success. 过程化风格在失败时返回 `false`。

### 错误／异常

If an invalid Date/Time string is passed, DateMalformedStringException is thrown. Previous to PHP 8.3, this was a warning.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | Now has a tentative return type of DateTimeImmutable. Previously it was DateTimeImmutable|false.
8.3.0 | DateTimeImmutable::modify() now throws DateMalformedStringException if an invalid string is passed. Previously, it returned `false`, and a warning was emitted.

### 示例

示例 #1 DateTimeImmutable::modify() example

面向对象风格

    <?php
    $date = new DateTimeImmutable('2006-12-12');
    $newDate = $date->modify('+1 day');
    echo $newDate->format('Y-m-d');

以上示例会输出：

    2006-12-13

示例 #2 Beware when adding or subtracting months

    <?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";

以上示例会输出：

    2001-01-31
    2001-03-03

### 参见

- DateTimeImmutable::add() - Returns a new object, with added amount of days, months, years, hours, minutes and seconds
- DateTimeImmutable::sub() - Subtracts an amount of days, months, years, hours, minutes and seconds
- DateTimeImmutable::setDate() - Sets the date
- DateTimeImmutable::setISODate() - Sets the ISO date
- DateTimeImmutable::setTime() - Sets the time
- DateTimeImmutable::setTimestamp() - Sets the date and time based on a Unix timestamp

# DateTimeImmutable::__set_state

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::__set_state — The __set_state handler

### 说明

public static function DateTimeImmutable::__set_state(array `$array`): DateTimeImmutable

The __set_state() handler.

### 参数

`array`

  Initialization array.

### 返回值

Returns a new instance of a DateTimeImmutable object.

# DateTimeImmutable::setDate

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setDate — Sets the date

### 说明

#[\NoDiscard(message: "as DateTimeImmutable::setDate() does not modify the object itself")]
public function DateTimeImmutable::setDate(int `$year`, int `$month`, int `$day`): DateTimeImmutable

Returns a new DateTimeImmutable object with the current date of the DateTimeImmutable object set to the given date.

### 参数

`object`
  仅过程化风格：由 date_create() 返回的 DateTime 类型的对象。此函数会修改这个对象。
`year`

  Year of the date.

`month`

  Month of the date.

`day`

  Day of the date.

### 返回值

返回带有修改数据的新 DateTimeImmutable 对象。

### 示例

示例 #1 DateTimeImmutable::setDate() example

面向对象风格

    <?php
    $date = new DateTimeImmutable();
    $newDate = $date->setDate(2001, 2, 3);
    echo $newDate->format('Y-m-d');

以上示例会输出：

    2001-02-03

示例 #2 Values exceeding ranges are added to their parent values

    <?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";

以上示例会输出：

    2001-02-28
    2001-03-01
    2002-02-03

### 参见

- DateTimeImmutable::setISODate() - Sets the ISO date
- DateTimeImmutable::setTime() - Sets the time

# DateTimeImmutable::setISODate

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setISODate — Sets the ISO date

### 说明

#[\NoDiscard(message: "as DateTimeImmutable::setISODate() does not modify the object itself")]
public function DateTimeImmutable::setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTimeImmutable

Returns a new DateTimeImmutable object with the date set according to the ISO 8601 standard - using weeks and day offsets rather than specific dates.

### 参数

`year`

  Year of the date.

`week`

  Week of the date.

`dayOfWeek`

  Offset from the first day of the week.

### 返回值

返回带有修改数据的新 DateTimeImmutable 对象。

### 示例

示例 #1 DateTimeImmutable::setISODate() example

面向对象风格

    <?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";

以上示例会输出：

    2008-01-07
    2008-01-13

过程化风格

    <?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";

以上示例会输出：

    2008-01-07
    2008-01-13

示例 #2 Values exceeding ranges are added to their parent values

    <?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";

以上示例会输出：

    2008-01-13
    2008-01-14
    2009-01-04

示例 #3 Finding the month a week is in

    <?php

    $date = new DateTimeImmutable();
    $newDate = $date->setISODate(2008, 14);
    echo $newDate->format('n');

以上示例会输出：

    3

### 参见

- DateTimeImmutable::setDate() - Sets the date
- DateTimeImmutable::setTime() - Sets the time

# DateTimeImmutable::setMicrosecond

(PHP 8 >= 8.4.0)

DateTimeImmutable::setMicrosecond — Sets microsecond part of the time

### 说明

#[\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.

### 参数

`microsecond`
  The microsecond value to set (`0` to `999999`).

### 返回值

返回带有修改数据的新 DateTimeImmutable 对象。

### 错误／异常

If the `microsecond` is outside the range [`0`, `999999`], a DateRangeError is thrown.

### 示例

示例 #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;
    ?>

以上示例会输出：

    1970-01-01 00:02:03.456789
    1970-01-01 00:02:03.987654

### 参见

- DateTimeInterface::getMicrosecond() - Gets the microsecond part of the Unix timestamp

# DateTimeImmutable::setTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTime — Sets the time

### 说明

#[\NoDiscard(message: "as DateTimeImmutable::setTime() does not modify the object itself")]
public function DateTimeImmutable::setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTimeImmutable

Returns a new DateTimeImmutable object with the time set to the given time.

### 参数

`hour`

  Hour of the time.

`minute`

  Minute of the time.

`second`

  Second of the time.

`microsecond`

  Microsecond of the time.

### 返回值

返回带有修改数据的新 DateTimeImmutable 对象。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The behaviour with double existing hours (during the fall-back DST transition) changed. Previously PHP would pick the second occurrence (after the DST transition), instead of the first occurrence (before DST transition).
7.1.0 | The `microsecond` parameter was added.

### 示例

示例 #1 DateTimeImmutable::setTime() example

面向对象风格

    <?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";
    ?>

以上示例的输出类似于：

    2001-01-01 14:55:00
    2001-01-01 14:55:24

示例 #2 Values exceeding ranges are added to their parent values

    <?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";
    ?>

以上示例会输出：

    2001-01-01 14:55:24
    2001-01-01 14:56:05
    2001-01-01 15:05:24
    2001-01-02 01:55:24

### 参见

- DateTimeImmutable::setDate() - Sets the date
- DateTimeImmutable::setISODate() - Sets the ISO date

# DateTimeImmutable::setTimestamp

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTimestamp — Sets the date and time based on a Unix timestamp

### 说明

#[\NoDiscard(message: "as DateTimeImmutable::setTimestamp() does not modify the object itself")]
public function DateTimeImmutable::setTimestamp(int `$timestamp`): DateTimeImmutable

Returns a new DateTimeImmutable object constructed from the old one, with the date and time set based on an Unix timestamp.

### 参数

`timestamp`

  Unix timestamp representing the date. Setting timestamps outside the range of int is possible by using DateTimeImmutable::modify() with the `@` format.

### 返回值

返回带有修改数据的新 DateTimeImmutable 对象。

### 示例

示例 #1 DateTimeImmutable::setTimestamp() example

面向对象风格

    <?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";

以上示例的输出类似于：

    1272508903 = 2010-04-28 22:41:43
    1171502725 = 2007-02-14 20:25:25

### 参见

- DateTimeImmutable::getTimestamp() - 获取 Unix 时间戳
- DateTimeImmutable::setMicrosecond() - Sets microsecond part of the time

# DateTimeImmutable::setTimezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTimezone — Sets the time zone

### 说明

#[\NoDiscard(message: "as DateTimeImmutable::setTimezone() does not modify the object itself")]
public function DateTimeImmutable::setTimezone(DateTimeZone `$timezone`): DateTimeImmutable

Returns a new DateTimeImmutable object with a new timezone set.

### 参数

`timezone`

  A DateTimeZone object representing the desired time zone.

### 返回值

Returns a new modified DateTimeImmutable object for method chaining. The underlying point-in-time is not changed when calling this method.

### 示例

示例 #1 DateTimeImmutable::setTimeZone() example

面向对象风格

    <?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";
    ?>

以上示例会输出：

    2000-01-01 00:00:00+12:00
    2000-01-01 01:45:00+13:45

### 参见

- DateTimeImmutable::getTimezone() - 返回相对于指定 DateTime 的时区
- DateTimeZone::__construct() - 创建新的DateTimeZone对象

# DateTimeImmutable::sub

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::sub — Subtracts an amount of days, months, years, hours, minutes and seconds

### 说明

#[\NoDiscard(message: "as DateTimeImmutable::sub() does not modify the object itself")]
public function DateTimeImmutable::sub(DateInterval `$interval`): DateTimeImmutable

Returns a new DateTimeImmutable object, with the specified DateInterval object subtracted from the specified DateTimeImmutable object.

### 参数

`interval`

  A DateInterval object

### 返回值

返回带有修改数据的新 DateTimeImmutable 对象。

### 错误／异常

If an unsupported operation is attempted, such as using a DateInterval object representing relative time specifications such as `next weekday`, a DateInvalidOperationException is thrown.

### 更新日志

版本 | 说明
--- | ---
8.3.0 | Now throws a DateInvalidOperationException instead of a warning when an unsupported operation is attempted.

### 示例

示例 #1 DateTimeImmutable::sub() example

面向对象风格

    <?php
    $date = new DateTimeImmutable('2000-01-20');
    $newDate = $date->sub(new DateInterval('P10D'));
    echo $newDate->format('Y-m-d') . "\n";
    ?>

以上示例会输出：

    2000-01-10

示例 #2 Further DateTimeImmutable::sub() examples

    <?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";
    ?>

以上示例会输出：

    2000-01-19 13:59:30
    1992-08-15 19:56:58

示例 #3 Beware when subtracting months

    <?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";
    ?>

以上示例会输出：

    2001-03-30
    2001-03-02

### 参见

- DateTimeImmutable::add() - Returns a new object, with added amount of days, months, years, hours, minutes and seconds
- DateTimeImmutable::diff() - 返回两个 DateTime 之间的差值
- DateTimeImmutable::modify() - Creates a new object with modified timestamp

## 目录

- DateTimeImmutable::add — Returns a new object, with added amount of days, months, years, hours, minutes and seconds
- DateTimeImmutable::__construct — Returns new DateTimeImmutable object
- DateTimeImmutable::createFromFormat — Parses a time string according to a specified format
- DateTimeImmutable::createFromInterface — Returns new DateTimeImmutable object encapsulating the given DateTimeInterface object
- DateTimeImmutable::createFromMutable — Returns new DateTimeImmutable instance encapsulating the given DateTime object
- DateTimeImmutable::createFromTimestamp — Creates an instance from a Unix timestamp
- DateTimeImmutable::getLastErrors — Returns the warnings and errors
- DateTimeImmutable::modify — Creates a new object with modified timestamp
- DateTimeImmutable::__set_state — The __set_state handler
- DateTimeImmutable::setDate — Sets the date
- DateTimeImmutable::setISODate — Sets the ISO date
- DateTimeImmutable::setMicrosecond — Sets microsecond part of the time
- DateTimeImmutable::setTime — Sets the time
- DateTimeImmutable::setTimestamp — Sets the date and time based on a Unix timestamp
- DateTimeImmutable::setTimezone — Sets the time zone
- DateTimeImmutable::sub — Subtracts an amount of days, months, years, hours, minutes and seconds

# The DateTimeInterface interface

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## 简介

创建 DateTimeInterface 是为了让参数、返回值、属性类型声明能够接受 DateTimeImmutable 或 DateTime 作为值。不可以使用用户定义的类实现该接口。

此接口也定义了公共常量，允许通过 DateTimeImmutable::format() 和 DateTime::format() 格式化 DateTimeImmutable 或 DateTime 对象。

## 接口摘要

interface DateTimeInterface {
/* 常量 */
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";
/* 方法 */
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
}

## 预定义常量

`DateTimeInterface::ATOM` string
`DATE_ATOM`
  Atom 格式（示例：2005-08-15T15:52:01+00:00）；兼容 ISO-8601、RFC 3339 和 XML Schema
`DateTimeInterface::COOKIE` string
`DATE_COOKIE`
  HTTP Cookies 格式（示例：Monday, 15-Aug-2005 15:52:01 UTC）
`DateTimeInterface::ISO8601` string
`DATE_ISO8601`
  类似 ISO-8601 格式（示例：2005-08-15T15:52:01+0000）

  > 注意: 这种格式和 ISO-8601 格式并不兼容，只是出于向后兼容的原因才保留的。 如果要使用和 ISO-8601 兼容的格式，请使用 `DateTimeInterface::ISO8601_EXPANDED` 和 `DateTimeInterface::ATOM` 两个常量。 （参见 ISO8601:2004 第 4.3.3 条 d 项）

`DateTimeInterface::ISO8601_EXPANDED` string
`DATE_ISO8601_EXPANDED`
  ISO-8601 扩大版（示例：+10191-07-26T08:59:52+01:00）

  > 注意: 通过始终包含符号字符，此格式允许超出 ISO-8601 正常范围（`0000`-`9999`）的年份。还确保时区部分（`+01:00`）与 ISO-8601 兼容。

`DateTimeInterface::RFC822` string
`DATE_RFC822`
  RFC 822 格式（示例：Mon, 15 Aug 05 15:52:01 +0000）
`DateTimeInterface::RFC850` string
`DATE_RFC850`
  RFC 850 格式（示例：Monday, 15-Aug-05 15:52:01 UTC）
`DateTimeInterface::RFC1036` string
`DATE_RFC1036`
  RFC 1036（示例：Mon, 15 Aug 05 15:52:01 +0000）
`DateTimeInterface::RFC1123` string
`DATE_RFC1123`
  RFC 1123 格式（示例：Mon, 15 Aug 2005 15:52:01 +0000）
`DateTimeInterface::RFC7231` string
`DATE_RFC7231`
  RFC 7231 格式 (自 PHP 7.0.19 和 7.1.5 可用) (示例：Sat, 30 Apr 2016 17:52:13 GMT)
`DateTimeInterface::RFC2822` string
`DATE_RFC2822`
  RFC 2822 格式（示例：Mon, 15 Aug 2005 15:52:01 +0000）
`DateTimeInterface::RFC3339` string
`DATE_RFC3339`
  同 `DATE_ATOM`（自 PHP 5.1.3 版本可用）
`DateTimeInterface::RFC3339_EXTENDED` string
`DATE_RFC3339_EXTENDED`
  RFC 3339 EXTENDED 格式（示例：2005-08-15T15:52:01.000+00:00）
`DateTimeInterface::RSS` string
`DATE_RSS`
  RSS（示例：Mon, 15 Aug 2005 15:52:01 +0000）
`DateTimeInterface::W3C` string
`DATE_W3C`
  RSS 格式（示例：2005-08-15T15:52:01+00:00）

## 更新日志

版本 | 说明
--- | ---
8.4.0 | 类常量现已类型化。
8.2.0 | 新增常量 `DateTimeInterface::ISO8601_EXPANDED`。
7.2.0 | DateTime 的类常量现在定义在了 DateTimeInterface 上。

# 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 — 返回两个 DateTime 之间的差值

### 说明

面向对象风格

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

过程化风格

function date_diff(DateTimeInterface `$baseObject`, DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval

返回两个 DateTimeInterface 对象的差值。

### 参数

`datetime`

  要比较的日期。

`absolute`

  间隔是否强制为正的？

### 返回值

DateInterval 对象表示两个日期之间的差值。

`absolute` 参数只影响 DateInterval 对象的 `invert` 属性。

返回更具体的表示应用于原始对象（`$this` 或 `$originObject`）到达 `$targetObject` 的时钟时间间隔的值。该过程始终不可逆。

该方法知道 DST 转换，因此可以根据示例返回 `24 小时 30 分钟`的时间间隔。如果想使用绝对时间计算，则需要先将 `$this`/`$baseObject` 和 `$targetObject` 都转换为 UTC。

### 示例

示例 #1 DateTimeImmutable::diff() 示例

面向对象风格

    <?php
    $origin = new DateTimeImmutable('2009-10-11');
    $target = new DateTimeImmutable('2009-10-13');
    $interval = $origin->diff($target);
    echo $interval->format('%R%a days');

以上示例会输出：

    +2 days

过程化风格

    <?php
    $origin = date_create('2009-10-11');
    $target = date_create('2009-10-13');
    $interval = date_diff($origin, $target);
    echo $interval->format('%R%a days');

以上示例会输出：

    +2 days

示例 #2 DST 转换期间的 DateTimeInterface::diff()

    <?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";

以上示例会输出：

    24:30:00 (Full days: 0)

示例 #3 DateTimeInterface::diff() range

该方法返回的值是从 `$this` 到达 `$targetObject` 所需要的精确时间。因此，将 1 月 1 日与 12 月 31 日进行比较，返回的结果是 364，而不是 365 天（对于非闰年）。

    <?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";

以上示例会输出：

    Full days: 364

示例 #4 DateTime 对象比较

> 注意:

> DateTimeImmutable 和 DateTime 对象可以使用比较运算符进行比较。

    <?php
    $date1 = new DateTime("now");
    $date2 = new DateTime("tomorrow");

    var_dump($date1 == $date2);
    var_dump($date1 < $date2);
    var_dump($date1 > $date2);

以上示例会输出：

    bool(false)
    bool(true)
    bool(false)

### 参见

- DateInterval::format() - Formats the interval
- DateTime::add() - 修改 DateTime 对象，增加天、月、年、小时、分钟以及秒的数量。
- DateTime::sub() - 对 DateTime 对象减去一定量的日、月、年、小时、分钟和秒。

# 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 — 按照指定格式返回格式化后的日期

### 说明

面向对象风格

public function DateTimeInterface::format(string `$format`): string
public function DateTimeImmutable::format(string `$format`): string
public function DateTime::format(string `$format`): string

过程化风格

function date_format(DateTimeInterface `$object`, string `$format`): string

按照指定格式返回格式化后的日期。

### 参数

`object`
  仅为过程化风格：由 date_create() 返回的 DateTime 类型的对象。
`format`

  输出的日期 string 的格式。参见下面的格式化选项。也有几个预定义日期常量可以代替。例如 `DATE_RSS` 包含格式化字符串 `'D, d M Y H:i:s'`。

  `format` 参数字符串可以识别以下字符
  `format` 字符 | 说明 | 返回值示例
  --- | --- | ---
  日 | --- | ---
  `d` | 月份中的第几天，有补零的两位数字 | `01` 到 `31`
  `D` | 文字表示星期几，三个字母 | `Mon` 到 `Sun`
  `j` | 月份中的第几天，没有补零 | `1` 到 `31`
  `l`（小写 'L'） | 完整文本表示星期几 | `Sunday` 到 `Saturday`
  `N` | ISO 8601 数字表示星期几 | `1`（星期一）到 `7`（星期天）
  `S` | 月份中的第几天英文后缀，两个字符 | `st`、`nd`、`rd` 或 `th`。可以和 `j` 一起使用
  `w` | 数字表示星期几 | `0`（星期天）到 `6`（星期六）
  `z` | 一年中的第几天（从 0 开始） | `0` 到 `365`
  周 | --- | ---
  `W` | ISO 8601 格式当年中的第几周，每周从周一开始 | 示例：`42`（当年的第 42 周）
  月 | --- | ---
  `F` | 月份的完整文本表示，比如 January 或者 March | `January` 到 `December`
  `m` | 月份的数字表示，补零 | `01` 到 `12`
  `M` | 简短文本表示月份，三个字母 | `Jan` 到 `Dec`
  `n` | 数字表示几月份，不补零 | `1` 到 `12`
  `t` | 指定月份的天数 | `28` 到 `31`
  年 | --- | ---
  `L` | 是否是闰年 | 如果是闰年为 `1`，否则为 `0`。
  `o` | ISO 8601 数字年份表示。这和 `Y` 值相同，但如果 ISO 周数（`W`）属于上一年或者下一年，则用那一年。 | 示例：`1999` 或 `2003`
  `X` | 年份的展开全数字表示，至少四位，`-` 表示公元前，`+` 表示公元。 | 示例：`-0055`、`+0787`、 `+1999`、`+10191`
  `x` | 如果需要，年份可以展开全数字表示，如果可能的话，也可以用标准的全数字（`Y`）表示。至少有四位数字。公元前以 `-` 为前缀，年份不小于 `10000` 时以 `+` 为前缀。 | 示例：`-0055`, `0787`, `1999`, `+10191`
  `Y` | 年份完整数字表示，至少四位，使用 `-` 表示公元前。 | 示例：`-0055`、`0787`、 `1999`、`2003`、`10191`
  `y` | 两位数的年份表示 | 示例：`99` 或 `03`
  时间 | --- | ---
  `a` | 小写的上午和下午 | `am` 或 `pm`
  `A` | 大写的上午和下午 | `AM` 或 `PM`
  `B` | Swatch 互联网时间 | `000` 到 `999`
  `g` | 不补零的小时（12 小时制） | `1` 到 `12`
  `G` | 不补零的小时（24 小时制） | `0` 到 `23`
  `h` | 补零的小时（12 小时制） | `01` 到 `12`
  `H` | 补零的小时（24 小时制） | `00` 到 `23`
  `i` | 补零的分钟 | `00` 到 `59`
  `s` | 补零的秒 | `00` 到 `59`
  `u` | 微秒。注意 date() 总是生成 `000000`，因为它需要一个 int 参数，而如果 DateTimeInterface 是使用微秒创建的，则 DateTimeInterface::format() 支持微秒。 | 示例：`654321`
  `v` | 毫秒。与 `u` 的说明相同。 | 示例：`654`
  时区 | --- | ---
  `e` | 时区标识符 | 示例：`UTC`、`GMT`、`Atlantic/Azores`
  `I`（大写 i） | 是否为夏令时 | 如果是夏令时为 `1`，否则为 `0`。
  `O` | 跟格林尼治时间（GMT）的差异，小时和分钟时间没有冒号 | 示例：`+0200`
  `P` | 跟格林尼治时间（GMT）的差异，小时和分钟时间有冒号 | 示例：`+02:00`
  `p` | 跟 `P` 相同，区别是使用 `Z` 替换 `+00:00` 返回（PHP 8.0.0 起可用） | 示例：`Z` 或 `+02:00`
  `T` | 如果知道会返回时区缩写，否则返回 GMT 时差。 | 示例：`EST`、`MDT`、`+05`
  `Z` | 以秒为单位的时差。UTC 以西的时区为负的时差，以东为正的时差。 | `-43200` 到 `50400`
  完整日期/时间 | --- | ---
  `c` | ISO 8601 日期。只兼容非扩展格式（最多到公元 9999 年）。 更晚的日期将导致无效字符串。对于更晚的日期和扩展格式，请参见 `x` and `X`。 | 2004-02-12T15:19:21+00:00
  `r` | » RFC 2822/» RFC 5322 格式化时间 | 示例：`Thu, 21 Dec 2000 16:01:07 +0200`
  `U` | 从 Unix 纪元（January 1 1970 00:00:00 GMT）到至今的秒数 | 参见 time()

  格式字符串中无法识别的字符将会原样打印。当使用 gmdate() 时，`Z` 格式将始终返回 `0`。

  > 注意:

  > 由于本函数仅接受 int 类型时间戳，所以 `u` 格式化标识符仅在用户使用 date_create() 且使用 date_format() 创建时间戳时才有用。

### 返回值

成功时返回格式化后的日期字符串。

### 更新日志

版本 | 说明
--- | ---
8.2.0 | 新增 `X` 和 `x` 格式化字符。
8.0.0 | 新增 `p` 格式化字符。

### 示例

示例 #1 DateTimeInterface::format() 示例

面向对象风格

    <?php
    $date = new DateTimeImmutable('2000-01-01');
    echo $date->format('Y-m-d H:i:s');
    ?>

以上示例会输出：

    2000-01-01 00:00:00

过程化风格

    <?php
    $date = date_create('2000-01-01');
    echo date_format($date, 'Y-m-d H:i:s');
    ?>

以上示例会输出：

    2000-01-01 00:00:00

示例 #2 更多示例

    <?php
    // 设置使用的默认时区。
    date_default_timezone_set('UTC');

    // 现在
    $date = new DateTimeImmutable();

    // 打印类似：Wednesday
    echo $date->format('l'), "\n";

    // 打印类似：Wednesday 19th of October 2022 08:40:48 AM
    echo $date->format('l jS \o\f F Y h:i:s A'), "\n";

    /* 在 format 参数中使用常量 */
    // 打印类似：Wed, 19 Oct 2022 08:40:48 +0000
    echo $date->format(DateTimeInterface::RFC2822), "\n";
    ?>

通过对格式化字符串中的识别字符添加反斜线，对其转义来防止被解析。如果带有反斜线的字符已经是特殊序列，那么还要对反斜线进行转义。

示例 #3 格式化时转义字符

    <?php
    $date = new DateTimeImmutable();

    // 打印类似：Wednesday the 19th
    echo $date->format('l \t\h\e jS');
    ?>

要格式化其它语言的日期，可以使用 IntlDateFormatter::format() 代替 DateTimeInterface::format()。

### 注释

此方法不使用区域设置，所有的输出都是英文。

### 参见

- IntlDateFormatter::format() - Format the date/time value as a string

# 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

### 说明

public function DateTimeInterface::getMicrosecond(): int
public function DateTimeImmutable::getMicrosecond(): int
public function DateTime::getMicrosecond(): int

Gets the microsecond part of the Unix timestamp.

### 参数

此函数没有参数。

### 返回值

Returns the microsecond part of the Unix timestamp representing the date.

### 示例

示例 #1 DateTimeInterface::getMicrosecond() example

    <?php
    $date = new DateTimeImmutable('2024-01-01 12:34:56.789123');
    var_dump($date->format('u'));
    var_dump($date->getMicrosecond());
    ?>

以上示例会输出：

    string(6) "789123"
    int(789123)

### 参见

- DateTimeInterface::getTimestamp() - 获取 Unix 时间戳
- DateTimeInterface::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 — 返回时差

### 说明

面向对象风格

public function DateTimeInterface::getOffset(): int
public function DateTimeImmutable::getOffset(): int
public function DateTime::getOffset(): int

过程化风格

function date_offset_get(DateTimeInterface `$object`): int

返回时差。

### 参数

`object`
  仅为过程化风格：由 date_create() 返回的 DateTime 类型的对象。

### 返回值

成功时返回与 UTC 之间的时差（以秒为单位）。

### 示例

示例 #1 DateTime::getOffset() 示例

面向对象风格

    <?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";

以上示例会输出：

    -18000
    -14400

过程化风格

    <?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";

以上示例会输出：

    -18000
    -14400

注意：-18000 = -5 小时，-14400 = -4 小时。

# 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 — 获取 Unix 时间戳

### 说明

面向对象风格

public function DateTimeInterface::getTimestamp(): int
public function DateTimeImmutable::getTimestamp(): int
public function DateTime::getTimestamp(): int

过程化风格

function date_timestamp_get(DateTimeInterface `$object`): int

获取 Unix 时间戳。

### 参数

此函数没有参数。

### 返回值

返回表示日期的 Unix 时间戳。

### 错误／异常

如果时间戳不能表示为 int，将抛出 DateRangeError。在 PHP 8.3.0 之前，将抛出 ValueError。并且在 PHP 8.0.0 之前，在这种情况下返回 `false`。不过，可以使用 `U` 格式和 DateTimeInterface::format() 作为 string 检索时间戳。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | 超出范围的异常现在是 DateRangeError。
8.0.0 | 这些函数在失败时不再返回 `false`。

### 示例

示例 #1 DateTime::getTimestamp() 示例

面向对象风格

    <?php
    $date = new DateTimeImmutable();
    echo $date->getTimestamp();

以上示例的输出类似于：

    1272509157

过程化风格

    <?php
    $date = date_create();
    echo date_timestamp_get($date);

以上示例的输出类似于：

    1272509157

如果需要以毫秒或微秒精度检索时间戳，则可以使用 DateTimeInterface::format() 函数。

示例 #2 以毫秒和微秒精度检索时间戳

面向对象风格

    <?php
    $date = new DateTimeImmutable();
    $milli = (int) $date->format('Uv'); // Timestamp in milliseconds
    $micro = (int) $date->format('Uu'); // Timestamp in microseconds

    echo $milli, "\n", $micro, "\n";

以上示例的输出类似于：

    1674057635586
    1674057635586918

### 参见

- DateTime::setTimestamp() - 以 Unix 时间戳的方式设置日期和时间
- DateTimeImmutable::setTimestamp() - Sets the date and time based on a Unix timestamp
- DateTimeInterface::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 — 返回相对于指定 DateTime 的时区

### 说明

面向对象风格

public function DateTimeInterface::getTimezone(): DateTimeZone|false
public function DateTimeImmutable::getTimezone(): DateTimeZone|false
public function DateTime::getTimezone(): DateTimeZone|false

过程化风格

function date_timezone_get(DateTimeInterface `$object`): DateTimeZone|false

返回相对于指定 DateTime 的时区。

### 参数

`object`
  仅为过程化风格：由 date_create() 返回的 DateTime 类型的对象。

### 返回值

成功时返回 DateTimeZone 对象 或者在失败时返回 `false`。

### 示例

示例 #1 DateTime::getTimezone() 示例

面向对象风格

    <?php
    $date = new DateTimeImmutable("now", new DateTimeZone('Europe/London'));
    $tz = $date->getTimezone();
    echo $tz->getName();

以上示例会输出：

    Europe/London

过程化风格

    <?php
    $date = date_create("now", timezone_open('Europe/London'));
    $tz = date_timezone_get($date);
    echo timezone_name_get($tz);

以上示例会输出：

    Europe/London

### 参见

- DateTime::setTimezone() - 设置 DateTime 对象的时区

# DateTime::__serialize

# DateTimeImmutable::__serialize

# DateTimeInterface::__serialize

(PHP 8 >= 8.2.0)

DateTime::__serialize -- DateTimeImmutable::__serialize -- DateTimeInterface::__serialize — Serialize a DateTime

### 说明

public function DateTime::__serialize(): array
public function DateTimeImmutable::__serialize(): array
public function DateTimeInterface::__serialize(): array

The __serialize() handler.

### 参数

此函数没有参数。

### 返回值

The serialized representation of the DateTime object.

### 示例

示例 #1 DateTime::serialize() example

    <?php
    $date = new DateTime('2025-03-27');
    var_dump(serialize($date));

以上示例会输出：

    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";}"

### 参见

- 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

### 说明

public function DateTime::__unserialize(array `$data`): void
public function DateTimeImmutable::__unserialize(array `$data`): void
public function DateTimeInterface::__unserialize(array `$data`): void

The __unserialize() handler.

### 参数

`data`

  The serialized DateTime.

### 返回值

The DateTime object.

### 示例

示例 #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));

以上示例会输出：

    object(DateTime)#1 (3) {
      ["date"]=>
      string(26) "2025-03-27 00:00:00.000000"
      ["timezone_type"]=>
      int(3)
      ["timezone"]=>
      string(3) "UTC"
    }

### 参见

- 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 — The __wakeup handler

警告

此函数自 PHP 8.5.0 起弃用。强烈建议不要应用此函数。

### 说明

#[\Deprecated]
public function DateTime::__wakeup(): void
#[\Deprecated]
public function DateTimeImmutable::__wakeup(): void
#[\Deprecated]
public function DateTimeInterface::__wakeup(): void

The __wakeup() handler.

### 参数

此函数没有参数。

### 返回值

Initializes a DateTime object.

## 目录

- DateTimeInterface::diff — 返回两个 DateTime 之间的差值
- DateTimeInterface::format — 按照指定格式返回格式化后的日期
- DateTimeInterface::getMicrosecond — Gets the microsecond part of the Unix timestamp
- DateTimeInterface::getOffset — 返回时差
- DateTimeInterface::getTimestamp — 获取 Unix 时间戳
- DateTimeInterface::getTimezone — 返回相对于指定 DateTime 的时区
- DateTime::__serialize — Serialize a DateTime
- DateTime::__unserialize — Unserialize an Datetime
- DateTime::__wakeup — The __wakeup handler

# DateTimeZone 类

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

## 简介

时区表示。

## 类摘要

class DateTimeZone {
/* 常量 */
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;
/* 方法 */
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` = 2147483647): array|false
public static function listAbbreviations(): array
public static function listIdentifiers(int `$timezoneGroup` = `DateTimeZone::ALL`, ?string `$countryCode` = `null`): array
}

## 预定义常量

`DateTimeZone::AFRICA` int

  非洲时区。

`DateTimeZone::AMERICA` int

  美洲时区。

`DateTimeZone::ANTARCTICA` int

  南极洲时区。

`DateTimeZone::ARCTIC` int

  北极时区。

`DateTimeZone::ASIA` int

  亚洲时区。

`DateTimeZone::ATLANTIC` int

  大西洋时区。

`DateTimeZone::AUSTRALIA` int

  澳洲时区。

`DateTimeZone::EUROPE` int

  欧洲时区。

`DateTimeZone::INDIAN` int

  印度洋（Indian）时区。

`DateTimeZone::PACIFIC` int

  太平洋时区。

`DateTimeZone::UTC` int

  UTC 时区。

`DateTimeZone::ALL` int

  所有时区。

`DateTimeZone::ALL_WITH_BC` int

  所有时区，包含向后兼容。

`DateTimeZone::PER_COUNTRY` int

  每个国家的时区。

## 更新日志

版本 | 说明
--- | ---
8.4.0 | 类常量现已类型化。

# DateTimeZone::__construct

# timezone_open

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::__construct -- timezone_open — 创建新的DateTimeZone对象

### 说明

面向对象风格

public function DateTimeZone::__construct(string `$timezone`)

过程化风格

function timezone_open(string `$timezone`): DateTimeZone|false

创建新的 DateTimeZone 对象。

DateTimeZone 对象提供了对三种不同类型的时区规则访问。UTC 时差（类型 `1`）、时区缩写（类型 `2`）、IANA 时区数据库中公布的时区标识符（类型 `3`）。

DateTimeZone 对象可以附加到 DateTime 和 DateTimeImmutable 对象上，以便能够在本地时区呈现这些对象所封装的时区。

### 参数

`timezone`

  所支持的时区名之一，时差（+0200）或时区缩写（BSD）。

### 返回值

成功时返回 DateTimeZone 对象。 过程化风格在失败时返回 `false`。

### 错误／异常

如果提供的时区不能识别为有效的时区，此方法将抛出 DateInvalidTimeZoneException 异常。在 PHP 8.3 之前，是 Exception。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | 无效值现在返回 DateInvalidTimeZoneException 而不是生成 Exception。

### 示例

示例 #1 创建 DateTimeZone 并附加到 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";
    }

以上示例会输出：

    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

示例 #2 实例化 DateTimeZone 时捕捉错误

    <?php
    // 通过捕获异常来处理错误
    $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";
        }
    }

以上示例会输出：

    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 — 返回与时区相关的定位信息

### 说明

面向对象风格

public function DateTimeZone::getLocation(): array|false

过程化风格

function timezone_location_get(DateTimeZone `$object`): array|false

返回时区的位置信息，包含国家代码，经纬度和注释。

### 参数

`object`
  仅过程化风格：由 timezone_open() 返回的 DateTimeZone 对象。

### 返回值

包含时区的位置信息的数组 或者在失败时返回 `false`。

### 示例

示例 #1 DateTimeZone::getLocation() 函数的示例

    <?php
    $tz = new DateTimeZone("Asia/Jakarta");
    print_r($tz->getLocation());
    print_r(timezone_location_get($tz));

以上示例会输出：

    Array
    (
        [country_code] => ID
        [latitude] => -6.16667
        [longitude] => 106.8
        [comments] => Java, Sumatra
    )
    Array
    (
        [country_code] => ID
        [latitude] => -6.16667
        [longitude] => 106.8
        [comments] => Java, Sumatra
    )

`country_code` 元素包含每个条目的 ISO 3166-1 alpha-2 国家代码。`latitude` 和 `longitude` 元素包含从时区标识符中对应城市的坐标，`comments` 包含（当其值不为 `false` 时）该时区在指定国家适用区域的提示信息。此信息适合向最终用户展示。

### 参见

- DateTimeZone::listIdentifiers() - 返回包含了所有时区标识符的数字索引数组，以获得所有支持的时区标识符的完整或部分列表

# DateTimeZone::getName

# timezone_name_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getName -- timezone_name_get — 返回时区名称

### 说明

面向对象风格

public function DateTimeZone::getName(): string

过程化风格

function timezone_name_get(DateTimeZone `$object`): string

返回时区名称。

### 参数

`object`

  要获得名称的 DateTimeZone。

### 返回值

根据区域类型、UTC 时差（类型 1）、时区缩写（类型 2）和 IANA 时区数据库发布的时区标识符（类型 3），描述符字符串使用相同时差和/或规则创建新的 DateTimeZone。例如：`02:00`、`CEST` 或者 时区列表中的其中一个时区名称。

# DateTimeZone::getOffset

# timezone_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getOffset -- timezone_offset_get — 返回相对于 GMT 的时差

### 说明

面向对象风格

public function DateTimeZone::getOffset(DateTimeInterface `$datetime`): int

过程化风格

function timezone_offset_get(DateTimeZone `$object`, DateTimeInterface `$datetime`): int

该函数返回参数 `datetime` 中指定的日期/时间相对于 GMT 的时差。GMT 时差是通过 DateTimeZone 对象的时区信息计算出来的。

### 参数

`object`
  仅过程化风格：由 timezone_open() 返回的 DateTimeZone 对象。
`datetime`

  用来计算时差的 DateTime，其包含日期/时间。

### 返回值

成功时返回精确到秒的时差， 或者在失败时返回 `false`。

### 示例

示例 #1 DateTimeZone::getOffset() 示例

    <?php
    // 创建两个时区对象，分别是台北（台湾）和东京（日本）
    $dateTimeZoneTaipei = new DateTimeZone("Asia/Taipei");
    $dateTimeZoneJapan = new DateTimeZone("Asia/Tokyo");

    // 创建两个包含相同 Unix 时间戳的 DateTime 对象。区别是对应的时区不同。
    $dateTimeTaipei = new DateTime("now", $dateTimeZoneTaipei);
    $dateTimeJapan = new DateTime("now", $dateTimeZoneJapan);

    // 计算包含日期/时间的 $dateTimeTaipei 对象与时区规则定义为东京的 $dateTimeZoneJapan 对象的 GMT 时差
    $timeOffset = $dateTimeZoneJapan->getOffset($dateTimeTaipei);

    // 应该展示 int(32400)（Sat Sep 8 01:00:00 1951 JST 之后的日期）。
    var_dump($timeOffset);

以上示例会输出：

    int(32400)

# DateTimeZone::getTransitions

# timezone_transitions_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getTransitions -- timezone_transitions_get — Returns all transitions for the timezone

### 说明

面向对象风格

public function DateTimeZone::getTransitions(int `$timestampBegin` = `PHP_INT_MIN`, int `$timestampEnd` = 2147483647): array|false

过程化风格

function timezone_transitions_get(DateTimeZone `$object`, int `$timestampBegin` = `PHP_INT_MIN`, int `$timestampEnd` = 2147483647): array|false

### 参数

`object`
  仅过程化风格：由 timezone_open() 返回的 DateTimeZone 对象。
`timestampBegin`

  Begin timestamp.

`timestampEnd`

  End timestamp.

### 返回值

Returns a numerically indexed array of transition arrays on success, 或者在失败时返回 `false`. DateTimeZone objects wrapping type 1 (UTC offsets) and type 2 (abbreviations) do not contain any transitions, and calling this method on them will return `false`.

If `timestampBegin` is given, the first entry in the returned array will contain a transition element at the time of `timestampBegin`.

Transition Array Structure
Key | Type | Description
--- | --- | ---
`ts` | int | Unix timestamp
`time` | string | `DateTimeInterface::ISO8601_EXPANDED` (PHP 8.2 and later), or `DateTimeInterface::ISO8601` (PHP 8.1 and lower) time string
`offset` | int | Offset to UTC in seconds
`isdst` | bool | Whether daylight saving time is active
`abbr` | string | Timezone abbreviation

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The default value of `timestampEnd` has been changed to 2147483647. Previously, it was `PHP_INT_MAX`.

### 示例

示例 #1 A timezone_transitions_get() example

    <?php
    $timezone = new DateTimeZone("Europe/London");
    $transitions = $timezone->getTransitions();
    print_r(array_slice($transitions, 0, 3));
    ?>

以上示例的输出类似于：

    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
            )

    )

示例 #2 A timezone_transitions_get() example with `timestampBegin` set

    <?php
    $timezone = new DateTimeZone("Europe/London");
    $transitions = $timezone->getTransitions(time());
    print_r(array_slice($transitions, 0, 3));
    ?>

以上示例的输出类似于：

    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 — 返回一个包含 dst (夏令时)，时差和时区信息的关联数组。

### 说明

面向对象风格

public static function DateTimeZone::listAbbreviations(): array

过程化风格

function timezone_abbreviations_list(): array

返回简写列表，包含历史上所有使用过的简写，这可能会导致既正确又混乱的条目。也会存在冲突，比如 `PST` 在美国和菲律宾都在有使用。

因此函数返回的列表不适合构建为带选项的数组，以便向用户提供时区选择。

> 注意:

> 出于性能考虑，会预先编译此函数的数据。在使用较新的 » timezonedb 时不会更新。

### 参数

此函数没有参数。

### 返回值

返回时区简写数组。

### 示例

示例 #1 timezone_abbreviations_list() 示例

    <?php
    $timezone_abbreviations = DateTimeZone::listAbbreviations();
    print_r($timezone_abbreviations["acst"]);

以上示例的输出类似于：

    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
            )

    )

### 参见

- timezone_identifiers_list() - 别名 DateTimeZone::listIdentifiers

# DateTimeZone::listIdentifiers

# timezone_identifiers_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::listIdentifiers -- timezone_identifiers_list — 返回包含了所有时区标识符的数字索引数组

### 说明

面向对象风格

public static function DateTimeZone::listIdentifiers(int `$timezoneGroup` = `DateTimeZone::ALL`, ?string `$countryCode` = `null`): array

过程化风格

function timezone_identifiers_list(int `$timezoneGroup` = `DateTimeZone::ALL`, ?string `$countryCode` = `null`): array

返回 » IANA 时区标识符列表。

> 注意: 可通过 JavaScript 使用 » Intl.DateTimeFormat 或 » Temporal.ZonedDateTime 检测客户端（浏览器）时区。

### 参数

`timezoneGroup`

  DateTimeZone 类中的常量之一（或组合）。

`countryCode`

  国家代码，兼容 ISO 3166-1 的两个大写字母。

  > 注意: 只有当 `timezoneGroup` 设置为 `DateTimeZone::PER_COUNTRY` 时,该选项才会被使用。

### 返回值

返回时区标识符的数组。只会返回没有过时的元素。要获取包含过时时区标识符的所有元素，使用 `DateTimeZone::ALL_WITH_BC` 作为 `timezoneGroup` 的值。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 在此版本之前，失败时返回 `false`。
7.1.0 | 现在，`countryCode` 可以为 null。

### 示例

示例 #1 列出带位置注释的标识符

    <?php
    $identifiers = DateTimeZone::listIdentifiers(DateTimeZone::ALL);

    foreach ($identifiers as $tzid) {
        $tz = new DateTimeZone($tzid);
        $comments = $tz->getLocation()['comments'];
        echo $tzid . " (" . ($comments ?: 'Whole region') . ")\n";
    }

以上示例的输出类似于：

    America/Antigua (Whole region)
    America/Araguaina (Tocantins)
    America/Argentina/Buenos_Aires (Buenos Aires (BA, CF))
    America/Argentina/Catamarca (Catamarca (CT), Chubut (CH))
    America/Argentina/Cordoba (Argentina (most areas: CB, CC, CN, ER, FM, MN, SE, SF))
    // (Output trimmed due to length)

示例 #2 列出指定区域的标识符

    <?php
    $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::ASIA );
    for ($i=0; $i < 5; $i++) {
        echo "$timezone_identifiers[$i]\n";
    }

以上示例的输出类似于：

    Asia/Aden
    Asia/Almaty
    Asia/Amman
    Asia/Anadyr
    Asia/Aqtau

示例 #3 列出多个区域的标识符

    <?php
    $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::ASIA | DateTimeZone::PACIFIC );
    echo join( ', ', $timezone_identifiers );

以上示例的输出类似于：

    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

示例 #4 列出单个国家的标识符

    <?php
    $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::PER_COUNTRY, "UA" );
    foreach( $timezone_identifiers as $identifier ) {
        echo "$identifier\n";
    }

以上示例的输出类似于：

    Europe/Kyiv
    Europe/Simferopol
    Europe/Uzhgorod
    Europe/Zaporozhye

### 参见

- timezone_abbreviations_list() - 别名 DateTimeZone::listAbbreviations

## 目录

- DateTimeZone::__construct — 创建新的DateTimeZone对象
- DateTimeZone::getLocation — 返回与时区相关的定位信息
- DateTimeZone::getName — 返回时区名称
- DateTimeZone::getOffset — 返回相对于 GMT 的时差
- DateTimeZone::getTransitions — Returns all transitions for the timezone
- DateTimeZone::listAbbreviations — 返回一个包含 dst (夏令时)，时差和时区信息的关联数组。
- DateTimeZone::listIdentifiers — 返回包含了所有时区标识符的数字索引数组

# DateInterval 类

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## 简介

表示时间间隔。

时间间隔表示固定量的时间（多少年，月，天，小时等），也可以表示一个字符串格式的相对时间，当表示相对时间的时候，字符串格式是 DateTimeImmutable 和 DateTime 类的构造函数所支持的格式。

更具体的说，DateInterval 类的对象中的信息是从一个日期/时间到另一个日期/时间的指令。这个过程并不始终可逆。

创建 DateInterval 对象的常用方法是通过 DateTimeInterface::diff() 计算两个日期/时间对象之间的差异。

由于没有明确定义的方法来比较日期间隔，因此 DateInterval 实例是无法比较的。

## 类摘要

class DateInterval {
/* 属性 */
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;
/* 方法 */
public function __construct(string `$duration`)
public static function createFromDateString(string `$datetime`): DateInterval
public function format(string `$format`): string
}

## 属性

警告

下列列出的有效属性依赖 PHP 版本，应视为 readonly。

y

  多少年。

m

  多少月。

d

  多少天。

h

  多少小时。

i

  多少分钟。

s

  多少秒。

f

  多少微秒。

invert

  如果是负的时间段，则为 `1`，否则为 `0`。请参见 DateInterval::format()。

days

  如果 DateInterval 对象是由 DateTimeImmutable::diff() 或者 DateTime::diff() 函数创建的，那么它表示开始日期和结束日期之间的完整天数。否则，days 属性为 `false`。

from_string

  如果 DateInterval 对象是通过 DateInterval::createFromDateString() 创建，则此属性值设为 `true` 并且 date_string 属性将填充数据。否则，此值设为 `false` 且为从 y 到 f、invert 和 days 属性填充数据。

date_string

  字符串，用作 DateInterval::createFromDateString() 的参数。

## 更新日志

版本 | 说明
--- | ---
8.2.0 | 为使用 DateInterval::createFromDateString() 方法创建的 DateInterval 实例添加了 from_string 和 date_string 属性。
8.2.0 | 仅从 `y` 到 `f`、`invert` 和 `days` 将可见。
7.4.0 | 现在 DateInterval 无法比较；之前所有的 DateInterval 实例都认为相等。
7.1.0 | 增加 f 属性。

# DateInterval::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::__construct — Creates a new DateInterval object

### 说明

public function DateInterval::__construct(string `$duration`)

Creates a new DateInterval object.

### 参数

`duration`

  An interval specification.

  The format starts with the letter `P`, for period. Each duration period is represented by an integer value followed by a period designator. If the duration contains time elements, that portion of the specification is preceded by the letter `T`.

  `duration` Period Designators
  Period Designator | Description
  --- | ---
  `Y` | years
  `M` | months
  `D` | days
  `W` | weeks. Converted into days. Prior to PHP 8.0.0, can not be combined with `D`.
  `H` | hours
  `M` | minutes
  `S` | seconds

  Here are some simple examples. Two days is `P2D`. Two seconds is `PT2S`. Six years and five minutes is `P6YT5M`.

  > 注意:

  > The unit types must be entered from the largest scale unit on the left to the smallest scale unit on the right. So years before months, months before days, days before minutes, etc. Thus one year and four days must be represented as `P1Y4D`, not `P4D1Y`.

  The specification can also be represented as a date time. A sample of one year and four days would be `P0001-00-04T00:00:00`. But the values in this format can not exceed a given period's roll-over-point (e.g. `25` hours is invalid).

  These formats are based on the » ISO 8601 duration specification.

### 错误／异常

Throws an DateMalformedIntervalStringException when the `duration` cannot be parsed as an interval. Prior to PHP 8.3, this was Exception.

### 更新日志

版本 | 说明
--- | ---
8.3.0 | Now throws DateMalformedIntervalStringException instead of Exception.
8.2.0 | Only the `y` to `f`, `invert`, and `days` will be visible, including a new `from_string` boolean property.
8.0.0 | `W` can be combined with `D`.

### 示例

示例 #1 Constructing and using DateInterval objects

    <?php
    // Create a specific date
    $someDate = \DateTime::createFromFormat("Y-m-d H:i", "2022-08-25 14:18");

    // Create interval
    $interval = new \DateInterval("P7D");

    // Add interval
    $someDate->add($interval);

    // Convert interval to string
    echo $interval->format("%d");

以上示例会输出：

    7

示例 #2 DateInterval example

    <?php
    $interval = new DateInterval('P1W2D');
    var_dump($interval);

以上示例在 PHP 8.2 中的输出：

    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)
    }

以上示例在 PHP 8 中的输出：

    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)
    }

以上示例在 PHP 7 中的输出：

    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)
    }

### 参见

- DateInterval::format() - Formats the interval
- DateTime::add() - 修改 DateTime 对象，增加天、月、年、小时、分钟以及秒的数量。
- DateTime::sub() - 对 DateTime 对象减去一定量的日、月、年、小时、分钟和秒。
- DateTime::diff() - 返回两个 DateTime 之间的差值

# DateInterval::createFromDateString

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::createFromDateString — Sets up a DateInterval from the relative parts of the string

### 说明

面向对象风格

public static function DateInterval::createFromDateString(string `$datetime`): DateInterval

过程化风格

function date_interval_create_from_date_string(string `$datetime`): DateInterval|false

Uses the date/time parsers as used in the DateTimeImmutable constructor to create a DateInterval from the relative parts of the parsed string.

### 参数

`datetime`

  A date with relative parts. Specifically, the relative formats supported by the parser used for DateTimeImmutable, DateTime, and strtotime() will be used to construct the DateInterval.

  To use an ISO-8601 format string like `P7D`, you must use the DateInterval::__construct().

### 返回值

Returns DateInterval on success. 过程化风格在失败时返回 `false`。

### 错误／异常

Object Oriented API only: If an invalid Date/Time string is passed, DateMalformedIntervalStringException is thrown.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | Now has a tentative return type of DateInterval. Previously it was DateInterval|false.
8.3.0 | DateInterval::createFromDateString() now throws DateMalformedIntervalStringException if an invalid string is passed. Previously, it returned `false`, and a warning was emitted. date_interval_create_from_date_string() has not been changed.
8.2.0 | Only the `from_string` and `date_string` properties will be visible when a DateInterval is created with this method.

### 示例

示例 #1 Parsing valid date intervals

    <?php
    // Each set of intervals is equal.
    $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');

示例 #2 Parsing combinations and negative intervals

    <?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";

以上示例会输出：

    449 2 70
    1 -10

示例 #3 Parsing special relative date intervals

    <?php
    $i = DateInterval::createFromDateString('last day of next month');
    var_dump($i);

    $i = DateInterval::createFromDateString('last weekday');
    var_dump($i);

以上示例在 PHP 8.2 中的输出：

    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"
    }

以上示例在 PHP 8 中的输出类似于：

    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 — Formats the interval

### 说明

public function DateInterval::format(string `$format`): string

Formats the interval.

### 参数

`format`

  The following characters are recognized in the `format` parameter string. Each format character must be prefixed by a percent sign (`%`).
  `format` character | Description | Example values
  --- | --- | ---
  `%` | Literal `%` | `%`
  `Y` | Years, numeric, at least 2 digits with leading 0 | `01`, `03`
  `y` | Years, numeric | `1`, `3`
  `M` | Months, numeric, at least 2 digits with leading 0 | `01`, `03`, `12`
  `m` | Months, numeric | `1`, `3`, `12`
  `D` | Days, numeric, at least 2 digits with leading 0 | `01`, `03`, `31`
  `d` | Days, numeric | `1`, `3`, `31`
  `a` | Total number of days as a result of a DateTime::diff() or `(unknown)` otherwise | `4`, `18`, `8123`
  `H` | Hours, numeric, at least 2 digits with leading 0 | `01`, `03`, `23`
  `h` | Hours, numeric | `1`, `3`, `23`
  `I` | Minutes, numeric, at least 2 digits with leading 0 | `01`, `03`, `59`
  `i` | Minutes, numeric | `1`, `3`, `59`
  `S` | Seconds, numeric, at least 2 digits with leading 0 | `01`, `03`, `57`
  `s` | Seconds, numeric | `1`, `3`, `57`
  `F` | Microseconds, numeric, at least 6 digits with leading 0 | `007701`, `052738`, `428291`
  `f` | Microseconds, numeric | `7701`, `52738`, `428291`
  `R` | Sign "`-`" when negative, "`+`" when positive | `-`, `+`
  `r` | Sign "`-`" when negative, empty when positive | `-`, ``

### 返回值

Returns the formatted interval.

### 更新日志

版本 | 说明
--- | ---
7.2.12 | The `F` and `f` format will now always be positive.
7.1.0 | The `F` and `f` format characters were added.

### 示例

示例 #1 DateInterval example

    <?php
    $interval = new DateInterval('P2Y4DT6H8M');
    echo $interval->format('%d days');

以上示例会输出：

    4 days

示例 #2 DateInterval and carry over points

    <?php
    $interval = new DateInterval('P32D');
    echo $interval->format('%d days');

以上示例会输出：

    32 days

示例 #3 DateInterval and DateTime::diff() with the %a and %d modifiers

    <?php
    $january = new DateTime('2010-01-01');
    $february = new DateTime('2010-02-01');
    $interval = $february->diff($january);

    // %a will output the total number of days.
    echo $interval->format('%a total days')."\n";

    // While %d will only output the number of days not already covered by the
    // month.
    echo $interval->format('%m month, %d days');

以上示例会输出：

    31 total days
    1 month, 0 days

### 注释

> 注意:

> The DateInterval::format() method does not recalculate carry over points in time strings nor in date segments. This is expected because it is not possible to overflow values like `"32 days"` which could be interpreted as anything from `"1 month and 4 days"` to `"1 month and 1 day"`.

### 参见

- DateTime::diff() - 返回两个 DateTime 之间的差值

## 目录

- DateInterval::__construct — Creates a new DateInterval object
- DateInterval::createFromDateString — Sets up a DateInterval from the relative parts of the string
- DateInterval::format — Formats the interval

# DatePeriod 类

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## 简介

DatePeriod 类表示一个时间周期。

时间周期内允许对一组日期和时间进行迭代，在指定的时间间隔内定期重复。

## 类摘要

class DatePeriod implements IteratorAggregate {
/* 常量 */
public const int EXCLUDE_START_DATE;
public const int INCLUDE_END_DATE;
/* 属性 */
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;
/* 方法 */
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
}

## 预定义常量

`DatePeriod::EXCLUDE_START_DATE` int

  在 DatePeriod::__construct() 构造函数中使用，排除开始时间。

`DatePeriod::INCLUDE_END_DATE` int

  在 DatePeriod::__construct() 构造函数中使用，包含结束时间。

## 属性

recurrences

  迭代器返回的最小实例数。

  如果在 DatePeriod 实例的构造函数中显式通过 recurrences 参数传递重复次数，然后此属性将包含该值，如果开始时间没有通过 `DatePeriod::EXCLUDE_START_DATE` 禁用，则该属性加 1，如果结束时间已经通过 `DatePeriod::INCLUDE_END_DATE` 启用，则该属性加 1。

  如果没有显式传递重复次数，则此属性包含返回实例的最小数量。这将是 `0`，如果开始时间没有通过 `DatePeriod::EXCLUDE_START_DATE` 禁用，则该属性加 1，如果结束时间已经通过 `DatePeriod::INCLUDE_END_DATE` 启用，则该属性加 1。

      <?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;

      // 通过构造函数显式设置重复次数
      $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";

      // 构造函数中没有设置重复次数
      $period = new DatePeriod($start, $interval, $end);
      echo $period->recurrences, "\n";

      $period = new DatePeriod($start, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
      echo $period->recurrences, "\n";

  以上示例会输出：

      5
      6
      7
      1
      0

  参见 DatePeriod::getRecurrences()。

include_end_date

  在循环过程中，是否包含结束时间。

include_start_date

  在循环过程中，是否包含开始时间。

start

  时间周期的开始时间。

current

  表示在时间周期内迭代的时候，当前的时间。

end

  时间周期的结束时间。

interval

  ISO 8601 格式的间隔。

## 更新日志

版本 | 说明
--- | ---
8.4.0 | 类常量现已类型化。
8.2.0 | 新增 `DatePeriod::INCLUDE_END_DATE` 常量和 include_end_date 属性。
8.0.0 | 现在 DatePeriod 实现了（implement） IteratorAggregate。之前实现的是 Traversable。

# DatePeriod::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DatePeriod::__construct — Creates a new DatePeriod object

### 说明

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
)
警告

The following constructor variant has been deprecated:

public function DatePeriod::__construct(string `$isostr`, int `$options` = 0)

This variant of the constructor is deprecated as of PHP 8.4.0, use DatePeriod::createFromISO8601String() instead.

Creates a new DatePeriod object.

DatePeriod objects can be used as an iterator to generate a number of DateTimeImmutable or DateTime object from a `start` date, a `interval`, and an `end` date or the number of `recurrences`.

The class of returned objects is equivalent to the DateTimeImmutable or DateTime ancestor class of the `start` object.

### 参数

`start`

  The start date of the period. Included by default in the result set.

`interval`

  The interval between recurrences within the period.

`recurrences`

  The number of recurrences. The number of returned results is one higher than this, as the start date is included in the result set by default. Must be greater than `0`.

`end`

  The end date of the period. Excluded by default from the result set.

`isostr`

  A subset of the » ISO 8601 repeating interval specification.

  Examples of some ISO 8601 interval specification features that PHP does not support are:

  1. zero occurrences (`R0/`)
  2. time offsets other than UTC (`Z`), such as `+02:00`.
`options`

  A bit field which can be used to control certain behaviour with start- and end- dates.

  With `DatePeriod::EXCLUDE_START_DATE` you exclude the start date from the set of recurring dates within the period.

  With `DatePeriod::INCLUDE_END_DATE` you include the end date in the set of recurring dates within the period.

### 错误／异常

Throws an DateMalformedPeriodStringException when the `isostr` cannot be parsed as a valid ISO 8601 period. Prior to PHP 8.3, this was Exception.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | The signature using `isostr` has been deprecated, use DatePeriod::createFromISO8601String() instead.
8.3.0 | Now throws DateMalformedPeriodStringException instead of Exception.
8.2.0 | The `DatePeriod::INCLUDE_END_DATE` constant has been added.
7.2.19, 7.3.6, 7.4.0 | `recurrences` must be greater than `0` now.

### 示例

示例 #1 DatePeriod example

    <?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';

    // All of these periods are equivalent.
    $period = new DatePeriod($start, $interval, $recurrences);
    $period = new DatePeriod($start, $interval, $end);
    $period = new DatePeriod($iso);

    // By iterating over the DatePeriod object, all of the
    // recurring dates within that period are printed.
    foreach ($period as $date) {
        echo $date->format('Y-m-d')."\n";
    }

以上示例会输出：

    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

示例 #2 DatePeriod example with `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);

    // By iterating over the DatePeriod object, all of the
    // recurring dates within that period are printed.
    // Note that, in this case, 2012-07-01 is not printed.
    foreach ($period as $date) {
        echo $date->format('Y-m-d')."\n";
    }

以上示例会输出：

    2012-07-08
    2012-07-15
    2012-07-22
    2012-07-29

示例 #3 DatePeriod example showing all last Thursdays in a year

    <?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";
    }

以上示例会输出：

    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

### 注释

Unbound numbers of repetitions as specified by ISO 8601 section 4.5 "Recurring time interval" are not supported, i.e. neither passing `"R/..."` as `isostr` nor passing `null` as `end` would work.

# DatePeriod::createFromISO8601String

(PHP 8 >= 8.3.0)

DatePeriod::createFromISO8601String — Creates a new DatePeriod object from an ISO8601 string

### 说明

public static function DatePeriod::createFromISO8601String(string `$specification`, int `$options` = 0): static

Creates a new DatePeriod object from an ISO8601 string, as specified with `specification`.

### 参数

`specification`

  A subset of the » ISO 8601 repeating interval specification.

  An example of an accepted ISO 8601 interval specifications is `R5/2008-03-01T13:00:00Z/P1Y2M10DT2H30M`, which specifies:

  - 5 iterations (`R5/`)
  - Starting at `2008-03-01T13:00:00Z`.
  - Each iteration is an 1 year, 2 months, 10 days, 2 hours, and 30 minute interval (`/P1Y2M10DT2H30M`).

  Examples of some ISO 8601 interval specification features that PHP does not support are:

  1. zero occurrences (`R0/`)
  2. time offsets other than UTC (`Z`), such as `+02:00`.
`options`

  A bit field which can be used to control certain behaviour with start- and end- dates.

  With `DatePeriod::EXCLUDE_START_DATE` you exclude the start date from the set of recurring dates within the period.

  With `DatePeriod::INCLUDE_END_DATE` you include the end date in the set of recurring dates within the period.

### 返回值

Creates a new DatePeriod object.

DatePeriod objects created with this method can be used as an iterator to generate a number of DateTimeImmutable objects.

### 错误／异常

Throws an DateMalformedPeriodStringException when the `specification` cannot be parsed as a valid ISO 8601 period.

### 示例

示例 #1 DatePeriod::createFromISO8601String example

    <?php
    $iso = 'R4/2023-07-01T00:00:00Z/P7D';
    $period = DatePeriod::createFromISO8601String($iso);

    // By iterating over the DatePeriod object, all of the
    // recurring dates within that period are printed.
    foreach ($period as $date) {
        echo $date->format('Y-m-d'), "\n";
    }

以上示例会输出：

    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 — Gets the interval

### 说明

面向对象风格

public function DatePeriod::getDateInterval(): DateInterval

Gets a DateInterval object representing the interval used for the period.

### 参数

此函数没有参数。

### 返回值

Returns a DateInterval object

### 示例

示例 #1 DatePeriod::getDateInterval() example

    <?php
    $period = DatePeriod::createFromIso8601String('R7/2016-05-16T00:00:00Z/P1D');
    $interval = $period->getDateInterval();
    echo $interval->format('%d day');

以上示例会输出：

    1 day

### 参见

- DatePeriod::getStartDate() - Gets the start date
- DatePeriod::getEndDate() - Gets the end date

# DatePeriod::getEndDate

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getEndDate — Gets the end date

### 说明

面向对象风格

public function DatePeriod::getEndDate(): ?DateTimeInterface

Gets the end date of the period.

### 参数

此函数没有参数。

### 返回值

Returns `null` if the DatePeriod does not have an end date. For example, when initialized with the `recurrences` parameter, or the `isostr` parameter without an end date.

Returns a DateTimeImmutable object when the DatePeriod is initialized with a DateTimeImmutable object as the `end` parameter.

Returns a cloned DateTime object representing the end date otherwise.

### 示例

示例 #1 DatePeriod::getEndDate() example

    <?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);

以上示例会输出：

    2016-05-20T00:00:00+0000

示例 #2 DatePeriod::getEndDate() without an end date

    <?php
    $period = new DatePeriod(
        new DateTime('2016-05-16T00:00:00Z'),
        new DateInterval('P1D'),
        7
    );
    var_dump($period->getEndDate());

以上示例会输出：

    NULL

### 参见

- DatePeriod::getStartDate() - Gets the start date
- DatePeriod::getDateInterval() - Gets the interval

# DatePeriod::getRecurrences

(PHP 7 >= 7.2.17/7.3.4, PHP 8)

DatePeriod::getRecurrences — Gets the number of recurrences

### 说明

面向对象风格

public function DatePeriod::getRecurrences(): ?int

Get the number of recurrences.

### 参数

此函数没有参数。

### 返回值

The number of recurrences as set by explicitly passing the `$recurrences` to the constructor of the DatePeriod class, or `null` otherwise.

### 示例

示例 #1 Different values for 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;

    // recurrences explicitly set through the constructor
    $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";

    // recurrences not set in the constructor
    $period = new DatePeriod($start, $interval, $end);
    var_dump($period->getRecurrences());

    $period = new DatePeriod($start, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
    var_dump($period->getRecurrences());

以上示例会输出：

    5
    5
    5

    NULL
    NULL

### 参见

- DatePeriod::$recurrences

# DatePeriod::getStartDate

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getStartDate — Gets the start date

### 说明

面向对象风格

public function DatePeriod::getStartDate(): DateTimeInterface

Gets the start date of the period.

### 参数

此函数没有参数。

### 返回值

Returns a DateTimeImmutable object when the DatePeriod is initialized with a DateTimeImmutable object as the `start` parameter.

Returns a DateTime object otherwise.

### 示例

示例 #1 DatePeriod::getStartDate() example

    <?php
    $period = DatePeriod::createFromIso8601String('R7/2016-05-16T00:00:00Z/P1D');
    $start = $period->getStartDate();
    echo $start->format(DateTime::ISO8601);

以上示例会输出：

    2016-05-16T00:00:00+0000

### 参见

- DatePeriod::getEndDate() - Gets the end date
- DatePeriod::getDateInterval() - Gets the interval

## 目录

- DatePeriod::__construct — Creates a new DatePeriod object
- DatePeriod::createFromISO8601String — Creates a new DatePeriod object from an ISO8601 string
- DatePeriod::getDateInterval — Gets the interval
- DatePeriod::getEndDate — Gets the end date
- DatePeriod::getRecurrences — Gets the number of recurrences
- DatePeriod::getStartDate — Gets the start date

# Date/Time 函数

# checkdate

(PHP 4, PHP 5, PHP 7, PHP 8)

checkdate — 验证一个格里高里日期

### 说明

function checkdate(int `$month`, int `$day`, int `$year`): bool

检查由参数构成的日期的合法性。如果每个参数都正确定义了则会被认为是有效的。

### 参数

`month`

  month 的值是从 1 到 12。

`day`

  `Day` 的值在给定的 `month` 所应该具有的天数范围之内，闰年已经考虑进去了。

`year`

  year 的值是从 1 到 32767。

### 返回值

如果给出的日期有效则返回 `true`，否则返回 `false`。

### 示例

示例 #1 checkdate() 示例

    <?php
    var_dump(checkdate(12, 31, 2000));
    var_dump(checkdate(2, 29, 2001));

以上示例会输出：

    bool(true)
    bool(false)

### 参见

- mktime() - 取得一个日期的 Unix 时间戳
- strtotime() - 将任何英文文本日期时间描述解析为 Unix 时间戳

# date

(PHP 4, PHP 5, PHP 7, PHP 8)

date — 格式化 Unix 时间戳

### 说明

function date(string `$format`, ?int `$timestamp` = `null`): string

使用指定整数 `timestamp`（Unix 时间戳），或者使用当前时间（如果没有指定时间戳），返回相应的指定格式的格式化字符串。换句话说，`timestamp` 是可选的，默认值是 time()。

警告

Unix 时间戳不处理时区。使用 DateTimeImmutable 及其 DateTimeInterface::format() 格式化方法来格式化携带时区的日期/时间信息。

### 参数

`format`

  DateTimeInterface::format() 接受的格式。

  > 注意: date() 将始终生成 `000000` 作为微秒，因为它采用 int 参数，而如果 DateTimeInterface 类型的对象是用微秒创建的， 则 DateTimeInterface::format() 支持微秒。

`timestamp`
  可选的 `timestamp` 参数是一个 int 的 Unix 时间戳，如未指定或是 `null`，参数值默认为当前本地时间。也就是说，其值默认为 time() 的返回值。

### 返回值

返回格式化后的日期字符串。

### 错误／异常

在每次调用日期/时间函数时，如果时区无效则会引发 `E_NOTICE` 错误。参见 date_default_timezone_set()。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `timestamp` 允许为 null。

### 示例

示例 #1 date() 示例

    <?php
    // 设置要使用的默认时区。
    date_default_timezone_set('UTC');

    // 打印类似：Monday
    echo date("l") . "\n";

    // 打印类似：Monday 8th of August 2005 03:12:46 PM
    echo date('l jS \of F Y h:i:s A') . "\n";

    // 打印：July 1, 2000 is on a Saturday
    echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000)) . "\n";

    /* 使用格式化参数中的常量 */
    // 打印类似：Wed, 25 Sep 2013 15:28:57 -0700
    echo date(DATE_RFC2822) . "\n";

    // 打印类似：2000-07-01T00:00:00+00:00
    echo date(DATE_ATOM, mktime(0, 0, 0, 7, 1, 2000));

可以对格式化字符串中的解析字符，在其前面添加反斜线来防止解析。如果带有反斜线的字符已经是特殊字符，需要对反斜线进行再次转义。

示例 #2 date() 中的转义字符

    <?php
    // 打印类似： Wednesday the 15th
    echo date('l \t\h\e jS');

date() 格式化的一些示例。请注意，即使是对于当前来说并不具有特殊含义的字符，也要像对待具有特殊含义的字符那样进行转义，以避免产生非预期的值，因为可能在将来的 PHP 版本中，这些字符会被赋予特殊的含义。进行转义的时候，请确保使用单引号，以避免 \n 这样的字符被解释为换行符号。

示例 #3 date() 格式化

    <?php
    // 假设今天是 2001 年 3 月 10 日下午 5 点 16 分 18 秒，
    // 并且位于山区标准时间（MST）时区
    date_default_timezone_set("America/Phoenix");

    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（MySQL DATETIME 格式）

如果需要将日期时间格式化为其他语言，使用 IntlDateFormatter::format() 而不是 date()。

### 注释

> 注意:

> 使用 strtotime() 将字符串表示的日期转换为时间戳。另外，一些数据库产品也提供了将日期格式转换为时间戳的函数（例如 MySQL 中的 » UNIX_TIMESTAMP 函数）。

小技巧

请求的开始时间可以从变量 $_SERVER['REQUEST_TIME'] 中获取。

### 参见

- DateTimeImmutable::__construct() - Returns new DateTimeImmutable object
- DateTimeInterface::format() - 按照指定格式返回格式化后的日期
- gmdate() - 格式化 GMT/UTC 日期／时间
- idate() - 将本地日期/时间格式化为整数
- getdate() - 获取日期/时间信息
- getlastmod() - 获取页面最后修改的时间
- mktime() - 取得一个日期的 Unix 时间戳
- IntlDateFormatter::format() - Format the date/time value as a string
- time() - 返回当前的 Unix 时间戳
- 预定义 DateTime 常量

# date_add

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_add — 别名 DateTime::add()

### 说明

此函数是该函数的别名： DateTime::add()

# date_create

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_create — create a new DateTime object

### 说明

function date_create(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`): DateTime|false

This is the procedural version of DateTime::__construct().

Unlike the DateTime constructor, it will return `false` instead of an exception if the passed in `datetime` string is invalid.

### 参数

See DateTimeImmutable::__construct.

### 返回值

Returns a new DateTime instance 或者在失败时返回 `false`

### 参见

- DateTimeImmutable::__construct() - Returns new DateTimeImmutable object
- DateTimeImmutable::createFromFormat() - Parses a time string according to a specified format
- DateTime::__construct() - 返回新的 DateTime 对象

# date_create_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_create_from_format — 别名 DateTime::createFromFormat()

### 说明

此函数是该函数的别名： DateTime::createFromFormat()

# date_create_immutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

date_create_immutable — create a new DateTimeImmutable object

### 说明

function date_create_immutable(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

This is the procedural version of DateTimeImmutable::__construct().

Unlike the DateTimeImmutable constructor, it will return `false` instead of an exception if the passed in `datetime` string is invalid.

### 参数

See DateTimeImmutable::__construct.

### 返回值

Returns a new DateTimeImmutable instance 或者在失败时返回 `false`

### 参见

- DateTimeImmutable::createFromFormat() - Parses a time string according to a specified format

# date_create_immutable_from_format

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

date_create_immutable_from_format — 别名 DateTimeImmutable::createFromFormat()

### 说明

此函数是该函数的别名： DateTimeImmutable::createFromFormat()

# date_date_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_date_set — 别名 DateTime::setDate()

### 说明

此函数是该函数的别名： DateTime::setDate()

# date_default_timezone_get

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

date_default_timezone_get — 取得脚本中所有日期/时间函数所使用的默认时区

### 说明

function date_default_timezone_get(): string

本函数按照如下顺序返回默认时区：

- 读取使用 date_default_timezone_set() 函数设置的时区（如果设置了的话）

- 读取 date.timezone ini 选项的值（如果设置了的话）

如果以上选择都不成功，date_default_timezone_get() 会则返回默认时区 `UTC` 。

### 参数

此函数没有参数。

### 返回值

返回 string。

### 示例

示例 #1 获取默认时区

    <?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');
    }

以上示例的输出类似于：

    date_default_timezone_set: Europe/London
    date.timezone: Europe/London

示例 #2 获取时区缩写

    <?php
    date_default_timezone_set('America/Los_Angeles');
    echo date_default_timezone_get() . ' => ' . date('e') . ' => ' . date('T');

以上示例会输出：

    America/Los_Angeles => America/Los_Angeles => PST

### 参见

- date_default_timezone_set() - 设置脚本中所有日期/时间函数使用的默认时区
- 所支持的时区列表

# date_default_timezone_set

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

date_default_timezone_set — 设置脚本中所有日期/时间函数使用的默认时区

### 说明

function date_default_timezone_set(string `$timezoneId`): bool

date_default_timezone_set() 设置所有日期/时间函数使用的默认时区

除了在脚本中使用此函数设置默认时区，还可以使用 INI 设置 date.timezone 设置默认时区。

### 参数

`timezoneId`

  时区标识符，像 `UTC`、`Africa/Lagos`、`Asia/Hong_Kong` 或 `Europe/Lisbon`。有效的标识符列表见所支持的时区列表。

### 返回值

如果 `timezoneId` 无效，此函数返回 `false`，否则返回 `true`。

### 示例

示例 #1 获取默认时区

    <?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 'Script timezone differs from ini-set timezone.';
    } else {
        echo 'Script timezone and ini-set timezone match.';
    }

### 参见

- date_default_timezone_get() - 取得脚本中所有日期/时间函数所使用的默认时区
- 所支持的时区列表

# date_diff

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_diff — 别名 DateTime::diff()

### 说明

此函数是该函数的别名： DateTime::diff()

# date_format

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_format — 别名 DateTime::format()

### 说明

此函数是该函数的别名： DateTime::format()

# date_get_last_errors

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_get_last_errors — 别名 DateTimeImmutable::getLastErrors()

### 说明

此函数是该函数的别名： DateTimeImmutable::getLastErrors()

# date_interval_create_from_date_string

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_interval_create_from_date_string — 别名 DateInterval::createFromDateString()

### 说明

此函数是该函数的别名： DateInterval::createFromDateString()

# date_interval_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_interval_format — 别名 DateInterval::format()

### 说明

此函数是该函数的别名： DateInterval::format()

# date_isodate_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_isodate_set — 别名 DateTime::setISODate()

### 说明

此函数是该函数的别名： DateTime::setISODate()

# date_modify

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_modify — 别名 DateTime::modify()

### 说明

此函数是该函数的别名： DateTime::modify()

# date_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_offset_get — 别名 DateTime::getOffset()

### 说明

此函数是该函数的别名： DateTime::getOffset()

# date_parse

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_parse — 返回指定日期/时间的详细信息的关联数组

### 说明

function date_parse(string `$datetime`): array

date_parse() 根据与 strtotime() 和 DateTimeImmutable::__construct() 相同的规则解析指定 `datetime` 字符串。它不返回 Unix 时间戳（使用 strtotime()）或者 DateTimeImmutable 对象（使用 DateTimeImmutable::__construct()），而是返回包含在指定 `datetime` 字符串中检测到相关信息的关联数组。

如果找不到某组元素的信息，那么这些数组元素将会设置为 `false` 或缺失。如果需要从相同的 `datetime` 字符串构建时间戳或者 DateTimeImmutable 对象，需要将更多字段设置为非 `false` 值。查看以下示例以了解情况。

### 参数

`datetime`

  DateTimeImmutable::__construct() 接受的日期/时间格式。

### 返回值

返回 array，包含解析日期/时间的信息。

返回的数组存在以下键 `year`、`month`、`day`、`hour`、`minute`、`second`、`fraction` 和 `is_localtime`。

如果存在 `is_localtime`，则 `zone_type` 表示时区类型。类型 `1`（UTC 时差），添加 `zone`、`is_dst`；类型 `2`（时区缩写），添加 `tz_abbr`、`is_dst`；类型 `3`（时区标识符），添加 `tz_abbr`、`tz_id`。

如果 `datetime` 字符串存在类似 `+3 days` 这样的相对时间元素，则返回的数组则包含键为 `relative` 的嵌套数组。然后此数组将包含如下键 `year`、`month`、`day`、`hour`、`minute`、`second`，如果必要还会包含 `weekday` 和 `weekdays`，具体取决于传入的字符串。

数组包含 `warning_count` 和 `warnings` 字段。第一个表示发现了多少警告。元素 `warnings` 的键表示指定 `datetime` 发生警告的位置，值为字符串，描述警告本身。

数组也包含 `error_count` 和 `errors` 字段。第一个表示发现了多少错误。元素 `errors` 的键表示指定 `datetime` 发生错误的位置，值为字符串，描述错误本身。

警告

如果同一个位置存在多个警告/错误，那么 `warnings` 和 `errors` 数组中元素的数量可能会少于 `warning_count` 或者 `error_count`。

### 错误／异常

date/time 的格式有错误时，返回数组的 'errors' 键将包含错误信息。

### 更新日志

版本 | 说明
--- | ---
7.2.0 | 返回数组的 `zone` 键现在代表秒，而不是分钟。并且正负符号已反转，例如：之前是 `-120` 现在是 `7200`。

### 示例

示例 #1 具有全面的 `datetime` 字符串的 date_parse() 示例

    <?php
    var_dump(date_parse("2006-12-12 10:00:00.5"));

以上示例会输出：

    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)
    }

如果在指定 `datetime` 字符串中出现时区元素，那才会展示。在这种情况下，总会存在 `zone_type` 和更多元素，具体取决于其值。

示例 #2 带时区缩写信息的 date_parse()

    <?php
    var_dump(date_parse("June 2nd, 2022, 10:28:17 BST"));

以上示例会输出：

    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"
    }

示例 #3 带时区标识符信息的 date_parse()

    <?php
    var_dump(date_parse("June 2nd, 2022, 10:28:17 Europe/London"));

以上示例会输出：

    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"
    }

如果解析的 `datetime` 字符串越小，那么可用的信息就越少。再本示例中，所有时间部分都返回为 `false`。

示例 #4 带最小字符串的 date_parse()

    <?php
    var_dump(date_parse("June 2nd, 2022"));

以上示例会输出：

    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”元素。

示例 #5 带相对格式的 date_parse()

    <?php
    var_dump(date_parse("2006-12-12 10:00:00.5 +1 week +1 hour"));

以上示例会输出：

    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)
      }
    }

在某些时候，比如 `Thursday` 将会设置字符串的时间部分设置为 `0`。如果 `Thursday` 传递给 DateTimeImmutable::__construct() 也会导致小时，分钟，秒和小数部分设置为 `0`。下面的示例中，year 元素将设置为 `false`。

示例 #6 带副作用的 date_parse()

    <?php
    var_dump(date_parse("Thursday, June 2nd"));

以上示例会输出：

    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)
      }
    }

### 参见

- date_parse_from_format() - Get info about given date formatted according to the specified format，以解析具有特定格式的`datetime`
- checkdate() - 验证一个格里高里日期，以便于公历日期验证
- getdate() - 获取日期/时间信息

# date_parse_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_parse_from_format — Get info about given date formatted according to the specified format

### 说明

function date_parse_from_format(string `$format`, string `$datetime`): array

Returns associative array with detailed info about given date/time.

### 参数

`format`

  Documentation on how the `format` is used, please refer to the documentation of DateTimeImmutable::createFromFormat(). The same rules apply.

`datetime`

  String representing the date/time.

### 返回值

Returns associative array with detailed info about given date/time.

The returned array has keys for `year`, `month`, `day`, `hour`, `minute`, `second`, `fraction`, and `is_localtime`.

If `is_localtime` is present then `zone_type` indicates the type of timezone. For type `1` (UTC offset) the `zone`, `is_dst` fields are added; for type `2` (abbreviation) the fields `tz_abbr`, `is_dst` are added; and for type `3` (timezone identifier) the `tz_abbr`, `tz_id` are added.

The array includes `warning_count` and `warnings` fields. The first one indicate how many warnings there were. The keys of elements `warnings` array indicate the position in the given `datetime` where the warning occurred, with the string value describing the warning itself. An example below shows such a warning.

The array also contains `error_count` and `errors` fields. The first one indicate how many errors were found. The keys of elements `errors` array indicate the position in the given `datetime` where the error occurred, with the string value describing the error itself. An example below shows such an error.

警告

The number of array elements in the `warnings` and `errors` arrays might be less than `warning_count` or `error_count` if they occurred at the same position.

### 错误／异常

This functions throws ValueError when the `datetime` contains NULL-bytes.

### 更新日志

版本 | 说明
--- | ---
8.0.21, 8.1.8, 8.2.0 | Now throws ValueError when NULL-bytes are passed into `datetime`, which previously was silently ignored.
7.2.0 | The `zone` element of the returned array represents seconds instead of minutes now, and its sign is inverted. For instance `-120` is now `7200`.

### 示例

示例 #1 date_parse_from_format() example

    <?php
    $date = "6.1.2009 13:00+01:00";
    print_r(date_parse_from_format("j.n.Y H:iP", $date));

以上示例会输出：

    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] =>
    )

示例 #2 date_parse_from_format() with warnings example

    <?php
    $date = "26 August 2022 22:30 pm";
    $parsed = date_parse_from_format("j F Y G:i a", $date);

    echo "Warnings count: ", $parsed['warning_count'], "\n";
    foreach ($parsed['warnings'] as $position => $message) {
        echo "\tOn position {$position}: {$message}\n";
    }

以上示例会输出：

    Warnings count: 1
    	On position 23: The parsed time was invalid

示例 #3 date_parse_from_format() with errors example

    <?php
    $date = "26 August 2022 CEST";
    $parsed = date_parse_from_format("j F Y H:i", $date);

    echo "Errors count: ", $parsed['error_count'], "\n";
    foreach ($parsed['errors'] as $position => $message) {
        echo "\tOn position {$position}: {$message}\n";
    }

以上示例会输出：

    Errors count: 3
    	On position 15: A two digit hour could not be found
    	On position 19: Not enough data available to satisfy format

### 参见

- DateTimeImmutable::createFromFormat() - Parses a time string according to a specified format
- checkdate() - 验证一个格里高里日期

# date_sub

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_sub — 别名 DateTime::sub()

### 说明

此函数是该函数的别名： DateTime::sub()

### 参见

- DateTimeImmutable::sub() - Subtracts an amount of days, months, years, hours, minutes and seconds
- DateTime::sub() - 对 DateTime 对象减去一定量的日、月、年、小时、分钟和秒。

# date_sun_info

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

date_sun_info — Returns an array with information about sunset/sunrise and twilight begin/end

### 说明

function date_sun_info(int `$timestamp`, float `$latitude`, float `$longitude`): array

### 参数

`timestamp`

  Unix timestamp.

`latitude`

  Latitude in degrees.

`longitude`

  Longitude in degrees.

### 返回值

Returns an array whose structure is detailed in the following list:

`sunrise`
  The timestamp of the sunrise (zenith angle = 90°35').
`sunset`
  The timestamp of the sunset (zenith angle = 90°35').
`transit`
  The timestamp when the sun is at its zenith, i.e. has reached its topmost point.
`civil_twilight_begin`
  The start of the civil dawn (zenith angle = 96°). It ends at `sunrise`.
`civil_twilight_end`
  The end of the civil dusk (zenith angle = 96°). It starts at `sunset`.
`nautical_twilight_begin`
  The start of the nautical dawn (zenith angle = 102°). It ends at `civil_twilight_begin`.
`nautical_twilight_end`
  The end of the nautical dusk (zenith angle = 102°). It starts at `civil_twilight_end`.
`astronomical_twilight_begin`
  The start of the astronomical dawn (zenith angle = 108°). It ends at `nautical_twilight_begin`.
`astronomical_twilight_end`
  The end of the astronomical dusk (zenith angle = 108°). It starts at `nautical_twilight_end`.

The values of the array elements are either UNIX timestamps, `false` if the sun is below the respective zenith for the whole day, or `true` if the sun is above the respective zenith for the whole day.

### 更新日志

版本 | 说明
--- | ---
7.2.0 | The calculation was fixed with regards to local midnight instead of local noon, which changes the results slightly.

### 示例

示例 #1 A date_sun_info() example

    <?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";
    }

以上示例会输出：

    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

示例 #2 Polar night, with some processing

    <?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";
    }

以上示例会输出：

    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

示例 #3 Midnight sun (Tromsø, Norway)

    <?php
    $si = date_sun_info(strtotime("2022-06-26"), 69.68, 18.94);
    print_r($si);

以上示例会输出：

    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
    )

示例 #4 Calculating length of day (Kyiv)

    <?php
    $si = date_sun_info(strtotime('2022-08-26'), 50.45, 30.52);
    $diff = $si['sunset'] - $si['sunrise'];
    echo "Length of day: ",
        floor($diff / 3600), "h ",
        floor(($diff % 3600) / 60), "s\n";

以上示例会输出：

    Length of day: 13h 56s

# date_sunrise

(PHP 5, PHP 7, PHP 8)

date_sunrise — 返回给定的日期与地点的日出时间

警告

该函数自 PHP 8.1.0 起弃用。强烈建议不要依赖此函数。请改用 date_sun_info()。

### 说明

#[\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() 返回给定的日期（以 `timestamp` 指定）与地点的日出时间。

### 参数

`timestamp`

  取 `timestamp`所在日期的日出时间。

`returnFormat`

  `returnFormat` 常量
  常量 | 说明 | 取值举例
  --- | --- | ---
  SUNFUNCS_RET_STRING | 以 string 格式返回结果 | 16:46
  SUNFUNCS_RET_DOUBLE | 以 float 格式返回结果 | 16.78243132
  SUNFUNCS_RET_TIMESTAMP | 以 int 格式（时间戳）返回结果 | 1095034606

`latitude`

  默认是指北纬。因此如果要指定南纬，必须传递一个负值。 参见 date.default_latitude

`longitude`

  默认是指东经。因此如果要指定西经，必须传递一个负值。 参见 date.default_longitude

`zenith`

  `zenith` is the angle between the center of the sun and a line perpendicular to earth's surface. It defaults to date.sunrise_zenith

  Common `zenith` angles
  Angle | Description
  --- | ---
  90°50' | Sunrise: the point where the sun becomes visible.
  96° | Civil twilight: conventionally used to signify the start of dawn.
  102° | Nautical twilight: the point at which the horizon starts being visible at sea.
  108° | Astronomical twilight: the point at which the sun starts being the source of any illumination.

`utcOffset`

  单位是小时。 The `utcOffset` is ignored, if `returnFormat` is `SUNFUNCS_RET_TIMESTAMP`.

### 返回值

按指定格式 `returnFormat` 返回的日出时间， 或者在失败时返回 `false`。 One potential reason for failure is that the sun does not rise at all, which happens inside the polar circles for part of the year.

### 错误／异常

在每次调用日期/时间函数时，如果时区无效则会引发 `E_NOTICE` 错误。参见 date_default_timezone_set()。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 此函数已弃用，请改用 date_sun_info()。
8.0.0 | `latitude`、`longitude`、`zenith` 和 `utcOffset` 现在可为 null。

### 示例

示例 #1 date_sunrise() 示例

    <?php

    /* 计算葡萄牙里斯本的日出时间
    Latitude:  北纬 38.4 度
    Longitude: 西经 9 度
    Zenith ~= 90
    offset: +1 GMT
    */

    echo date("D M d Y"). ', sunrise time : ' .date_sunrise(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1);

以上示例的输出类似于：

    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

示例 #2 No sunrise

    <?php
    $solstice = strtotime('2017-12-21');
    var_dump(date_sunrise($solstice, SUNFUNCS_RET_STRING, 69.245833, -53.537222));

以上示例会输出：

    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)

### 参见

- date_sun_info() - Returns an array with information about sunset/sunrise and twilight begin/end

# date_sunset

(PHP 5, PHP 7, PHP 8)

date_sunset — 返回给定的日期与地点的日落时间

警告

该函数自 PHP 8.1.0 起弃用。强烈建议不要依赖此函数。请改用 date_sun_info()。

### 说明

#[\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() 返回给定的日期（以 `timestamp` 指定）与地点的日落时间。

### 参数

`timestamp`

  返回给定的日期（以 `timestamp` 指定）的日落时间。

`returnFormat`

  `returnFormat` 常量
  常量 | 说明 | 取值举例
  --- | --- | ---
  SUNFUNCS_RET_STRING | 以 string 格式返回结果 | 16:46
  SUNFUNCS_RET_DOUBLE | 以 float 格式返回结果 | 16.78243132
  SUNFUNCS_RET_TIMESTAMP | 以 int 格式（时间戳）返回结果 | 1095034606

`latitude`

  默认是指北纬。因此如果要指定南纬，必须传递一个负值。参见：date.default_latitude

`longitude`

  默认是指东经。因此如果要指定西经，必须传递一个负值。参见：date.default_longitude

`zenith`

  `zenith` is the angle between the center of the sun and a line perpendicular to earth's surface. It defaults to date.sunrise_zenith

  Common `zenith` angles
  Angle | Description
  --- | ---
  90°50' | Sunrise: the point where the sun becomes visible.
  96° | Civil twilight: conventionally used to signify the start of dawn.
  102° | Nautical twilight: the point at which the horizon starts being visible at sea.
  108° | Astronomical twilight: the point at which the sun starts being the source of any illumination.

`utcOffset`

  单位是小时。 The `utcOffset` is ignored, if `returnFormat` is `SUNFUNCS_RET_TIMESTAMP`.

### 返回值

用指定的格式 `returnFormat` 返回日落时间， 或者在失败时返回 `false`。 One potential reason for failure is that the sun does not rise at all, which happens inside the polar circles for part of the year.

### 错误／异常

在每次调用日期/时间函数时，如果时区无效则会引发 `E_NOTICE` 错误。参见 date_default_timezone_set()。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 此函数已弃用，请改用 date_sun_info()。
8.0.0 | `latitude`, `longitude`, `zenith` and `utcOffset` are nullable now.

### 示例

示例 #1 date_sunset() 示例

    <?php

    /* calculate the sunset time for Lisbon, Portugal
    Latitude: 38.4 North
    Longitude: 9 West
    Zenith ~= 90
    offset: +1 GMT
    */

    echo date("D M d Y"). ', sunset time : ' .date_sunset(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1);

以上示例的输出类似于：

    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

示例 #2 No sunrise

    <?php
    $solstice = strtotime('2017-12-21');
    var_dump(date_sunset($solstice, SUNFUNCS_RET_STRING, 69.245833, -53.537222));

以上示例会输出：

    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)

### 参见

- date_sun_info() - Returns an array with information about sunset/sunrise and twilight begin/end

# date_time_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_time_set — 别名 DateTime::setTime()

### 说明

此函数是该函数的别名： DateTime::setTime()

# date_timestamp_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_timestamp_get — 别名 DateTime::getTimestamp()

### 说明

此函数是该函数的别名： DateTime::getTimestamp()

# date_timestamp_set

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_timestamp_set — 别名 DateTime::setTimestamp()

### 说明

此函数是该函数的别名： DateTime::setTimestamp()

# date_timezone_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_timezone_get — 别名 DateTime::getTimezone()

### 说明

此函数是该函数的别名： DateTime::getTimezone()

# date_timezone_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_timezone_set — 别名 DateTime::setTimezone()

### 说明

此函数是该函数的别名： DateTime::setTimezone()

# getdate

(PHP 4, PHP 5, PHP 7, PHP 8)

getdate — 获取日期/时间信息

### 说明

function getdate(?int `$timestamp` = `null`): array

返回关联 array，包含 `timestamp` 或者当前本地时间（如果省略 `timestamp` 或为 `null`）的日期信息。

### 参数

`timestamp`
  可选的 `timestamp` 参数是一个 int 的 Unix 时间戳，如未指定或是 `null`，参数值默认为当前本地时间。也就是说，其值默认为 time() 的返回值。

### 返回值

返回关联 array，包含 `timestamp` 相关信息。返回的关联数组中的元素如下：

返回的关联数组中的键元素
键名 | 说明 | 返回值示例
--- | --- | ---
`"seconds"` | 秒的数字表示 | `0` 到 `59`
`"minutes"` | 分钟的数字表示 | `0` 到 `59`
`"hours"` | 小时的数字表示 | `0` 到 `23`
`"mday"` | 月份中第几天的数字表示 | `1` 到 `31`
`"wday"` | 星期几的数字表示 | `0`（周日）到 `6`（周六）
`"mon"` | 月份的数字表示 | `1` 到 `12`
`"year"` | 4 位数字表示的完整年份 | 比如： `1999` 或 `2003`
`"yday"` | 一年中第几天的数字表示 | `0` 到 `365`
`"weekday"` | 星期几的完整文本表示 | `Sunday` 到 `Saturday`
`"month"` | 月份的完整文本表示，比如 January 或 March | `January` 到 `December`
`0` | 自从 Unix 纪元开始至今的秒数，和 time() 的返回值以及用于 date() 的值类似。 | 系统相关，通常从 `-2147483648` 到 `2147483647`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `timestamp` 允许为 null。

### 示例

示例 #1 getdate() 示例

    <?php
    $today = getdate();
    print_r($today);

以上示例的输出类似于：

    Array
    (
        [seconds] => 40
        [minutes] => 58
        [hours] => 21
        [mday] => 17
        [wday] => 2
        [mon] => 6
        [year] => 2003
        [yday] => 167
        [weekday] => Tuesday
        [month] => June
        [0] => 1055901520
    )

### 参见

- date() - 格式化 Unix 时间戳
- idate() - 将本地日期/时间格式化为整数
- localtime() - 取得本地时间
- time() - 返回当前的 Unix 时间戳
- setlocale() - 设置区域信息

# gettimeofday

(PHP 4, PHP 5, PHP 7, PHP 8)

gettimeofday — 取得当前时间

### 说明

function gettimeofday(bool `$as_float` = `false`): array|float

本函数是 gettimeofday(2) 的接口。返回一个关联数组，包含有系统调用返回的数据。

### 参数

`as_float`

  当其设为 `true` 时，会返回浮点数而不是数组。

### 返回值

默认返回 array。如果设置了 `as_float` 则会返回 float。

数组中的键为：

- "sec" - 自 Unix 纪元起的秒数
- "usec" - 微秒数
- "minuteswest" - 格林威治向西的分钟数
- "dsttime" - 夏令时修正的类型

### 示例

示例 #1 gettimeofday() 示例

    <?php
    print_r(gettimeofday());

    echo gettimeofday(true);

以上示例的输出类似于：

    Array
    (
        [sec] => 1073504408
        [usec] => 238215
        [minuteswest] => 0
        [dsttime] => 1
    )
    1073504408.23910

# gmdate

(PHP 4, PHP 5, PHP 7, PHP 8)

gmdate — 格式化 GMT/UTC 日期／时间

### 说明

function gmdate(string `$format`, ?int `$timestamp` = `null`): string

同 date() 函数一样，只是返回的时间是格林威治标准时（GMT）。

### 参数

`format`

  输出日期 string 的格式。参阅 date() 函数格式化选项。

`timestamp`
  可选的 `timestamp` 参数是一个 int 的 Unix 时间戳，如未指定或是 `null`，参数值默认为当前本地时间。也就是说，其值默认为 time() 的返回值。

### 返回值

返回格式化的日期字符串。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `timestamp` 允许为 null。

### 示例

示例 #1 gmdate() 示例

    <?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));

以上示例会输出：

    Jan 01 1998 00:00:00 Europe/Helsinki
    Dec 31 1997 22:00:00 UTC

### 参见

- DateTimeImmutable::__construct() - Returns new DateTimeImmutable object
- DateTimeInterface::format() - 按照指定格式返回格式化后的日期
- date() - 格式化 Unix 时间戳
- mktime() - 取得一个日期的 Unix 时间戳
- gmmktime() - 取得 GMT 日期的 UNIX 时间戳
- IntlDateFormatter::format() - Format the date/time value as a string

# gmmktime

(PHP 4, PHP 5, PHP 7, PHP 8)

gmmktime — 取得 GMT 日期的 UNIX 时间戳

### 说明

function gmmktime(
int `$hour`,
?int `$minute` = `null`,
?int `$second` = `null`,
?int `$month` = `null`,
?int `$day` = `null`,
?int `$year` = `null`
): int|false

和 mktime() 相同，但传递的参数是 GMT 日期。 gmmktime() internally uses mktime() so only times valid in derived local time can be used.

和 mktime() 一样，可选参数可以从右到左的顺序省略，省略的参数会被设为当前对应的 GMT 值。

不再支持不带参数调用 gmmktime()，并会导致 ArgumentCountError。 time() 可用于获取当前时间戳。

### 参数

`hour`

  相对于一天开始的小时数，由 `month`、`day` 和 `year` 确定。负值是指当天零点前的小时。值大于 23 是指接下来几天的适当小时。

`minute`

  相对于 `hour` 开始的分钟数。负值指的是上个小时的分钟。大于 59 的值将指向接下来几个小时的适当分钟。

`second`

  相对于 `minute` 开始的秒数。负值是指前一分钟的秒数。大于 59 的值是指接下来几分钟的适当秒。

`month`

  相对于去年年底的月份数。值 1 到 12 是指相关年份的正常日历月份。小于 1 的值（包括负值）按相反的顺序指向去年的月份，因此 0 是 12 月，-1 是 11 月，以此类推。值大于 12 是指接下来几年的适当月份。

`day`

  相对于上个月月底的天数。值 1 到 28、29、30 或 31（取决于月份）是指相关月份的正常天数。小于 1 的值（包括负值）是指上个月的天数，因此 0 是上个月的最后一天，-1 是倒数第二天，以此类推。大于相关月份天数的值是指接下来几个月的适当某一天。

`year`

  年份

### 返回值

成功时返回 int Unix 时间戳，如果时间戳不适合 PHP 整数则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `hour` 不再可选。如果需要获取 Unix 时间戳，可以使用 time()。
8.0.0 | 现在 `minute`、`second`、`month`、`day` 和 `year` 可以为 null。

### 示例

示例 #1 gmmktime() 基础示例

    <?php
    date_default_timezone_set("Indian/Maldives");

    echo "July 1, 2000 is on a " . date("l", gmmktime(0, 0, 0, 7, 1, 2000));

以上示例会输出：

    July 1, 2000 is on a Saturday

### 参见

- DateTimeImmutable 类
- mktime() - 取得一个日期的 Unix 时间戳
- date() - 格式化 Unix 时间戳
- time() - 返回当前的 Unix 时间戳

# gmstrftime

(PHP 4, PHP 5, PHP 7, PHP 8)

gmstrftime — 根据区域设置格式化 GMT/UTC 时间/日期

警告

该函数自 PHP 8.1 起弃用。强烈建议不要依赖此函数。

此函数可以使用如下替代：

- gmdate()
- IntlDateFormatter::format()

### 说明

#[\Deprecated]
function gmstrftime(string `$format`, ?int `$timestamp` = `null`): string|false

行为和 strftime() 相同，只是返回的时间是格林威治标准时（GMT）。例如，在东部标准时（EST，GMT -0500）运行时，下面第一行显示“Dec 31 1998 20:00:00”，而第二行显示“Jan 01 1999 01:00:00”。

警告

此函数依赖于操作系统区域设置信息，这些信息可能彼此不一致，或者根本不能用。而是使用 IntlDateFormatter::format() 方法。

### 参数

`format`

  See description in strftime().

`timestamp`
  可选的 `timestamp` 参数是一个 int 的 Unix 时间戳，如未指定或是 `null`，参数值默认为当前本地时间。也就是说，其值默认为 time() 的返回值。

### 返回值

根据指定的格式字符串使用指定的 `timestamp` 或当前本地时间（若未提供时间戳）返回格式化的字符串。月份、星期名称及其他与语言相关的字符串遵循通过 setlocale() 设置的当前区域。失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `timestamp` 允许为 null。

### 示例

示例 #1 gmstrftime() 示例

    <?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";

### 参见

- IntlDateFormatter::format() - Format the date/time value as a string
- DateTimeInterface::format() - 按照指定格式返回格式化后的日期
- strftime() - 根据区域设置格式化本地时间/日期

# idate

(PHP 5, PHP 7, PHP 8)

idate — 将本地日期/时间格式化为整数

### 说明

function idate(string `$format`, ?int `$timestamp` = `null`): int|false

使用明确的 int 类型 `timestamp` 或者当前本地时间（如果没有明确时间戳），根据明确的格式化字符串返回格式化后的数字。换句话说，`timestamp` 是可选的，默认值是 time() 的值。

跟 date() 不同，idate() 只接受一个字符作为 `format` 的参数。

### 参数

`format`

  `format` 参数字符串仅识别以下字符
  `format` 字符 | 说明
  --- | ---
  `B` | Swatch Beat/互联网时间
  `d` | 月份中的第几天
  `h` | 小时（12 小时制）
  `H` | 小时（24 小时制）
  `i` | 分钟
  `I`（大写 i） | 如果启用夏令时则返回 `1`，否则返回 `0`
  `L`（大写 l） | 如果是闰年则返回 `1`，否则返回 `0`
  `m` | 月份的数字
  `N` | ISO-8601 格式的周几（`1` 表示周一到 `7` 表示周日）
  `o` | ISO-8601 格式的年份（4位）
  `s` | 秒数
  `t` | 本月的总天数
  `U` | 自 Unix 纪元（January 1 1970 00:00:00 GMT）起的秒数——这和 time() 相同
  `w` | 周几（`0` 是周日）
  `W` | ISO-8601 格式的年份中第几个星期，每星期从星期一开始
  `y` | 年份（1 或 2 位数字——见下面说明）
  `Y` | 年份（4 位数字）
  `z` | 年份中的第几天
  `Z` | 以秒为单位的时差

`timestamp`
  可选的 `timestamp` 参数是一个 int 的 Unix 时间戳，如未指定或是 `null`，参数值默认为当前本地时间。也就是说，其值默认为 time() 的返回值。

### 返回值

成功时返回 int， 或者在失败时返回 `false`。

由于 idate() 始终返回不以“0”开头的 int，因此 idate() 返回的数字可能位数要比期望的小。查看以下示例。

### 错误／异常

在每次调用日期/时间函数时，如果时区无效则会引发 `E_NOTICE` 错误。参见 date_default_timezone_set()。

### 更新日志

版本 | 说明
--- | ---
8.2.0 | 添加 `N`（ISO-8601 格式的周几）和 `o`（ISO-8601 格式的年份）格式字符。
8.0.0 | 现在 `timestamp` 允许为 null。

### 示例

示例 #1 idate() 示例

    <?php
    $timestamp = strtotime('1st January 2004'); // 1072915200

    // 下面以两位数字格式打印年份，但是因为
    // 以“0”打头，因此只会打印“4”
    echo idate('y', $timestamp) . "\n";

    $timestamp = strtotime('1st January 2024'); // 1704067200
    echo idate('y', $timestamp);

以上示例会输出：

    4
    24

### 参见

- DateTimeInterface::format() - 按照指定格式返回格式化后的日期
- date() - 格式化 Unix 时间戳
- getdate() - 获取日期/时间信息
- time() - 返回当前的 Unix 时间戳

# localtime

(PHP 4, PHP 5, PHP 7, PHP 8)

localtime — 取得本地时间

### 说明

function localtime(?int `$timestamp` = `null`, bool `$associative` = `false`): array

localtime() 函数返回和 C 函数调用返回的结构相同数组。

### 参数

`timestamp`
  可选的 `timestamp` 参数是一个 int 的 Unix 时间戳，如未指定或是 `null`，参数值默认为当前本地时间。也就是说，其值默认为 time() 的返回值。
`associative`

  确定函数应该返回常规的数字索引数组还是关联数组。

### 返回值

如果 `associative` 设为 `false` 或未提供则返回的是普通的数字索引数组。如果 `associative` 设为 `true` 则 localtime() 返回关联数组，其中包含所有从 C 函数调用 localtime 结构元素。关联数组中键如下：

- "tm_sec" - 秒数，`0` 到 `59`
- "tm_min" - 分钟数，`0` 到 `59`
- "tm_hour" - 小时，`0` 到 `23`
- "tm_mday" - 月份中的第几日，`1` 到 `31`
- "tm_mon" - 年份中的第几个月，`0` (Jan) 到 `11` (Dec)
- "tm_year" - 年份，从 1900 开始
- "tm_wday" - 星期中的第几天，`0` (Sun) 到 `6` (Sat)
- "tm_yday" - 一年中的第几天，`0` 到 `365`
- "tm_isdst" - 夏令时当前是否生效？ 如果是生效的是正数， `0` 代表未生效，负数代表未知。

### 错误／异常

在每次调用日期/时间函数时，如果时区无效则会引发 `E_NOTICE` 错误。参见 date_default_timezone_set()。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `timestamp` 可为 null。

### 示例

示例 #1 localtime() 示例

    <?php
    $localtime = localtime();
    $localtime_assoc = localtime(time(), true);
    print_r($localtime);
    print_r($localtime_assoc);

以上示例的输出类似于：

    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
    )

### 参见

- getdate() - 获取日期/时间信息

# microtime

(PHP 4, PHP 5, PHP 7, PHP 8)

microtime — 返回当前 Unix 时间戳和微秒数

### 说明

function microtime(bool `$as_float` = `false`): string|float

microtime() 返回当前 Unix 时间戳以及微秒数。本函数仅在支持 gettimeofday() 系统调用的操作系统下可用。

对于性能测量，建议使用 hrtime()。

### 参数

`as_float`

  如果使用并设置为 `true`，microtime() 将返回浮点数而不是字符串，具体查看下面的返回值相关描述。

### 返回值

默认情况下，microtime() 返回“msec sec”形式的 string，其中 `sec` 是自 Unix 纪元（格林威治标准时间 1970 年 1 月 1 日 0:00:00）以来的秒数，`msec` 是自 `sec` 以来经过的微秒，表示为秒数的小数部分。

如果 `as_float` 设置为 `true`，然后 microtime() 返回 float，表示自 Unix 纪元以来的当前时间，以秒为单位，精确到最接近的微秒。

### 示例

示例 #1 计时脚本执行时间

    <?php
    $time_start = microtime(true);

    // Sleep 一会
    usleep(10_000);

    $time_end = microtime(true);
    $time = $time_end - $time_start;

    print "Did nothing in $time seconds\n";
    ?>

示例 #2 microtime() 和 `REQUEST_TIME_FLOAT`

    <?php
    // 随机 sleep 时间
    usleep(random_int(10_000, 1_000_000));

    // 在 $_SERVER 超全局数组中 REQUEST_TIME_FLOAT 是有效的。
    // 包含请求开始的时间戳，精度为微秒。
    $time = microtime(true) - $_SERVER["REQUEST_TIME_FLOAT"];

    echo "Did nothing in $time seconds\n";

### 参见

- time() - 返回当前的 Unix 时间戳
- hrtime() - 获取系统的高精度时间

# mktime

(PHP 4, PHP 5, PHP 7, PHP 8)

mktime — 取得一个日期的 Unix 时间戳

### 说明

function mktime(
int `$hour`,
?int `$minute` = `null`,
?int `$second` = `null`,
?int `$month` = `null`,
?int `$day` = `null`,
?int `$year` = `null`
): int|false

根据给出的参数返回 Unix 时间戳。时间戳是一个长整数，包含了从 Unix 纪元（January 1 1970 00:00:00 GMT）到给定时间的秒数。

任何可选或为 `null` 的参数都将根据本地日期和时间设置为当前值。

警告

请注意，参数的顺序是很奇怪：`month`、`day`、`year`，而不是更合理的 `year`、`month`、`day` 顺序。

不带参数调用 mktime() 已经不受支持，会导致 ArgumentCountError。 time() 可以用来获取当前时间戳。

### 参数

`hour`

  相对于一天开始的小时数，由 `month`、`day` 和 `year` 确定。负值是指当天零点前的小时。值大于 23 是指接下来几天的适当小时。

`minute`

  相对于 `hour` 开始的分钟数。负值指的是上个小时的分钟。大于 59 的值将指向接下来几个小时的适当分钟。

`second`

  相对于 `minute` 开始的秒数。负值是指前一分钟的秒数。大于 59 的值是指接下来几分钟的适当秒。

`month`

  相对于去年年底的月份数。值 1 到 12 是指相关年份的正常日历月份。小于 1 的值（包括负值）按相反的顺序指向去年的月份，因此 0 是 12 月，-1 是 11 月，以此类推。值大于 12 是指接下来几年的适当月份。

`day`

  相对于上个月月底的天数。值 1 到 28、29、30 或 31（取决于月份）是指相关月份的正常天数。小于 1 的值（包括负值）是指上个月的天数，因此 0 是上个月的最后一天，-1 是倒数第二天，以此类推。大于相关月份天数的值是指接下来几个月的适当某一天。

`year`

  年份数，可以是两位或四位数字，0-69 对应于 2000-2069，70-100 对应于 1970-2000。在如今系统中普遍把 time_t 作为一个 32 位有符号整数的情况下，`year` 的合法范围是 1901 到 2038 之间。

### 返回值

mktime() 根据给出的参数返回 Unix 时间戳，如果时间戳不适合 PHP 整数则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `hour` 不再可选。如果需要 Unix 时间戳，可以使用 time()。
8.0.0 | 现在 `minute`、`second`、`month`、`day` 和 `year` 允许为 null。

### 示例

示例 #1 基本示例

    <?php
    // 设置使用的默认时区。
    date_default_timezone_set('UTC');

    // 打印：July 1, 2000 is on a Saturday
    echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000)) . "\n";

    // 打印类似的东西：2006-04-05T01:02:03+00:00
    echo date('c', mktime(1, 2, 3, 4, 5, 2006)) . "\n";
    ?>

以上示例的输出类似于：

    July 1, 2000 is on a Saturday
    2006-04-05T01:02:03+00:00

示例 #2 mktime() 示例

mktime() 在做日期计算和验证方面很有用，它会自动计算超出范围的输入的正确值。例如下面示例中每一行都会产生字符串 "Jan-01-1998"。

    <?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";

以上示例的输出类似于：

    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

示例 #3 使用 mktime 查找相对日期

    <?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";

以上示例的输出类似于：

    2025-09-30T00:00:00+09:00
    2025-08-29T00:00:00+09:00
    2026-09-29T00:00:00+09:00

> 注意:

> 由于夏令时的存在，这种方法比简单地对时间戳加减一天或一个月的秒数更加可靠。

示例 #4 下个月的最后一天

任何给定月份的最后一天都可以被表示为下个月的第 "0" 天，而不是 -1 天。下面两个示例都会产生字符串 "The last day in Feb 2000 is: 29"。

    <?php

    $lastday = mktime(0, 0, 0, 3, 0, 2000);
    echo 'Last day in Feb 2000 is: ', date('d', $lastday) . "\n";

    $lastday = mktime(0, 0, 0, 4, -31, 2000);
    echo 'Last day in Feb 2000 is: ', date('d', $lastday) . "\n";

以上示例会输出：

    Last day in Feb 2000 is: 29
    Last day in Feb 2000 is: 29

### 参见

- DateTimeImmutable 类
- checkdate() - 验证一个格里高里日期
- gmmktime() - 取得 GMT 日期的 UNIX 时间戳
- date() - 格式化 Unix 时间戳
- time() - 返回当前的 Unix 时间戳

# strftime

(PHP 4, PHP 5, PHP 7, PHP 8)

strftime — 根据区域设置格式化本地时间/日期

警告

该函数自 PHP 8.1 起弃用。强烈建议不要依赖此函数。

此函数可以使用如下替代：

- date()
- IntlDateFormatter::format()

### 说明

#[\Deprecated]
function strftime(string `$format`, ?int `$timestamp` = `null`): string|false

返回用给定的格式字串对给出的 `timestamp` 进行格式输出后的字符串。如果没有给出时间戳则用当前的本地时间。月份和星期几以及其它和语言有关的字符串写法和用 setlocale() 设定的当前的区域有关。

警告

可能不是所有的转换标记都被 C 库文件支持，这种情况下 PHP 的 strftime() 也不支持。此外，不是所有的平台都支持负的时间戳，因此日期的范围可能限定在不早于 Unix 纪元。这意味着例如 %e, %T，%R 和 %D（可能更多）以及早于 `Jan 1, 1970` 的时间在 Windows，一些 Linux 发行版本，以及其它几个操作系统中无效。对于 Windows 系统，所支持的转换标记可在 » MSDN 网站找到。 Instead use the IntlDateFormatter::format() method.

### 参数

`format`

  `format` 里能够识别的格式字串有以下标记：
  `格式` | 描述 | 返回值示例
  --- | --- | ---
  日 | --- | ---
  `%a` | 当前区域星期几的简写 | `Sun` 到 `Sat`
  `%A` | 当前区域星期几的全称 | `Sunday` 到 `Saturday`
  `%d` | 月份中的第几天，十进制数字（范围从 01 到 31） | `01` 到 `31`
  `%e` | 月份中的第几天，十进制数字，一位的数字前会加上一个空格（范围从 ' 1' 到 '31'） 在 Windows 上尚未按描述实现。更多信息见下方。 | `1` 到 `31`
  `%j` | 年份中的第几天，带前导零的三位十进制数（范围从 001 到 366） | `001` 到 `366`
  `%u` | 符合 ISO-8601 星期几的十进制数表达 [1,7]，1 表示星期一 | `1` (星期一) 到 `7` (星期日)
  `%w` | 星期中的第几天，星期天为 0 | `0` (星期天) 到 `6` (星期六)
  周 | --- | ---
  `%U` | 本年的第几周，从第一周的第一个星期天作为第一天开始 | `13` (for the 13th full week of the year)
  `%V` | %V - 本年第几周的 ISO-8601:1988 格式，范围从 01 到 53，第 1 周是本年第一个至少还有 4 天的星期，星期一作为每周的第一天。（用 %G 或者 %g 作为指定时间戳相应周数的年份组成。） | `01` 到 `53` (where 53 accounts for an overlapping week)
  `%W` | 本年的第几周数，从第一周的第一个星期一作为第一天开始 | `46` (for the 46th week of the year beginning with a Monday)
  月 | --- | ---
  `%b` | 当前区域月份的简写 | `Jan` 到 `Dec`
  `%B` | 当前区域月份的全称 | `January` 到 `December`
  `%h` | 当前区域月份的简写（%b 的别名） | `Jan` 到 `Dec`
  `%m` | 两位数的月份 | `01` (是一月份) 到 `12` (是十二月份)
  年 | --- | ---
  `%C` | 两位数显示世纪（年份除以 100，截成整数） | `19` 是 20 世纪
  `%g` | 2 位数的年份，符合 ISO-8601:1988 星期数（参见 %V）。和 %V 的格式和值一样，只除了如果 ISO 星期数属于前一年或者后一年，则使用那一年。 | 比如：2009年1月6日那一周是 `09`。
  `%G` | %g 的完整四位数版本 | 比如：2009年1月3日那一周是 `2008`.
  `%y` | 两位数显示年份 | 比如： `09` 是 2009，`79` 是 1979
  `%Y` | 四位数显示年份 | 比如： `2038`
  时间 | --- | ---
  `%H` | 以 24 小时格式显示两位小时数 | `00` 到 `23`
  `%k` | Hour in 24-hour format, with a space preceding single digits | `0` through `23`
  `%I` | 以 12 小时格式显示两位小时数 | `01` 到 `12`
  `%l（'L' 的小写）` | 以 12 小时格式显示小时数，单个数字前含空格 | `1` 到 `12`
  `%M` | 两位的分钟数 | `00` 到 `59`
  `%p` | 指定时间的大写 “AM” 或 “PM” | 比如： 00:31 是 `AM` ，22:23 是`PM`。The exact result depends on the Operating System, and they can also return lower-case variants, or variants with dots (such as `a.m.`).
  `%P` | 指定时间的小写 “am” 或 “pm” | 比如：00:31 是 `am` ，22:23 是`pm`。Not supported by all Operating Systems.
  `%r` | 和 "%I:%M:%S %p" 一样 | 比如： 21:34:17 是 `09:34:17 PM`
  `%R` | 和 "%H:%M" 一样 | 比如： 12:35 AM 是 `00:35`，4:44 PM 是 `16:44`
  `%S` | 两位数字表示秒 | `00` 到 `59`
  `%T` | 和 "%H:%M:%S" 一样 | 比如： 09:34:17 PM 是 `21:34:17`
  `%X` | 当前区域首选的时间表示法，不包括日期 | 例如： `03:59:16` 或 `15:59:16`
  `%z` | The time zone offset. Not implemented as described on Windows. See below for more information. | Example: `-0500` for US Eastern Time
  `%Z` | The time zone abbreviation. Not implemented as described on Windows. See below for more information. | Example: `EST` for Eastern Time
  时间和日期戳 | --- | ---
  `%c` | 当前区域设置首选的日期时间表达 | 比如： 2009 年 2 月 5 日上午 12:45:10 是 `Tue Feb 5 00:45:10 2009`
  `%D` | 和 "%m/%d/%y" 一样 | 比如： 2009 年 2 月 5 日是 `02/05/09`
  `%F` | Same as "%Y-%m-%d" (commonly used in database datestamps) | 比如：2009 年 2 月 5 日是 `2009-02-05`
  `%s` | Unix纪元的时间戳（和 time() 函数一样） | 比如： 1979 年 9 月 10 日上午 8 点 40 分 00 秒是 `305815200`
  `%x` | 当前区域首选的时间表示法，不包括时间 | 比如： 2009 年 2 月 5 日是 `02/05/09`
  其他 | --- | ---
  `%n` | 换行符("\n") | ---
  `%t` | Tab 字符("\t") | ---
  `%%` | 文字上的百分字符("%") | ---

  警告

  尽管 ISO 9889:1999（当前的 C 标准）明确指出一周从星期一开始，但是 Sun Solaris 的一周似乎从星期天开始并作为 1。所以 %u 的结果也许不会和手册里描述得一样。

  警告

  仅针对 Windows：

  这个函数里 `%e` 修饰符修饰符还不能支持 Windows。为了得到这个值可以用 `%#d` 修饰符来代替。下例说明了如何写一个跨平台支持的函数。

  The `%z` and `%Z` modifiers both return the time zone name instead of the offset or abbreviation.

  警告

  仅针对 macOS 和 musl：这个函数里 `%P` 修饰符还不能支持 macOS。

`timestamp`
  可选的 `timestamp` 参数是一个 int 的 Unix 时间戳，如未指定或是 `null`，参数值默认为当前本地时间。也就是说，其值默认为 time() 的返回值。

### 返回值

根据指定的 `timestamp` 或未给出 timestamp 是使用当前本地时间， 返回 `format` 格式化的字符。 月份、星期名和其他与语言相关的字符串遵守 setlocale() 设置的当前区域设置。 The function returns `false` if `format` is empty, contains unsupported conversion specifiers, or if the length of the returned string would be greater than `4095`.

### 错误／异常

在每次调用日期/时间函数时，如果时区无效则会引发 `E_NOTICE` 错误。参见 date_default_timezone_set()。

由于输出依赖于 C 库，所以一些转换标记并不被支持。 在 Windows 上，使用未知的转换标记将导致 5 `E_WARNING` 信息，并返回 `false`。 在其他的操作系统上，你可能不能得到任何 `E_WARNING` 信息， 并且可能输出未经转换的转换标记。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `timestamp` 现在可为 null。

### 示例

如果你的系统里安装了各自的语言环境则下例能够正常运行。

示例 #1 strftime() 区域示例

    <?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");

示例 #2 ISO 8601:1988 周数示例

    <?php
    /*     December 2002 / January 2003
    ISOWk  M   Tu  W   Thu F   Sa  Su
    ----- ----------------------------
    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   */

    // 输出： 12/28/2002 - %V,%G,%Y = 52,2002,2002
    echo "12/28/2002 - %V,%G,%Y = " . strftime("%V,%G,%Y", strtotime("12/28/2002")) . "\n";

    // 输出： 12/30/2002 - %V,%G,%Y = 1,2003,2002
    echo "12/30/2002 - %V,%G,%Y = " . strftime("%V,%G,%Y", strtotime("12/30/2002")) . "\n";

    // 输出： 1/3/2003 - %V,%G,%Y = 1,2003,2003
    echo "1/3/2003 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/3/2003")) . "\n";

    // 输出： 1/10/2003 - %V,%G,%Y = 2,2003,2003
    echo "1/10/2003 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/10/2003")) . "\n";

    /*     December 2004 / January 2005
    ISOWk  M   Tu  W   Thu F   Sa  Su
    ----- ----------------------------
    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   */

    // 输出： 12/23/2004 - %V,%G,%Y = 52,2004,2004
    echo "12/23/2004 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("12/23/2004")) . "\n";

    // 输出： 12/31/2004 - %V,%G,%Y = 53,2004,2004
    echo "12/31/2004 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("12/31/2004")) . "\n";

    // 输出： 1/2/2005 - %V,%G,%Y = 53,2004,2005
    echo "1/2/2005 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/2/2005")) . "\n";

    // 输出： 1/3/2005 - %V,%G,%Y = 1,2005,2005
    echo "1/3/2005 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/3/2005")) . "\n";

示例 #3 `%e` 修改器跨平台兼容的示例

    <?php

    // Jan 1: results in: '%e%1%' (%%, e, %%, %e, %%)
    $format = '%%e%%%e%%';

    // Check for Windows to find and replace the %e
    // modifier correctly
    if (strtoupper(substr(PHP_OS, 0, 3)) == 'WIN') {
        $format = preg_replace('#(?<!%)((?:%%)*)%e#', '</refsect1>%#d', $format);
    }

    echo strftime($format);

示例 #4 显示所有已知和未知的格式

    <?php

    // Describe the formats
    $strftimeFormats = array(
        'A' => 'A full textual representation of the day',
        'B' => 'Full month name, based on the locale',
        'C' => 'Two digit representation of the century (year divided by 100, truncated to an integer)',
        'D' => 'Same as "%m/%d/%y"',
        'E' => '',
        'F' => 'Same as "%Y-%m-%d"',
        'G' => 'The full four-digit version of %g',
        'H' => 'Two digit representation of the hour in 24-hour format',
        'I' => 'Two digit representation of the hour in 12-hour format',
        'J' => '',
        'K' => '',
        'L' => '',
        'M' => 'Two digit representation of the minute',
        'N' => '',
        'O' => '',
        'P' => 'lower-case "am" or "pm" based on the given time',
        'Q' => '',
        'R' => 'Same as "%H:%M"',
        'S' => 'Two digit representation of the second',
        'T' => 'Same as "%H:%M:%S"',
        'U' => 'Week number of the given year, starting with the first Sunday as the first week',
        'V' => 'ISO-8601:1988 week number of the given year, starting with the first week of the year with at least 4 weekdays, with Monday being the start of the week',
        'W' => 'A numeric representation of the week of the year, starting with the first Monday as the first week',
        'X' => 'Preferred time representation based on locale, without the date',
        'Y' => 'Four digit representation for the year',
        'Z' => 'The time zone offset/abbreviation option NOT given by %z (depends on operating system)',
        'a' => 'An abbreviated textual representation of the day',
        'b' => 'Abbreviated month name, based on the locale',
        'c' => 'Preferred date and time stamp based on local',
        'd' => 'Two-digit day of the month (with leading zeros)',
        'e' => 'Day of the month, with a space preceding single digits',
        'f' => '',
        'g' => 'Two digit representation of the year going by ISO-8601:1988 standards (see %V)',
        'h' => 'Abbreviated month name, based on the locale (an alias of %b)',
        'i' => '',
        'j' => 'Day of the year, 3 digits with leading zeros',
        'k' => 'Hour in 24-hour format, with a space preceding single digits',
        'l' => 'Hour in 12-hour format, with a space preceding single digits',
        'm' => 'Two digit representation of the month',
        'n' => 'A newline character ("\n")',
        'o' => '',
        'p' => 'UPPER-CASE "AM" or "PM" based on the given time',
        'q' => '',
        'r' => 'Same as "%I:%M:%S %p"',
        's' => 'Unix Epoch Time timestamp',
        't' => 'A Tab character ("\t")',
        'u' => 'ISO-8601 numeric representation of the day of the week',
        'v' => '',
        'w' => 'Numeric representation of the day of the week',
        'x' => 'Preferred date representation based on locale, without the time',
        'y' => 'Two digit representation of the year',
        'z' => 'Either the time zone offset from UTC or the abbreviation (depends on operating system)',
        '%' => 'A literal percentage character ("%")',
    );

    // Results
    $strftimeValues = array();

    // Evaluate the formats whilst suppressing any errors
    foreach ($strftimeFormats as $format => $description) {
        if (false !== ($value = @strftime("%{$format}"))) {
            $strftimeValues[$format] = $value;
        }
    }

    // Find the longest value
    $maxValueLength = 2 + max(array_map('strlen', $strftimeValues));

    // Report known formats
    foreach ($strftimeValues as $format => $value) {
        echo "Known format   : '{$format}' = ", str_pad("'{$value}'", $maxValueLength), " ( {$strftimeFormats[$format]} )\n";
    }

    // Report unknown formats
    foreach (array_diff_key($strftimeFormats, $strftimeValues) as $format => $description) {
        echo "Unknown format : '{$format}'   ", str_pad(' ', $maxValueLength), ($description ? " ( {$description} )" : ''), "\n";
    }

以上示例的输出类似于：

    Known format   : 'A' = 'Friday'            ( A full textual representation of the day )
    Known format   : 'B' = 'December'          ( Full month name, based on the locale )
    Known format   : 'H' = '11'                ( Two digit representation of the hour in 24-hour format )
    Known format   : 'I' = '11'                ( Two digit representation of the hour in 12-hour format )
    Known format   : 'M' = '24'                ( Two digit representation of the minute )
    Known format   : 'S' = '44'                ( Two digit representation of the second )
    Known format   : 'U' = '48'                ( Week number of the given year, starting with the first Sunday as the first week )
    Known format   : 'W' = '48'                ( A numeric representation of the week of the year, starting with the first Monday as the first week )
    Known format   : 'X' = '11:24:44'          ( Preferred time representation based on locale, without the date )
    Known format   : 'Y' = '2010'              ( Four digit representation for the year )
    Known format   : 'Z' = 'GMT Standard Time' ( The time zone offset/abbreviation option NOT given by %z (depends on operating system) )
    Known format   : 'a' = 'Fri'               ( An abbreviated textual representation of the day )
    Known format   : 'b' = 'Dec'               ( Abbreviated month name, based on the locale )
    Known format   : 'c' = '12/03/10 11:24:44' ( Preferred date and time stamp based on local )
    Known format   : 'd' = '03'                ( Two-digit day of the month (with leading zeros) )
    Known format   : 'j' = '337'               ( Day of the year, 3 digits with leading zeros )
    Known format   : 'm' = '12'                ( Two digit representation of the month )
    Known format   : 'p' = 'AM'                ( UPPER-CASE "AM" or "PM" based on the given time )
    Known format   : 'w' = '5'                 ( Numeric representation of the day of the week )
    Known format   : 'x' = '12/03/10'          ( Preferred date representation based on locale, without the time )
    Known format   : 'y' = '10'                ( Two digit representation of the year )
    Known format   : 'z' = 'GMT Standard Time' ( Either the time zone offset from UTC or the abbreviation (depends on operating system) )
    Known format   : '%' = '%'                 ( A literal percentage character ("%") )
    Unknown format : 'C'                       ( Two digit representation of the century (year divided by 100, truncated to an integer) )
    Unknown format : 'D'                       ( Same as "%m/%d/%y" )
    Unknown format : 'E'
    Unknown format : 'F'                       ( Same as "%Y-%m-%d" )
    Unknown format : 'G'                       ( The full four-digit version of %g )
    Unknown format : 'J'
    Unknown format : 'K'
    Unknown format : 'L'
    Unknown format : 'N'
    Unknown format : 'O'
    Unknown format : 'P'                       ( lower-case "am" or "pm" based on the given time )
    Unknown format : 'Q'
    Unknown format : 'R'                       ( Same as "%H:%M" )
    Unknown format : 'T'                       ( Same as "%H:%M:%S" )
    Unknown format : 'V'                       ( ISO-8601:1988 week number of the given year, starting with the first week of the year with at least 4 weekdays, with Monday being the start of the week )
    Unknown format : 'e'                       ( Day of the month, with a space preceding single digits )
    Unknown format : 'f'
    Unknown format : 'g'                       ( Two digit representation of the year going by ISO-8601:1988 standards (see %V) )
    Unknown format : 'h'                       ( Abbreviated month name, based on the locale (an alias of %b) )
    Unknown format : 'i'
    Unknown format : 'k'                       ( Hour in 24-hour format, with a space preceding single digits )
    Unknown format : 'l'                       ( Hour in 12-hour format, with a space preceding single digits )
    Unknown format : 'n'                       ( A newline character ("\n") )
    Unknown format : 'o'
    Unknown format : 'q'
    Unknown format : 'r'                       ( Same as "%I:%M:%S %p" )
    Unknown format : 's'                       ( Unix Epoch Time timestamp )
    Unknown format : 't'                       ( A Tab character ("\t") )
    Unknown format : 'u'                       ( ISO-8601 numeric representation of the day of the week )
    Unknown format : 'v'

### 注释

> 注意: %G 和 %V，如果数字编号系统未能充分理解，基于 ISO 8601:1988 的星期数可能得出未预期的结果。见上面的 %V 和以下的示例。

### 参见

- IntlDateFormatter::format() - Format the date/time value as a string
- DateTimeInterface::format() - 按照指定格式返回格式化后的日期
- » Online strftime() format design tool
- setlocale() - 设置区域信息
- mktime() - 取得一个日期的 Unix 时间戳
- strptime() - 解析由 strftime 生成的日期／时间
- gmstrftime() - 根据区域设置格式化 GMT/UTC 时间/日期
- » Open Group specification of strftime()

# strptime

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

strptime — 解析由 strftime() 生成的日期／时间

警告

此函数自 PHP 8.1.0 起弃用。强烈建议不要应用此函数。

### 说明

#[\Deprecated]
function strptime(string `$timestamp`, string `$format`): array|false

strptime() 返回一个将 `timestamp` 解析后的数组，如果出错返回 `false`。

月份和星期几的名字以及其它与语种有关的字符串对应于 setlocale()设定的当前区域（`LC_TIME`）。

### 参数

`timestamp`（string）

  被解析的字符串（例如从 strftime() 返回的）

`format`（string）

  `timestamp` 所使用的格式（例如同 strftime() 中所使用的相同）。

  更多有关格式选项的信息见 strftime() 页面。

### 返回值

返回一个数组 或者在失败时返回 `false`

数组中包含以下单元
键名 | 说明
--- | ---
tm_sec | 当前分钟内的秒数（0-61）
tm_min | 当前小时内的分钟数（0-59）
tm_hour | 午夜起的小时数（0-23）
tm_mday | 月份中的第几天（1-31）
tm_mon | 自一月起过了几个月（0-11）
tm_year | 自 1900 年起过了几年
tm_wday | 自星期天起过了几天（0-6）
tm_yday | 本年自一月一日起过了多少天（0-365）
unparsed | `timestamp` 中未能通过指定的 `format` 识别的部分

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 此函数已弃用。改用 date_parse_from_format()（用于单独区域设置解析）或者 IntlDateFormatter::parse()（用于依赖区域设置解析）

### 示例

示例 #1 strptime() 示例

    <?php
    $format = '%d/%m/%Y %H:%M:%S';
    $strf = strftime($format);

    echo "$strf\n";

    print_r(strptime($strf, $format));

以上示例的输出类似于：

    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] =>
    )

### 注释

> 注意: 此函数未在 Windows 平台下实现。

> 注意:

> Internally, this function calls the `strptime()` function provided by the system's C library. This function can exhibit noticeably different behaviour across different operating systems. The use of date_parse_from_format(), which does not suffer from these issues, is recommended.

> 注意:

> `"tm_sec"` includes any leap seconds (currently upto 2 a year). For more information on leap seconds, see the » Wikipedia article on leap seconds.

### 参见

- IntlDateFormatter::parse() - Parse string to a timestamp value
- DateTime::createFromFormat() - 根据指定格式解析时间字符串
- checkdate() - 验证一个格里高里日期
- strftime() - 根据区域设置格式化本地时间/日期
- date_parse_from_format() - Get info about given date formatted according to the specified format

# strtotime

(PHP 4, PHP 5, PHP 7, PHP 8)

strtotime — 将任何英文文本日期时间描述解析为 Unix 时间戳

### 说明

function strtotime(string `$datetime`, ?int `$baseTimestamp` = `null`): int|false

本函数期望接受包含英文日期格式的字符串并尝试将其解析为 Unix 时间戳（自 January 1 1970 00:00:00 UTC 起的秒数），其值跟 `baseTimestamp` 参数给出的时间相关，如果没有提供 `baseTimestamp` 参数则为当前时间。在日期和时间格式中定义了日期字符串解析，并且有几个微秒的注意事项，强烈建议查看完整详细信息。

警告

本函数返回的 Unix 时间戳不包含时区信息，为了实现对日期/时间信息进行计算，推荐使用功能更强大的 DateTimeImmutable。

本函数的每个参数都使用默认时区，除非在该参数指定了时区。注意不要在每个参数中使用不同的时区，除非是故意的。参考 date_default_timezone_get() 获取定义默认时区的各种方法。

### 参数

`datetime`

  日期/时间字符串。正确格式的说明详见 日期与时间格式。

`baseTimestamp`

  时间戳，用作计算相对日期的基础。

### 返回值

成功则返回时间戳，否则返回 `false`。

### 错误／异常

在每次调用日期/时间函数时，如果时区无效则会引发 `E_NOTICE` 错误。参见 date_default_timezone_set()。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `baseTimestamp` 允许为 null。

### 示例

示例 #1 strtotime() 示例

    <?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";

示例 #2 失败检查

    <?php
    $str = 'Not Good';

    if (($timestamp = strtotime($str)) === false) {
        echo "The string ($str) is bogus";
    } else {
        echo "$str == " . date('l dS \o\f F Y h:i:s A', $timestamp);
    }

### 注释

> 注意:

> 在这种情况下，“相对”日期还意味着，如果未提供日期/时间的特定组成部分，则将从 `baseTimestamp` 逐字获取。也就是说如果在 2022 年 5 月 31 日运行 `strtotime('February')`，将被解释为 `31 February 2022`，它将溢出到 `3 March` 的时间戳。（在闰年，应该是 `2 March`。）使用 `strtotime('1 February')` 或者 `strtotime('first day of February')` 可以避免这个问题。

> 注意:

> 如果指定的年份位数是两位数字，则其值 0-69 表示 2000-2069，70-99 表示 1970-1999。参阅下面的注释了解 32 位系统上可能的差异（结束日期可能是 2038-01-19 03:14:07）。

> 注意:

> 时间戳的有效范围通常从 Fri, 13 Dec 1901 20:45:54 UTC 到 Tue, 19 Jan 2038 03:14:07 UTC（这些日期对应 32 位有符号整数的最小值和最大值）。

> 在 64 位的 PHP 版本中，时间戳的有效范围实际上是无限的，因为 64 位在任一方向上都可以代表大约 2930 亿年。

> 注意:

> 不建议使用此函数对日期进行数学运算。推荐使用 DateTime::add() 和 DateTime::sub() 函数。

### 参见

- DateTimeImmutable
- DateTimeImmutable::createFromFormat() - Parses a time string according to a specified format
- 日期和时间格式
- checkdate() - 验证一个格里高里日期
- strptime() - 解析由 strftime 生成的日期／时间

# time

(PHP 4, PHP 5, PHP 7, PHP 8)

time — 返回当前的 Unix 时间戳

### 说明

function time(): int

返回自从 Unix 纪元（格林威治时间 1970 年 1 月 1 日 00:00:00）到当前时间的秒数。

> 注意:

> Unix 时间戳不包含任何有关本地时区的信息。建议使用 DateTimeImmutable 类来处理日期和时间信息， 以避免 Unix 时间戳带来的陷阱。

### 参数

此函数没有参数。

### 返回值

返回当前时间戳。

### 示例

示例 #1 time() 示例

    <?php
    echo 'Now: '. time();

以上示例的输出类似于：

    Now: 1660338149

### 注释

小技巧

在 $_SERVER['REQUEST_TIME'] 中保存了发起该请求时刻的时间戳。

### 参见

- DateTimeImmutable
- date() - 格式化 Unix 时间戳
- microtime() - 返回当前 Unix 时间戳和微秒数

# timezone_abbreviations_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_abbreviations_list — 别名 DateTimeZone::listAbbreviations()

### 说明

此函数是该函数的别名： DateTimeZone::listAbbreviations()

# timezone_identifiers_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_identifiers_list — 别名 DateTimeZone::listIdentifiers()

### 说明

此函数是该函数的别名： DateTimeZone::listIdentifiers()

# timezone_location_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

timezone_location_get — 别名 DateTimeZone::getLocation()

### 说明

此函数是该函数的别名： DateTimeZone::getLocation()

# timezone_name_from_abbr

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

timezone_name_from_abbr — Returns a timezone name by guessing from abbreviation and UTC offset

### 说明

function timezone_name_from_abbr(string `$abbr`, int `$utcOffset` = -1, int `$isDST` = -1): string|false

### 参数

`abbr`

  Time zone abbreviation.

`utcOffset`

  Offset from GMT in seconds. Defaults to -1 which means that first found time zone corresponding to `abbr` is returned. Otherwise exact offset is searched and only if not found then the first time zone with any offset is returned.

`isDST`

  Daylight saving time indicator. Defaults to -1, which means that whether the time zone has daylight saving or not is not taken into consideration when searching. If this is set to 1, then the `utcOffset` is assumed to be an offset with daylight saving in effect; if 0, then `utcOffset` is assumed to be an offset without daylight saving in effect. If `abbr` doesn't exist then the time zone is searched solely by the `utcOffset` and `isDST`.

### 返回值

Returns time zone name on success 或者在失败时返回 `false`.

### 示例

示例 #1 A timezone_name_from_abbr() example

    <?php
    echo timezone_name_from_abbr("CET") . "\n";
    echo timezone_name_from_abbr("", 3600, 0) . "\n";

以上示例的输出类似于：

    Europe/Berlin
    Europe/Paris

### 参见

- timezone_abbreviations_list() - 别名 DateTimeZone::listAbbreviations

# timezone_name_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_name_get — 别名 DateTimeZone::getName()

### 说明

此函数是该函数的别名： DateTimeZone::getName()

# timezone_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_offset_get — 别名 DateTimeZone::getOffset()

### 说明

此函数是该函数的别名： DateTimeZone::getOffset()

# timezone_open

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_open — 别名 DateTimeZone::__construct()

### 说明

此函数是该函数的别名： DateTimeZone::__construct()

# timezone_transitions_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_transitions_get — 别名 DateTimeZone::getTransitions()

### 说明

此函数是该函数的别名： DateTimeZone::getTransitions()

# timezone_version_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

timezone_version_get — 获取 timezonedb 版本

### 说明

function timezone_version_get(): string

返回当前 timezonedb 版本。

### 参数

此函数没有参数。

### 返回值

返回格式为 `YYYY.increment` 的 string，比如 `2022.2`。

如果时区数据库版本比较旧（比如不显示今年），然后可以通过升级 PHP 版本或者安装 » timezonedb PECL 包来更新时区信息。

一些系统发行版对 PHP 的日期/时间支持打了补丁，以便使用另一个来源的时区信息。在这种情况下，此函数将会返回 `0.system`。在这种情况下也建议安装 » timezonedb 包。

### 示例

示例 #1 获取 timezonedb 版本

    <?php
    echo timezone_version_get();

以上示例的输出类似于：

    2022.2

### 参见

- 时区支持列表

## 目录

- checkdate — 验证一个格里高里日期
- date — 格式化 Unix 时间戳
- date_add — 别名 DateTime::add
- date_create — create a new DateTime object
- date_create_from_format — 别名 DateTime::createFromFormat
- date_create_immutable — create a new DateTimeImmutable object
- date_create_immutable_from_format — 别名 DateTimeImmutable::createFromFormat
- date_date_set — 别名 DateTime::setDate
- date_default_timezone_get — 取得脚本中所有日期/时间函数所使用的默认时区
- date_default_timezone_set — 设置脚本中所有日期/时间函数使用的默认时区
- date_diff — 别名 DateTime::diff
- date_format — 别名 DateTime::format
- date_get_last_errors — 别名 DateTimeImmutable::getLastErrors
- date_interval_create_from_date_string — 别名 DateInterval::createFromDateString
- date_interval_format — 别名 DateInterval::format
- date_isodate_set — 别名 DateTime::setISODate
- date_modify — 别名 DateTime::modify
- date_offset_get — 别名 DateTime::getOffset
- date_parse — 返回指定日期/时间的详细信息的关联数组
- date_parse_from_format — Get info about given date formatted according to the specified format
- date_sub — 别名 DateTime::sub
- date_sun_info — Returns an array with information about sunset/sunrise and twilight begin/end
- date_sunrise — 返回给定的日期与地点的日出时间
- date_sunset — 返回给定的日期与地点的日落时间
- date_time_set — 别名 DateTime::setTime
- date_timestamp_get — 别名 DateTime::getTimestamp
- date_timestamp_set — 别名 DateTime::setTimestamp
- date_timezone_get — 别名 DateTime::getTimezone
- date_timezone_set — 别名 DateTime::setTimezone
- getdate — 获取日期/时间信息
- gettimeofday — 取得当前时间
- gmdate — 格式化 GMT/UTC 日期／时间
- gmmktime — 取得 GMT 日期的 UNIX 时间戳
- gmstrftime — 根据区域设置格式化 GMT/UTC 时间/日期
- idate — 将本地日期/时间格式化为整数
- localtime — 取得本地时间
- microtime — 返回当前 Unix 时间戳和微秒数
- mktime — 取得一个日期的 Unix 时间戳
- strftime — 根据区域设置格式化本地时间/日期
- strptime — 解析由 strftime 生成的日期／时间
- strtotime — 将任何英文文本日期时间描述解析为 Unix 时间戳
- time — 返回当前的 Unix 时间戳
- timezone_abbreviations_list — 别名 DateTimeZone::listAbbreviations
- timezone_identifiers_list — 别名 DateTimeZone::listIdentifiers
- timezone_location_get — 别名 DateTimeZone::getLocation
- timezone_name_from_abbr — Returns a timezone name by guessing from abbreviation and UTC offset
- timezone_name_get — 别名 DateTimeZone::getName
- timezone_offset_get — 别名 DateTimeZone::getOffset
- timezone_open — 别名 DateTimeZone::__construct
- timezone_transitions_get — 别名 DateTimeZone::getTransitions
- timezone_version_get — 获取 timezonedb 版本

# 日期/时间 Error 和 Exception

- DateError (extends Error)
  - DateObjectError DateRangeError
- DateException (extends Exception)
  - - DateInvalidOperationException
    - DateInvalidTimezoneException
    - DateMalformedIntervalStringException
    - DateMalformedPeriodStringException
    - DateMalformedStringException

# Supported Date and Time Formats

This section describes all the different formats in a BNF-like format, that the DateTimeImmutable, DateTime, date_create_immutable(), date_create(), date_parse(), and strtotime() parser understands. The formats are grouped by section. In most cases formats from different sections, separated by whitespace, comma or dot, can be used in the same date/time string. For each of the supported formats, one or more examples are given, as well as a description for the format. Characters in single quotes in the formats are case-insensitive (`'t'` could be `t` or `T`), characters in double quotes are case-sensitive (`"T"` is only `T`).

To format DateTimeImmutable and DateTime objects, please refer to the documentation of the DateTimeInterface::format() method.

A general set of rules should be taken into account.

1. The parser, allows for each unit (year, month, day, hour, minute, second) the full range of values. For a year that's just 4 digits, for a month that's 0-12, day is 0-31, hour is 0-24, and minute is 0-59.
2. 60 is allowed for seconds, as sometimes date strings with that leapsecond do show up. But PHP implements Unix time where "60" is not a valid second number and hence it overflows.
3. strtotime() returns `false` if any number is outside of the ranges, and DateTimeImmutable::__construct() throws an exception.
4. If a string contains a date, all time elements are reset to 0.
5. All less-significant time elements are reset to 0 if any part of a time is present in the given string.
6. The parser is dumb, and doesn't do any checks to make it faster (and more generic).
7. Besides rules for individual time elements, the parser also understand more specific compound formats, such as parsing Unix timestamps (`@1690388256`) and ISO Weekdates (`2008-W28-3`).

8. There is an additional check if an invalid date is provided:

       <?php
       $res = date_parse("2015-09-31");
       var_dump($res["warnings"]);

   以上示例会输出：

       array(1) {
         [11] =>
         string(27) "The parsed date was invalid"
       }

9. It is already possible to handle the edge cases, but then DateTimeImmutable::createFromFormat() must be used while supplying the correct format.

       <?php
       $res = DateTimeImmutable::createFromFormat("Y-m-d", "2015-09-34");
       var_dump($res);

   以上示例会输出：

       object(DateTimeImmutable)#1 (3) {
         ["date"]=>
         string(26) "2015-10-04 17:24:43.000000"
         ["timezone_type"]=>
         int(3)
         ["timezone"]=>
         string(13) "Europe/London"
       }

## Time Formats

This page describes the different date/time formats in a BNF-like syntax, that the DateTimeImmutable, DateTime, date_create(), date_create_immutable(), and strtotime() parser understands.

To format DateTimeImmutable and DateTime objects, please refer to the documentation of the DateTimeInterface::format() method.

Used Symbols
Description | Formats | Examples
--- | --- | ---
`frac` | . [0-9]+ | ".21342", ".85"
`hh` | "0"?[1-9] | "1"[0-2] | "04", "7", "12"
`HH` | [01][0-9] | "2"[0-4] | "04", "07", "19"
`meridian` | [AaPp] .? [Mm] .? [\0\t ] | "A.m.", "pM", "am."
`MM` | [0-5][0-9] | "00", "12", "59"
`II` | [0-5][0-9] | "00", "12", "59"
`space` | [ \t] |
`tz` | "("? [A-Za-z]{1,6} ")"? | [A-Z][a-z]+([_/][A-Z][a-z]+)+ | "CEST", "Europe/Amsterdam", "America/Indiana/Knox"
`tzcorrection` | "GMT"? [+-] `hh` ":"? `MM`? | "+0400", "GMT-07:00", "-07:00"

12 Hour Notation
Description | Format | Examples
--- | --- | ---
Hour only, with meridian | `hh` `space`? `meridian` | "4 am", "5PM"
Hour and minutes, with meridian | `hh` [.:] `MM` `space`? `meridian` | "4:08 am", "7:19P.M."
Hour, minutes and seconds, with meridian | `hh` [.:] `MM` [.:] `II` `space`? `meridian` | "4:08:37 am", "7:19:19P.M."
MS SQL (Hour, minutes, seconds and fraction with meridian) | `hh` ":" `MM` ":" `II` [.:] [0-9]+ `meridian` | "4:08:39:12313am"

24 Hour Notation
Description | Format | Examples
--- | --- | ---
Hour and minutes | 't'? `HH` [.:] `MM` | "04:08", "19.19", "T23:43"
Hour and minutes, no colon | 't'? `HH` `MM` | "0408", "t1919", "T2343"
Hour, minutes and seconds | 't'? `HH` [.:] `MM` [.:] `II` | "04.08.37", "t19:19:19"
Hour, minutes and seconds, no colon | 't'? `HH` `MM` `II` | "040837", "T191919"
Hour, minutes, seconds and timezone | 't'? `HH` [.:] `MM` [.:] `II` `space`? ( `tzcorrection` | `tz` ) | "040837CEST", "T191919-0700"
Hour, minutes, seconds and fraction | 't'? `HH` [.:] `MM` [.:] `II` `frac` | "04.08.37.81412", "19:19:19.532453"
Time zone information | `tz` | `tzcorrection` | "CEST", "Europe/Amsterdam", "+0430", "GMT-06:00"

## Date Formats

This page describes the different date formats in a BNF-like syntax, that the DateTimeImmutable, DateTime, date_create(), date_create_immutable(), and strtotime() parser understands.

To format DateTimeImmutable and DateTime objects, please refer to the documentation of the DateTimeInterface::format() method.

Used Symbols
Description | Format | Examples
--- | --- | ---
`daysuf` | "st" | "nd" | "rd" | "th" |
`dd` | ([0-2]?[0-9] | "3"[01]) `daysuf`? | "7th", "22nd", "31"
`DD` | "0" [0-9] | [1-2][0-9] | "3" [01] | "07", "31"
`m` | '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` | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' |
`mm` | "0"? [0-9] | "1"[0-2] | "0", "04", "7", "12"
`MM` | "0" [0-9] | "1"[0-2] | "00", "04", "07", "12"
`y` | [0-9]{1,4} | "00", "78", "08", "8", "2008"
`yy` | [0-9]{2} | "00", "08", "78"
`YY` | [0-9]{4} | "2000", "2008", "1978"
`YYY` | [0-9]{5,19} | "81412", "20192"

Localized Notations
Description | Format | Examples
--- | --- | ---
American month and day | `mm` "/" `dd` | "5/12", "10/27"
American month, day and year | `mm` "/" `dd` "/" `y` | "12/22/78", "1/17/2006", "1/17/6"
Four digit year, month and day with slashes | `YY` "/" `mm` "/" `dd` | "2008/6/30", "1978/12/22"
Four digit year and month (GNU) | `YY` "-" `mm` | "2008-6", "2008-06", "1978-12"
Year, month and day with dashes | `y` "-" `mm` "-" `dd` | "2008-6-30", "78-12-22", "8-6-21"
Day, month and four digit year, with dots, tabs or dashes | `dd` [.\t-] `mm` [.-] `YY` | "30-6-2008", "22.12.1978"
Day, month and two digit year, with dots or tabs | `dd` [.\t] `mm` "." `yy` | "30.6.08", "22\t12.78"
Day, textual month and year | `dd` ([ \t.-])* `m` ([ \t.-])* `y` | "30-June 2008", "22DEC78", "14 III 1879"
Textual month and four digit year (Day reset to 1) | `m` ([ \t.-])* `YY` | "June 2008", "DEC1978", "March 1879"
Four digit year and textual month (Day reset to 1) | `YY` ([ \t.-])* `m` | "2008 June", "1978-XII", "1879.MArCH"
Textual month, day and year | `m` ([ .\t-])* `dd` [,.stndrh\t ]+ `y` | "July 1st, 2008", "April 17, 1790", "May.9,78"
Textual month and day | `m` ([ .\t-])* `dd` [,.stndrh\t ]* | "July 1st,", "Apr 17", "May.9"
Day and textual month | `dd` ([ .\t-])* `m` | "1 July", "17 Apr", "9.May"
Month abbreviation, day and year | `M` "-" `DD` "-" `y` | "May-09-78", "Apr-17-1790"
Year, month abbreviation and day | `y` "-" `M` "-" `DD` | "78-Dec-22", "1814-MAY-17"
Year (and just the year) | `YY` | "1978", "2008"
Year (expanded, 5-19 digits with sign) | [+-] `YYY` | "-81120", "+20192"
Textual month (and just the month) | `m` | "March", "jun", "DEC"

ISO8601 Notations
Description | Format | Examples
--- | --- | ---
Eight digit year, month and day | `YY` `MM` `DD` | "15810726", "19780417", "18140517"
Four digit year, month and day with slashes | `YY` "/" `MM` "/" `DD` | "2008/06/30", "1978/12/22"
Two digit year, month and day with dashes | `yy` "-" `MM` "-" `DD` | "08-06-30", "78-12-22"
Four digit year with optional sign, month and day | [+-]? `YY` "-" `MM` "-" `DD` | "-0002-07-26", "+1978-04-17", "1814-05-17"
Five+ digit year with required sign, month and day | [+-] `YYY` "-" `MM` "-" `DD` | "-81120-02-26", "+20192-04-17"

> 注意:

> For the `y` and `yy` formats, years below 100 are handled in a special way when the `y` or `yy` symbol is used. If the year falls in the range 0 (inclusive) to 69 (inclusive), 2000 is added. If the year falls in the range 70 (inclusive) to 99 (inclusive) then 1900 is added. This means that "00-01-01" is interpreted as "2000-01-01".

> 注意:

> The "Day, month and two digit year, with dots or tabs" format (`dd` [.\t] `mm` "." `yy`) only works for the year values 61 (inclusive) to 99 (inclusive) - outside those years the time format "`HH` [.:] `MM` [.:] `SS`" has precedence.

> 注意:

> The "Year (and just the year)" format only reliably works if a time string has already been found. Otherwise, if the four digit year matches `HH` `MM` then these two date elements are set instead.

> To consistently parse just a year, use DateTimeImmutable::createFromFormat() with the `Y` specifier.

警告

It is possible to over- and underflow the `dd` and `DD` format. Day 0 means the last day of previous month, whereas overflows count into the next month. This makes "2008-08-00" equivalent to "2008-07-31" and "2008-06-31" equivalent to "2008-07-01" (June only has 30 days).

Note that the day range is restricted to 0-31 as indicated by the regular expression above. Thus "2008-06-32" is not a valid date string, for instance.

It is also possible to underflow the `mm` and `MM` formats with the value 0. A month value of 0 means December of the previous year. As example "2008-00-22" is equivalent to "2007-12-22".

If you combine the previous two facts and underflow both the day and the month, the following happens: "2008-00-00" first gets converted to "2007-12-00" which then gets converted to "2007-11-30". This also happens with the string "0000-00-00", which gets transformed into "-0001-11-30" (the year -1 in the ISO 8601 calendar, which is 2 BC in the proleptic Gregorian calendar).

## Compound Formats

This page describes the different compound date/time formats in a BNF-like syntax, that the DateTimeImmutable, DateTime, date_create(), date_create_immutable(), and strtotime() parser understands.

To format DateTimeImmutable and DateTime objects, please refer to the documentation of the DateTimeInterface::format() method.

Used Symbols
Description | Formats | Examples
--- | --- | ---
`DD` | "0" [0-9] | [1-2][0-9] | "3" [01] | "02", "12", "31"
`doy` | "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` | . [0-9]+ | ".21342", ".85"
`hh` | "0"?[1-9] | "1"[0-2] | "04", "7", "12"
`HH` | [01][0-9] | "2"[0-4] | "04", "07", "19"
`meridian` | [AaPp] .? [Mm] .? [\0\t ] | "A.m.", "pM", "am."
`ii` | [0-5]?[0-9] | "04", "8", "59"
`II` | [0-5][0-9] | "04", "08", "59"
`M` | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' |
`MM` | [0-1][0-9] | "00", "12"
`space` | [ \t] |
`ss` | ([0-5]?[0-9])|60 | "04", "8", "59", "60" (leap second)
`SS` | [0-5][0-9] | "04", "08", "59"
`W` | "0"[1-9] | [1-4][0-9] | "5"[0-3] | "05", "17", "53"
`tzcorrection` | "GMT"? [+-] `hh` ":"? `II`? | "+0400", "GMT-07:00", "-07:00"
`YY` | [0-9]{4} | "2000", "2008", "1978"

Standards Formats
Description | Examples
--- | ---
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 Extended | "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"

Localized Notations
Description | Format | Examples
--- | --- | ---
Common Log Format | `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 year with ISO week | `YY` "-"? "W" `W` | "2008W27", "2008-W28"
ISO year with ISO week and day | `YY` "-"? "W" `W` "-"? [0-7] | "2008W273", "2008-W28-3"
MySQL | `YY` "-" `MM` "-" `DD` " " `HH` ":" `II` ":" `SS` | "2008-08-07 18:11:31"
PostgreSQL: Year with day-of-year | `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 Timestamp | "@" "-"? [0-9]+ | "@1215282385"
Unix Timestamp with microseconds | "@" "-"? [0-9]+ "." [0-9]{0,6} | "@1607974647.503686"
XMLRPC | `YY` `MM` `DD` "T" `hh` ":" `II` ":" `SS` | "20080701T22:38:07", "20080701T9:38:07"
XMLRPC (Compact) | `YY` `MM` `DD` 't' `hh` `II` `SS` | "20080701t223807", "20080701T093807"
WDDX | `YY` "-" `mm` "-" `dd` "T" `hh` ":" `ii` ":" `ss` | "2008-7-1T9:3:37"

> 注意:

> The "W" in the "ISO year with ISO week" and "ISO year with ISO week and day" formats is case-sensitive, you can only use the upper case "W".

> The "T" in the SOAP, XMLRPC and WDDX formats is case-sensitive, you can only use the upper case "T".

> The "Unix Timestamp" format sets the timezone to UTC.

## Relative Formats

This page describes the different relative date/time formats in a BNF-like syntax, that the DateTimeImmutable, DateTime, date_create(), date_create_immutable(), and strtotime() parser understands.

To format DateTimeImmutable and DateTime objects, please refer to the documentation of the DateTimeInterface::format() method.

Used Symbols
Description | Format
--- | ---
`dayname` | 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
`daytext` | 'weekday' | 'weekdays'
`number` | [+-]?[0-9]+
`ordinal` | 'first' | 'second' | 'third' | 'fourth' | 'fifth' | 'sixth' | 'seventh' | 'eighth' | 'ninth' | 'tenth' | 'eleventh' | 'twelfth' | 'next' | 'last' | 'previous' | 'this'
`reltext` | 'next' | 'last' | 'previous' | 'this'
`space` | [ \t]+
`unit` | 'ms' | 'µs' | (( 'msec' | 'millisecond' | 'µsec' | 'microsecond' | 'usec' | 'sec' | 'second' | 'min' | 'minute' | 'hour' | 'day' | 'fortnight' | 'forthnight' | 'month' | 'year') 's'?) | 'weeks' | `daytext`

Day-based Notations
Format | Description | Examples
--- | --- | ---
'yesterday' | Midnight of yesterday | "yesterday 14:00"
'midnight' | The time is set to 00:00:00 |
'today' | The time is set to 00:00:00 |
'now' | Now - this is simply ignored |
'noon' | The time is set to 12:00:00 | "yesterday noon"
'tomorrow' | Midnight of tomorrow |
'back of' `hour` | 15 minutes past the specified hour | "back of 7pm", "back of 15"
'front of' `hour` | 15 minutes before the specified hour | "front of 5am", "front of 23"
'first day of' | Sets the day of the first of the current month. This phrase is usually best used together with a month name following it as it only effects the current month | "first day of January 2008"
'last day of' | Sets the day to the last day of the current month. This phrase is usually best used together with a month name following it as it only effects the current month | "last day of next month"
`ordinal` `space` `dayname` `space` 'of' | Calculates the `x`-th week day of the current month. | "first sat of July 2008"
'last' `space` `dayname` `space` 'of' | Calculates the last week day of the current month. | "last sat of July 2008"
`number` `space`? (`unit` | 'week') | Handles relative time items where the value is a number. | "+5 weeks", "12 day", "-7 weekdays"
(`ordinal` | `reltext`) `space` `unit` | Handles relative time items where the value is text. `last` and `previous` are equivalent to `-1`, `this` to nothing, and `next` to `+1`. | "fifth day", "second month", "last day", "previous year"
'ago' | Negates all the values of previously found relative time items. | "2 days ago", "8 days ago 14:00", "2 months 5 days ago", "2 months ago 5 days", "2 days ago"
`dayname` | Moves to the next day of this name. (See note) | "Monday"
`reltext` `space` 'week' | Handles the special format "weekday + last/this/next week". | "Monday next week"

> 注意:

> Relative statements are always processed after non-relative statements. This makes "+1 week july 2008" and "july 2008 +1 week" equivalent.

> Exceptions to this rule are: "yesterday", "midnight", "today", "noon" and "tomorrow". Note that "tomorrow 11:00" and "11:00 tomorrow" are different. Considering today's date of "July 23rd, 2008" the first one produces "2008-07-24 11:00" where as the second one produces "2008-07-24 00:00". The reason for this is that those five statements directly influence the current time.

> Keywords such as "first day of" depend on the context in which the relative format string is used. If used with a static method or function, the referent is the current system timestamp. However, if used in DateTime::modify() or DateTimeImmutable::modify(), the referent is the object on which the `modify()` method is called.

> 注意:

> Observe the following remarks when the current day-of-week is the same as the day-of-week used in the date/time string. The current day-of-week could have been (re-)calculated by non-relative parts of the date/time string however.

> 1. "`dayname`" does not advance to another day. (Example: "Wed July 23rd, 2008" means "2008-07-23").
> 2. "`number` `dayname`" does not advance to another day. (Example: "1 wednesday july 23rd, 2008" means "2008-07-23").
> 3. "`number` week `dayname`" will first add the number of weeks, but does not advance to another day. In this case "`number` week" and "`dayname`" are two distinct blocks. (Example: "+1 week wednesday july 23rd, 2008" means "2008-07-30").
> 4. "`ordinal` `dayname`" does advance to another day. (Example "first wednesday july 23rd, 2008" means "2008-07-30").
> 5. "`number` week `ordinal` `dayname`" will first add the number of weeks, and then advances to another day. In this case "`number` week" and "`ordinal` `dayname`" are two distinct blocks. (Example: "+1 week first wednesday july 23rd, 2008" means "2008-08-06").
> 6. "`ordinal` `dayname` 'of' " does not advance to another day. (Example: "first wednesday of july 23rd, 2008" means "2008-07-02" because the specific phrase with 'of' resets the day-of-month to '1' and the '23rd' is ignored here).

> Also observe that the "of" in "`ordinal` `space` `dayname` `space` 'of' " and "'last' `space` `dayname` `space` 'of' " does something special.

> 1. It sets the day-of-month to 1.
> 2. "`ordinal` `dayname` 'of' " does not advance to another day. (Example: "first tuesday of july 2008" means "2008-07-01").
> 3. "`ordinal` `dayname` " does advance to another day. (Example: "first tuesday july 2008" means "2008-07-08", see also point 4 in the list above).
> 4. "'last' `dayname` 'of' " takes the last `dayname` of the current month. (Example: "last wed of july 2008" means "2008-07-30")
> 5. "'last' `dayname`" takes the last `dayname` from the current day. (Example: "last wed july 2008" means "2008-06-25"; "july 2008" first sets the current date to "2008-07-01" and then "last wed" moves to the previous Wednesday which is "2008-06-25").

> 注意:

> Relative month values are calculated based on the length of months that they pass through. An example would be "+2 month 2011-11-30", which would produce "2012-01-30". This is due to November being 30 days in length, and December being 31 days in length, producing a total of 61 days.

> 注意:

> `number` is an integer number; if a decimal number is given, the dot (or comma) is likely interpreted as delimiter. For instance, `'+1.5 hours'` is parsed like `'+1 5 hours'`, not as `'+1 hour +30 minutes'`.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `number` now again accepts a plus sign followed by a minus sign, e.g. `+-2`, and other combinations of multiple signs.
8.2.0 | `number` no longer accepts a plus sign followed by a minus sign, e.g. `+-2`.
7.0.8 | Weeks always start on monday. Formerly, sunday would also be considered to start a week.

# 所支持的时区列表

## 目录

- 非洲
- 美洲
- 南极洲
- 北极
- 亚洲
- 大西洋
- 澳洲
- 欧洲
- 印度
- 太平洋地区
- 其他

在这你可找到 PHP 所支持的所有时区的列表，可用于诸如 date_default_timezone_set() 等函数。

警告

这里没有列出的时区是未定义的。

> 注意: 最新版的时区数据库可从 PECL 的 » timezonedb 进行安装。

> 注意: 基于时区数据库版本的列表 2026.1.

## 非洲

非洲
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

## 美洲

美洲
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

## 南极洲

南极洲
Antarctica/Casey | Antarctica/Davis | Antarctica/DumontDUrville | Antarctica/Macquarie
Antarctica/Mawson | Antarctica/McMurdo | Antarctica/Palmer | Antarctica/Rothera
Antarctica/Syowa | Antarctica/Troll | Antarctica/Vostok |

## 北极

北极
Arctic/Longyearbyen

## 亚洲

亚洲
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 |  |

## 大西洋

大西洋
Atlantic/Azores | Atlantic/Bermuda | Atlantic/Canary | Atlantic/Cape_Verde
Atlantic/Faroe | Atlantic/Madeira | Atlantic/Reykjavik | Atlantic/South_Georgia
Atlantic/St_Helena | Atlantic/Stanley |  |

## 澳洲

澳洲
Australia/Adelaide | Australia/Brisbane | Australia/Broken_Hill | Australia/Darwin
Australia/Eucla | Australia/Hobart | Australia/Lindeman | Australia/Lord_Howe
Australia/Melbourne | Australia/Perth | Australia/Sydney |

## 欧洲

欧洲
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 |  |

## 印度

印度
Indian/Antananarivo | Indian/Chagos | Indian/Christmas | Indian/Cocos
Indian/Comoro | Indian/Kerguelen | Indian/Mahe | Indian/Maldives
Indian/Mauritius | Indian/Mayotte | Indian/Reunion |

## 太平洋地区

太平洋地区
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 |  |

## 其他

警告

在此请不要使用任何时区列表（除 UTC 外），仅用于向后兼容，可能会引起某些错误行为。此外，这些时区可能随时会从 IANA 时区数据库中移除。

警告

If you disregard the above warning, please also note that the IANA timezone database that provides PHP's timezone support uses POSIX style signs, which results in the `Etc/GMT+n` and `Etc/GMT-n` time zones being reversed from common usage.

For example, the time zone 8 hours ahead of GMT that is used in China and Western Australia (among other places) is actually `Etc/GMT-8` in this database, not `Etc/GMT+8` as you would normally expect.

Once again, it is strongly recommended that you use the correct time zone for your location, such as `Asia/Shanghai` or `Australia/Perth` for the above examples.

其他
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

# The DateError class

(PHP 8 >= 8.3.0)

## 简介

Thrown when the timezone database is not found, or contains invalid data.

This error should never occur, and is not dependent on code. There are two child-exceptions (DateObjectError and DateRangeError) which are thrown depending on programmer error or range related issues.

## 类摘要

class DateError extends Error {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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
}

## 参见

- DateObjectError
- DateRangeError

# The DateObjectError class

(PHP 8 >= 8.3.0)

## 简介

Thrown when one of the Date/Time classes has not been correctly initialised.

Because Date/Time classes are not final, these classes can be inherit. When the parent constructor is not called, this error is thrown. This is always a programming error.

## 类摘要

class DateObjectError extends DateError {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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
}

## 参见

- DateError
- DateRangeError

# The DateRangeError class

(PHP 8 >= 8.3.0)

## 简介

Thrown by DateTime::getTimestamp(), DateTimeImmutable::getTimestamp(), and date_timestamp_get(), on 32-bit platforms if the date object represents a date outside of the 32-bit signed range.

## 类摘要

class DateRangeError extends DateError {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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
}

## 参见

- DateError
- DateObjectError

# The DateException class

(PHP 8 >= 8.3.0)

## 简介

Parent class of Date/Time exceptions, for issues that come to light due to user input, or free form text arguments that need to be parsed.

The following child exceptions are thrown by the extension:

- DateInvalidOperationException
- DateInvalidTimezoneException
- DateMalformedIntervalStringException
- DateMalformedPeriodStringException
- DateMalformedStringException

## 类摘要

class DateException extends Exception {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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 DateInvalidOperationException class

(PHP 8 >= 8.3.0)

## 简介

Thrown by DateTimeImmutable::sub() and DateTime::sub() when an unsupported operation is attempted.

An example of such an unsupported operation is using a DateInterval object representing relative time specifications such as `next weekday`, as no logical reversed statement can be constructed.

## 类摘要

class DateInvalidOperationException extends DateException {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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 DateInvalidTimeZoneException class

(PHP 8 >= 8.3.0)

## 简介

Thrown when an incorrect value is passed to DateTimeZone::__construct().

## 类摘要

class DateInvalidTimeZoneException extends DateException {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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 DateMalformedIntervalStringException class

(PHP 8 >= 8.3.0)

## 简介

Thrown when an invalid `duration` argument is passed to DateInterval::__construct().

## 类摘要

class DateMalformedIntervalStringException extends DateException {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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 DateMalformedPeriodStringException class

(PHP 8 >= 8.3.0)

## 简介

Thrown when an invalid `isostr` argument is passed to DatePeriod::__construct().

## 类摘要

class DateMalformedPeriodStringException extends DateException {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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 DateMalformedStringException class

(PHP 8 >= 8.3.0)

## 简介

Thrown when an invalid Date/Time string is detected.

This can be as value to DateTimeImmutable::__construct(), DateTimeImmutable::modify(), DateTime::__construct(), or DateTime::modify().

## 类摘要

class DateMalformedStringException extends DateException {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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
}

- 安装/配置
  - 安装
  - 运行时配置
- 预定义常量
- 示例
  - 日期/时间算法
- DateTime — DateTime 类
  - DateTime::add — 修改 DateTime 对象，增加天、月、年、小时、分钟以及秒的数量。
  - DateTime::__construct — 返回新的 DateTime 对象
  - DateTime::createFromFormat — 根据指定格式解析时间字符串
  - DateTime::createFromImmutable — Returns new DateTime instance encapsulating the given DateTimeImmutable object
  - DateTime::createFromInterface — Returns new DateTime object encapsulating the given DateTimeInterface object
  - DateTime::createFromTimestamp — Creates an instance from a Unix timestamp
  - DateTime::getLastErrors — 别名 DateTimeImmutable::getLastErrors
  - DateTime::modify — 修改日期时间对象的值
  - DateTime::__set_state — __set_state 处理程序
  - DateTime::setDate — 设置日期
  - DateTime::setISODate — 设置 ISO 日期
  - DateTime::setMicrosecond — Sets microsecond part of the time
  - DateTime::setTime — 设置时间
  - DateTime::setTimestamp — 以 Unix 时间戳的方式设置日期和时间
  - DateTime::setTimezone — 设置 DateTime 对象的时区
  - DateTime::sub — 对 DateTime 对象减去一定量的日、月、年、小时、分钟和秒。
- DateTimeImmutable — The DateTimeImmutable class
  - DateTimeImmutable::add — Returns a new object, with added amount of days, months, years, hours, minutes and seconds
  - DateTimeImmutable::__construct — Returns new DateTimeImmutable object
  - DateTimeImmutable::createFromFormat — Parses a time string according to a specified format
  - DateTimeImmutable::createFromInterface — Returns new DateTimeImmutable object encapsulating the given DateTimeInterface object
  - DateTimeImmutable::createFromMutable — Returns new DateTimeImmutable instance encapsulating the given DateTime object
  - DateTimeImmutable::createFromTimestamp — Creates an instance from a Unix timestamp
  - DateTimeImmutable::getLastErrors — Returns the warnings and errors
  - DateTimeImmutable::modify — Creates a new object with modified timestamp
  - DateTimeImmutable::__set_state — The __set_state handler
  - DateTimeImmutable::setDate — Sets the date
  - DateTimeImmutable::setISODate — Sets the ISO date
  - DateTimeImmutable::setMicrosecond — Sets microsecond part of the time
  - DateTimeImmutable::setTime — Sets the time
  - DateTimeImmutable::setTimestamp — Sets the date and time based on a Unix timestamp
  - DateTimeImmutable::setTimezone — Sets the time zone
  - DateTimeImmutable::sub — Subtracts an amount of days, months, years, hours, minutes and seconds
- DateTimeInterface — The DateTimeInterface interface
  - DateTimeInterface::diff — 返回两个 DateTime 之间的差值
  - DateTimeInterface::format — 按照指定格式返回格式化后的日期
  - DateTimeInterface::getMicrosecond — Gets the microsecond part of the Unix timestamp
  - DateTimeInterface::getOffset — 返回时差
  - DateTimeInterface::getTimestamp — 获取 Unix 时间戳
  - DateTimeInterface::getTimezone — 返回相对于指定 DateTime 的时区
  - DateTime::__serialize — Serialize a DateTime
  - DateTime::__unserialize — Unserialize an Datetime
  - DateTime::__wakeup — The __wakeup handler
- DateTimeZone — DateTimeZone 类
  - DateTimeZone::__construct — 创建新的DateTimeZone对象
  - DateTimeZone::getLocation — 返回与时区相关的定位信息
  - DateTimeZone::getName — 返回时区名称
  - DateTimeZone::getOffset — 返回相对于 GMT 的时差
  - DateTimeZone::getTransitions — Returns all transitions for the timezone
  - DateTimeZone::listAbbreviations — 返回一个包含 dst (夏令时)，时差和时区信息的关联数组。
  - DateTimeZone::listIdentifiers — 返回包含了所有时区标识符的数字索引数组
- DateInterval — DateInterval 类
  - DateInterval::__construct — Creates a new DateInterval object
  - DateInterval::createFromDateString — Sets up a DateInterval from the relative parts of the string
  - DateInterval::format — Formats the interval
- DatePeriod — DatePeriod 类
  - DatePeriod::__construct — Creates a new DatePeriod object
  - DatePeriod::createFromISO8601String — Creates a new DatePeriod object from an ISO8601 string
  - DatePeriod::getDateInterval — Gets the interval
  - DatePeriod::getEndDate — Gets the end date
  - DatePeriod::getRecurrences — Gets the number of recurrences
  - DatePeriod::getStartDate — Gets the start date
- Date/Time 函数
  - checkdate — 验证一个格里高里日期
  - date — 格式化 Unix 时间戳
  - date_add — 别名 DateTime::add
  - date_create — create a new DateTime object
  - date_create_from_format — 别名 DateTime::createFromFormat
  - date_create_immutable — create a new DateTimeImmutable object
  - date_create_immutable_from_format — 别名 DateTimeImmutable::createFromFormat
  - date_date_set — 别名 DateTime::setDate
  - date_default_timezone_get — 取得脚本中所有日期/时间函数所使用的默认时区
  - date_default_timezone_set — 设置脚本中所有日期/时间函数使用的默认时区
  - date_diff — 别名 DateTime::diff
  - date_format — 别名 DateTime::format
  - date_get_last_errors — 别名 DateTimeImmutable::getLastErrors
  - date_interval_create_from_date_string — 别名 DateInterval::createFromDateString
  - date_interval_format — 别名 DateInterval::format
  - date_isodate_set — 别名 DateTime::setISODate
  - date_modify — 别名 DateTime::modify
  - date_offset_get — 别名 DateTime::getOffset
  - date_parse — 返回指定日期/时间的详细信息的关联数组
  - date_parse_from_format — Get info about given date formatted according to the specified format
  - date_sub — 别名 DateTime::sub
  - date_sun_info — Returns an array with information about sunset/sunrise and twilight begin/end
  - date_sunrise — 返回给定的日期与地点的日出时间
  - date_sunset — 返回给定的日期与地点的日落时间
  - date_time_set — 别名 DateTime::setTime
  - date_timestamp_get — 别名 DateTime::getTimestamp
  - date_timestamp_set — 别名 DateTime::setTimestamp
  - date_timezone_get — 别名 DateTime::getTimezone
  - date_timezone_set — 别名 DateTime::setTimezone
  - getdate — 获取日期/时间信息
  - gettimeofday — 取得当前时间
  - gmdate — 格式化 GMT/UTC 日期／时间
  - gmmktime — 取得 GMT 日期的 UNIX 时间戳
  - gmstrftime — 根据区域设置格式化 GMT/UTC 时间/日期
  - idate — 将本地日期/时间格式化为整数
  - localtime — 取得本地时间
  - microtime — 返回当前 Unix 时间戳和微秒数
  - mktime — 取得一个日期的 Unix 时间戳
  - strftime — 根据区域设置格式化本地时间/日期
  - strptime — 解析由 strftime 生成的日期／时间
  - strtotime — 将任何英文文本日期时间描述解析为 Unix 时间戳
  - time — 返回当前的 Unix 时间戳
  - timezone_abbreviations_list — 别名 DateTimeZone::listAbbreviations
  - timezone_identifiers_list — 别名 DateTimeZone::listIdentifiers
  - timezone_location_get — 别名 DateTimeZone::getLocation
  - timezone_name_from_abbr — Returns a timezone name by guessing from abbreviation and UTC offset
  - timezone_name_get — 别名 DateTimeZone::getName
  - timezone_offset_get — 别名 DateTimeZone::getOffset
  - timezone_open — 别名 DateTimeZone::__construct
  - timezone_transitions_get — 别名 DateTimeZone::getTransitions
  - timezone_version_get — 获取 timezonedb 版本
- 日期/时间 Error 和 Exception
- Supported Date and Time Formats
- 所支持的时区列表
  - 非洲
  - 美洲
  - 南极洲
  - 北极
  - 亚洲
  - 大西洋
  - 澳洲
  - 欧洲
  - 印度
  - 太平洋地区
  - 其他
- DateError — The DateError class
- DateObjectError — The DateObjectError class
- DateRangeError — The DateRangeError class
- DateException — The DateException class
- DateInvalidOperationException — The DateInvalidOperationException class
- DateInvalidTimeZoneException — The DateInvalidTimeZoneException class
- DateMalformedIntervalStringException — The DateMalformedIntervalStringException class
- DateMalformedPeriodStringException — The DateMalformedPeriodStringException class
- DateMalformedStringException — The DateMalformedStringException class

# High resolution timing

# 简介

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.

> 注意: As of PHP 7.3.0 the related function hrtime() is part of the core.

# 安装/配置

## 目录

- 安装

## 安装

此 » PECL 扩展未与 PHP 捆绑。

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/hrtime.

# 示例

## 目录

- Basic usage

## Basic usage

The example illustrates the basic StopWatch class usage

示例 #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)

## 简介

## 类摘要

class HRTime\PerformanceCounter {
/* 方法 */
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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns int indicating the timer frequency.

# HRTime\PerformanceCounter::getTicks

(PECL hrtime >= 0.6.0)

HRTime\PerformanceCounter::getTicks — Current ticks from the system

### 说明

public static function HRTime\PerformanceCounter::getTicks(): int

Returns the ticks count.

### 参数

此函数没有参数。

### 返回值

Returns int indicating the ticks count.

# HRTime\PerformanceCounter::getTicksSince

(PECL hrtime >= 0.6.0)

HRTime\PerformanceCounter::getTicksSince — Ticks elapsed since the given value

### 说明

public static function HRTime\PerformanceCounter::getTicksSince(int `$start`): int

Returns the ticks count elapsed since the given start value.

### 参数

`start`
  Starting ticks value.

### 返回值

Returns int indicating the ticks count.

## 目录

- 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)

## 简介

## 类摘要

class HRTime\StopWatch extends HRTime\PerformanceCounter {
/* 方法 */
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
/* 继承的方法 */
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

### 说明

public function HRTime\StopWatch::getElapsedTicks(): int

Get elapsed ticks for all the previously closed intervals.

### 参数

此函数没有参数。

### 返回值

Returns int indicating elapsed ticks.

# HRTime\StopWatch::getElapsedTime

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getElapsedTime — Get elapsed time for all intervals

### 说明

public function HRTime\StopWatch::getElapsedTime(int `$unit` = ?): float

Get elapsed time for all the previously closed intervals.

### 参数

`unit`
  Time unit represented by a HRTime\Unit constant. Default is HRTime\Unit::SECOND.

### 返回值

Returns float indicating elapsed time.

# HRTime\StopWatch::getLastElapsedTicks

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getLastElapsedTicks — Get elapsed ticks for the last interval

### 说明

public function HRTime\StopWatch::getLastElapsedTicks(): int

Get elapsed ticks for the previously closed interval.

### 参数

此函数没有参数。

### 返回值

Returns int indicating elapsed ticks.

# HRTime\StopWatch::getLastElapsedTime

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getLastElapsedTime — Get elapsed time for the last interval

### 说明

public function HRTime\StopWatch::getLastElapsedTime(int `$unit` = ?): float

Get elapsed time for the previously closed interval.

### 参数

`unit`
  Time unit represented by a HRTime\Unit constant. Default is HRTime\Unit::SECOND.

### 返回值

Returns float indicating elapsed time.

# HRTime\StopWatch::isRunning

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::isRunning — 确认测量是否在运行

### 说明

public function HRTime\StopWatch::isRunning(): bool

显示测量是否已经开始。

### 参数

此函数没有参数。

### 返回值

返回 bool 表明测量是否在运行。

# HRTime\StopWatch::start

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::start — Start time measurement

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns void.

# HRTime\StopWatch::stop

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::stop — Stop time measurement

### 说明

public function HRTime\StopWatch::stop(): void

Stop the time measurement for the previously started interval.

### 参数

此函数没有参数。

### 返回值

Returns void.

## 目录

- 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 — 确认测量是否在运行
- HRTime\StopWatch::start — Start time measurement
- HRTime\StopWatch::stop — Stop time measurement

# The HRTime\Unit class

(PECL hrtime >= 0.4.3)

## 简介

## 类摘要

class HRTime\Unit {
/* 常量 */
const int SECOND = 0;
const int MILLISECOND = 1;
const int MICROSECOND = 2;
const int NANOSECOND = 3;
/* 方法 */
}

## 预定义常量

`HRTime\Unit::SECOND`
`HRTime\Unit::MILLISECOND`
`HRTime\Unit::MICROSECOND`
`HRTime\Unit::NANOSECOND`

- 安装/配置
  - 安装
- 示例
  - 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 — 确认测量是否在运行
  - HRTime\StopWatch::start — Start time measurement
  - HRTime\StopWatch::stop — Stop time measurement
- HRTime\Unit — The HRTime\Unit class

- Calendar
  - 安装/配置
  - 预定义常量
  - Calendar 函数
- 日期/时间 — 日期和时间
  - 安装/配置
  - 预定义常量
  - 示例
  - DateTime — DateTime 类
  - DateTimeImmutable — The DateTimeImmutable class
  - DateTimeInterface — The DateTimeInterface interface
  - DateTimeZone — DateTimeZone 类
  - DateInterval — DateInterval 类
  - DatePeriod — DatePeriod 类
  - Date/Time 函数
  - 日期/时间 Error 和 Exception
  - Supported Date and Time Formats
  - 所支持的时区列表
  - DateError — The DateError class
  - DateObjectError — The DateObjectError class
  - DateRangeError — The DateRangeError class
  - DateException — The DateException class
  - DateInvalidOperationException — The DateInvalidOperationException class
  - DateInvalidTimeZoneException — The DateInvalidTimeZoneException class
  - DateMalformedIntervalStringException — The DateMalformedIntervalStringException class
  - DateMalformedPeriodStringException — The DateMalformedPeriodStringException class
  - DateMalformedStringException — The DateMalformedStringException class
- HRTime — High resolution timing
  - 安装/配置
  - 示例
  - HRTime\PerformanceCounter — The HRTime\PerformanceCounter class
  - HRTime\StopWatch — The HRTime\StopWatch class
  - HRTime\Unit — The HRTime\Unit class

# 文件系统相关扩展

# 直接 IO

# 简介

PHP 支持 POSIX 标准（第 6 节）中所描述的直接 IO 函数，执行比 C 语言 I/O 流函数（fopen()、fread()......）更低级别的 I/O 函数。当仅需要直接控制设备时，才考虑使用 DIO 函数。通常情况下，标准的 filesystem 函数已经足够了。

# 安装/配置

## 目录

- 安装
- 资源类型

## 安装

此 » PECL 扩展未与 PHP 捆绑。

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/dio.

## 资源类型

此扩展定义了一种资源类型：dio_open() 返回的文件描述符。

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`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 函数

# dio_close

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_close — 通过 fd 关闭文件描述符

### 说明

function dio_close(resource `$fd`): void

dio_close() 函数关闭 `fd` 文件描述符。

### 参数

`fd`

  dio_open() 返回的文件描述符。

### 返回值

没有返回值。

### 示例

示例 #1 关闭文件描述符

    <?php
    $fd = dio_open('/dev/ttyS0', O_RDWR);

    dio_close($fd);
    ?>

### 参见

- dio_open() - 在 C 库输入/输出流函数允许的更低级别打开（必要时创建）文件

# dio_fcntl

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_fcntl — 在 fd 上执行 C 标准库的 fcntl

### 说明

function dio_fcntl(resource `$fd`, int `$cmd`, mixed `$args` = ?): mixed

dio_fcntl() 函数在 `fd` 文件描述符上执行 `cmd` 指定的操作。一些命令需要提供额外的 `args` 参数。

### 参数

`fd`

  dio_open() 返回的文件描述符。

`cmd`

  可以是以下操作：

  - `F_SETLK` - 设置或清除锁。如果其他人持有锁 dio_fcntl() 返回 -1。

  - `F_SETLKW` - 和 `F_SETLK` 相似，但如果其他人持有锁，dio_fcntl() 等待锁释放。

  - `F_GETLK` - 如果其他人阻止锁定，dio_fcntl() 返回关联数组（如下所述）。如果没有阻塞，键“type”将设置为 `F_UNLCK`。

  - `F_DUPFD` - 查找大于或等于 `args` 的最小可用文件描述符，并将其返回。

  - `F_SETFL` - 设置 `args` 指定的文件描述符标志。可以是 `O_APPEND`、`O_NONBLOCK` 或 `O_ASYNC`。要使用 `O_ASYNC` 需要依赖 PCNTL 扩展。

`args`

  当 `cmd` 是 `F_SETLK` 或 `F_SETLLW` 时，`args` 是包含以下键的关联数组：

  - `start` - 开始锁定的偏移

  - `length` - 锁定区域大小。0 代表文件结尾

  - `whence` - l_start 的相对位置可以是：`SEEK_SET`、`SEEK_END` 和 `SEEK_CUR`

  - `type` - 锁类型：可以是 `F_RDLCK` （读锁），`F_WRLCK`（写锁）或 `F_UNLCK` （解锁）。

### 返回值

返回 C 调用的结果。

### 示例

示例 #1 设置并清除锁

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR);

    if (dio_fcntl($fd, F_SETLK, Array("type"=>F_WRLCK)) == -1) {
       // the file descriptor appears locked
       echo "The lock can not be cleared. It is held by someone else.";
    } else {
       echo "Lock successfully set/cleared";
    }

    dio_close($fd);
    ?>

### 注释

> 注意: 此函数未在 Windows 平台下实现。

# dio_open

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_open — 在 C 库输入/输出流函数允许的更低级别打开（必要时创建）文件

### 说明

function dio_open(string `$filename`, int `$flags`, int `$mode` = 0): resource

dio_open() 打开文件并返回新的文件描述符。

### 参数

`filename`

  要打开的文件路径。

`flags`

  `flags` 参数是按位或运算值，包含以下列表的标志。 必须包含 `O_RDONLY`、`O_WRONLY` 或 `O_RDWR` 中的一个。此外，可以包含此列表中其它标志的任意组合。

  - `O_RDONLY` - 打开文件读访问。

  - `O_WRONLY` - 打开文件写访问。

  - `O_RDWR` - 打开文件读写。

  - `O_CREAT` - 如果文件不存在，创建文件。

  - `O_EXCL` - 如果同时设置了 `O_CREAT` 和 `O_EXCL`，并且文件已存在，dio_open() 将执行失败。

  - `O_TRUNC` - 如果文件存在且已打开写访问，将会被截断到 0 长度。

  - `O_APPEND` - 写操作在文件末尾写数据。

  - `O_NONBLOCK` - 设置非阻塞模式。

  - `O_NOCTTY` - 防止操作系统在打开 TTY 设备文件时将文件指定为进程的控制终端。

`mode`

  如果 `flags` 包含 `O_CREAT`，`mode` 将设置文件权限（创建权限）。当 `flags` 指定了 `O_CREAT` 标志时，需要 `mode` 才能正确操作，否则将会被忽略。

  分配给创建文件的实际权限照例受到进程的 umask 设置的影响。

### 返回值

文件描述符，错误时是 `false`。

### 示例

示例 #1 打开文件描述符

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);

    dio_close($fd);
    ?>

### 参见

- dio_close() - 通过 fd 关闭文件描述符

# dio_read

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_read — 从文件描述符读取字节

### 说明

function dio_read(resource `$fd`, int `$len` = 1024): string

dio_read() 函数读取并返回描述符 `fd` 指定文件中的 `len` 字节。

### 参数

`fd`

  由 dio_open() 返回的文件描述符。

`len`

  要读取的字节数。如果未指定，dio_read() 读取 1K 大小的块。

### 返回值

从 `fd` 读取的字节。

### 参见

- dio_write() - 截取可选长度的数据写入文件

# dio_seek

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_seek — 在 fd 指定 pos 位置

### 说明

function dio_seek(resource `$fd`, int `$pos`, int `$whence` = SEEK_SET): int

函数 dio_seek() 用于更改给定文件描述符的文件当前读/写位置。

### 参数

`fd`

  由 dio_open() 返回的文件描述符。

`pos`

  新位置。

`whence`

  指定如何解释 `pos` 的位置：

  - `SEEK_SET` （默认）- 从文件开头指定 `pos`。

  - `SEEK_CUR` - 指定 `pos` 是从文件当前位置计算的字符数。数量可以是正数或负数。

  - `SEEK_END` - 指定 `pos` 是从文件结尾计算的字符数。负数指定文件当前范围内的位置；正数指定超过当前末端的位置。 如果将位置设置为超过当前末尾并写入数据，将用零将文件扩展到该位置。

### 返回值

### 示例

示例 #1 在文件中定位

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR);

    dio_seek($fd, 10, SEEK_SET);
    // position is now at 10 characters from the start of the file

    dio_seek($fd, -2, SEEK_CUR);
    // position is now at 8 characters from the start of the file

    dio_seek($fd, -5, SEEK_END);
    // position is now at 5 characters from the end of the file

    dio_seek($fd, 10, SEEK_END);
    // position is now at 10 characters past the end of the file.
    // The 10 characters between the end of the file and the current
    // position are filled with zeros.

    dio_close($fd);
    ?>

# dio_stat

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_stat — 获取有关文件描述符 fd 的统计信息

### 说明

function dio_stat(resource `$fd`): array

dio_stat() 返回有关文件描述符的信息。

### 参数

`fd`

  由 dio_open() 返回的文件描述符。

### 返回值

返回带有以下键的关联数组：

- "device" - 设备

- "inode" - inode

- "mode" - 模式

- "nlink" - 硬链接数

- "uid" - 用户 id

- "gid" - 组 id

- "device_type" - 设备类型（如果是 inode 设备）

- "size" - 字节总大小

- "blocksize" - 块大小

- "blocks" - 分配的块个数

- "atime" - 最后访问时间

- "mtime" - 最后修改时间

- "ctime" - 最后变更时间

错误时 dio_stat() 返回 `null`。

# dio_tcsetattr

(PHP 4 >= 4.3.0, PHP 5 < 5.1.0)

dio_tcsetattr — 设置串行端口的终端属性和波特率

### 说明

function dio_tcsetattr(resource `$fd`, array `$options`): bool

dio_tcsetattr() 为打开的 `fd` 设置串行端口的终端属性和波特率。

### 参数

`fd`

  由 dio_open() 返回的文件描述符。

`options`

  当前可用选项：

  - 'baud' - 端口波特率 - 可以是 38400、19200、9600、4800、2400、1800、1200、600、300、200、150、134、110、75 或 50，默认为 9600。

  - 'bits' - 数据位 - 可以是 8、7、6 或 5。默认为 8。

  - 'stop' - 停止位 - 可以是 1 或 2。默认为 1。

  - 'parity' - 可以是 0、1 或 2。默认是 0。

### 返回值

没有返回值。

### 示例

示例 #1 在串口上设置波特率

    <?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 (true) {
        $data = dio_read($fd, 256);
        if ($data !== null && $date !== '') {
            echo $data;
        }
    }

    ?>

### 注释

> 注意: 此函数未在 Windows 平台下实现。

# dio_truncate

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_truncate — 截断文件描述符 fd 为 offset 字节

### 说明

function dio_truncate(resource `$fd`, int `$offset`): bool

dio_truncate() 将文件截断为最多 `offset` 字节的大小。

如果先前的文件大于此大小，则额外的数据将丢失。如果先前的文件较小，不确定是保持文件不变还是扩展文件。在后一种情况下，扩展部分读取为零字节。

### 参数

`fd`

  由 dio_open() 返回的文件描述符。

`offset`

  偏移字节。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 注释

> 注意: 此函数未在 Windows 平台下实现。

# dio_write

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_write — 截取可选长度的数据写入文件

### 说明

function dio_write(resource `$fd`, string `$data`, int `$len` = 0): int

dio_write() 从 `data` 写入至多 `len` 字节数据到文件 `fd`。

### 参数

`fd`

  由 dio_open() 返回的文件描述符。

`data`

  写入的数据。

`len`

  从数据中写入的字节长度。如果没有指定，函数将所有数据写入指定的文件。

### 返回值

返回写入 `fd` 的字节数。

### 参见

- dio_read() - 从文件描述符读取字节

## 目录

- dio_close — 通过 fd 关闭文件描述符
- dio_fcntl — 在 fd 上执行 C 标准库的 fcntl
- dio_open — 在 C 库输入/输出流函数允许的更低级别打开（必要时创建）文件
- dio_read — 从文件描述符读取字节
- dio_seek — 在 fd 指定 pos 位置
- dio_stat — 获取有关文件描述符 fd 的统计信息
- dio_tcsetattr — 设置串行端口的终端属性和波特率
- dio_truncate — 截断文件描述符 fd 为 offset 字节
- dio_write — 截取可选长度的数据写入文件

- 安装/配置
  - 安装
  - 资源类型
- 预定义常量
- Direct IO 函数
  - dio_close — 通过 fd 关闭文件描述符
  - dio_fcntl — 在 fd 上执行 C 标准库的 fcntl
  - dio_open — 在 C 库输入/输出流函数允许的更低级别打开（必要时创建）文件
  - dio_read — 从文件描述符读取字节
  - dio_seek — 在 fd 指定 pos 位置
  - dio_stat — 获取有关文件描述符 fd 的统计信息
  - dio_tcsetattr — 设置串行端口的终端属性和波特率
  - dio_truncate — 截断文件描述符 fd 为 offset 字节
  - dio_write — 截取可选长度的数据写入文件

# 目录

# 预定义常量

`DIRECTORY_SEPARATOR` (string)
`PATH_SEPARATOR` (string)
  Windows 上使用分号，除此之外使用冒号。
`SCANDIR_SORT_ASCENDING` (int)
`SCANDIR_SORT_DESCENDING` (int)
`SCANDIR_SORT_NONE` (int)

# Directory 类

(PHP 4, PHP 5, PHP 7, PHP 8)

## 简介

Directory 实例是通过调用 dir() 函数创建的，而不是 new 操作符。

## 类摘要

final class Directory {
/* 属性 */
public readonly string $path;
public readonly resource $handle;
/* 方法 */
public function close(): void
public function read(): string|false
public function rewind(): void
}

## 属性

path

  被打开目录的地址。

handle

  目录句柄。可以被其他的目录操作函数使用，例如 readdir()、rewinddir() 和 closedir()。

## 更新日志

版本 | 说明
--- | ---
8.5.0 | 该类现为最终类。
8.1.0 | 现在 path 和 handle 属性是只读的。

# Directory::close

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::close — 关闭目录句柄

### 说明

public function Directory::close(): void

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 不接受任何参数。在此之前，目录句柄可以作为参数传递。

# Directory::read

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::read — 从目录句柄中读取条目

### 说明

public function Directory::read(): string|false

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 不接受任何参数。在此之前，目录句柄可以作为参数传递。

# Directory::rewind

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::rewind — 倒回目录句柄

### 说明

public function Directory::rewind(): void

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 不接受任何参数。在此之前，目录句柄可以作为参数传递。

## 目录

- Directory::close — 关闭目录句柄
- Directory::read — 从目录句柄中读取条目
- Directory::rewind — 倒回目录句柄

# 目录函数函数

# 参见

相关函数，例如：dirname()、 is_dir()、 mkdir() 和 rmdir()， 请查看文件系统章节。

# chdir

(PHP 4, PHP 5, PHP 7, PHP 8)

chdir — 改变目录

### 说明

function chdir(string `$directory`): bool

将 PHP 的当前目录改为 `directory`。

### 参数

`directory`

  新的当前目录

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

Throws an error of level `E_WARNING` on failure.

### 示例

示例 #1 chdir() 例子

    <?php

    // current directory
    echo getcwd() . "\n";

    chdir('public_html');

    // current directory
    echo getcwd() . "\n";

    ?>

以上示例的输出类似于：

    /home/vincent
    /home/vincent/public_html

### 注释

警告

If the PHP interpreter has been built with ZTS (Zend Thread Safety) enabled, any changes to the current directory made through chdir() will be invisible to the operating system. All built-in PHP functions will still respect the change in current directory; but external library functions called using FFI will not. You can tell whether your copy of PHP was built with ZTS enabled using php -i or the built-in constant `PHP_ZTS`.

### 参见

- getcwd() - 取得当前工作目录

# chroot

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

chroot — 改变根目录

### 说明

function chroot(string `$directory`): bool

将当前进程的根目录改变为 `directory`。

本函数仅在系统支持且运行于 CLI，CGI 或嵌入 SAPI 版本时才能正确工作。此外本函数还需要 root 权限。

调用此函数不会改变 `__DIR__` 和 `__FILE__` 魔术常量的值。

### 参数

`directory`

  新目录

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 chroot() example

    <?php
    chroot("/path/to/your/chroot/");
    echo getcwd();
    ?>

以上示例会输出：

    /

### 注释

> 注意: 此函数未在 Windows 平台下实现。

> 注意: 此函数未在 ZTS (Zend Thread Safety) PHP 解释器中实现。确认你的 PHP 版本，可以在命令行输入 php -i 来查看是否包含 `PHP_ZTS` 常量。

# closedir

(PHP 4, PHP 5, PHP 7, PHP 8)

closedir — 关闭目录句柄

### 说明

function closedir(?resource `$dir_handle` = `null`): void

关闭由 `dir_handle` 指定的目录流。

### 参数

`dir_handle`
  先前通过 opendir() 打开的目录句柄 resource。如果 `dir_handle` 为 `null`，则使用最近一次通过 opendir() 打开的句柄。

### 返回值

没有返回值。

### 更新日志

版本 | 说明
--- | ---
8.5.0 | 现在已弃用将 `dir_handle` 设为 `null` 的做法，应明确提供最近打开的目录句柄。
8.0.0 | `dir_handle` 现在可为 null。

### 示例

完整示例请参见 opendir() 的文档。

### 参见

- opendir() - 打开目录句柄
- readdir() - 从目录句柄中读取条目
- rewinddir() - 倒回目录句柄
- dir() - 返回一个 Directory 类实例
- is_dir() - 判断给定文件名是否是一个目录
- glob() - 寻找与模式匹配的文件路径
- scandir() - 列出指定路径中的文件和目录

# dir

(PHP 4, PHP 5, PHP 7, PHP 8)

dir — 返回一个 Directory 类实例

### 说明

function dir(string `$directory`, ?resource `$context` = `null`): Directory|false

以面向对象的方式访问目录。打开 `directory` 参数指定的目录。

### 参数

`directory`

  被打开的目录

`context`
  上下文流（context stream） resource。

### 返回值

返回 Directory 的实例，出现错误时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `context` 现在可为空（nullable）。

### 示例

示例 #1 dir() 示例

请特别注意下面示例中 Directory::read() 函数返回值的判断方式。 我们严格测试（值相等，并且类型相同，请参考 比较运算符 ）返回值等于 `false` ，因为有些情况下，目录名可能"等于" `false` ，导致 跳出循环。

    <?php
    $d = dir("/etc/php5");
    echo "Handle: " . $d->handle . "\n";
    echo "Path: " . $d->path . "\n";
    while (false !== ($entry = $d->read())) {
       echo $entry."\n";
    }
    $d->close();
    ?>

以上示例的输出类似于：

    Handle: Resource id #2
    Path: /etc/php5
    .
    ..
    apache
    cgi
    cli

### 注释

> 注意:

> 目录条目返回的顺序依赖于系统。

# getcwd

(PHP 4, PHP 5, PHP 7, PHP 8)

getcwd — 取得当前工作目录

### 说明

function getcwd(): string|false

取得当前工作目录。

### 参数

此函数没有参数。

### 返回值

成功则返回当前工作目录，失败返回 `false`。

在某些 Unix 的变种下，如果任何父目录没有设定可读或搜索模式，即使当前目录设定了，getcwd() 还是会返回 `false`。有关模式与权限的更多信息见 chmod()。

### 示例

示例 #1 getcwd() 例子

    <?php

    // 当前目录
    echo getcwd() . "\n";

    chdir('cvs');

    // 当前目录
    echo getcwd() . "\n";

    ?>

以上示例的输出类似于：

    /home/didou
    /home/didou/cvs

### 注释

警告

如果是启用 ZTS（Zend 线程安全）构建的 PHP 解释器，则 getcwd() 返回的当前工作目录可能与操作系统接口返回的不同。当前工作目录的外部库依赖（通过 FFI 调用）可能会受到影响。

### 参见

- chdir() - 改变目录
- chmod() - 改变文件模式

# opendir

(PHP 4, PHP 5, PHP 7, PHP 8)

opendir — 打开目录句柄

### 说明

function opendir(string `$directory`, ?resource `$context` = `null`): resource|false

打开一个目录句柄，可用于之后的 closedir()，readdir() 和 rewinddir() 调用中。

### 参数

`directory`
  要打开的目录路径。
`context`
  `context` 参数的说明见手册中的 Streams API 一章。

### 返回值

成功时返回目录句柄， 或者在失败时返回 `false`。

### 错误／异常

失败时抛出 `E_WARNING` 警告。

如果 `directory` 不是有效的目录，由于权限不足或文件系统错误而无法打开目录，则可能会发生这种情况。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `context` 允许为 null。

### 示例

示例 #1 列出目录中的所有条目，跳过特殊目录 `.` 和 `..`

由于文件和目录名称可能是 PHP 视为“假值”的字符串（例如名为 `"0"` 的目录），而 readdir() 在读取完目录中所有条目后会返回 `false`，因此需使用 `===` 比较运算符，才能准确区分名称为“假值”的目录条目与已读取完所有目录条目的情况。

    <?php

    if ($handle = opendir('/path/to/files')) {
        echo "Entries:\n";

        /* 正确处理可能会视为假值的目录条目 */
        while (false !== ($entry = readdir($handle))) {
            if ($entry === '.' || $entry === '..') {
                continue;
            }
            echo "$entry\n";
        }

        closedir($handle);
    }
    ?>

以上示例的输出类似于：

    Entries:
    base
    en
    fr
    output.md
    test.php

### 参见

- readdir() - 从目录句柄中读取条目
- rewinddir() - 倒回目录句柄
- closedir() - 关闭目录句柄
- dir() - 返回一个 Directory 类实例
- is_dir() - 判断给定文件名是否是一个目录
- glob() - 寻找与模式匹配的文件路径
- scandir() - 列出指定路径中的文件和目录

# readdir

(PHP 4, PHP 5, PHP 7, PHP 8)

readdir — 从目录句柄中读取条目

### 说明

function readdir(?resource `$dir_handle` = `null`): string|false

返回目录中下一个文件的文件名。文件名以在文件系统中的排序返回。

### 参数

`dir_handle`
  先前通过 opendir() 打开的目录句柄 resource。如果 `dir_handle` 为 `null`，则使用最近一次通过 opendir() 打开的句柄。

### 返回值

成功则返回文件名 或者在失败时返回 `false`

警告

此函数可能返回布尔值 `false`，但也可能返回等同于 `false` 的非布尔值。请阅读 布尔类型章节以获取更多信息。应使用 === 运算符来测试此函数的返回值。

### 更新日志

版本 | 说明
--- | ---
8.5.0 | 现在已弃用将 `dir_handle` 设为 `null` 的做法，应明确提供最近打开的目录句柄。
8.0.0 | 现在 `dir_handle` 可以为 null。

### 示例

完整示例请参见 opendir() 的文档。

### 参见

- opendir() - 打开目录句柄
- rewinddir() - 倒回目录句柄
- closedir() - 关闭目录句柄
- dir() - 返回一个 Directory 类实例
- is_dir() - 判断给定文件名是否是一个目录
- glob() - 寻找与模式匹配的文件路径
- scandir() - 列出指定路径中的文件和目录

# rewinddir

(PHP 4, PHP 5, PHP 7, PHP 8)

rewinddir — 倒回目录句柄

### 说明

function rewinddir(?resource `$dir_handle` = `null`): void

将 `dir_handle` 指定的目录流重置到目录的开头。

### 参数

`dir_handle`
  先前通过 opendir() 打开的目录句柄 resource。如果 `dir_handle` 为 `null`，则使用最近一次通过 opendir() 打开的句柄。

### 返回值

没有返回值。

### 更新日志

版本 | 说明
--- | ---
8.5.0 | 现在已弃用将 `dir_handle` 设为 `null` 的做法，应明确提供最近打开的目录句柄。
8.0.0 | 现在 `dir_handle` 现在允许为 null。

### 示例

完整示例请参见 opendir() 的文档。

### 参见

- opendir() - 打开目录句柄
- readdir() - 从目录句柄中读取条目
- closedir() - 关闭目录句柄
- dir() - 返回一个 Directory 类实例
- is_dir() - 判断给定文件名是否是一个目录
- glob() - 寻找与模式匹配的文件路径
- scandir() - 列出指定路径中的文件和目录

# scandir

(PHP 5, PHP 7, PHP 8)

scandir — 列出指定路径中的文件和目录

### 说明

function scandir(string `$directory`, int `$sorting_order` = `SCANDIR_SORT_ASCENDING`, ?resource `$context` = `null`): array|false

返回 array，包含有 `directory` 中的文件和目录。

### 参数

`directory`

  要被浏览的目录

`sorting_order`

  默认的排序顺序是按字母升序排列。如果使用了可选参数 `sorting_order`（设为 1），则排序顺序是按字母降序排列。

`context`

  `context` 参数的说明见手册中的 Streams API 一章。

### 返回值

成功则返回包含有文件名的 array，如果失败则返回 `false`。如果 `directory` 不是个目录，则返回布尔值 `false` 并生成一条 `E_WARNING` 级的错误。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `context` 允许为 null。

### 示例

示例 #1 简单的 scandir() 示例

    <?php
    $dir    = '/tmp';
    $files1 = scandir($dir);
    $files2 = scandir($dir, SCANDIR_SORT_DESCENDING);

    print_r($files1);
    print_r($files2);
    ?>

以上示例的输出类似于：

    Array
    (
        [0] => .
        [1] => ..
        [2] => bar.php
        [3] => foo.txt
        [4] => somedir
    )
    Array
    (
        [0] => somedir
        [1] => foo.txt
        [2] => bar.php
        [3] => ..
        [4] => .
    )

### 注释

小技巧

如已启用fopen 包装器，在此函数中， URL 可作为文件名。关于如何指定文件名详见 fopen()。各种 wapper 的不同功能请参见 支持的协议和封装协议，注意其用法及其可提供的预定义变量。

### 参见

- opendir() - 打开目录句柄
- readdir() - 从目录句柄中读取条目
- glob() - 寻找与模式匹配的文件路径
- is_dir() - 判断给定文件名是否是一个目录
- sort() - 对数组升序排序

## 目录

- chdir — 改变目录
- chroot — 改变根目录
- closedir — 关闭目录句柄
- dir — 返回一个 Directory 类实例
- getcwd — 取得当前工作目录
- opendir — 打开目录句柄
- readdir — 从目录句柄中读取条目
- rewinddir — 倒回目录句柄
- scandir — 列出指定路径中的文件和目录

- 预定义常量
- Directory — Directory 类
  - Directory::close — 关闭目录句柄
  - Directory::read — 从目录句柄中读取条目
  - Directory::rewind — 倒回目录句柄
- 目录函数函数
  - chdir — 改变目录
  - chroot — 改变根目录
  - closedir — 关闭目录句柄
  - dir — 返回一个 Directory 类实例
  - getcwd — 取得当前工作目录
  - opendir — 打开目录句柄
  - readdir — 从目录句柄中读取条目
  - rewinddir — 倒回目录句柄
  - scandir — 列出指定路径中的文件和目录

# 文件信息

# 简介

本模块中的函数通过在文件的给定位置查找特定的 魔术 字节序列 来猜测文件的内容类型以及编码。 虽然不是百分百的精确， 但是通常情况下能够很好的工作。

# 安装/配置

## 目录

- 安装
- 资源类型

## 安装

扩展默认开启。

Windows 用户需要在 php.ini 中开启绑定的 php_fileinfo.dll DLL 来启用本扩展。

PHP 中绑定了 libmagic 库，某些 PHP 版本变更中也可能包含此库。在 PHP fileinfo 扩展的源代码中，有 libmagic.patch 文件，这是 libmagic 库的补丁包文件。

## 资源类型

在 PHP 8.1.0 之前，Fileinfo 扩展中用到了 1 个资源：finfo_open() 返回的魔数数据库文件描述符。

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`FILEINFO_NONE` (int)
  无特殊处理。
`FILEINFO_SYMLINK` (int)
  跟随符号链接。
`FILEINFO_MIME_TYPE` (int)
  返回 mime 类型。 自 PHP 5.3.0 可用。
`FILEINFO_MIME_ENCODING` (int)
  返回文件的 mime 编码。
`FILEINFO_MIME` (int)
  按照 RFC 2045 定义的格式返回文件 mime 类型和编码。
`FILEINFO_COMPRESS` (int)
  解压缩文件。 由于线程安全问题而禁用。
`FILEINFO_DEVICES` (int)
  查看设备的块内容或字符。
`FILEINFO_CONTINUE` (int)
  返回全部匹配的类型。
`FILEINFO_PRESERVE_ATIME` (int)
  如果可以的话，尽可能保持原始的访问时间。
`FILEINFO_RAW` (int)
  对于不可打印字符不转换成 `\ooo` 八进制表示格式。
`FILEINFO_EXTENSION` (int)
  根据在文件中检测到的 MIME 类型返回适当的文件扩展名。 有的文件类型具有多种扩展名，例如 `JPEG` 将会返回多个扩展名，以斜线分隔，比如 `"jpeg/jpg/jpe/jfif"`。如果在 magic.mime 数据库里类型未知，则返回的是 `"???"`。 PHP 7.2.0 起有效。
`FILEINFO_APPLE` (int)
  返回 Apple 创建者和类型。

# Fileinfo 函数

# finfo_buffer

# finfo::buffer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_buffer -- finfo::buffer — 返回一个字符串缓冲区的信息

### 说明

过程化风格

function finfo_buffer(
finfo `$finfo`,
string `$string`,
int `$flags` = `FILEINFO_NONE`,
?resource `$context` = `null`
): string|false

面向对象风格

public function finfo::buffer(string `$string`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

本函数用来获取字符串中二进制数据的信息。

### 参数

`finfo`
  经 finfo_open() 返回的 finfo 实例。
`string`
  要检查的文件内容。
`flags`
  一个 Fileinfo 常量 或多个 Fileinfo 常量 进行逻辑或运算。
`context`

### 返回值

返回 `string` 参数所指定内容的类型描述。 发生错误时返回 `false` 。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | `finfo` 参数现在接受 finfo 实例，之前接受 resource。
8.0.0 | `context` 现在可以为 null。

### 示例

示例 #1 finfo_buffer() 示例

    <?php
    $finfo = new finfo(FILEINFO_MIME);
    echo $finfo->buffer($_POST["script"]) . "\n";
    ?>

以上示例的输出类似于：

    application/x-sh; charset=us-ascii

### 参见

- finfo_file() - 返回一个文件的信息

# finfo_close

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_close — 关闭 finfo 实例

警告

此函数自 PHP 8.5.0 起弃用。强烈建议不要应用此函数。

### 说明

#[\Deprecated]
function finfo_close(finfo `$finfo`): true

此函数用于关闭由 finfo_open() 打开的实例，直到 PHP 7.4， 但自 PHP 8.0 以来，由于 finfo 资源到对象的转换， 此函数已成为无操作，并且在 PHP 8.5 中已被弃用。

### 参数

`finfo`
  经 finfo_open() 返回的 finfo 实例。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.5.0 | 此函数已被弃用。
8.5.0 | 返回类型现在是 `true`；之前是 bool。
8.1.0 | 此函数现在是 NOP（空操作）。
8.1.0 | `finfo` 参数现在接受 finfo 实例，之前接受 resource。

# finfo_file

# finfo::file

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_file -- finfo::file — 返回一个文件的信息

### 说明

过程化风格

function finfo_file(
finfo `$finfo`,
string `$filename`,
int `$flags` = `FILEINFO_NONE`,
?resource `$context` = `null`
): string|false

面向对象风格

public function finfo::file(string `$filename`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

本函数用来获取一个文件的信息。

### 参数

`finfo`
  经 finfo_open() 返回的 finfo 实例。
`filename`
  要检查的文件名。
`flags`
  一个 Fileinfo 常量或多个进行逻辑或。
`context`
  关于 `contexts` 的更多描述，请参考 Stream 函数。

### 返回值

返回 `filename` 参数指定的文件信息。发生错误时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | `finfo` 参数现在接受 finfo 实例，之前接受 resource。
8.0.0 | `context` 现在可以为 null。

### 示例

示例 #1 finfo_file() 示例

    <?php
    $finfo = finfo_open(FILEINFO_MIME_TYPE); // 返回 mime 类型，也被称为 mime 类型扩展。
    foreach (glob("*") as $filename) {
        echo finfo_file($finfo, $filename) . "\n";
    }
    finfo_close($finfo);
    ?>

以上示例的输出类似于：

    text/html
    image/gif
    application/vnd.ms-excel

### 参见

- finfo_buffer() - 返回一个字符串缓冲区的信息

# finfo_open

# finfo::__construct

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_open -- finfo::__construct — 创建新 finfo 实例

### 说明

过程化风格

function finfo_open(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`): finfo|false

面向对象风格（构造器）：

public function finfo::__construct(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`)

本函数打开一个魔数数据库并且返回它的实例。

### 参数

`flags`
  一个 Fileinfo 常量 或多个 Fileinfo 常量 进行逻辑或运算。
`magic_database`
  魔数数据库文件名称， 通常是 /path/to/magic.mime。 如果未指定，则使用 `MAGIC` 环境变量。 如果未指定此环境变量， 则使用 PHP 绑定的魔数数据库。 传入 `null` 或者空字符串，等同于使用默认值。

### 返回值

（仅适用于过程化风格） 成功时返回 finfo 实例， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在返回 finfo 实例，之前返回 resource。
8.0.3 | `magic_database` 现在可以为 null。

### 示例

示例 #1 面向对象风格

    <?php
    $finfo = new finfo(FILEINFO_MIME, "/usr/share/misc/magic"); // 返回 mime 类型

    /* get mime-type for a specific file */
    $filename = "/usr/local/something.txt";
    echo $finfo->file($filename);

    ?>

示例 #2 过程化风格

    <?php
    $finfo = finfo_open(FILEINFO_MIME, "/usr/share/misc/magic"); // 返回 mime 类型

    if (!$finfo) {
        echo "Opening fileinfo database failed";
        exit();
    }

    /* 获取指定文件的 mime 类型 */
    $filename = "/usr/local/something.txt";
    echo finfo_file($finfo, $filename);

    /* 关闭资源 */
    finfo_close($finfo);
    ?>

以上示例会输出：

    text/plain; charset=us-ascii

### 注释

> 注意: 通常来说，除非特别需要自定义的魔数数据库。否则使用绑定的魔数数据库（不设置 `magic_file` 和 `MAGIC` 环境变量）是最好的做法。

### 参见

- finfo_close() - 关闭 finfo 实例

# 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 — 设置 libmagic 配置选项

### 说明

过程化风格

function finfo_set_flags(finfo `$finfo`, int `$flags`): true

面向对象风格

public function finfo::set_flags(int `$flags`): true

此函数用来设置 Fileinfo 选项。 这些选项也可以在调用 finfo_open() 或者其他 Fileinfo 函数时直接指定。

### 参数

`finfo`
  经 finfo_open() 返回的 finfo 实例。
`flags`
  一个 Fileinfo 常量 或多个 Fileinfo 常量 进行逻辑或运算。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | `finfo` 参数现在接受 finfo 实例，之前接受 resource。

# mime_content_type

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mime_content_type — 检测文件的 MIME 类型

### 说明

function mime_content_type(resource|string `$filename`): string|false

返回通过使用 magic.mime 检测到的文件 MIME 类型。

### 参数

`filename`
  要检测的文件名。

### 返回值

返回文件的 MIME 内容类型，例如 `text/plain` 或 `application/octet-stream`。 或者在失败时返回 `false`。

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 示例

示例 #1 mime_content_type() 示例

    <?php
    echo mime_content_type('php.gif') . "\n";
    echo mime_content_type('test.php');
    ?>

以上示例会输出：

    image/gif
    text/plain

### 参见

- finfo_file() - 返回一个文件的信息
- finfo_buffer() - 返回一个字符串缓冲区的信息

## 目录

- finfo_buffer — 返回一个字符串缓冲区的信息
- finfo_close — 关闭 finfo 实例
- finfo_file — 返回一个文件的信息
- finfo_open — 创建新 finfo 实例
- finfo_set_flags — 设置 libmagic 配置选项
- mime_content_type — 检测文件的 MIME 类型

# finfo 类

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

## 简介

该类在 fileinfo 函数集中提供了一个面向对象的接口。

## 类摘要

class finfo {
/* 方法 */
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 — 别名 finfo_buffer()

### 说明

public function finfo::buffer(string `$string`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

此函数是该函数的别名： finfo_buffer()

# finfo::__construct

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::__construct — 别名 finfo_open()

### 说明

public function finfo::__construct(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`)

此函数是该函数的别名： finfo_open()

### 更新日志

版本 | 说明
--- | ---
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 — 别名 finfo_file()

### 说明

public function finfo::file(string `$filename`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

此函数是该函数的别名： finfo_file()

# finfo::set_flags

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::set_flags — 别名 finfo_set_flags()

### 说明

public function finfo::set_flags(int `$flags`): true

此函数是该函数的别名： finfo_set_flags()

## 目录

- finfo::buffer — 别名 finfo_buffer()
- finfo::__construct — 别名 finfo_open
- finfo::file — 别名 finfo_file()
- finfo::set_flags — 别名 finfo_set_flags()

- 安装/配置
  - 安装
  - 资源类型
- 预定义常量
- Fileinfo 函数
  - finfo_buffer — 返回一个字符串缓冲区的信息
  - finfo_close — 关闭 finfo 实例
  - finfo_file — 返回一个文件的信息
  - finfo_open — 创建新 finfo 实例
  - finfo_set_flags — 设置 libmagic 配置选项
  - mime_content_type — 检测文件的 MIME 类型
- finfo — finfo 类
  - finfo::buffer — 别名 finfo_buffer()
  - finfo::__construct — 别名 finfo_open
  - finfo::file — 别名 finfo_file()
  - finfo::set_flags — 别名 finfo_set_flags()

# 文件系统

# 简介

编译此扩展无需任何额外的库，但想要 PHP 支持 Linux 的 LFS（large files），需要最新的 glibc，并在编译 PHP 时带上以下标记： `-D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64`。

# 安装/配置

## 目录

- 运行时配置
- 资源类型

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

文件系统和流配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
allow_url_fopen | "1" | `INI_SYSTEM` |
allow_url_include | "0" | `INI_SYSTEM` | 自 PHP 7.4.0 起废弃。
user_agent | NULL | `INI_ALL` |
default_socket_timeout | "60" | `INI_ALL` |
from | "" | `INI_ALL` |
auto_detect_line_endings | "0" | `INI_ALL` | 自 PHP 8.1.0 起弃用。
sys_temp_dir | "" | `INI_SYSTEM` |

这是配置指令的简短说明。

`allow_url_fopen` bool

  本选项激活了 URL 形式的 fopen 封装协议使得可以访问 URL 对象例如文件。默认的封装协议提供用 ftp 和 http 协议来访问远程文件，一些扩展库例如 zlib 可能会注册更多的封装协议。

`allow_url_include` bool

  This option allows the use of URL-aware fopen wrappers with the following functions: include, include_once, require, require_once.

  > 注意:

  > 这个设置项需要开启 allow_url_fopen 。

`user_agent` string

  定义 PHP 发送的 User-Agent。

`default_socket_timeout` int

  指定基于 socket 的流的默认超时时间（秒）。指定一个负值意味着不会超时。

`from` string

  这个 email 地址在使用 ftp 封装器的时候用于未认证的 FTP 连接，在使用 http 封装器的时候用于 HTTP 连接的消息头中的 From 字段。

`auto_detect_line_endings` bool

  当设为 On 时，PHP 将检查通过 fgets() 和 file() 取得的数据中的行结束符号是符合 Unix，MS-DOS，还是 Macintosh 的习惯。

  这使得 PHP 可以和 Macintosh 系统交互操作，但是默认值是 Off，因为在检测第一行的 EOL 习惯时会有很小的性能损失，而且在 Unix 系统下使用回车符号作为项目分隔符的人们会遭遇向下不兼容的行为。

`sys_temp_dir` string

## 资源类型

文件系统使用 `streams` 作为资源类型。 Streams 的文档有专门的章节：Streams。

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`SEEK_SET` (int)
`SEEK_CUR` (int)
`SEEK_END` (int)
`LOCK_SH` (int)
`LOCK_EX` (int)
`LOCK_UN` (int)
`LOCK_NB` (int)

file() 的可用 `flags`
`FILE_USE_INCLUDE_PATH` (int)
  在 include_path 里搜索 `filename`。
`FILE_NO_DEFAULT_CONTEXT` (int)
`FILE_APPEND` (int)
  为存在的文件添加内容。
`FILE_IGNORE_NEW_LINES` (int)
  过滤换行（EOL）字符。
`FILE_SKIP_EMPTY_LINES` (int)
  过滤空行。
`FILE_BINARY` (int)

  二进制模式。

  警告

  此常量无效，并且自 PHP 8.1.0 起弃用。

`FILE_TEXT` (int)

  文本模式。

  警告

  此常量无效，并且自 PHP 8.1.0 起弃用。

glob() 的可用 `flags`
`GLOB_AVAILABLE_FLAGS` (int)
  所有 `GLOB_*` flag 的组合。等同于 `0` | `GLOB_BRACE` | `GLOB_MARK` | `GLOB_NOSORT` | `GLOB_NOCHECK` | `GLOB_NOESCAPE` | `GLOB_ERR` | `GLOB_ONLYDIR`
`GLOB_BRACE` (int)
  扩展 {a,b,c} 为匹配“a”、“b”或“c”

  > 注意: `GLOB_BRACE` 在一些非 GUN 系统无效，像 Solaris 或 Alpine Linux。

`GLOB_ERR` (int)
  读取错误（如目录无法读取）时停止，默认忽略错误。
`GLOB_MARK` (int)
  向每个返回的目录添加斜线（在 Windows 上为反斜线）
`GLOB_NOCHECK` (int)
  如果没有找到匹配该模式的文件，则返回搜索模式
`GLOB_NOESCAPE` (int)
  反斜线不引用元字符
`GLOB_NOSORT` (int)
  按照目录中出现的顺序返回文件（不排序）。当不使用此 flag 时，路径名按字母顺序排序
`GLOB_ONLYDIR` (int)
  只返回与模式匹配的目录条目

pathinfo() 的可用 `flags`
`PATHINFO_ALL` (int)
  路径信息的所有部分都以关联数组的形式返回。
`PATHINFO_DIRNAME` (int)
  目录或文件的路径。
`PATHINFO_BASENAME` (int)
  目录的名称或文件的名称和扩展名。
`PATHINFO_EXTENSION` (int)
  文件的扩展名。
`PATHINFO_FILENAME` (int)
  文件的名称（不带扩展名）或目录的名称。

parse_ini_file() 和 parse_ini_string() 的可用 `scanner_mode`
`INI_SCANNER_NORMAL` (int)
  普通的 INI 扫描模式。
`INI_SCANNER_RAW` (int)
  原始（Raw） INI 扫描模式。
`INI_SCANNER_TYPED` (int)
  Typed INI 扫描模式。

fnmatch() 的可用 `flags`
`FNM_NOESCAPE` (int)
  禁用反斜线转义
`FNM_PATHNAME` (int)
  字符串里的斜杠只匹配指定模式里的斜杠。
`FNM_PERIOD` (int)
  字符串里的起始点号必须完全匹配指定模式里的点号。
`FNM_CASEFOLD` (int)
  大小写不敏感的匹配，GNU 扩展的一部分。

PHP 文件上传常量
`UPLOAD_ERR_CANT_WRITE` (int)

  文件无法写入磁盘。常量值为 `7`。

`UPLOAD_ERR_EXTENSION` (int)

  PHP 扩展程序停止了文件上传。PHP 没有提供确定是哪个扩展程序导致文件上传停止的方法；使用 phpinfo() 检查已加载扩展程序的列表可能会有所帮助。常量的值为 `8`。

`UPLOAD_ERR_FORM_SIZE` (int)

  上传的文件超出了 HTML 表单中指定的 MAX_FILE_SIZE 指令。常量的值为 `2`。

`UPLOAD_ERR_INI_SIZE` (int)

  上传的文件超出了 php.ini 中 upload_max_filesize 命令的大小。该常量的值是 `1`。

`UPLOAD_ERR_NO_FILE` (int)

  未上传任何文件。常量值为 `4`。

`UPLOAD_ERR_NO_TMP_DIR` (int)

  缺少临时文件夹。常量的值为 `6`。

`UPLOAD_ERR_OK` (int)

  没有错误，文件上传成功。常量值为 `0`。

`UPLOAD_ERR_PARTIAL` (int)

  上传的文件仅部分上传。常量值为 `3`。

# 文件系统函数

# 参见

相关函数参见目录和程序执行章节。

远程文件能使用的 URL 包装器（ wrapper）列表和详细解释，可参见 支持的协议和封装协议。

# basename

(PHP 4, PHP 5, PHP 7, PHP 8)

basename — 返回路径中的文件名部分

### 说明

function basename(string `$path`, string `$suffix` = ""): string

给出一个包含有指向一个文件的全路径的字符串，本函数返回基本的文件名。

> 注意:

> basename() 纯粹基于输入字符串操作， 它不会受实际文件系统和类似 "`..`" 的路径格式影响。

警告

basename() 是本地化的，所以如果要正确处理多字节字符的路径，需要用 setlocale() 正确设置匹配的 locale。如果 `path` 包含当前区域设置无效的字符，basename() 的行为未定义。

### 参数

`path`

  一个路径。

  在 Windows 中，斜线（`/`）和反斜线（`\`）都可以用作目录分隔符。在其它环境下是斜线（`/`）。

`suffix`

  如果文件名是以 `suffix` 结束的，那这一部分也会被去掉。

### 返回值

返回指定 `path` 的基本名称。

### 示例

示例 #1 basename() 例子

    <?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("/");
    ?>

以上示例会输出：

    1) sudoers
    2) sudoers.d
    3) passwd
    4) etc
    5) .
    6)

### 参见

- dirname() - 返回路径中的目录部分
- pathinfo() - 返回文件路径的信息

# chgrp

(PHP 4, PHP 5, PHP 7, PHP 8)

chgrp — 改变文件所属的组

### 说明

function chgrp(string `$filename`, string|int `$group`): bool

尝试将文件 `filename` 所属的组改成 `group`（通过组名或组 ID 指定）。

只有超级用户可以任意修改文件的组，其它用户可能只能将文件的组改成该用户自己所在的组。

### 参数

`filename`

  文件的路径。

`group`

  组的名称或数字。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 改变文件所属的组

    <?php
    $filename = 'shared_file.txt';
    $format = "%s's Group ID @ %s: %d\n";
    printf($format, $filename, date('r'), filegroup($filename));
    chgrp($filename, 8);
    clearstatcache(); // 不要缓存 filegroup() 结果
    printf($format, $filename, date('r'), filegroup($filename));
    ?>

### 注释

> 注意: 此函数不能作用于远程文件，被检查的文件必须是可通过服务器的文件系统访问的。

> 注意: 在 Windows 上，此函数应用在常规文件时会默默失败。

### 参见

- chown() - 改变文件的所有者
- chmod() - 改变文件模式

# chmod

(PHP 4, PHP 5, PHP 7, PHP 8)

chmod — 改变文件模式

### 说明

function chmod(string `$filename`, int `$permissions`): bool

尝试将 `filename` 所指定文件的模式改成 `permissions` 所给定的。

### 参数

`filename`

  文件的路径。

`permissions`

  注意 `permissions` 不会被自动当成八进制数值，因此为确保正确操作，需要给 `permissions` 前面加上 0。诸如“g+w”之类的字符串将无法正常工作。

      <?php
      chmod("/somedir/somefile", 755);   // 十进制数，可能不对
      chmod("/somedir/somefile", "u+rwx,go+rx"); // 字符串，不对
      chmod("/somedir/somefile", 0755);  // 八进制数，正确的 mode 值
      ?>

  `permissions` 参数包含三个八进制数按顺序分别指定了所有者、所有者所在的组以及所有人的访问限制。每一部分都可以通过加入所需的权限来计算出所要的权限。数字 1 表示使文件可执行，数字 2 表示使文件可写，数字 4 表示使文件可读。加入这些数字来制定所需要的权限。有关 UNIX 系统的文件权限可以阅读手册“man 1 chmod”和“man 2 chmod”。

      <?php
      // 所有者可以读写，其他人什么也不能做
      chmod("/somedir/somefile", 0600);

      // 所有者可以读写，其他人可以读
      chmod("/somedir/somefile", 0644);

      // 所有者可以读写执行，其他人可以读和执行
      chmod("/somedir/somefile", 0755);

      // 所有者可以读写执行，所有者同组可以读和执行
      chmod("/somedir/somefile", 0750);
      ?>

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

失败时会发出 `E_WARNING`。

### 注释

> 注意:

> 当前用户指的是执行 PHP 的用户。很可能和通常访问 shell 或者 FTP 的用户不是同一个。在大多数系统下文件模式只能被拥有该文件的用户改变。

> 注意: 此函数不能作用于远程文件，被检查的文件必须是可通过服务器的文件系统访问的。

### 参见

- chown() - 改变文件的所有者
- chgrp() - 改变文件所属的组
- fileperms() - 获取文件权限
- stat() - 给出文件的信息

# chown

(PHP 4, PHP 5, PHP 7, PHP 8)

chown — 改变文件的所有者

### 说明

function chown(string `$filename`, string|int `$user`): bool

尝试将文件 `filename` 的所有者改成用户 `user`（由用户名或用户 ID 指定）。 只有超级用户可以改变文件的所有者。

### 参数

`filename`

  文件路径。

`user`

  用户名或数字。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 简单的 chown() 用法

    <?php

    // 要使用的文件名和用户名
    $file_name= "foo.php";
    $path = "/home/sites/php.net/public_html/sandbox/" . $file_name ;
    $user_name = "root";

    // 设置用户
    chown($path, $user_name);

    // 检测结果
    $stat = stat($path);
    print_r(posix_getpwuid($stat['uid']));

    ?>

以上示例的输出类似于：

    Array
    (
        [name] => root
        [passwd] => x
        [uid] => 0
        [gid] => 0
        [gecos] => root
        [dir] => /root
        [shell] => /bin/bash
    )

### 注释

> 注意: 此函数不能作用于远程文件，被检查的文件必须是可通过服务器的文件系统访问的。

> 注意: 在 Windows 上对普通文件使用此函数会静默失败。

### 参见

- chmod() - 改变文件模式
- chgrp() - 改变文件所属的组

# clearstatcache

(PHP 4, PHP 5, PHP 7, PHP 8)

clearstatcache — 清除文件状态缓存

### 说明

function clearstatcache(bool `$clear_realpath_cache` = `false`, string `$filename` = ""): void

当使用 stat()，lstat() 或者任何列在受影响函数表（见下面）中的函数时，PHP 将缓存这些函数的返回信息以提供更快的性能。然而在某些情况下，你可能想清除被缓存的信息。例如如果在一个脚本中多次检查同一个文件，而该文件在此脚本执行期间有被删除或修改的危险时，你需要清除文件状态缓存。这种情况下，可以用 clearstatcache() 函数来清除被 PHP 缓存的该文件信息。

必须注意的是，对于不存在的文件，PHP 并不会缓存其信息。所以如果调用 file_exists() 来检查不存在的文件，在该文件没有被创建之前，它都会返回 `false`。如果该文件被创建了，就算以后被删除，它都会返回 `true` 函数 unlink() 会自动清除该缓存.

> 注意:

> 本函数缓存特定文件名的信息，因此只在对同一个文件名进行多次操作并且需要该文件信息不被缓存时才需要调用 clearstatcache()。

受影响的函数包括 stat()， lstat()， file_exists()， is_writable()， is_readable()， is_executable()， is_file()， is_dir()， is_link()， filectime()， fileatime()， filemtime()， fileinode()， filegroup()， fileowner()， filesize()， filetype() 和 fileperms()。

### 参数

`clear_realpath_cache`

  是否也清除真实路径缓存

`filename`

  仅清除指定文件名的真实路径缓存; 只在 `clear_realpath_cache` 为 `true` 时启用。

### 返回值

没有返回值。

### 示例

示例 #1 clearstatcache() 例子

    <?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));
    ?>

以上示例的输出类似于：

    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 — 拷贝文件

### 说明

function copy(string `$from`, string `$to`, ?resource `$context` = `null`): bool

将文件从 `from` 拷贝到 `to`。

如果要移动文件的话，请使用 rename() 函数。

### 参数

`from`

  源文件路径。

`to`

  目标路径。如果 `to` 是一个 URL，则如果封装协议不支持覆盖已有的文件时拷贝操作会失败。

  警告

  如果目标文件已存在，将会被覆盖。

`context`

  A valid context resource created with stream_context_create().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 copy() 例子

    <?php
    $file = 'example.txt';
    $newfile = 'example.txt.bak';

    if (!copy($file, $newfile)) {
        echo "failed to copy $file...\n";
    }
    ?>

### 参见

- move_uploaded_file() - 将上传的文件移动到新位置
- rename() - 重命名一个文件或目录
- The section of the manual about handling file uploads

# delete

(None)

delete — 参见 unlink() 或 unset()

### 说明

在 PHP 语言里，没有 delete 关键词或函数。在这里，你若要删除文件，可以使用 unlink()。在本地作用域删除变量可使用 unset()。

### 参见

- unlink() - 删除文件
- unset() - unset 指定变量

# dirname

(PHP 4, PHP 5, PHP 7, PHP 8)

dirname — 返回路径中的目录部分

### 说明

function dirname(string `$path`, int `$levels` = 1): string

给出一个包含有指向一个文件的全路径的字符串，本函数返回去掉文件名后的目录名，且目录深度为 `levels` 级。

> 注意:

> dirname() 纯粹基于输入字符串操作， 它不会受实际文件系统和类似 "`..`" 的路径格式影响。

警告

在 Windows 上，dirname() 假设当前设置的代码页，因此要查看具有多字节字符路径的正确目录名称，必须设置匹配的代码页。如果 `path` 包含当前代码页无效的字符，则 dirname() 的行为是未定义的。

在其它系统上，dirname() 假设 `path` 是以 ASCII 兼容编码进行编码的。否则函数的行为是未定义的。

### 参数

`path`

  一个路径。

  在 Windows 中，斜线（`/`）和反斜线（`\`）都可以用作目录分隔符。在其它环境下是斜线（`/`）。

`levels`

  要向上的父目录数量。

  整型，必须大于 0。

### 返回值

返回 path 的父目录。如果在 `path` 中没有斜线，则返回一个点（'`.`'），表示当前目录。否则返回的是把 `path` 中结尾的 `/component`（最后一个斜线以及后面部分）去掉之后的字符串。

警告

Be careful when using this function in a loop that can reach the top-level directory as this can result in an infinite loop.

    <?php
    dirname('.');    // Will return '.'.
    dirname('/');    // Will return `\` on Windows and '/' on *nix systems.
    dirname('\\');   // Will return `\` on Windows and '.' on *nix systems.
    dirname('C:\\'); // Will return 'C:\' on Windows and '.' on *nix systems.
    ?>

### 示例

示例 #1 dirname() 例子

    <?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);

以上示例的输出类似于：

    /etc
    / (or \ on Windows)
    .
    C:\
    /usr

### 参见

- basename() - 返回路径中的文件名部分
- pathinfo() - 返回文件路径的信息
- realpath() - 返回规范化的绝对路径名

# disk_free_space

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

disk_free_space — 返回目录中的可用空间

### 说明

function disk_free_space(string `$directory`): float|false

给出一个包含有一个目录的字符串，本函数将根据相应的文件系统或磁盘分区返回可用的字节数。

### 参数

`directory`

  文件系统目录或者磁盘分区。

  > 注意:

  > 如果指定了文件名而不是文件目录，这个函数的行为将并不统一，会因操作系统和 PHP 版本而异。

### 返回值

以浮点返回可用的字节数， 或者在失败时返回 `false`。

### 示例

示例 #1 disk_free_space() 例子

    <?php
    // $df 包含根目录下可用的字节数
    $df = disk_free_space("/");

    //在 Windows 下:
    $df_c = disk_free_space("C:");
    $df_d = disk_free_space("D:");
    ?>

### 注释

> 注意: 此函数不能作用于远程文件，被检查的文件必须是可通过服务器的文件系统访问的。

### 参见

- disk_total_space() - 返回一个目录的磁盘总大小

# disk_total_space

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

disk_total_space — 返回一个目录的磁盘总大小

### 说明

function disk_total_space(string `$directory`): float|false

给出一个包含有一个目录的字符串，本函数将根据相应的文件系统或磁盘分区返回所有的字节数。 【译者注】本函数返回的是该目录所在的磁盘分区的总大小，因此在给出同一个磁盘分区的不同目录作为参数所得到的结果完全相同。 在 Unix 和 Windows 200x/XP 中都支持将一个磁盘分区加载为一个子目录，这时正确使用本函数就很有意义。

### 参数

`directory`

  文件系统的目录或者磁盘分区。

### 返回值

以浮点返回一个目录的磁盘总大小字节数， 或者在失败时返回 `false`。

### 示例

示例 #1 disk_total_space() 例子

    <?php
    // $df 包含 "/" 目录的磁盘大小
    $ds = disk_total_space("/");

    //在 Windows 下:
    $ds = disk_total_space("C:");
    $ds = disk_total_space("D:");
    ?>

### 注释

> 注意: 此函数不能作用于远程文件，被检查的文件必须是可通过服务器的文件系统访问的。

### 参见

- disk_free_space() - 返回目录中的可用空间

# diskfreespace

(PHP 4, PHP 5, PHP 7, PHP 8)

diskfreespace — disk_free_space() 的别名

### 说明

此函数是该函数的别名：disk_free_space()。

# fclose

(PHP 4, PHP 5, PHP 7, PHP 8)

fclose — 关闭一个已打开的文件指针

### 说明

function fclose(resource `$stream`): bool

将 `stream` 指向的文件关闭。

### 参数

`stream`

  文件指针必须有效，并且是通过 fopen() 或 fsockopen() 成功打开的。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 一个简单 fclose() 例子

    <?php

    $handle = fopen('somefile.txt', 'r');

    fclose($handle);

    ?>

### 参见

- fopen() - 打开文件或者 URL
- fsockopen() - 打开 Internet 或者 Unix 套接字连接

# fdatasync

(PHP 8 >= 8.1.0)

fdatasync — 同步文件数据（不包含元数据）

### 说明

function fdatasync(resource `$stream`): bool

此函数同步 `stream` 的内容到存储介质，就像是 fsync() 所做的那样，但不会同步文件元数据。注意，此函数仅在 POSIX 系统中有实际区别。在 Windows 中，是 fsync() 的别名。

### 参数

`stream`
  文件指针必须是有效的，必须指向由 fopen() 或 fsockopen() 成功打开的文件(并还未由 fclose() 关闭)。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 fdatasync() 示例

    <?php

    $file = 'test.txt';

    $stream = fopen($file, 'w');
    fwrite($stream, 'test data');
    fwrite($stream, "\r\n");
    fwrite($stream, 'additional data');

    fdatasync($stream);
    fclose($stream);
    ?>

### 参见

- fflush() - 将缓冲内容输出到文件
- fsync() - 同步文件变更（包括元数据）

# feof

(PHP 4, PHP 5, PHP 7, PHP 8)

feof — 测试文件指针是否到了文件结束的位置

### 说明

function feof(resource `$stream`): bool

测试文件指针是否到了文件结束的位。

### 参数

`stream`
  文件指针必须是有效的，必须指向由 fopen() 或 fsockopen() 成功打开的文件(并还未由 fclose() 关闭)。

### 返回值

如果文件指针到了 EOF 或者出错时则返回 `true`，否则返回一个错误（包括 socket 超时），其它情况则返回 `false`。

### 注释

警告

如果服务器没有关闭由 fsockopen() 所打开的连接，feof() 会一直等待直到超时。要解决这个问题可参见以下范例：

示例 #1 处理 feof() 的超时

    <?php
    function safe_feof($fp, &$start = NULL) {
     $start = microtime(true);

     return feof($fp);
    }

    /* $fp 的赋值是由之前 fsockopen() 打开  */

    $start = NULL;
    $timeout = ini_get('default_socket_timeout');

    while(!safe_feof($fp, $start) && (microtime(true) - $start) < $timeout)
    {
     /* Handle */
    }
    ?>

警告

如果传递的文件指针无效可能会陷入无限循环中，因为 feof() 不会返回 `true`。

示例 #2 使用无效文件指针的 feof() 例子

    <?php
    // 如果文件不可读取或者不存在，fopen 函数返回 FALSE
    $file = @fopen("no_such_file", "r");

    // 来自 fopen 的 FALSE 会发出一条警告信息并在这里陷入无限循环
    while (!feof($file)) {
    }

    fclose($file);
    ?>

# fflush

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

fflush — 将缓冲内容输出到文件

### 说明

function fflush(resource `$stream`): bool

本函数强制将所有缓冲的输出写入 `stream` 文件句柄所指向的资源。 成功时返回 `true`， 或者在失败时返回 `false`。

文件指针必须是有效的，必须指向由 fopen() 或 fsockopen() 成功打开的文件(并还未由 fclose() 关闭)。

### 参数

`stream`
  文件指针必须是有效的，必须指向由 fopen() 或 fsockopen() 成功打开的文件(并还未由 fclose() 关闭)。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

### 参见

- clearstatcache() - 清除文件状态缓存
- fwrite() - 写入文件（可安全用于二进制文件）

# fgetc

(PHP 4, PHP 5, PHP 7, PHP 8)

fgetc — 从文件指针中读取字符

### 说明

function fgetc(resource `$stream`): string|false

从文件句柄中获取一个字符。

### 参数

`stream`
  文件指针必须是有效的，必须指向由 fopen() 或 fsockopen() 成功打开的文件(并还未由 fclose() 关闭)。

### 返回值

返回一个包含有一个字符的字符串，该字符从 `stream` 指向的文件中得到。 碰到 EOF 则返回 `false`。

警告

此函数可能返回布尔值 `false`，但也可能返回等同于 `false` 的非布尔值。请阅读 布尔类型章节以获取更多信息。应使用 === 运算符来测试此函数的返回值。

### 示例

示例 #1 一个 fgetc() 例子

    <?php
    $fp = fopen('somefile.txt', 'r');
    if (!$fp) {
        echo 'Could not open file somefile.txt';
    }
    while (false !== ($char = fgetc($fp))) {
        echo "$char\n";
    }
    ?>

### 注释

> 注意: 此函数可安全用于二进制对象。

### 参见

- fread() - 读取文件（可安全用于二进制文件）
- fopen() - 打开文件或者 URL
- popen() - 打开进程文件指针
- fsockopen() - 打开 Internet 或者 Unix 套接字连接
- fgets() - 从文件指针中读取一行

# fgetcsv

(PHP 4, PHP 5, PHP 7, PHP 8)

fgetcsv — 从文件指针中读入一行并解析 CSV 字段

### 说明

function fgetcsv(
resource `$stream`,
?int `$length` = `null`,
string `$separator` = ",",
string `$enclosure` = "\"",
string `$escape` = "\\"
): array|false

和 fgets() 类似，只除了 fgetcsv() 解析读入的行并找出 CSV 格式的字段然后返回一个包含这些字段的数组。

> 注意:

> 此函数会考虑区域设置。例如，如果 `LC_CTYPE` 为 `en_US.UTF-8`，可能会错误的解析某些单字节编码的数据。

### 参数

`stream`

  一个由 fopen()、popen() 或 fsockopen() 产生的有效文件指针。

`length`

  必须大于在 CVS 文件（允许尾随行尾字符）中找到的最长行（以字符为单位）。否则，该行将拆分为 `length` 字符的块，除非拆分发生在环绕字符内。

  忽略此参数（或者设为 0 或者在 PHP 8.0.0 及以后的版本中设为 `null`）行的最大长度将不受限制，速度稍慢。

`separator`

  可选的 `separator` 参数，设置字段分隔符。必须是单字节字符。

`enclosure`

  可选的 `enclosure` 参数，设置字段环绕符。必须是单字节字符。

`escape`

  可选的 `escape` 参数，设置转义字符。必须是单字节字符或者空字符串。空字符串（`""`）禁用所有的转义机制。

  警告

  在输入流中，`enclosure` 字符在引号字符串内可通过重复自身进行转义，解析后结果中将只保留一个 `enclosure` 字符。而 `escape` 字符的行为有所不同：若输入中出现 `escape` 字符与 `enclosure` 字符的组合序列，这两个字符都会保留在解析结果中。因此，在默认参数下，类似 `"a""b","c\"d"` 的 CSV 行将被解析为两个字段，分别为 `a"b` 和 `c\"d`。

  警告

  从 PHP 8.4.0 开始，弃用依赖 `escape` 的默认值。需要通过位置或使用命名参数明确提供。

警告

当 `escape` 被设置为非空字符串（`""`）时， 可能导致生成的 CSV 不符合 » RFC 4180 的要求， 或者无法通过 PHP CSV 函数的往返处理。 `escape` 的默认值是 `"\\"`，因此建议显式地将其设置为空字符串。 默认值将在未来的 PHP 版本中更改，不早于 PHP 9.0。

### 返回值

成功时返回包含读取字段的索引数组， 或者在失败时返回 `false`。

> 注意:

> CSV 文件中的空行将被返回为一个包含有单个 null 字段的数组，不会被当成错误。

> 注意: 在读取在 Macintosh 电脑中或由其创建的文件时， 如果 PHP 不能正确的识别行结束符，启用运行时配置可选项 auto_detect_line_endings 也许可以解决此问题。

### 错误／异常

如果 `separator` 或者 `enclosure` 长度不是一个字节，则抛出 ValueError。

如果 `escape` 的长度不是一个字节或者为空字符串，则抛出 ValueError。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 现在已弃用依赖 escape 的默认值。
8.3.0 | 如果最后一个字段仅包含未终止的 enclosure，则返回空字符串，而不是带有单个 NULL 字节的字符串。
8.0.0 | 现在 `length` 允许为 null.
7.4.0 | `escape` 参数也接受空字符串来禁用所有的转义机制。

### 示例

示例 #1 读取并显示 CSV 文件的整个内容

    <?php
    $row = 1;
    if (($handle = fopen("test.csv", "r")) !== FALSE) {
        while (($data = fgetcsv($handle, 1000, ",")) !== FALSE) {
            $num = count($data);
            echo "<p> $num fields in line $row: <br /></p>\n";
            $row++;
            for ($c=0; $c < $num; $c++) {
                echo $data[$c] . "<br />\n";
            }
        }
        fclose($handle);
    }
    ?>

### 参见

- fputcsv() - 将行格式化为 CSV 并写入文件指针
- str_getcsv() - 解析 CSV 字符串为一个数组
- 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() - 使用一个字符串分割另一个字符串
- file() - 把整个文件读入一个数组中
- pack() - 将数据打包成二进制字符串

# fgets

(PHP 4, PHP 5, PHP 7, PHP 8)

fgets — 从文件指针中读取一行

### 说明

function fgets(resource `$stream`, ?int `$length` = `null`): string|false

从文件指针中读取一行。

### 参数

`stream`
  文件指针必须是有效的，必须指向由 fopen() 或 fsockopen() 成功打开的文件(并还未由 fclose() 关闭)。
`length`

  从 `handle` 指向的文件中读取一行并返回长度最多为 `length` - 1 字节的字符串。碰到换行符（包括在返回值中）、EOF 或者已经读取了 length - 1 字节后停止（看先碰到那一种情况）。如果没有指定 `length`，则默认为 1K，或者说 1024 字节。

### 返回值

从指针 `stream` 指向的文件中读取了 `length` - 1 字节后返回字符串。 如果文件指针中没有更多的数据了则返回 `false`。

错误发生时返回 `false`。

### 示例

示例 #1 逐行读取文件

    <?php

    $fp = @fopen("/tmp/inputfile.txt", "r");

    if ($fp) {
        while (($buffer = fgets($fp, 4096)) !== false) {
            echo $buffer, PHP_EOL;
        }

        if (!feof($fp)) {
            echo "Error: unexpected fgets() fail\n";
        }

        fclose($fp);
    }

    ?>

### 注释

> 注意: 在读取在 Macintosh 电脑中或由其创建的文件时， 如果 PHP 不能正确的识别行结束符，启用运行时配置可选项 auto_detect_line_endings 也许可以解决此问题。

> 注意:

> 习惯了 C 语言中 fgets() 语法的人应该注意到 `EOF` 是怎样被返回的。

### 参见

- fgetss() - 从文件指针中读取一行并过滤掉 HTML 标记
- fread() - 读取文件（可安全用于二进制文件）
- fgetc() - 从文件指针中读取字符
- stream_get_line() - 从资源流里读取一行直到给定的定界符
- fopen() - 打开文件或者 URL
- popen() - 打开进程文件指针
- fsockopen() - 打开 Internet 或者 Unix 套接字连接
- stream_set_timeout() - Set timeout period on a stream

# fgetss

(PHP 4, PHP 5, PHP 7)

fgetss — 从文件指针中读取一行并过滤掉 HTML 标记

警告

本函数已自 PHP 7.3.0 起弃用，自 PHP 8.0.0 起移除。强烈建议不要依赖本函数。

### 说明

function fgetss(resource `$handle`, int `$length` = ?, string `$allowable_tags` = ?): string

和 fgets() 相同，只除了 fgetss() 尝试从读取的文本中去掉任何 HTML 和 PHP 标记。 The function retains the parsing state from call to call, and as such is not equivalent to calling strip_tags() on the return value of fgets().

### 参数

`handle`
  文件指针必须是有效的，必须指向由 fopen() 或 fsockopen() 成功打开的文件(并还未由 fclose() 关闭)。
`length`

  取回该长度的数据。

`allowable_tags`

  可以用可选的第三个参数指定哪些标记不被去掉。 See strip_tags() for details regarding `allowable_tags`.

### 返回值

从 `handle` 指向的文件中大读取 `length` - 1 个字节的字符，并过滤了所有的 HTML 和 PHP 代码。

错误发生时返回 `false`。

### 示例

示例 #1 一行行读取一个 PHP 文件

    <?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);
    }
    ?>

以上示例的输出类似于：

    Welcome! Today is the  of .

    Text outside of the HTML block.

### 注释

> 注意: 在读取在 Macintosh 电脑中或由其创建的文件时， 如果 PHP 不能正确的识别行结束符，启用运行时配置可选项 auto_detect_line_endings 也许可以解决此问题。

### 参见

- fgets() - 从文件指针中读取一行
- fopen() - 打开文件或者 URL
- popen() - 打开进程文件指针
- fsockopen() - 打开 Internet 或者 Unix 套接字连接
- strip_tags() - 从字符串中去除 HTML 和 PHP 标签
- SplFileObject::fgetss() - Gets line from file and strip HTML tags
- string.strip_tags 过滤

# file

(PHP 4, PHP 5, PHP 7, PHP 8)

file — 把整个文件读入一个数组中

### 说明

function file(string `$filename`, int `$flags` = 0, ?resource `$context` = `null`): array|false

把整个文件读入一个数组中。

> 注意:

> 你可以通过 file_get_contents() 以字符串形式获取文件的内容。

### 参数

`filename`

  文件的路径。

  小技巧

  如已启用fopen 包装器，在此函数中， URL 可作为文件名。关于如何指定文件名详见 fopen()。各种 wapper 的不同功能请参见 支持的协议和封装协议，注意其用法及其可提供的预定义变量。

`flags`

  可选参数 `flags` 可以是以下一个或多个常量：

  `FILE_USE_INCLUDE_PATH`
    在 include_path 中查找文件。
  `FILE_IGNORE_NEW_LINES`
    省略数组中每个元素末尾的换行符。
  `FILE_SKIP_EMPTY_LINES`
    跳过空行。
  `FILE_NO_DEFAULT_CONTEXT`
    不使用默认的上下文。
`context`
  上下文流（context stream） resource。

### 返回值

返回数组形式的文件内容。数组的每个元素对应于文件中的一行（结尾会附加换行符）。 失败时，file() 返回 `false`。

> 注意:

> 除非使用了 `FILE_IGNORE_NEW_LINES` ，否则结果数组中的每一行都将包含行尾。

> 注意: 在读取在 Macintosh 电脑中或由其创建的文件时， 如果 PHP 不能正确的识别行结束符，启用运行时配置可选项 auto_detect_line_endings 也许可以解决此问题。

### 错误／异常

自 PHP 8.3.0 起，如果 `flags` 包含任意无效值（例如 `FILE_APPEND`），则会抛出 ValueError。

如果文件不存在，则发出 `E_WARNING` 级错误。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | `flags` 包含任意无效值会抛出 ValueError。

### 示例

示例 #1 file() 示例

    <?php
    // 将一个文件读入数组。本例中通过 HTTP 从 URL 中取得 HTML 源文件。

    $lines = file('http://www.example.com/');

    // 在数组中循环，显示 HTML 的源文件并加上行号。

    foreach ($lines as $line_num => $line) {
        echo "Line #<b>{$line_num}</b> : " . htmlspecialchars($line) . "<br />\n";
    }

    // 使用可选的 flags 参数
    $trimmed = file('somefile.txt', FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
    ?>

### 注释

警告

使用 SSL 时，Microsoft IIS 会违反协议不发送 `close_notify` 标记就关闭连接。PHP 会在到达数据尾端时报告“SSL: Fatal Protocol Error”。 要解决此问题，error_reporting 应设定为降低级别至不包含警告。PHP 4.3.7 及更高版本可以在使用 `https://` 包装器打开流时检测出有问题的 IIS 服务器软件 并抑制警告。在使用 fsockopen() 创建 `ssl://` 套接字时，开发者需检测并抑制此警告。

### 参见

- file_get_contents() - 将整个文件读入一个字符串
- readfile() - 输出文件
- fopen() - 打开文件或者 URL
- fsockopen() - 打开 Internet 或者 Unix 套接字连接
- popen() - 打开进程文件指针
- include - include
- stream_context_create() - 创建资源流上下文

# file_exists

(PHP 4, PHP 5, PHP 7, PHP 8)

file_exists — 检查文件或目录是否存在

### 说明

function file_exists(string `$filename`): bool

检查文件或目录是否存在。

### 参数

`filename`

  文件或目录的路径。

  在 Windows 中要用 //computername/share/filename 或者 \\computername\share\filename 来检查网络中的共享文件。

### 返回值

如果由 `filename` 指定的文件或目录存在则返回 `true`，否则返回 `false`。

> 注意:

> 对于指向文件不存在的符号链接，此函数将会返回 `false`。

> 注意:

> The check is done using the real UID/GID instead of the effective one.

> 注意: 因为 PHP 的整数类型是有符号整型而且很多平台使用 32 位整型，对 2GB 以上的文件，一些文件系统函数可能返回无法预期的结果。

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 示例

示例 #1 测试一个文件是否存在

    <?php
    $filename = '/path/to/foo.txt';

    if (file_exists($filename)) {
        echo "The file $filename exists";
    } else {
        echo "The file $filename does not exist";
    }
    ?>

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 参见

- is_readable() - 判断给定文件名是否可读
- is_writable() - 判断给定的文件名是否可写
- is_file() - 判断给定文件名是否为一个正常的文件
- file() - 把整个文件读入一个数组中
- SplFileInfo

# file_get_contents

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

file_get_contents — 将整个文件读入一个字符串

### 说明

function file_get_contents(
string `$filename`,
bool `$use_include_path` = `false`,
?resource `$context` = `null`,
int `$offset` = 0,
?int `$length` = `null`
): string|false

和 file() 一样，只除了 file_get_contents() 把文件读入一个字符串。将在参数 `offset` 所指定的位置开始读取长度为 `length` 的内容。如果失败，file_get_contents() 将返回 `false`。

file_get_contents() 函数是用来将文件的内容读入到一个字符串中的首选方法。如果操作系统支持还会使用内存映射技术来增强性能。

> 注意:

> 如果要打开有特殊字符的 URL （比如说有空格），就需要使用 urlencode() 进行 URL 编码。

### 参数

`filename`

  要读取的文件的名称。

`use_include_path`

  > 注意:

  > 常量 `FILE_USE_INCLUDE_PATH` 用于触发搜索 include path。 因为 `FILE_USE_INCLUDE_PATH` 是个 int，如果开启了严格类型 将无法启用。 所以要用 `true` 来代替常量。

`context`

  stream_context_create() 创建的有效的上下文（context）资源。 如果你不需要自定义 context，可以用 `null` 来忽略。

`offset`

  读取原始数据流的开始位置偏移量。负的 offset 会从数据流的末尾开始统计。

  远程文件不支持偏移量寻址（`offset`）。 对远程文件以较小的 offset 可能可以正常寻址， 但由于是对缓冲流进行操作，所以操作结果不可预测。

`length`

  要读取数据的最大长度。 默认情况下会读到文件末尾。 注意，该参数会应用到处理 stream 的过滤器（filter）中。

### 返回值

函数返回读取到的数据， 或者在失败时返回 `false`。

警告

此函数可能返回布尔值 `false`，但也可能返回等同于 `false` 的非布尔值。请阅读 布尔类型章节以获取更多信息。应使用 === 运算符来测试此函数的返回值。

### 错误／异常

以下情况会导致 `E_WARNING` 级别错误： 无法找到 `filename` 文件； `length` 小于零； 在 steam 中无法寻址偏移量 `offset`。

Windows 下用 file_get_contents() 读取目录会导致 `E_WARNING` 错误。 PHP 7.4 起，其他操作系统也会出现同样错误。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `length` 允许为 null。
7.1.0 | 支持负数 `offset`。

### 示例

示例 #1 获取并输出网站首页 HTML 源码

    <?php
    $homepage = file_get_contents('http://www.example.com/');
    echo $homepage;
    ?>

示例 #2 在 include_path 里搜索

    <?php
    // 如果开启了严格类型，例如 declare(strict_types=1);
    $file = file_get_contents('./people.txt', true);
    // 否则就这样写
    $file = file_get_contents('./people.txt', FILE_USE_INCLUDE_PATH);
    ?>

示例 #3 读取文件一小节

    <?php
    // 从第 21 个字符开始，读取 14 字符长度
    $section = file_get_contents('./people.txt', FALSE, NULL, 20, 14);
    var_dump($section);
    ?>

以上示例的输出类似于：

    string(14) "lle Bjori Ro"

示例 #4 使用 stream 上下文（context）

    <?php
    // 创建 stream
    $opts = [
      'http' => [
        'method' => "GET",
        'header' => "Accept-language: en\r\n" .
                    "Cookie: foo=bar",
      ]
    ];

    $context = stream_context_create($opts);

    // 以下面设置的 HTTP 头来打开文件
    $file = file_get_contents('http://www.example.com/', false, $context);
    ?>

### 注释

> 注意: 此函数可安全用于二进制对象。

小技巧

如已启用fopen 包装器，在此函数中， URL 可作为文件名。关于如何指定文件名详见 fopen()。各种 wapper 的不同功能请参见 支持的协议和封装协议，注意其用法及其可提供的预定义变量。

警告

使用 SSL 时，Microsoft IIS 会违反协议不发送 `close_notify` 标记就关闭连接。PHP 会在到达数据尾端时报告“SSL: Fatal Protocol Error”。 要解决此问题，error_reporting 应设定为降低级别至不包含警告。PHP 4.3.7 及更高版本可以在使用 `https://` 包装器打开流时检测出有问题的 IIS 服务器软件 并抑制警告。在使用 fsockopen() 创建 `ssl://` 套接字时，开发者需检测并抑制此警告。

### 参见

- file() - 把整个文件读入一个数组中
- fgets() - 从文件指针中读取一行
- fread() - 读取文件（可安全用于二进制文件）
- readfile() - 输出文件
- file_put_contents() - 将数据写入文件
- stream_get_contents() - 读取资源流到一个字符串
- stream_context_create() - 创建资源流上下文
- $http_response_header

# file_put_contents

(PHP 5, PHP 7, PHP 8)

file_put_contents — 将数据写入文件

### 说明

function file_put_contents(
string `$filename`,
mixed `$data`,
int `$flags` = 0,
?resource `$context` = `null`
): int|false

和依次调用 fopen()，fwrite() 以及 fclose() 功能一样。

如果 `filename` 不存在，将会创建文件。反之，存在的文件将会重写，除非设置 `FILE_APPEND` flag。

### 参数

`filename`

  要被写入数据的文件名。

`data`

  要写入的数据。类型可以是 string，array 或者是 stream 资源（如上面所说的那样）。

  如果 `data` 指定为 stream 资源，这里 stream 中所保存的缓存数据将被写入到指定文件中，这种用法就相似于使用 stream_copy_to_stream() 函数。

  参数 `data` 可以是数组（但不能为多维数组），这就相当于 `file_put_contents($filename, join('', $array))`。

`flags`

  `flags` 的值可以是 以下 flag 使用 OR (`|`) 运算符进行的组合。

  Available flags
  Flag | 描述
  --- | ---
  `FILE_USE_INCLUDE_PATH` | 在 include 目录里搜索 `filename`。 更多信息可参见 include_path。
  `FILE_APPEND` | 如果文件 `filename` 已经存在，追加数据而不是覆盖。
  `LOCK_EX` | 在写入时获取文件独占锁。换句话说，在调用 fopen() 和 fwrite() 中间发生了 flock() 调用。这与调用带模式“x”的 fopen() 不同。

`context`

  一个 context 资源。

### 返回值

该函数将返回写入到文件内数据的字节数，失败时返回`false`

警告

此函数可能返回布尔值 `false`，但也可能返回等同于 `false` 的非布尔值。请阅读 布尔类型章节以获取更多信息。应使用 === 运算符来测试此函数的返回值。

### 示例

示例 #1 简单用法示例

    <?php
    $file = 'people.txt';
    // 打开文件获取已经存在的内容
    $current = file_get_contents($file);
    // 追加新成员到文件
    $current .= "John Smith\n";
    // 将内容写回文件
    file_put_contents($file, $current);
    ?>

示例 #2 Using flags

    <?php
    $file = 'people.txt';
    // The new person to add to the file
    $person = "John Smith\n";
    // Write the contents to the file,
    // using the FILE_APPEND flag to append the content to the end of the file
    // and the LOCK_EX flag to prevent anyone else writing to the file at the same time
    file_put_contents($file, $person, FILE_APPEND | LOCK_EX);
    ?>

### 注释

> 注意: 此函数可安全用于二进制对象。

小技巧

如已启用fopen 包装器，在此函数中， URL 可作为文件名。关于如何指定文件名详见 fopen()。各种 wapper 的不同功能请参见 支持的协议和封装协议，注意其用法及其可提供的预定义变量。

### 参见

- fopen() - 打开文件或者 URL
- fwrite() - 写入文件（可安全用于二进制文件）
- file_get_contents() - 将整个文件读入一个字符串
- stream_context_create() - 创建资源流上下文

# fileatime

(PHP 4, PHP 5, PHP 7, PHP 8)

fileatime — 取得文件的上次访问时间

### 说明

function fileatime(string `$filename`): int|false

取得文件的上次访问时间。

### 参数

`filename`

  文件的路径。

### 返回值

返回文件上次被访问的时间， 或者在失败时返回 `false`。时间以 Unix 时间戳的方式返回。

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 示例

示例 #1 fileatime() 例子

    <?php

    // 输出类似：somefile.txt was last accessed: December 29 2002 22:16:23.

    $filename = 'somefile.txt';
    if (file_exists($filename)) {
        echo "$filename was last accessed: " . date("F d Y H:i:s.", fileatime($filename));
    }

    ?>

### 注释

> 注意:

> 注意：一个文件的 atime 应该在不论何时读取了此文件中的数据块时被更改。当一个应用程序定期访问大量文件或目录时很影响性能。

> 有些 Unix 文件系统可以在加载时关闭 atime 的更新以提高这类程序的性能。USENET 新闻组假脱机是一个常见的例子。在这种文件系统下本函数没有用处。

> 注意: 注意：不同文件系统对时间的判断方法可能是不相同的。

> 注意: 此函数的结果会被缓存。参见 clearstatcache() 以获得更多细节。

小技巧

自 PHP 5.0.0 起, 此函数也用于某些 URL 包装器。请参见 支持的协议和封装协议以获得支持 stat() 系列函数功能的包装器列表。

### 参见

- filemtime() - 取得文件修改时间
- fileinode() - 取得文件的 inode
- date() - 格式化 Unix 时间戳

# filectime

(PHP 4, PHP 5, PHP 7, PHP 8)

filectime — 取得文件的 inode 修改时间

### 说明

function filectime(string `$filename`): int|false

取得文件的 inode 修改时间。

### 参数

`filename`

  文件的路径。

### 返回值

返回文件上次 inode 被修改的时间， 或者在失败时返回 `false`。 时间以 Unix 时间戳的方式返回。

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 示例

示例 #1 filectime() 例子

    <?php

    // 输出类似：  somefile.txt was last changed: December 29 2002 22:16:23.

    $filename = 'somefile.txt';
    if (file_exists($filename)) {
        echo "$filename was last changed: " . date("F d Y H:i:s.", filectime($filename));
    }

    ?>

### 注释

> 注意:

> 注意：在大多数 Unix 文件系统中，当一个文件的 inode 数据被改变时则该文件被认为是修改了。也就是说，当文件的权限，所有者，所有组或其它 inode 中的元数据被更新时。参见 filemtime()（这才是你想用于在 Web 页面中建立“最后更新时间”脚注的函数）和 fileatime()。

> 注意:

> 注意某些 Unix 说明文本中把 ctime 说成是该文件建立的时间，这是错的。在大多数 Unix 文件系统中没有 Unix 文件的建立时间。

> 注意: 注意：不同文件系统对时间的判断方法可能是不相同的。

> 注意: 此函数的结果会被缓存。参见 clearstatcache() 以获得更多细节。

小技巧

自 PHP 5.0.0 起, 此函数也用于某些 URL 包装器。请参见 支持的协议和封装协议以获得支持 stat() 系列函数功能的包装器列表。

### 参见

- filemtime() - 取得文件修改时间

# filegroup

(PHP 4, PHP 5, PHP 7, PHP 8)

filegroup — 取得文件的组

### 说明

function filegroup(string `$filename`): int|false

取得该文件所属组的 ID。组 ID 以数字格式返回，用 posix_getgrgid() 来将其解析为组名。

### 参数

`filename`

  文件的路径。

### 返回值

返回该文件所属组的 ID。或在错误时返回 `false`。 组 ID 以数字格式返回，用 posix_getgrgid() 来将其解析为组名。如果出错则返回 `false`。

### 错误／异常

失败时会发出 `E_WARNING`。

### 示例

示例 #1 查找文件所在的组

    <?php
    $filename = 'index.php';
    print_r(posix_getgrgid(filegroup($filename)));
    ?>

### 注释

> 注意: 此函数的结果会被缓存。参见 clearstatcache() 以获得更多细节。

小技巧

自 PHP 5.0.0 起, 此函数也用于某些 URL 包装器。请参见 支持的协议和封装协议以获得支持 stat() 系列函数功能的包装器列表。

### 参见

- fileowner() - 取得文件的所有者
- posix_getgrgid() - Return info about a group by group id

# fileinode

(PHP 4, PHP 5, PHP 7, PHP 8)

fileinode — 取得文件的 inode

### 说明

function fileinode(string `$filename`): int|false

取得文件的 inode。

### 参数

`filename`

  文件的路径。

### 返回值

返回文件的 inode 节点号， 或者在失败时返回 `false`。

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 示例

示例 #1 将某个文件和当前文件的 inode 进行对比

    <?php
    $filename = 'index.php';
    if (getmyinode() == fileinode($filename)) {
        echo 'You are checking the current file.';
    }
    ?>

### 注释

> 注意: 此函数的结果会被缓存。参见 clearstatcache() 以获得更多细节。

小技巧

自 PHP 5.0.0 起, 此函数也用于某些 URL 包装器。请参见 支持的协议和封装协议以获得支持 stat() 系列函数功能的包装器列表。

### 参见

- getmyinode() - 获取当前脚本的索引节点（inode）
- stat() - 给出文件的信息

# filemtime

(PHP 4, PHP 5, PHP 7, PHP 8)

filemtime — 取得文件修改时间

### 说明

function filemtime(string `$filename`): int|false

本函数返回文件中的数据块上次被写入的时间，也就是说，文件的内容上次被修改的时间。

### 参数

`filename`

  文件的路径。

### 返回值

返回文件上次被修改的时间， 或者在失败时返回 `false`。时间以 Unix 时间戳的方式返回，可用于 date()。

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 示例

示例 #1 filemtime() 例子

    <?php
    // outputs e.g.  somefile.txt was last modified: December 29 2002 22:16:23.

    $filename = 'somefile.txt';
    if (file_exists($filename)) {
        echo "$filename was last modified: " . date ("F d Y H:i:s.", filemtime($filename));
    }
    ?>

### 注释

> 注意: 注意：不同文件系统对时间的判断方法可能是不相同的。

> 注意: 此函数的结果会被缓存。参见 clearstatcache() 以获得更多细节。

小技巧

自 PHP 5.0.0 起, 此函数也用于某些 URL 包装器。请参见 支持的协议和封装协议以获得支持 stat() 系列函数功能的包装器列表。

### 参见

- filectime() - 取得文件的 inode 修改时间
- stat() - 给出文件的信息
- touch() - 设定文件的访问和修改时间
- getlastmod() - 获取页面最后修改的时间

# fileowner

(PHP 4, PHP 5, PHP 7, PHP 8)

fileowner — 取得文件的所有者

### 说明

function fileowner(string `$filename`): int|false

取得文件的所有者。

### 参数

`filename`

  文件的路径。

### 返回值

返回文件所有的用户 ID，如果出错则返回 `false`。用户 ID 以数字格式返回，用 posix_getpwuid() 来将其解析为用户名。

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 示例

示例 #1 找到文件的所有者

    <?php
    $filename = 'index.php';
    print_r(posix_getpwuid(fileowner($filename)));
    ?>

### 注释

> 注意: 此函数的结果会被缓存。参见 clearstatcache() 以获得更多细节。

小技巧

自 PHP 5.0.0 起, 此函数也用于某些 URL 包装器。请参见 支持的协议和封装协议以获得支持 stat() 系列函数功能的包装器列表。

### 参见

- filegroup() - 取得文件的组
- stat() - 给出文件的信息
- posix_getpwuid() - Return info about a user by user id

# fileperms

(PHP 4, PHP 5, PHP 7, PHP 8)

fileperms — 获取文件权限

### 说明

function fileperms(string `$filename`): int|false

获取指定文件权限。

### 参数

`filename`

  文件的路径。

### 返回值

以数字模式返回文件权限。此模式的低位与 chmod() 期望权限相同，然而在大多数平台上，返回值还将会包含指定 `filename` 的文件类型信息。下面的示例示范了如何在 POSIX 系统上测试特定权限和文件类型的返回值。

对于本地文件，特定的返回值是通过 C 库的 stat() 函数返回结构中的 `st_mode` 成员的值。Exactly which bits are set can vary from platform to platform, and looking up your specific platform's documentation is recommended if parsing the non-permission bits of the return value is required.

失败时返回 `false`。

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 示例

示例 #1 以八进制的形式显示文件的权限

    <?php
    echo substr(sprintf('%o', fileperms('/tmp')), -4);
    echo substr(sprintf('%o', fileperms('/etc/passwd')), -4);
    ?>

以上示例会输出：

    1777
    0644

示例 #2 输出全部权限

    <?php
    $perms = fileperms('/etc/passwd');

    switch ($perms & 0xF000) {
        case 0xC000: // 套接字
            $info = 's';
            break;
        case 0xA000: // 符号链接
            $info = 'l';
            break;
        case 0x8000: // regular
            $info = 'r';
            break;
        case 0x6000: // 块设备
            $info = 'b';
            break;
        case 0x4000: // 目录
            $info = 'd';
            break;
        case 0x2000: // 字符设备
            $info = 'c';
            break;
        case 0x1000: // FIFO 管道
            $info = 'p';
            break;
        default: // 位置
            $info = 'u';
    }

    // 所有者
    $info .= (($perms & 0x0100) ? 'r' : '-');
    $info .= (($perms & 0x0080) ? 'w' : '-');
    $info .= (($perms & 0x0040) ?
                (($perms & 0x0800) ? 's' : 'x' ) :
                (($perms & 0x0800) ? 'S' : '-'));

    // 组
    $info .= (($perms & 0x0020) ? 'r' : '-');
    $info .= (($perms & 0x0010) ? 'w' : '-');
    $info .= (($perms & 0x0008) ?
                (($perms & 0x0400) ? 's' : 'x' ) :
                (($perms & 0x0400) ? 'S' : '-'));

    // 其它
    $info .= (($perms & 0x0004) ? 'r' : '-');
    $info .= (($perms & 0x0002) ? 'w' : '-');
    $info .= (($perms & 0x0001) ?
                (($perms & 0x0200) ? 't' : 'x' ) :
                (($perms & 0x0200) ? 'T' : '-'));

    echo $info;
    ?>

以上示例会输出：

    -rw-r--r--

### 注释

> 注意: 此函数的结果会被缓存。参见 clearstatcache() 以获得更多细节。

小技巧

自 PHP 5.0.0 起, 此函数也用于某些 URL 包装器。请参见 支持的协议和封装协议以获得支持 stat() 系列函数功能的包装器列表。

### 参见

- chmod() - 改变文件模式
- is_readable() - 判断给定文件名是否可读
- stat() - 给出文件的信息

# filesize

(PHP 4, PHP 5, PHP 7, PHP 8)

filesize — 取得文件大小

### 说明

function filesize(string `$filename`): int|false

取得指定文件的大小。

### 参数

`filename`

  文件的路径。

### 返回值

返回文件大小的字节数，如果出错返回 `false` 并生成一条 `E_WARNING` 级的错误。

> 注意: 因为 PHP 的整数类型是有符号整型而且很多平台使用 32 位整型，对 2GB 以上的文件，一些文件系统函数可能返回无法预期的结果。

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 示例

示例 #1 filesize() 例子

    <?php

    // 输出类似：somefile.txt: 1024 bytes

    $filename = 'somefile.txt';
    echo $filename . ': ' . filesize($filename) . ' bytes';

    ?>

### 注释

> 注意: 此函数的结果会被缓存。参见 clearstatcache() 以获得更多细节。

小技巧

自 PHP 5.0.0 起, 此函数也用于某些 URL 包装器。请参见 支持的协议和封装协议以获得支持 stat() 系列函数功能的包装器列表。

### 参见

- file_exists() - 检查文件或目录是否存在

# filetype

(PHP 4, PHP 5, PHP 7, PHP 8)

filetype — 取得文件类型

### 说明

function filetype(string `$filename`): string|false

返回文件的类型。

### 参数

`filename`

  文件的路径。

### 返回值

返回文件的类型。 可能的值有 fifo，char，dir，block，link，file 和 unknown。

如果出错则返回 `false`。如果 stat 调用失败或者文件类型未知的话 filetype() 还会产生一个 `E_NOTICE` 消息。

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 示例

示例 #1 filetype() 例子

    <?php

    echo filetype('/etc/passwd');
    echo "\n";
    echo filetype('/etc/');

    ?>

以上示例会输出：

    file
    dir

### 注释

> 注意: 此函数的结果会被缓存。参见 clearstatcache() 以获得更多细节。

小技巧

自 PHP 5.0.0 起, 此函数也用于某些 URL 包装器。请参见 支持的协议和封装协议以获得支持 stat() 系列函数功能的包装器列表。

### 参见

- is_dir() - 判断给定文件名是否是一个目录
- is_file() - 判断给定文件名是否为一个正常的文件
- is_link() - 判断给定文件名是否为一个符号连接
- file_exists() - 检查文件或目录是否存在
- mime_content_type() - 检测文件的 MIME 类型
- pathinfo() - 返回文件路径的信息
- stat() - 给出文件的信息

# flock

(PHP 4, PHP 5, PHP 7, PHP 8)

flock — 可移植的协同文件锁定

### 说明

function flock(resource `$stream`, int `$operation`, int `&$would_block` = `null`): bool

flock() 允许执行简单的读取/写入模型,该模型可以在任何平台（包括大部分 Unix 衍生产品，甚至是 Windows）上使用。

当调用 fclose() 或者对 `stream` 垃圾收集时，锁会释放。

PHP 支持以协同且可移植的方式锁定完整文件（也就是说所有访问程序必须使用相同锁定方式, 否则将无法工作）。默认情况下，该函数将堵塞直到获得锁；这可以通过下面文档中 `LOCK_NB` 选项来控制。

### 参数

`stream`
  文件系统指针，是典型地由 fopen() 创建的 resource(资源)。
`operation`

  `operation` 可以是以下值之一：

  - `LOCK_SH`取得共享锁定（读取的程序）。
  - `LOCK_EX` 取得独占锁定（写入的程序。
  - `LOCK_UN` 释放锁定（无论共享或独占）。

  It is also possible to add `LOCK_NB` as a bitmask to one of the above operations, if flock() should not block during the locking attempt.

`would_block`

  如果锁将堵塞（EWOULDBLOCK 错误码情况下），第三个可选参数会设置为 1。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 flock() 例子

    <?php

    $fp = fopen("/tmp/lock.txt", "r+");

    if (flock($fp, LOCK_EX)) {  // 进行排它型锁定
        ftruncate($fp, 0);      // truncate file
        fwrite($fp, "Write something here\n");
        fflush($fp);            // flush output before releasing the lock
        flock($fp, LOCK_UN);    // 释放锁定
    } else {
        echo "Couldn't get the lock!";
    }

    fclose($fp);

    ?>

示例 #2 flock() 使用 `LOCK_NB` 选项

    <?php
    $fp = fopen('/tmp/lock.txt', 'r+');

    /* Activate the LOCK_NB option on an LOCK_EX operation */
    if(!flock($fp, LOCK_EX | LOCK_NB)) {
        echo 'Unable to obtain lock';
        exit(-1);
    }

    /* ... */

    fclose($fp);
    ?>

### 注释

> 注意:

> 在 Windows 上，flock() 使用的是强制锁而不是协同锁。 Mandatory locking is also supported on Linux and System V based operating systems via the usual mechanism supported by the fcntl() system call: that is, if the file in question has the setgid permission bit set and the group execution bit cleared. On Linux, the file system will also need to be mounted with the mand option for this to work.

> 注意:

> 由于 flock() 需要一个文件指针， 因此可能不得不用一个特殊的锁定文件来保护打算通过写模式打开的文件的访问（在 fopen() 函数中加入 "w" 或 "w+"）。

> 注意:

> 只能用于 fopen() 返回本地文件的文件指针，或指向实现 streamWrapper::stream_lock() 方法的用户空间流的文件指针。

警告

在后续代码中为 `stream` 分配另一个值将释放锁。

警告

在部分操作系统中 flock() 以进程级实现。当用多线程服务器 API 时，可能无法依靠 flock() 来保护文件，因为运行于同一服务器实例中其它并行线程的 PHP 脚本可以对该文件进行处理！

旧的文件系统（如 `FAT` 及其衍生）不支持 flock()，也因此在这些环境下总是返回 `false`。

> 注意:

> 在 Windows 上，如果锁进程再次打开文件，那么在解锁文件之前，无法通过第二个句柄访问文件。

# fnmatch

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

fnmatch — 用模式匹配文件名

### 说明

function fnmatch(string `$pattern`, string `$filename`, int `$flags` = 0): bool

fnmatch() 检查传入的 `filename` 是否匹配给出的 shell 通配符 `pattern`。

### 参数

`pattern`

  要匹配的 `pattern`。通常，`pattern` 将包含匹配符，像 `'?'` 和 `'*'`。

  `pattern` 参数要使用的匹配符
  匹配符 | 说明
  --- | ---
  `?` | 问号将匹配任何单个字符。比如，模式 `"file?.txt"` 将匹配 `"file1.txt"` 和 `"fileA.txt"`，但不会匹配 `"file10.txt"`。
  `*` | 星号将匹配零或多个字符。例如 `"foo*.xml"` 将匹配 `"foo.xml"` 和 `"foobar.xml"`。
  `[ ]` | 中括号用于创建 ASCII 码点范围或字符集。例如，模式 `"index.php[45]"` 将匹配 `"index.php4"` 和 `"index.php5"`，但不会匹配 `"index.phpt"`。众所周知的范围是 `[0-9]`、`[a-z]` 和 `[A-Z]`。可以同时使用多个集合和范围，例如 `[0-9a-zABC]`。
  `!` | 感叹号用于否定中括号内的字符。例如，`"[!A-Z]*.html"` 将匹配 `"demo.html"`，但不会匹配 `"Demo.html"`。
  `\` | 反斜线用于转义特殊字符。例如 `"Name\?"` 将匹配 `"Name?"` ，但不会匹配 `"Names"`。

`filename`

  要检查的字符串。 此函数对于文件名尤其有用，但也可以用于普通的字符串。

  普通用户可能习惯于 shell 模式或者至少在最简单的形式下使用 `'?'` 和 `'*'` 通配符， 因此在前端搜索表达式输入中，使用 fnmatch() 来代替 preg_match() 对于非编程用户更加方便。

`flags`

  `flags` 值可以是下列 flag 的任意组合，并用位运算符 OR (|) 连接。

  fnmatch() flag 列表
  `Flag` | 说明
  --- | ---
  `FNM_NOESCAPE` | 禁用反斜线转义。
  `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.

### 返回值

匹配则返回 `true`，否则返回 `false`。

### 示例

示例 #1 用 shell 中的通配符模式匹配来检查颜色名称

    <?php
    if (fnmatch("*gr[ae]y", $color)) {
      echo "some form of gray ...";
    }
    ?>

### 注释

警告

目前该函数无法在 Windows 或其它非 POSIX 兼容的系统上使用。

### 参见

- glob() - 寻找与模式匹配的文件路径
- preg_match() - 执行匹配正则表达式
- sscanf() - 根据指定格式解析输入的字符
- printf() - 输出格式化字符串
- sprintf() - 返回格式化字符串

# fopen

(PHP 4, PHP 5, PHP 7, PHP 8)

fopen — 打开文件或者 URL

### 说明

function fopen(
string `$filename`,
string `$mode`,
bool `$use_include_path` = `false`,
?resource `$context` = `null`
): resource|false

fopen() 将由 `filename` 指定的命名资源绑定到流。

### 参数

`filename`

  如果 `filename` 是 "scheme://..." 的格式，则被当成一个 URL，PHP 将搜索协议处理器（也被称为封装协议）来处理此模式。如果该协议尚未注册封装协议，PHP 将发出一条消息来帮助检查脚本中潜在的问题并将 `filename` 当成一个普通的文件名继续执行下去。

  如果 PHP 认为 `filename` 指定的是一个本地文件，将尝试在该文件上打开一个流。该文件必须是 PHP 可以访问的，因此需要确认文件访问权限允许该访问。如果激活了 open_basedir 则会应用进一步的限制。

  如果 PHP 认为 `filename` 指定的是一个已注册的协议，而该协议被注册为一个网络 URL，PHP 将检查并确认 allow_url_fopen 已被激活。如果关闭了，PHP 将发出一个警告，而 fopen() 的调用则失败。

  > 注意:

  > 所支持的协议列表见支持的协议和封装协议。某些协议（也被称为 `wrappers`）支持 `context` 和／或 php.ini 选项。参见相应的页面哪些选项可以被设定（例如 php.ini 中用于 `http` wrapper 的 `user_agent` 值）。

  在 Windows 平台上，注意对文件路径中的反斜线进行转义，或者使用斜线。

      <?php
      $handle = fopen("c:\\folder\\resource.txt", "r");
      ?>

`mode`

  `mode` 参数指定了所要求到该流的访问类型。可以是以下：

  fopen() 中 `mode` 的可能值列表
  `mode` | 说明
  --- | ---
  `'r'` | 只读方式打开，将文件指针指向文件头。
  `'r+'` | 读写方式打开，将文件指针指向文件头。
  `'w'` | 写入方式打开，将文件指针指向文件头并将文件大小截为零。如果文件不存在则尝试创建之。
  `'w+'` | 读写方式打开，否则行为同 `'w'`。
  `'a'` | 写入方式打开，将文件指针指向文件末尾。如果文件不存在则尝试创建之。在这种情况下，fseek() 没有效果，写入总是追加。
  `'a+'` | 读写方式打开，将文件指针指向文件末尾。如果文件不存在则尝试创建之。在这种情况下，fseek() 只相应读取位置，写入总是追加。
  `'x'` | 创建并以写入方式打开，将文件指针指向文件头。如果文件已存在，则 fopen() 调用失败并返回 `false`，并生成一条 `E_WARNING` 级别的错误信息。如果文件不存在则尝试创建之。这和给底层的 `open(2)` 系统调用指定 `O_EXCL|O_CREAT` 标记是等价的。
  `'x+'` | 创建并以读写方式打开，其他的行为和 `'x'` 一样。
  `'c'` | 以只写模式打开文件。如果文件不存在，则创建该文件；如果文件已存在，既不会截断文件（与 `'w'` 不同），也不会导致函数调用失败（与 `'x'` 不同）。文件指针位于文件开头。如果希望在尝试修改文件之前获取劝告锁（参见 flock()），这可能很有用，因为使用 `'w'` 模式可能会在获取锁之前截断文件（如果需要截断，可以在请求锁后使用 ftruncate()）。
  `'c+'` | 以读写模式打开文件；除此之外，其行为与 `'c'` 相同。
  `'e'` | 在打开的文件描述符上设置 close-on-exec flag。仅在符合 POSIX.1-2008 标准的系统上编译的 PHP 中可用。
  `'n'` | 在打开的文件描述符上设置非阻塞 flag。仅在符合 POSIX.1-2008 标准的系统上编译的 PHP 中可用。

  > 注意:

  > 不同的操作系统家族具有不同的行结束习惯。当写入一个文本文件并想插入一个新行时，需要使用符合操作系统的行结束符号。基于 Unix 的系统使用 `\n` 作为行结束字符，基于 Windows 的系统使用 `\r\n` 作为行结束字符，基于 Macintosh 的系统（传统 Mac OS）使用 `\r` 作为行结束字符。

  > 如果写入文件时使用了错误的行结束符号，则其它应用程序打开这些文件时可能会表现得很怪异。

  > Windows 下提供了一个文本转换标记（`'t'`）可以透明地将 `\n` 转换为 `\r\n`。与此对应还可以使用 `'b'` 来强制使用二进制模式，这样就不会转换数据。要使用这些标记，要么用 `'b'` 或者用 `'t'` 作为 `mode` 参数的最后一个字符。

  > 默认的转换模式是 `'b'`。如果是操作纯文本文件并在脚本中使用了 `\n` 作为行结束符，但还要期望这些文件可以被其它应用程序例如 旧版本的 Notepad 读取，则在 mode 中使用 `'t'`。在所有其它情况下使用 `'b'`。

  > 在操作二进制文件时如果指定 `'t'` 标记，可能会碰到一些奇怪的问题，包括坏掉的图片文件以及关于 `\r\n` 字符的奇怪问题。

  > 注意:

  > 为移植性考虑，强烈建议重写那些依赖于 `'t'` 模式的代码使其使用正确的行结束符并改成 `'b'` 模式。

  > 注意: 对于 php://output、php://input、php://stdin、php://stdout、php://stderr 和 php://fd 流封装协议，会忽略 `mode`。

`use_include_path`

  如果也需要在 include_path 中搜寻文件的话，可以将可选的第三个参数 `use_include_path` 设为 `true`。

`context`
  上下文流（context stream） resource。

### 返回值

成功时返回文件指针资源， 或者在失败时返回 `false`。

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 更新日志

版本 | 说明
--- | ---
7.0.16, 7.1.2 | 新增 `'e'` 选项。

### 示例

示例 #1 fopen() 示例

    <?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");
    ?>

### 注释

警告

使用 SSL 时，Microsoft IIS 会违反协议不发送 `close_notify` 标记就关闭连接。PHP 会在到达数据尾端时报告“SSL: Fatal Protocol Error”。 要解决此问题，error_reporting 应设定为降低级别至不包含警告。PHP 4.3.7 及更高版本可以在使用 `https://` 包装器打开流时检测出有问题的 IIS 服务器软件 并抑制警告。在使用 fsockopen() 创建 `ssl://` 套接字时，开发者需检测并抑制此警告。

> 注意:

> 如果在用服务器模块版本的 PHP 时在打开和写入文件上遇到问题，记住要确保所使用的文件和目录是服务器进程所能够访问的。

> 注意:

> 当 `filename` 为目录时，此函数也可能成功。如果不确定 `filename` 是文件还是目录，则在调用 fopen() 之前可能需要使用 is_dir() 函数进行判断。

### 参见

- 支持的协议和封装协议
- fclose() - 关闭一个已打开的文件指针
- fgets() - 从文件指针中读取一行
- fread() - 读取文件（可安全用于二进制文件）
- fwrite() - 写入文件（可安全用于二进制文件）
- fsockopen() - 打开 Internet 或者 Unix 套接字连接
- file() - 把整个文件读入一个数组中
- file_exists() - 检查文件或目录是否存在
- is_readable() - 判断给定文件名是否可读
- stream_set_timeout() - Set timeout period on a stream
- popen() - 打开进程文件指针
- stream_context_create() - 创建资源流上下文
- umask() - 改变当前的 umask
- SplFileObject

# fpassthru

(PHP 4, PHP 5, PHP 7, PHP 8)

fpassthru — 输出文件指针处的所有剩余数据

### 说明

function fpassthru(resource `$stream`): int

将给定的文件指针从当前的位置读取到 EOF 并把结果写到输出缓冲区。

如果已经向文件写入数据，就必须调用 rewind() 来将文件指针指向文件头。

如果既不修改文件也不在特定位置检索，只想将文件的内容下载到输出缓冲区，应该使用 readfile()，这样可以省去 fopen() 调用。

### 参数

`stream`
  文件指针必须是有效的，必须指向由 fopen() 或 fsockopen() 成功打开的文件(并还未由 fclose() 关闭)。

### 返回值

返回从 `stream` 读取并传递到输出的字符数量。

### 示例

示例 #1 对二进制文件使用 fpassthru()

    <?php

    // 以二进制格式打开文件
    $name = './img/ok.png';
    $fp = fopen($name, 'rb');

    // 发送合适的报头
    header("Content-Type: image/png");
    header("Content-Length: " . filesize($name));

    // 发送图片并终止脚本
    fpassthru($fp);
    exit;

    ?>

### 注释

> 注意:

> 当在 Windows 系统中将 fpassthru() 用于二进制文件，要确保在用 fopen() 打开文件时在 mode 中附加了 `b` 来将文件以二进制方式打开。

> 鼓励在处理二进制文件时使用 `b` 标志，即使系统并不需要，这样可以使脚本的移植性更好。

### 参见

- readfile() - 输出文件
- fopen() - 打开文件或者 URL
- popen() - 打开进程文件指针
- fsockopen() - 打开 Internet 或者 Unix 套接字连接

# fputcsv

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

fputcsv — 将行格式化为 CSV 并写入文件指针

### 说明

function fputcsv(
resource `$stream`,
array `$fields`,
string `$separator` = ",",
string `$enclosure` = "\"",
string `$escape` = "\\",
string `$eol` = "\n"
): int|false

fputcsv() 将一行（传递 `fields` 数组）格式化为 CSV，并将其写入（以 `eol` 终止）到指定的 `stream`。

### 参数

`stream`
  文件指针必须是有效的，必须指向由 fopen() 或 fsockopen() 成功打开的文件(并还未由 fclose() 关闭)。
`fields`

  string 数组。

`separator`

  可选的 `separator` 参数，设置字段分隔符。必须是单字节字符。

`enclosure`

  可选的 `enclosure` 参数，设置字段环绕符。必须是单字节字符。

`escape`

  可选的 `escape` 参数，设置转义字符。必须是单字节字符或者空字符串。空字符串（`""`）禁用所有的转义机制。

  警告

  在输入流中，`enclosure` 字符在引号字符串内可通过重复自身进行转义，解析后结果中将只保留一个 `enclosure` 字符。而 `escape` 字符的行为有所不同：若输入中出现 `escape` 字符与 `enclosure` 字符的组合序列，这两个字符都会保留在解析结果中。因此，在默认参数下，类似 `"a""b","c\"d"` 的 CSV 行将被解析为两个字段，分别为 `a"b` 和 `c\"d`。

  警告

  从 PHP 8.4.0 开始，弃用依赖 `escape` 的默认值。需要通过位置或使用命名参数明确提供。

`eol`

  可选的 `eol` 参数设置自定义行尾序列。

警告

当 `escape` 被设置为非空字符串（`""`）时， 可能导致生成的 CSV 不符合 » RFC 4180 的要求， 或者无法通过 PHP CSV 函数的往返处理。 `escape` 的默认值是 `"\\"`，因此建议显式地将其设置为空字符串。 默认值将在未来的 PHP 版本中更改，不早于 PHP 9.0。

> 注意:

> 如果字段中包含 `enclosure` 字符，则会通过将其双倍 `enclosure` 来进行转义，除非该字符前面紧接着一个 `escape`。

### 返回值

返回写入字符串的长度， 或者在失败时返回 `false`。

### 错误／异常

如果 `separator` 或者 `enclosure` 长度不是一个字节，则抛出 ValueError。

如果 `escape` 的长度不是一个字节或者为空字符串，则抛出 ValueError。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 现在已弃用依赖 escape 的默认值。
8.1.0 | 新增可选的 `eol` 参数。
7.4.0 | `escape` 参数现在接受空字符串来禁用专有转义机制。

### 示例

示例 #1 fputcsv() 示例

    <?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);
    ?>

以上示例会写入以下的 `file.csv`：

    aaa,bbb,ccc,dddd
    123,456,789
    """aaa""","""bbb"""

### 参见

- fgetcsv() - 从文件指针中读入一行并解析 CSV 字段
- str_getcsv() - 解析 CSV 字符串为一个数组
- 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 — fwrite() 的别名

### 说明

此函数是该函数的别名：fwrite()。

# fread

(PHP 4, PHP 5, PHP 7, PHP 8)

fread — 读取文件（可安全用于二进制文件）

### 说明

function fread(resource `$stream`, int `$length`): string|false

fread() 从文件指针 `stream` 读取最多 `length` 个字节。 该函数在遇上以下几种情况时停止读取文件：

- 读取了 `length` 个字节
- 到达了文件末尾（EOF）
- a packet becomes available or the socket timeout occurs (for network streams)
- if the stream is read buffered and it does not represent a plain file, at most one read of up to a number of bytes equal to the chunk size (usually 8192) is made; depending on the previously buffered data, the size of the returned data may be larger than the chunk size.

### 参数

`stream`
  文件系统指针，是典型地由 fopen() 创建的 resource(资源)。
`length`

  最多读取 `length` 个字节。

### 返回值

返回所读取的字符串， 或者在失败时返回 `false`。

### 示例

示例 #1 一个简单的 fread() 例子

    <?php
    // get contents of a file into a string
    $filename = "/usr/local/something.txt";
    $handle = fopen($filename, "r");
    $contents = fread($handle, filesize($filename));
    fclose($handle);
    ?>

示例 #2 Binary fread() example

警告

在区分二进制文件和文本文件的系统上（如 Windows）打开文件时，fopen() 函数的 mode 参数要加上 'b'。

    <?php
    $filename = "c:\\files\\somepic.gif";
    $handle = fopen($filename, "rb");
    $contents = fread($handle, filesize($filename));
    fclose($handle);
    ?>

示例 #3 Remote fread() examples

警告

当从任何不是普通本地文件读取时，例如在读取从远程文件或 popen() 以及 fsockopen() 返回的流时，读取会在一个包可用之后停止。这意味着应该如下例所示将数据收集起来合并成大块。

    <?php
    $handle = fopen("http://www.example.com/", "rb");
    if (FALSE === $handle) {
        exit("Failed to open stream to URL");
    }

    $contents = stream_get_contents($handle);

    fclose($handle);
    ?>

    <?php
    $handle = fopen("http://www.example.com/", "rb");
    $contents = '';
    while (!feof($handle)) {
        $contents .= fread($handle, 8192);
    }
    fclose($handle);
    ?>

### 注释

> 注意:

> 如果只是想将一个文件的内容读入到一个字符串中，用 file_get_contents()，它的性能比上面的代码好得多。

> 注意:

> Note that fread() reads from the current position of the file pointer. Use ftell() to find the current position of the pointer and rewind() to rewind the pointer position.

### 参见

- fwrite() - 写入文件（可安全用于二进制文件）
- fopen() - 打开文件或者 URL
- fsockopen() - 打开 Internet 或者 Unix 套接字连接
- popen() - 打开进程文件指针
- fgets() - 从文件指针中读取一行
- fgetss() - 从文件指针中读取一行并过滤掉 HTML 标记
- fscanf() - 从文件中格式化输入
- file() - 把整个文件读入一个数组中
- fpassthru() - 输出文件指针处的所有剩余数据
- fseek() - 在文件指针中定位
- ftell() - 返回文件指针读/写的位置
- rewind() - 倒回文件指针的位置
- unpack() - Unpack data from binary string

# fscanf

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

fscanf — 从文件中格式化输入

### 说明

function fscanf(resource `$stream`, string `$format`, mixed `&...$vars`): array|int|false|null

fscanf() 函数和 sscanf() 相似，但是它从与 `stream` 关联的文件中接受输入并根据指定的 `format` 来解释输入。

格式字符串中的任何空白会与输入流中的任何空白匹配。这意味着甚至格式字符串中的制表符（`\t`）也会与输入流中的一个空格字符匹配。

每次调用 fscanf() 都会从文件中读取一行。

### 参数

`stream`
  文件系统指针，是典型地由 fopen() 创建的 resource(资源)。
`format`

  `string` 的格式解释，在 sprintf() 的文档中进行了描述，但有以下区别：

  - 函数不支持区域设置。
  - 不支持 `F`、`g`、`G` 和 `b`。
  - `D` 代表十进制数字。
  - `i` stands for integer with base detection.
  - `n` 代表到目前为止处理的字符数。
  - `s` 在任何空白字符处停止阅读。
  - `*` 代替 `argnum$` 禁止分配此转换规范。
`vars`

  可选赋值。

### 返回值

如果只给此函数传递了两个参数，解析后的值会被作为数组返回。否则，如果提供了可选参数，此函数将返回被赋值的数目。 可选参数必须用引用传递。

如果 `format` 中预期的子字符串超出 `string` 中有效的子字符串，则返回 `null`。其它错误将返回 `false`。

### 示例

示例 #1 fscanf() 例子

    <?php
    $handle = fopen("users.txt", "r");
    while ($userinfo = fscanf($handle, "%s\t%s\t%s\n")) {
        list ($name, $profession, $countrycode) = $userinfo;
        //... do something with the values
    }
    fclose($handle);
    ?>

示例 #2 users.txt 的内容

    javier  argonaut        pe
    hiroshi sculptor        jp
    robert  slacker us
    luigi   florist it

### 参见

- fread() - 读取文件（可安全用于二进制文件）
- fgets() - 从文件指针中读取一行
- fgetss() - 从文件指针中读取一行并过滤掉 HTML 标记
- sscanf() - 根据指定格式解析输入的字符
- printf() - 输出格式化字符串
- sprintf() - 返回格式化字符串

# fseek

(PHP 4, PHP 5, PHP 7, PHP 8)

fseek — 在文件指针中定位

### 说明

function fseek(resource `$stream`, int `$offset`, int `$whence` = `SEEK_SET`): int

在与 `stream` 关联的文件中设定文件指针位置。新位置从文件头开始以字节数度量，是以 `whence` 指定的位置加上 `offset`。

一般来说，允许定位超过文件末尾的位置；如果随后写入数据，则从文件末尾和定位位置之间已读取的任何未写入区域将产生值为 0 的字节。但是，某些 stream 可能不支持此行为，尤其是当它们具有底层固定大小的存储时。

### 参数

`stream`
  文件系统指针，是典型地由 fopen() 创建的 resource(资源)。
`offset`

  偏移量。

  要移动到文件尾之前的位置，必须传递负数值给 `offset`，而且 `whence` 参数设置为 `SEEK_END`。

`whence`

  `whence` 值是：

  - `SEEK_SET` - 设定位置等于距文件开头为 `offset` 字节。
  - `SEEK_CUR` - 设定位置为当前位置加上 `offset` 字节。
  - `SEEK_END` - 设定位置为文件尾加上 `offset` 字节。

### 返回值

成功返回 `0`；否则返回 `-1`。

警告

此函数是为了模仿 C 语言中同名函数而创建的。请注意返回值，因为它们与 PHP 中的期望值不同。

### 示例

示例 #1 fseek() 示例

    <?php

    $fp = fopen('somefile.txt', 'r');

    // read some data
    $data = fgets($fp, 4096);

    // move back to the beginning of the file
    // same as rewind($fp);
    fseek($fp, 0);

    ?>

### 注释

> 注意:

> 如果使用附加模试（`a` 或 `a+`），任何写入文件数据都会被附加上去，而文件的位置将会被忽略，调用 fseek() 的结果尚未定义。

> 注意:

> 并非所有 stream 都支持定位。对于不支持定位的 stream，从当前位置向前定位是通过读取和丢弃数据来实现的；其他形式的定位将会失败。

### 参见

- ftell() - 返回文件指针读/写的位置
- rewind() - 倒回文件指针的位置

# fstat

(PHP 4, PHP 5, PHP 7, PHP 8)

fstat — 通过已打开的文件指针取得文件信息

### 说明

function fstat(resource `$stream`): array|false

获取由文件指针 `stream` 所打开文件的统计信息。本函数和 stat() 函数相似，除了它是作用于已打开的文件指针而不是文件名。

### 参数

`stream`
  文件系统指针，是典型地由 fopen() 创建的 resource(资源)。

### 返回值

返回一个数组具有该文件的统计信息，该数组的格式详细说明于手册中 stat() 页面里。失败时返回 `false`。

### 示例

示例 #1 fstat() 例子

    <?php

    // 打开文件
    $fp = fopen("/etc/passwd", "r");

    // 取得统计信息
    $fstat = fstat($fp);

    // 关闭文件
    fclose($fp);

    // 只显示关联数组部分
    print_r(array_slice($fstat, 13));
    ?>

以上示例的输出类似于：

    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
    )

### 注释

> 注意: 此函数不能作用于远程文件，被检查的文件必须是可通过服务器的文件系统访问的。

# fsync

(PHP 8 >= 8.1.0)

fsync — 同步文件变更（包括元数据）

### 说明

function fsync(resource `$stream`): bool

此函数同步文件变更，包括元数据。与 fflush() 类似，但同时还让操作系统将变更写入到存储介质。

### 参数

`stream`
  文件指针必须是有效的，必须指向由 fopen() 或 fsockopen() 成功打开的文件(并还未由 fclose() 关闭)。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 fsync() 示例

    <?php

    $file = 'test.txt';

    $stream = fopen($file, 'w');
    fwrite($stream, 'test data');
    fwrite($stream, "\r\n");
    fwrite($stream, 'additional data');

    fsync($stream);
    fclose($stream);
    ?>

### 参见

- fdatasync() - 同步文件数据（不包含元数据）
- fflush() - 将缓冲内容输出到文件

# ftell

(PHP 4, PHP 5, PHP 7, PHP 8)

ftell — 返回文件指针读/写的位置

### 说明

function ftell(resource `$stream`): int|false

返回由 `stream` 指定的文件指针的位置，也就是文件流中的偏移量。

### 参数

`stream`

  文件指针必须是有效的，且必须指向一个通过 fopen() 或 popen() 成功打开的文件。在附加模式（加参数 "a" 打开文件）中 ftell() 会返回未定义错误。

### 返回值

以整数形式返回由 `stream` 引用的文件指针的位置，即文件流中的偏移量。

如果出错，返回 `false`。

> 注意: 因为 PHP 的整数类型是有符号整型而且很多平台使用 32 位整型，对 2GB 以上的文件，一些文件系统函数可能返回无法预期的结果。

### 示例

示例 #1 ftell() 例子

    <?php

    // opens a file and read some data
    $fp = fopen("/etc/passwd", "r");
    $data = fgets($fp, 12);

    // where are we ?
    echo ftell($fp); // 11

    fclose($fp);

    ?>

### 参见

- fopen() - 打开文件或者 URL
- popen() - 打开进程文件指针
- fseek() - 在文件指针中定位
- rewind() - 倒回文件指针的位置

# ftruncate

(PHP 4, PHP 5, PHP 7, PHP 8)

ftruncate — 将文件截断到指定的长度

### 说明

function ftruncate(resource `$stream`, int `$size`): bool

接受文件指针 `stream` 作为参数，并将文件大小截取为 `size`。

### 参数

`stream`

  文件指针。

  > 注意:

  > `stream` 必须打开写入。

`size`

  截断的大小。

  > 注意:

  > If `size` is larger than the file then the file is extended with null bytes.

  > If `size` is smaller than the file then the file is truncated to that size.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 文件截取示例

    <?php
    $filename = 'lorem_ipsum.txt';

    $handle = fopen($filename, 'r+');
    ftruncate($handle, rand(1, filesize($filename)));
    rewind($handle);
    echo fread($handle, filesize($filename));
    fclose($handle);
    ?>

### 注释

> 注意:

> 文件指针不会改变。

### 参见

- fopen() - 打开文件或者 URL
- fseek() - 在文件指针中定位

# fwrite

(PHP 4, PHP 5, PHP 7, PHP 8)

fwrite — 写入文件（可安全用于二进制文件）

### 说明

function fwrite(resource `$stream`, string `$data`, ?int `$length` = `null`): int|false

fwrite() 把 `data` 的内容写入 文件指针 `stream` 处。

### 参数

`stream`
  文件系统指针，是典型地由 fopen() 创建的 resource(资源)。
`data`

  要写入的字符串。

`length`

  如果 `length` 是 int，当写入了 `length` 个字节或者写完了 `string` 以后，写入就会停止，看先碰到哪种情况。

### 返回值

fwrite() 返回写入的字符数， 或者在失败时返回 `false`。

### 错误／异常

fwrite() 失败时会引发 `E_WARNING`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `length` 可以为 null。

### 示例

示例 #1 简单的 fwrite() 示例

    <?php
    $filename = 'test.txt';
    $somecontent = "Add this to the file\n";

    // 首先确认文件存在且可写。
    if (is_writable($filename)) {

        // 在示例中，使用追加模式打开 $filename。
        // 文件指针应该在文件的末尾，
        // 那就是使用 fwrite() 写入 $somecontent 的地方。
        if (!$fp = fopen($filename, 'a')) {
             echo "Cannot open file ($filename)";
             exit;
        }

        // 将 $somecontent 写入到打开的文件。
        if (fwrite($fp, $somecontent) === FALSE) {
            echo "Cannot write to file ($filename)";
            exit;
        }

        echo "Success, wrote ($somecontent) to file ($filename)";

        fclose($fp);

    } else {
        echo "The file $filename is not writable";
    }
    ?>

### 注释

> 注意:

> Writing to a network stream may end before the whole string is written. Return value of fwrite() may be checked:

>     <?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;
>     }
>     ?>

> 注意:

> 在区分二进制文件和文本文件的系统上（如 Windows） 打开文件时，fopen() 函数的 mode 参数要加上 'b'。

> 注意:

> 如果 `stream` 是 fopen() 追加模式，fwrite() 是原子操作（unless the size of `data` exceeds the filesystem's block size, on some platforms, and as long as the file is on a local filesystem）。也就是说，在调用 fwrite() 之前不需要 flock() 资源；所有的数据都将会不间断写入。

> 注意:

> 如果向文件指针写入两次，然后数据将追加到文件内容的末尾：

>     <?php
>     $fp = fopen('data.txt', 'w');
>     fwrite($fp, '1');
>     fwrite($fp, '23');
>     fclose($fp);

>     // “data.txt”的内容是 123 而不是 23！
>     ?>

### 参见

- fread() - 读取文件（可安全用于二进制文件）
- fopen() - 打开文件或者 URL
- fsockopen() - 打开 Internet 或者 Unix 套接字连接
- popen() - 打开进程文件指针
- file_get_contents() - 将整个文件读入一个字符串
- pack() - 将数据打包成二进制字符串

# glob

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

glob — 寻找与模式匹配的文件路径

### 说明

function glob(string `$pattern`, int `$flags` = 0): array|false

glob() 函数依照 libc glob() 函数使用的规则寻找所有与 `pattern` 匹配的文件路径，类似于一般 shells 所用的规则一样。

Unix 系统和 macOS 上的行为由系统级 glob() 实现来决定。在 Windows 上，使用符合 POSIX 1003.2 定义的 glob() 实现，它包含一个扩展来处理 `[!...]` 约定以否定范围。

### 参数

`pattern`

  匹配模式（pattern）。 不进行缩写扩展或参数替代。

  特殊字符：

  - `*` - 匹配零个或多个字符。
  - `?` - 只匹配单个字符（任意字符）。
  - `[...]` - 匹配一组字符中的一个字符。 如果第一个字符是 `!`，则为否定模式， 即匹配不在这组字符中的任意字符。
  - `{a,b,c}` - 当使用 `GLOB_BRACE` 标志时，匹配以逗号分隔的字符串组中的一个字符串。
  - `\` - 只要没有使用 `GLOB_NOESCAPE` 标记，该字符会转义后面的字符。
`flags`

  任何 `GLOB_*` 常量。

### 返回值

返回包含有匹配文件和目录的数组，没有匹配文件时返回空数组，出错返回 `false`。除非使用了 `GLOB_NOSORT`，否则名称将按字母顺序排序。

### 示例

示例 #1 怎样用 glob() 方便地替代 opendir() 和相关函数

    <?php
    foreach (glob("*.txt") as $filename) {
        echo "$filename size " . filesize($filename) . "\n";
    }
    ?>

以上示例的输出类似于：

    funclist.txt size 44686
    funcsummary.txt size 267625
    quickref.txt size 137820

示例 #2 更复杂模式的示例

    <?php
    foreach (glob("path/*/*.{txt,md}", \GLOB_BRACE) as $filename) {
        echo "$filename\n";
    }
    ?>

以上示例的输出类似于：

    path/docs/mailinglist-rules.md
    path/docs/README.md
    path/docs/release-process.md
    path/pear/install-pear.txt
    path/Zend/README.md

### 注释

> 注意: 此函数不能作用于远程文件，被检查的文件必须是可通过服务器的文件系统访问的。

> 注意: 此函数在一些系统上还不能工作（例如一些旧的 Sun OS）。

### 参见

- opendir() - 打开目录句柄
- readdir() - 从目录句柄中读取条目
- closedir() - 关闭目录句柄
- fnmatch() - 用模式匹配文件名

# is_dir

(PHP 4, PHP 5, PHP 7, PHP 8)

is_dir — 判断给定文件名是否是一个目录

### 说明

function is_dir(string `$filename`): bool

判断给定文件名是否是一个目录。

### 参数

`filename`

  文件路径，如果 `filename` 是相对文件名，会相对于当前工作目录进行检查。如果 `filename` 是符号链接或者硬链接，然后解析链接并检查。如果启用了 open_basedir，则会应用更多限制。

### 返回值

如果文件名存在，并且是个目录，返回 `true`，否则返回`false`。

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 示例

示例 #1 is_dir() 例子

    <?php
    var_dump(is_dir('a_file.txt'));
    var_dump(is_dir('bogus_dir/abc'));

    var_dump(is_dir('..')); //one dir up
    ?>

以上示例会输出：

    bool(false)
    bool(false)
    bool(true)

### 注释

> 注意: 此函数的结果会被缓存。参见 clearstatcache() 以获得更多细节。

小技巧

自 PHP 5.0.0 起, 此函数也用于某些 URL 包装器。请参见 支持的协议和封装协议以获得支持 stat() 系列函数功能的包装器列表。

### 参见

- chdir() - 改变目录
- dir() - 返回一个 Directory 类实例
- opendir() - 打开目录句柄
- is_file() - 判断给定文件名是否为一个正常的文件
- is_link() - 判断给定文件名是否为一个符号连接

# is_executable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_executable — 判断给定文件名是否可执行

### 说明

function is_executable(string `$filename`): bool

判断给定文件名是否可执行。

### 参数

`filename`

  文件的路径。

### 返回值

如果文件存在且可执行则返回 `true`，错误时返回 `false`。在 POSIX 系统中，如果设置了文件权限的可执行位，则文件可执行。对于 Windows，请参阅下面的注释。

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 示例

示例 #1 is_executable() 例子

    <?php

    $file = '/home/vincent/somefile.sh';

    if (is_executable($file)) {
        echo $file.' is executable';
    } else {
        echo $file.' is not executable';
    }

    ?>

### 注释

> 注意: 此函数的结果会被缓存。参见 clearstatcache() 以获得更多细节。

小技巧

自 PHP 5.0.0 起, 此函数也用于某些 URL 包装器。请参见 支持的协议和封装协议以获得支持 stat() 系列函数功能的包装器列表。

> 注意: 在 Windows 上，如果文件是 Win API `GetBinaryType()` 报告的正确可执行文件，则该文件视为可执行文件；由于 BC 原因，扩展名是 .bat 或 .cmd 的文件也被视为可执行文件。在 PHP 7.4.0 之前，任何扩展名是 .bat 或 .cmd 的非空文件都被视为可执行文件。注意 PATHEXT 与 is_executable() 无关。

### 参见

- is_file() - 判断给定文件名是否为一个正常的文件
- is_link() - 判断给定文件名是否为一个符号连接

# is_file

(PHP 4, PHP 5, PHP 7, PHP 8)

is_file — 判断给定文件名是否为一个正常的文件

### 说明

function is_file(string `$filename`): bool

判断指定文件名是否为正常的文件。如果 `filename` 是符号链接，将会解析符号链接并提供有关所引用文件的信息。

### 参数

`filename`

  文件的路径。

### 返回值

如果文件存在且为正常的文件则返回 `true`，否则返回 `false`。

> 注意: 因为 PHP 的整数类型是有符号整型而且很多平台使用 32 位整型，对 2GB 以上的文件，一些文件系统函数可能返回无法预期的结果。

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 示例

示例 #1 is_file() 例子

    <?php
    var_dump(is_file('a_file.txt')) . "\n";
    var_dump(is_file('/usr/bin/')) . "\n";
    ?>

以上示例会输出：

    bool(true)
    bool(false)

### 注释

> 注意: 此函数的结果会被缓存。参见 clearstatcache() 以获得更多细节。

小技巧

自 PHP 5.0.0 起, 此函数也用于某些 URL 包装器。请参见 支持的协议和封装协议以获得支持 stat() 系列函数功能的包装器列表。

### 参见

- is_dir() - 判断给定文件名是否是一个目录
- is_link() - 判断给定文件名是否为一个符号连接
- SplFileInfo

# is_link

(PHP 4, PHP 5, PHP 7, PHP 8)

is_link — 判断给定文件名是否为一个符号连接

### 说明

function is_link(string `$filename`): bool

判断给定文件名是否为一个符号连接。

### 参数

`filename`

  文件的路径。

### 返回值

如果文件存在并且是一个符号连接则返回 `true`，否则返回 `false`。

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 示例

示例 #1 创建并确认一个文件是否为符号连接

    <?php
    $link = 'uploads';

    if (is_link($link)) {
        echo readlink($link);
    } else {
        symlink('uploads.php', $link);
    }
    ?>

### 注释

> 注意: 此函数的结果会被缓存。参见 clearstatcache() 以获得更多细节。

小技巧

自 PHP 5.0.0 起, 此函数也用于某些 URL 包装器。请参见 支持的协议和封装协议以获得支持 stat() 系列函数功能的包装器列表。

### 参见

- is_dir() - 判断给定文件名是否是一个目录
- is_file() - 判断给定文件名是否为一个正常的文件
- readlink() - 返回符号连接指向的目标
- symlink() - 建立符号连接

# is_readable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_readable — 判断给定文件名是否可读

### 说明

function is_readable(string `$filename`): bool

判断给定文件名是否存在并且可读。

### 参数

`filename`

  文件的路径。

### 返回值

如果由 `filename` 指定的文件或目录存在并且可读则返回 `true`，否则返回 `false`。

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 示例

示例 #1 is_readable() 例子

    <?php
    $filename = 'test.txt';
    if (is_readable($filename)) {
        echo 'The file is readable';
    } else {
        echo 'The file is not readable';
    }
    ?>

### 注释

记住 PHP 也许只能以运行 webserver 的用户名（通常为 'nobody'）来访问文件。不计入安全模式的限制。

> 注意: 此函数的结果会被缓存。参见 clearstatcache() 以获得更多细节。

小技巧

自 PHP 5.0.0 起, 此函数也用于某些 URL 包装器。请参见 支持的协议和封装协议以获得支持 stat() 系列函数功能的包装器列表。

> 注意:

> The check is done using the real UID/GID instead of the effective one.

对于目录这个函数可能会返回 `true`。请使用 is_dir() 来区分文件和目录。

### 参见

- is_writable() - 判断给定的文件名是否可写
- file_exists() - 检查文件或目录是否存在
- fgets() - 从文件指针中读取一行

# is_uploaded_file

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

is_uploaded_file — 判断文件是否是通过 HTTP POST 上传的

### 说明

function is_uploaded_file(string `$filename`): bool

如果 `filename` 所给出的文件是通过 HTTP POST 上传的则返回 `true`。这可以用来确保恶意的用户无法欺骗脚本去访问本不能访问的文件，例如 /etc/passwd。

这种检查显得格外重要，如果上传的文件有可能会造成对用户或本系统的其他用户显示其内容的话。

为了能使 is_uploaded_file() 函数正常工作，必须指定类似于 $_FILES['userfile']['tmp_name'] 的变量，而在从客户端上传的文件名 $_FILES['userfile']['name'] 不能正常运作。

### 参数

`filename`

  要检查的文件名。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 is_uploaded_file() 例子

    <?php

    if (is_uploaded_file($_FILES['userfile']['tmp_name'])) {
       echo "File ". $_FILES['userfile']['name'] ." uploaded successfully.\n";
       echo "Displaying contents\n";
       readfile($_FILES['userfile']['tmp_name']);
    } else {
       echo "Possible file upload attack: ";
       echo "filename '". $_FILES['userfile']['tmp_name'] . "'.";
    }

    ?>

### 参见

- move_uploaded_file() - 将上传的文件移动到新位置
- $_FILES
- 关于用法的简单例子 文件上传处理

# is_writable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_writable — 判断给定的文件名是否可写

### 说明

function is_writable(string `$filename`): bool

如果文件存在并且可写则返回 `true`。`filename` 参数可以是一个允许进行是否可写检查的目录名。

记住 PHP 也许只能以运行 webserver 的用户名（通常为 'nobody'）来访问文件。

### 参数

`filename`

  要检查的文件名称。

### 返回值

如果文件 `filename` 存在并且可写则返回 `true`。

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 示例

示例 #1 is_writable() 例子

    <?php
    $filename = 'test.txt';
    if (is_writable($filename)) {
        echo 'The file is writable';
    } else {
        echo 'The file is not writable';
    }
    ?>

### 注释

> 注意: 此函数的结果会被缓存。参见 clearstatcache() 以获得更多细节。

小技巧

自 PHP 5.0.0 起, 此函数也用于某些 URL 包装器。请参见 支持的协议和封装协议以获得支持 stat() 系列函数功能的包装器列表。

### 参见

- is_readable() - 判断给定文件名是否可读
- file_exists() - 检查文件或目录是否存在
- fwrite() - 写入文件（可安全用于二进制文件）

# is_writeable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_writeable — is_writable() 的别名

### 说明

此函数是该函数的别名：is_writable()。

# lchgrp

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

lchgrp — 修改符号链接的所有组

### 说明

function lchgrp(string `$filename`, string|int `$group`): bool

尝试修改符号链接 `filename` 的所有组 `group`

只有超级用户可以任意修改符号链接的所有组;其他用户可能需要有修改目标组的权限才能修改至目标所有组。

### 参数

`filename`

  符号链接路径

`group`

  所有组的名字或者编号

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 更改符号链接的所有组

    <?php
    $target = 'output.php';
    $link = 'output.html';
    symlink($target, $link);

    lchgrp($link, 8);
    ?>

### 注释

> 注意: 此函数不能作用于远程文件，被检查的文件必须是可通过服务器的文件系统访问的。

> 注意: 此函数未在 Windows 平台下实现。

### 参见

- chgrp() - 改变文件所属的组
- lchown() - 修改符号链接的所有者
- chown() - 改变文件的所有者
- chmod() - 改变文件模式

# lchown

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

lchown — 修改符号链接的所有者

### 说明

function lchown(string `$filename`, string|int `$user`): bool

尝试修改符号链接 `filename` 的 所有者 `user`

只有超级用户任意修改符号链接的所有者。

### 参数

`filename`

  文件路径。

`user`

  所有者名称或编号

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Changing the owner of a symbolic link

    <?php
    $target = 'output.php';
    $link = 'output.html';
    symlink($target, $link);

    lchown($link, 8);
    ?>

### 注释

> 注意: 此函数不能作用于远程文件，被检查的文件必须是可通过服务器的文件系统访问的。

> 注意: 此函数未在 Windows 平台下实现。

### 参见

- chown() - 改变文件的所有者
- lchgrp() - 修改符号链接的所有组
- chgrp() - 改变文件所属的组
- chmod() - 改变文件模式

# link

(PHP 4, PHP 5, PHP 7, PHP 8)

link — 建立一个硬连接

### 说明

function link(string `$target`, string `$link`): bool

link() 建立一个硬连接。

### 参数

`target`

  要链接的目标。

`link`

  链接的名称。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

如果 `link` 已存在或者 `target` 不存在，此函数会失败并发出 `E_WARNING`。

### 示例

示例 #1 创建简单的硬链接

    <?php
    $target = 'source.ext'; // This is the file that already exists
    $link = 'newfile.ext'; // This the filename that you want to link it to

    link($target, $link);
    ?>

### 注释

> 注意: 此函数不能作用于远程文件，被检查的文件必须是可通过服务器的文件系统访问的。

> 注意: 仅适用于 Windows：此函数需要 PHP 在提升模式或者禁用 UAC 时运行。

### 参见

- symlink() - 建立符号连接
- readlink() - 返回符号连接指向的目标
- linkinfo() - 获取一个连接的信息
- unlink() - 删除文件

# linkinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

linkinfo — 获取一个连接的信息

### 说明

function linkinfo(string `$path`): int|false

获取一个连接的信息。

本函数用来验证一个连接（由 `path` 所指向的）是否确实存在（使用 stat.h 中的 S_ISLNK 宏同样的方法）。

### 参数

`path`

  连接的路径。

### 返回值

linkinfo() 返回 `lstat` 系统调用所返回的 UNIX C stat 结构中的 `st_dev` 字段。成功时返回非负数，如果链接未找到则返回 -1，如果跟 open.base_dir 冲突则返回 `false`。

### 示例

示例 #1 linkinfo() 例子

    <?php

    echo linkinfo('/vmlinuz'); // 835

    ?>

### 参见

- symlink() - 建立符号连接
- link() - 建立一个硬连接
- readlink() - 返回符号连接指向的目标

# lstat

(PHP 4, PHP 5, PHP 7, PHP 8)

lstat — 给出一个文件或符号连接的信息

### 说明

function lstat(string `$filename`): array|false

获取由 `filename` 指定的文件或符号连接的统计信息。

### 参数

`filename`

  文件或符号连接的路径。

### 返回值

有关 lstat() 返回的数组结构见手册中 stat() 函数的页面。 本函数和 stat() 函数相同，只除了如果 `filename` 参数是符号连接的话，则该符号连接的状态被返回，而不是该符号连接所指向的文件的状态。

失败时返回 `false`。

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 示例

示例 #1 stat() 和 lstat() 的对照

    <?php
    symlink('uploads.php', 'uploads');

    // Contrast information for uploads.php and uploads
    array_diff(stat('uploads'), lstat('uploads'));
    ?>

以上示例的输出类似于：

Information that differs between the two files.

    Array
    (
        [ino] => 97236376
        [mode] => 33188
        [size] => 34
        [atime] => 1223580003
        [mtime] => 1223581848
        [ctime] => 1223581848
        [blocks] => 8
    )

### 注释

> 注意: 此函数的结果会被缓存。参见 clearstatcache() 以获得更多细节。

小技巧

自 PHP 5.0.0 起, 此函数也用于某些 URL 包装器。请参见 支持的协议和封装协议以获得支持 stat() 系列函数功能的包装器列表。

### 参见

- stat() - 给出文件的信息

# mkdir

(PHP 4, PHP 5, PHP 7, PHP 8)

mkdir — 新建目录

### 说明

function mkdir(
string `$directory`,
int `$permissions` = 0777,
bool `$recursive` = `false`,
?resource `$context` = `null`
): bool

尝试新建由 `directory` 指定的目录。

### 参数

`directory`

  目录的路径。

  小技巧

  如已启用fopen 包装器，在此函数中， URL 可作为文件名。关于如何指定文件名详见 fopen()。各种 wapper 的不同功能请参见 支持的协议和封装协议，注意其用法及其可提供的预定义变量。

`permissions`

  默认权限是 0777，意味着最大可能的访问权。有关权限的更多信息请阅读 chmod() 页面。

  > 注意:

  > `permissions` 在 Windows 下被忽略。

  注意也许想用八进制数指定 `permissions`，也就是说该数应以零打头。`permissions` 也会被当前的 umask 修改，可以用 umask() 来改变。

`recursive`

  如果为 `true`，还将会创建指定 `directory` 的任何父级目录，并具有相同的权限。

`context`
  上下文流（context stream） resource。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

> 注意:

> 如果创建的目录已存在，则视为错误，仍然返回 `false`。在尝试创建之前，使用 is_dir() 或者 file_exists() 检查目录是否已经存在。

### 错误／异常

目录已存在时，产生 `E_WARNING` 错误。

如果因为权限问题无法创建目录，导致 `E_WARNING` 错误。

### 示例

示例 #1 mkdir() 例子

    <?php
    mkdir("/path/to/my/dir", 0700);
    ?>

示例 #2 通过 `recursive` 参数使用 mkdir()

    <?php
    // 期望的目录结构
    $structure = './depth1/depth2/depth3/';

    // 要创建嵌套结构，必须指定 mkdir()
    // 的 $recursive 参数。

    if (!mkdir($structure, 0777, true)) {
        die('Failed to create directories...');
    }

    // ...
    ?>

### 参见

- is_dir() - 判断给定文件名是否是一个目录
- rmdir() - 删除目录
- umask() - 改变当前的 umask

# move_uploaded_file

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

move_uploaded_file — 将上传的文件移动到新位置

### 说明

function move_uploaded_file(string `$from`, string `$to`): bool

本函数检查并确保由 `from` 指定的文件是合法的上传文件（即通过 PHP 的 HTTP POST 上传机制所上传的）。如果文件合法，则将其移动为由 `to` 指定的文件。

这种检查显得格外重要，如果上传的文件有可能会造成对用户或本系统的其他用户显示其内容的话。

### 参数

`from`

  上传的文件的文件名。

`to`

  移动文件到这个位置。

### 返回值

成功时返回 `true`。

如果 `from` 不是合法的上传文件，不会出现任何操作，move_uploaded_file() 将返回 `false`。

如果 `from` 是合法的上传文件，但出于某些原因无法移动，不会出现任何操作，move_uploaded_file() 将返回 `false`。此外还会发出一条警告。

### 示例

示例 #1 Uploading multiple files

    <?php
    $uploads_dir = '/uploads';
    foreach ($_FILES["pictures"]["error"] as $key => $error) {
        if ($error == UPLOAD_ERR_OK) {
            $tmp_name = $_FILES["pictures"]["tmp_name"][$key];
            // basename() 可以防止遍历攻击文件系统；
            // 进一步验证/清理文件名可能是合适的
            $name = basename($_FILES["pictures"]["name"][$key]);
            move_uploaded_file($tmp_name, "$uploads_dir/$name");
        }
    }
    ?>

### 注释

> 注意:

> move_uploaded_file() 对 open_basedir 是敏感的。不过，限制只针对 `to` 路径，因为允许移动上传的文件名 `from` 可能会与这些限制产生冲突。move_uploaded_file() 仅作用于通过 PHP 上传的文件以确保这个操作的安全性。

警告

如果目标文件已经存在，将会被覆盖。

### 参见

- is_uploaded_file() - 判断文件是否是通过 HTTP POST 上传的
- rename() - 重命名一个文件或目录
- 参见文件上传处理一章中的简单使用例子。

# parse_ini_file

(PHP 4, PHP 5, PHP 7, PHP 8)

parse_ini_file — 解析一个配置文件

### 说明

function parse_ini_file(string `$filename`, bool `$process_sections` = `false`, int `$scanner_mode` = `INI_SCANNER_NORMAL`): array|false

parse_ini_file() 载入一个由 `filename` 指定的 ini 文件，并将其中的设置作为一个关联数组返回。

ini 文件的结构和 php.ini 的相同。

警告

此函数不得用于不可信的输入，除非 `scanner_mode` 设置为 `INI_SCANNER_RAW`，因为解析后的输出可能包含敏感常量的值，例如存储数据库密码的常量。

### 参数

`filename`

  要解析的 ini 文件的文件名。如果使用相对路径，则优先在相对于当前工作目录的目录中查找文件，如果未找到则在 include_path 中查找文件进行解析。

`process_sections`

  如果将 `process_sections` 参数设为 `true`，将得到多维数组，包括了配置文件中的节名和配置。`process_sections` 的默认值是 `false`。

`scanner_mode`

  可以是 `INI_SCANNER_NORMAL`（默认），也可以是 `INI_SCANNER_RAW`。如果提供了 `INI_SCANNER_RAW`，然后将不会解析选项值。

  As of PHP 5.6.1 can also be specified as `INI_SCANNER_TYPED`. In this mode boolean, null and integer types are preserved when possible. String values `"true"`, `"on"` and `"yes"` are converted to `true`. `"false"`, `"off"`, `"no"` and `"none"` are considered `false`. `"null"` is converted to `null` in typed mode. Also, all numeric strings are converted to integer type if it is possible.

### 返回值

成功时以关联数组 array 返回设置，失败时返回 `false`。

### 示例

示例 #1 sample.ini 的内容

    ; This is a sample configuration file
    ; Comments start with ';', as in php.ini

    [first_section]
    one = 1
    five = 5
    animal = BIRD

    [second_section]
    path = "/usr/local/bin"
    URL = "http://www.example.com/~username"

    [third_section]
    phpversion[] = "5.0"
    phpversion[] = "5.1"
    phpversion[] = "5.2"
    phpversion[] = "5.3"

    urls[svn] = "http://svn.php.net"
    urls[git] = "http://git.php.net"

示例 #2 parse_ini_file() 例子

常量（并非像 `__FILE__` 之类的“魔术常量”）也可以在 ini 文件中被解析，因此如果在运行 parse_ini_file() 之前定义了常量作为 ini 的值，将会被集成到结果中去。只有 ini 的值会被求值，且该值必须是常量。例如：

    <?php

    define('BIRD', 'Dodo bird');

    // Parse without sections
    $ini_array = parse_ini_file("sample.ini");
    print_r($ini_array);

    // Parse with sections
    $ini_array = parse_ini_file("sample.ini", true);
    print_r($ini_array);

    ?>

以上示例的输出类似于：

    Array
    (
        [one] => 1
        [five] => 5
        [animal] => Dodo bird
        [path] => /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
    (
        [first_section] => Array
            (
                [one] => 1
                [five] => 5
                [animal] => Dodo bird
            )

        [second_section] => Array
            (
                [path] => /usr/local/bin
                [URL] => http://www.example.com/~username
            )

        [third_section] => 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
                    )

            )

    )

示例 #3 parse_ini_file() 格式化 php.ini 文件

    <?php
    // 简单的函数，用于比较下面的结果
    function yesno($expression)
    {
        return($expression ? 'Yes' : 'No');
    }

    // 使用 php_ini_loaded_file() 函数获取 php.ini 的路径
    $ini_path = php_ini_loaded_file();

    // 解析 php.ini
    $ini = parse_ini_file($ini_path);

    // Print and compare the values, note that using get_cfg_var()
    // will give the same results for parsed and loaded here
    echo '(parsed) magic_quotes_gpc = ' . yesno($ini['magic_quotes_gpc']) . PHP_EOL;
    echo '(loaded) magic_quotes_gpc = ' . yesno(get_cfg_var('magic_quotes_gpc')) . PHP_EOL;
    ?>

以上示例的输出类似于：

    (parsed) magic_quotes_gpc = Yes
    (loaded) magic_quotes_gpc = Yes

示例 #4 内插值

除了对常量求值之外，某些字符在 ini 值中具有特殊含义。此外，可以使用 `${}` 语法读取环境变量和之前定义的配置项（参阅 get_cfg_var()）。

    ; | is used for bitwise OR
    three = 2|3

    ; & is used for bitwise AND
    four = 6&5

    ; ^ is used for bitwise XOR
    five = 3^6

    ; ~ is used for bitwise negate
    negative_two = ~1

    ; () is used for grouping
    seven = (8|7)&(6|5)

    ; Interpolate the PATH environment variable
    path = ${PATH}

    ; Interpolate the configuration option 'memory_limit'
    configured_memory_limit = ${memory_limit}

示例 #5 转义字符

Some characters have special meaning in double-quoted strings and must be escaped by the backslash prefix. First of all, these are the double quote `"` as the boundary marker, and the backslash `\` itself (if followed by one of the special characters):

    quoted = "She said \"Exactly my point\"." ; Results in a string with quote marks in it.
    hint = "Use \\\" to escape double quote" ; Results in: Use \" to escape double quote

There is an exception made for Windows-like paths: it's possible to not escape trailing backslash if the quoted string is directly followed by a linebreak:

    save_path = "C:\Temp\"

If one does need to escape double quote followed by linebreak in a multiline value, it's possible to use value concatenation in the following way (there is one double-quoted string directly followed by another one):

    long_text = "Lorem \"ipsum\"""
     dolor" ; Results in: Lorem "ipsum"\n dolor

Another character with special meaning is `$` (the dollar sign). It must be escaped if followed by the open curly brace:

    code = "\${test}"

`INI_SCANNER_RAW` 模式不支持转义字符（在此模式下，所有字符都会“不做任何处理”）。

注意 ini 解析器不支持标准转义序列（`\n`、`\t` 等）。如有必要，使用 stripcslashes() 函数对 parse_ini_file() 后的结果进行后处理。

### 注释

> 注意:

> 本函数和 php.ini 文件无关，该文件在运行脚本时就已经处理过了。本函数可以用来读取应用程序的配置文件。

> 注意:

> 如果 ini 文件中的值包含任何非字母数字的字符，需要将其括在双引号中（"）。

> 注意: 有些保留字不能作为 ini 文件中的键名，包括：`null`、`yes`、`no`、`true`、`false`、`on`、`off`、`none`。除非使用 `INI_SCANNER_TYPED` 模式，否则 `null`、`off`、`no` 和 `false` 的值等效于 `""`，`on`、`yes` 和 `true` 的值等效于 `"1"`。字符 `?{}|&~!()^"` 也不能用在键名的任何地方，而且这些字符在选项值中有着特殊的意义。

> 注意:

> 不带等号的条目会忽略。例如“foo”会忽略，而“bar =”将会解析并添加空值。例如，会忽略 MySQL 在 my.cnf 中不带值的“no-auto-rehash”设置。

> 注意:

> ini 文件通常被 Web 服务器视为纯文本，因此在请求时会提供给浏览器。这意味着为了安全起见，必须将 ini 文件保存在 docroot 之外，或者重新配置 Web 服务器，不会提供这些文件。如果不这么做，可能会带来安全风险。

### 参见

- parse_ini_string() - 解析配置字符串

# parse_ini_string

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

parse_ini_string — 解析配置字符串

### 说明

function parse_ini_string(string `$ini_string`, bool `$process_sections` = `false`, int `$scanner_mode` = `INI_SCANNER_NORMAL`): array|false

parse_ini_string() 返回 `ini_string` 字符串解析后的关联数组。

ini 字符串的格式参考 php.ini

警告

此函数不得用于不可信的输入，除非 `scanner_mode` 设置为 `INI_SCANNER_RAW`，因为解析后的输出可能包含敏感常量的值，例如存储数据库密码的常量。

### 参数

`ini_string`

  ini 字符串内容。

`process_sections`

  设置 `process_sections` 参数为 `true`，得到一个多维数组，包含名称和设置。`process_sections` 默认为 `false`。

`scanner_mode`

  可以是 `INI_SCANNER_NORMAL` (默认)或 `INI_SCANNER_RAW`。如果是 `INI_SCANNER_RAW`，那么选项值不会被解析。

  As of PHP 5.6.1 can also be specified as `INI_SCANNER_TYPED`. In this mode boolean, null and integer types are preserved when possible. String values `"true"`, `"on"` and `"yes"` are converted to `true`. `"false"`, `"off"`, `"no"` and `"none"` are considered `false`. `"null"` is converted to `null` in typed mode. Also, all numeric strings are converted to integer type if it is possible.

### 返回值

执行成功返回一个关联数组，返回 `false` 为失败。

### 注释

> 注意: 有些保留字不能作为 ini 文件中的键名，包括：`null`、`yes`、`no`、`true`、`false`、`on`、`off`、`none`。除非使用 `INI_SCANNER_TYPED` 模式，否则 `null`、`off`、`no` 和 `false` 的值等效于 `""`，`on`、`yes` 和 `true` 的值等效于 `"1"`。字符 `?{}|&~![()^"` 也不能用在键名的任何地方，而且这些字符在选项值中有着特殊的意义。

### 参见

- parse_ini_file() - 解析一个配置文件

# pathinfo

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pathinfo — 返回文件路径的信息

### 说明

function pathinfo(string `$path`, int `$flags` = `PATHINFO_ALL`): array|string

pathinfo() 返回一个关联数组包含有 `path` 的信息。返回关联数组还是字符串取决于 `flags`。

> 注意:

> 有关取得当前路径信息的说明，请阅读 预定义变量 一节。

> 注意:

> pathinfo() 纯粹基于输入字符串操作， 它不会受实际文件系统和类似 "`..`" 的路径格式影响。

> 注意:

> 反斜线字符 `\` 仅在 Windows 系统上会解释为目录分隔符。在其他系统上，它将视为普通字符。

警告

pathinfo() 是本地化的，所以为了让它能正确地解析一个包含多字节编码的路径， 必须使用 setlocale() 函数来设置地区信息。

### 参数

`path`

  要解析的路径。

`flags`

  如果指定了，将会返回指定元素；它们包括： `PATHINFO_DIRNAME`、 `PATHINFO_BASENAME`、 `PATHINFO_EXTENSION`、 `PATHINFO_FILENAME`。

  如果没有指定 `flags` 默认是返回全部的单元。

### 返回值

如果没有传入 `options` ，将会返回包括以下单元的数组 array：`dirname`，`basename` 和 `extension`（如果有），以及`filename`。

> 注意:

> 如果 `path` 有一个以上的扩展名， `PATHINFO_EXTENSION` 只返回最后一个，而 `PATHINFO_FILENAME` 仅剥离最后一个。 （参考第一个示例）。

> 注意:

> 如果 `path` 没有扩展名，返回数据中就不会有 `extension` 元素。（参考第二个示例）

> 注意:

> 如果 `path` 中的 `basename` 以点开始， 那后面的字符串将被解释为 `extension` ， 并且 `filename` 为空。（参考第三个示例）

如果 `flags` 存在的， 则返回一个包含请求元素的 string。

### 示例

示例 #1 pathinfo() 例子

    <?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";
    ?>

以上示例会输出：

    /www/htdocs/inc
    lib.inc.php
    php
    lib.inc

示例 #2 pathinfo() 对比空扩展名和无扩展名之间区别的示例

    <?php
    $path_parts = pathinfo('/path/emptyextension.');
    var_dump($path_parts['extension']);

    $path_parts = pathinfo('/path/noextension');
    var_dump($path_parts['extension']);
    ?>

以上示例的输出类似于：

    string(0) ""

    Notice: Undefined index: extension in test.php on line 6
    NULL

示例 #3 pathinfo() 形如 .file 的示例

    <?php
    print_r(pathinfo('/some/path/.test'));
    ?>

以上示例的输出类似于：

    Array
    (
        [dirname] => /some/path
        [basename] => .test
        [extension] => test
        [filename] =>
    )

示例 #4 pathinfo() 示例和解除数组引用

`flags` 参数不是位掩码。只能提供单个值。要是只选择某些格式化值，请使用数组解构，如下所示：

    <?php
    ['basename' => $basename, 'dirname' => $dirname] = pathinfo('/www/htdocs/inc/lib.inc.php');

    var_dump($basename, $dirname);
    ?>

以上示例的输出类似于：

    string(11) "lib.inc.php"
    string(15) "/www/htdocs/inc"

### 参见

- dirname() - 返回路径中的目录部分
- basename() - 返回路径中的文件名部分
- parse_url() - 解析 URL，返回其组成部分
- realpath() - 返回规范化的绝对路径名

# pclose

(PHP 4, PHP 5, PHP 7, PHP 8)

pclose — 关闭进程文件指针

### 说明

function pclose(resource `$handle`): int

关闭用 popen() 打开的指向管道的文件指针。

### 参数

`handle`

  文件指针必须有效，且必须是成功调用 popen() 所返回的。

### 返回值

返回运行的进程的终止状态。发生错误时会返回 `-1`。

> 注意: 如果 PHP 是通过 --enable-sigchild 编译的，此函数将没有返回值。

### 示例

示例 #1 pclose() 例子

    <?php
    $handle = popen('/bin/ls', 'r');
    pclose($handle);
    ?>

### 注释

> 注意: 仅限 Unix

> pclose() 在内部使用 `waitpid(3)` 系统调用实现的。要获得真正的退出状态码，应该使用 pcntl_wexitstatus() 函数。

### 参见

- popen() - 打开进程文件指针

# popen

(PHP 4, PHP 5, PHP 7, PHP 8)

popen — 打开进程文件指针

### 说明

function popen(string `$command`, string `$mode`): resource|false

打开一个指向进程的管道，该进程由派生给定的 command 命令执行而产生。

### 参数

`command`

  命令。

`mode`

  模式。`'r'` 表示阅读，`'w'` 表示写入。

  在 Windows 上，popen() 默认是文本模式，即任何从管道中读取/写入的 `\n` 字符都将转换为 `\r\n`。如果避免这种情况，可以通过将 `mode` 设置为 `'rb'` 和 `'wb'` 来强制执行二进制模式。

### 返回值

返回一个和 fopen() 所返回的相同的文件指针，只不过它是单向的（只能用于读或写）并且必须用 pclose() 来关闭。此指针可以用于 fgets()，fgetss() 和 fwrite()。 当模式为 'r'，返回的文件指针等于命令的 STDOUT，当模式为 'w'，返回的文件指针等于命令的 STDIN。

如果出错返回 `false`。

### 示例

示例 #1 popen() 例子

    <?php
    $handle = popen("/bin/ls", "r");
    ?>

如果未找到要执行的命令，会返回一个合法的资源。这看上去很怪，但有道理。它允许访问 shell 返回的任何错误信息：

示例 #2 popen() 例子

    <?php
    error_reporting(E_ALL);

    /* 加入重定向以得到标准错误输出 stderr。 */
    $handle = popen('/path/to/executable 2>&1', 'r');
    echo "'$handle'; " . gettype($handle) . "\n";
    $read = fread($handle, 2096);
    echo $read;
    pclose($handle);
    ?>

### 注释

> 注意:

> 如果需要双向支持，使用 proc_open()。

### 参见

- pclose() - 关闭进程文件指针
- fopen() - 打开文件或者 URL
- proc_open() - 执行一个命令，并且打开用来输入/输出的文件指针。

# readfile

(PHP 4, PHP 5, PHP 7, PHP 8)

readfile — 输出文件

### 说明

function readfile(string `$filename`, bool `$use_include_path` = `false`, ?resource `$context` = `null`): int|false

读取文件并写入到输出缓冲。

### 参数

`filename`

  要读取的文件名。

`use_include_path`

  想要在 include_path 中搜索文件，可使用这个可选的第二个参数，设为 `true`。

`context`
  上下文流（context stream） resource。

### 返回值

成功时返回从文件中读入的字节数， 或者在失败时返回 `false`

### 错误／异常

失败时抛出 `E_WARNING` 警告。

### 示例

示例 #1 使用 readfile() 强制下载

    <?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;
    }
    ?>

以上示例的输出类似于：

### 注释

> 注意:

> readfile() 自身不会导致任何内存问题。 如果出现内存不足的错误，使用 ob_get_level() 确保输出缓存已经关闭。

小技巧

如已启用fopen 包装器，在此函数中， URL 可作为文件名。关于如何指定文件名详见 fopen()。各种 wapper 的不同功能请参见 支持的协议和封装协议，注意其用法及其可提供的预定义变量。

### 参见

- fpassthru() - 输出文件指针处的所有剩余数据
- file() - 把整个文件读入一个数组中
- fopen() - 打开文件或者 URL
- include - include
- require - require
- virtual() - 执行 Apache 子请求
- file_get_contents() - 将整个文件读入一个字符串
- 支持的协议和封装协议

# readlink

(PHP 4, PHP 5, PHP 7, PHP 8)

readlink — 返回符号连接指向的目标

### 说明

function readlink(string `$path`): string|false

readlink() 和同名的 C 函数做同样的事，返回符号连接的内容。

### 参数

`path`

  链接符号的路径。

### 返回值

返回链接的路径内容，出错则返回 `false`。

> 注意: 如果 `path` 不是符号链接，则该函数将失败，但在 Windows 上除外，其中将返回规范化的路径。

### 示例

示例 #1 readlink() 示例

    <?php

    // output e.g. /boot/vmlinux-2.4.20-xfs
    echo readlink('/vmlinuz');

    ?>

### 参见

- is_link() - 判断给定文件名是否为一个符号连接
- symlink() - 建立符号连接
- linkinfo() - 获取一个连接的信息

# realpath

(PHP 4, PHP 5, PHP 7, PHP 8)

realpath — 返回规范化的绝对路径名

### 说明

function realpath(string `$path`): string|false

realpath() 扩展所有符号连接，并处理输入 `path` 中的 `/./`、`/../` 和多余的 `/`，并返回规范化的绝对路径名。

### 参数

`path`

  要处理的路径。

  > 注意:

  > 虽然必须提供路径，但该值可以是一个空字符串。 在这种情况下，该值将被解释为当前目录。

### 返回值

成功时返回规范化的绝对路径名。返回的路径中没有符号连接（symbolic link）、`/./` 或 `/../` 成分。 例如 `\` 和 `/` 这样的尾随分隔符也将被删除。

realpath() 失败时返回 `false`，例如文件不存在。

> 注意:

> 当前运行的脚本必须对要处理的路径中的每层目录都具有可执行权限，否则 realpath() 将返回 `false`。

> 注意:

> 对于不区分大小写的文件系统，realpath() 不一定会规范字符大小写。

> 注意:

> realpath() 函数不适用于 Phar 内的文件，因为该路径是虚拟路径，而不是真实路径。

> 注意:

> 在 Windows 上，目录的结点和符号链接仅扩展一级。

> 注意: 因为 PHP 的整数类型是有符号整型而且很多平台使用 32 位整型，对 2GB 以上的文件，一些文件系统函数可能返回无法预期的结果。

### 示例

示例 #1 realpath() 例子

    <?php
    chdir('/var/www/');
    echo realpath('./../../etc/passwd') . PHP_EOL;

    echo realpath('/tmp/') . PHP_EOL;
    ?>

以上示例会输出：

    /etc/passwd
    /tmp

示例 #2 Windows 上的 realpath()

在 Windows 上，realpath() 会将 unix 风格的路径改成 Windows 风格。

    <?php
    echo realpath('/windows/system32'), PHP_EOL;

    echo realpath('C:\Program Files\\'), PHP_EOL;
    ?>

以上示例会输出：

    C:\WINDOWS\System32
    C:\Program Files

### 参见

- basename() - 返回路径中的文件名部分
- dirname() - 返回路径中的目录部分
- pathinfo() - 返回文件路径的信息

# realpath_cache_get

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

realpath_cache_get — 获取真实目录缓存的详情

### 说明

function realpath_cache_get(): array

获得真实路径缓存的详情。

### 参数

此函数没有参数。

### 返回值

返回真实路径缓存详情的数组。键是原始路径以及值为具体信息数组，含有该解析的路径，过期时间以及其他的更多选项。

### 示例

示例 #1 realpath_cache_get() 示例

    <?php
    var_dump(realpath_cache_get());
    ?>

以上示例的输出类似于：

    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)
      }
    }

### 参见

- realpath_cache_size() - 获取真实路径缓冲区的大小

# realpath_cache_size

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

realpath_cache_size — 获取真实路径缓冲区的大小

### 说明

function realpath_cache_size(): int

获取真实路径缓存区大小在内存中的使用量。

### 参数

此函数没有参数。

### 返回值

返回真实路径缓存区使用内存的用量。

### 示例

示例 #1 realpath_cache_size() 示例

    <?php
    var_dump(realpath_cache_size());
    ?>

以上示例的输出类似于：

    int(412)

### 参见

- realpath_cache_get() - 获取真实目录缓存的详情
- realpath_cache_size 方法的配置选项

# rename

(PHP 4, PHP 5, PHP 7, PHP 8)

rename — 重命名一个文件或目录

### 说明

function rename(string `$from`, string `$to`, ?resource `$context` = `null`): bool

尝试把 `from` 重命名为 `to`，必要时会在不同目录间移动。 如果重命名文件时 `to` 已经存在，将会覆盖掉它。 如果重命名文件夹时 `to` 已经存在，本函数将导致一个警告。

### 参数

`from`

  原名

  > 注意:

  > 用于 `from` 中的封装协议必须和用于 `to` 中的相匹配。

`to`

  新的名字。

  > 注意: 在 Windows 上，如果 `to` 已经存在，它必须是可写的。 否则 rename() 将失败，并导致 `E_WARNING`。

`context`
  上下文流（context stream） resource。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 rename() 例子

    <?php
    rename("/tmp/tmp_file.txt", "/home/user/login/docs/my_file.txt");
    ?>

### 参见

- copy() - 拷贝文件
- unlink() - 删除文件
- move_uploaded_file() - 将上传的文件移动到新位置

# rewind

(PHP 4, PHP 5, PHP 7, PHP 8)

rewind — 倒回文件指针的位置

### 说明

function rewind(resource `$stream`): bool

将 `stream` 的文件位置指针设为文件流的开头。

> 注意:

> 如果将文件以附加（"a" 或者 "a+"）模式打开，无论文件指针位置如何，写入文件的任何数据总是会被附加在后面。

### 参数

`stream`

  文件指针必须合法，并且指向由 fopen() 成功打开的文件。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 rewind() overwriting example

    <?php
    $handle = fopen('output.txt', 'r+');

    fwrite($handle, 'Really long sentence.');
    rewind($handle);
    fwrite($handle, 'Foo');
    rewind($handle);

    echo fread($handle, filesize('output.txt'));

    fclose($handle);
    ?>

以上示例的输出类似于：

    Foolly long sentence.

### 参见

- fread() - 读取文件（可安全用于二进制文件）
- fseek() - 在文件指针中定位
- ftell() - 返回文件指针读/写的位置
- fwrite() - 写入文件（可安全用于二进制文件）

# rmdir

(PHP 4, PHP 5, PHP 7, PHP 8)

rmdir — 删除目录

### 说明

function rmdir(string `$directory`, ?resource `$context` = `null`): bool

尝试删除 `directory` 所指定的目录。 该目录必须是空的，而且要有相应的权限。 失败时会产生一个 `E_WARNING` 级别的错误。

### 参数

`directory`

  目录的路径。

`context`
  上下文流（context stream） resource。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 rmdir() 例子

    <?php
    if (!is_dir('examples')) {
        mkdir('examples');
    }

    rmdir('examples');
    ?>

### 参见

- is_dir() - 判断给定文件名是否是一个目录
- mkdir() - 新建目录
- unlink() - 删除文件

# set_file_buffer

(PHP 4, PHP 5, PHP 7, PHP 8)

set_file_buffer — stream_set_write_buffer() 的别名

### 说明

此函数是该函数的别名：stream_set_write_buffer()。

# stat

(PHP 4, PHP 5, PHP 7, PHP 8)

stat — 给出文件的信息

### 说明

function stat(string `$filename`): array|false

获取由 `filename` 指定的文件的统计信息。如果 `filename` 是符号连接，则统计信息是关于被连接文件本身的，而不是符号连接。在 PHP 7.4.0 之前，使用 Windows NTS 版本获取 `size`、`atime`、`mtime` 和 `ctime` 统计信息将从符号链接获取。

lstat() 和 stat() 相同，只除了它会返回符号连接的状态。

### 参数

`filename`

  文件的路径。

### 返回值

stat() 和 fstat() 返回格式
数字下标 | 关联键名 | 说明
--- | --- | ---
0 | dev | 设备号 ***
1 | ino | inode 号 ****
2 | mode | inode 保护模式 *****
3 | nlink | 连接数目
4 | uid | 所有者的用户 id *
5 | gid | 所有者的组 id *
6 | rdev | 设备类型，如果是 inode 设备的话
7 | size | 文件大小的字节数
8 | atime | 上次访问时间（Unix 时间戳）
9 | mtime | 上次修改时间（Unix 时间戳）
10 | ctime | 上次 inodb 改变时间（Unix 时间戳）
11 | blksize | 文件系统 IO 的块大小 **
12 | blocks | 分配的 512 字节块数 **

* Windows 下总是 `0`。

* - 仅在支持 st_blksize 类型的系统下有效。其它系统（如 Windows）返回 `-1`。

*** On Windows, as of PHP 7.4.0, this is the serial number of the volume that contains the file, which is a 64-bit unsigned integer, so may overflow. Previously, it was the numeric representation of the drive letter (e.g. `2` for `C:`) for stat(), and `0` for lstat().

**** 在 Windows 上，自 PHP 7.4.0 起，这是跟文件相关的标识符，因为是64位 unsigned 整数，因此可能会溢出。之前始终为 `0`。

***** On Windows, the writable permission bit is set according to the read-only file attribute, and the same value is reported for all users, group and owner. The ACL is not taken into account, contrary to is_writable().

`mode` 的值包含几个函数读取到的信息。当用八进制编写时，从右开始，前三位由 chmod() 返回。PHP 忽略下一个数字。接下来的两位数字表示文件类型：

`mode` 文件类型
八进制表示 `mode` | 含义
--- | ---
`0140000` | socket
`0120000` | link
`0100000` | 常规文件
`0060000` | 块设备
`0040000` | 目录
`0020000` | 字符设备
`0010000` | fifo

例如普通文件可能是 `0100644`，目录可能是 `0040755`。

如果出错，stat() 返回 `false`。

> 注意: 因为 PHP 的整数类型是有符号整型而且很多平台使用 32 位整型，对 2GB 以上的文件，一些文件系统函数可能返回无法预期的结果。

### 错误／异常

错误时会产生 `E_WARNING` 级别的错误。

### 更新日志

版本 | 说明
--- | ---
7.4.0 | On Windows, the device number is now the serial number of the volume that contains the file, and the inode number is the identifier associated with the file.
7.4.0 | The `size`, `atime`, `mtime` and `ctime` statistics of symlinks are always those of the target. This was previously not the case for NTS builds on Windows.

### 示例

示例 #1 stat() 例子

    <?php
    /* Get file stat */
    $stat = stat('C:\php\php.exe');

    /*
     * Print file access time, this is the same
     * as calling fileatime()
     */
    echo 'Access time: ' . $stat['atime'];

    /*
     * Print file modification time, this is the
     * same as calling filemtime()
     */
    echo 'Modification time: ' . $stat['mtime'];

    /* Print the device number */
    echo 'Device number: ' . $stat['dev'];
    ?>

示例 #2 Using stat() information together with touch()

    <?php
    /* Get file stat */
    $stat = stat('C:\php\php.exe');

    /* Did we failed to get stat information? */
    if (!$stat) {
        echo 'stat() call failed...';
    } else {
        /*
         * We want the access time to be 1 week
         * after the current access time.
         */
        $atime = $stat['atime'] + 604800;

        /* Touch the file */
        if (!touch('some_file.txt', time(), $atime)) {
            echo 'Failed to touch file...';
        } else {
            echo 'touch() returned success...';
        }
    }
    ?>

### 注释

> 注意: 注意：不同文件系统对时间的判断方法可能是不相同的。

> 注意: 此函数的结果会被缓存。参见 clearstatcache() 以获得更多细节。

小技巧

自 PHP 5.0.0 起, 此函数也用于某些 URL 包装器。请参见 支持的协议和封装协议以获得支持 stat() 系列函数功能的包装器列表。

### 参见

- lstat() - 给出一个文件或符号连接的信息
- fstat() - 通过已打开的文件指针取得文件信息
- filemtime() - 取得文件修改时间
- filegroup() - 取得文件的组
- SplFileInfo

# symlink

(PHP 4, PHP 5, PHP 7, PHP 8)

symlink — 建立符号连接

### 说明

function symlink(string `$target`, string `$link`): bool

symlink() 对于已有的 `target` 建立一个名为 `link` 的符号连接。

### 参数

`target`

  连接的目标。

`link`

  连接的名称。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

如果 `link` 已存在，函数将失败，并发出 `E_WARNING`。在 Windows 上，如果 `target` 不存在，函数也会失败，并发出 `E_WARNING`。

### 示例

示例 #1 创建一个符号连接

    <?php
    $target = 'uploads.php';
    $link = 'uploads';
    symlink($target, $link);

    echo readlink($link);
    ?>

### 参见

- is_link() - 判断给定文件名是否为一个符号连接
- link() - 建立一个硬连接
- readlink() - 返回符号连接指向的目标
- linkinfo() - 获取一个连接的信息
- unlink() - 删除文件

# tempnam

(PHP 4, PHP 5, PHP 7, PHP 8)

tempnam — 建立一个具有唯一文件名的文件

### 说明

function tempnam(string `$directory`, string `$prefix`): string|false

在指定目录中建立一个具有唯一文件名的文件。如果该目录不存在或不可写，tempnam() 会在系统临时目录中生成一个文件，并返回该文件包含文件名的完整路径。

### 参数

`directory`

  将在其中创建临时文件名的目录。

`prefix`

  产生临时文件的前缀。

  > 注意: 仅使用前缀的前 63 个字符，忽略其它字符。Windows 仅使用前缀的前三个字符。

### 返回值

返回新的带路径的临时文件名，出错返回 `false`。

### 更新日志

版本 | 说明
--- | ---
7.1.0 | 当回退到系统的临时目录时 tempnam() 会发出一个通知。

### 示例

示例 #1 tempnam() 例子

    <?php
    $tmpfname = tempnam("/tmp", "FOO");

    $handle = fopen($tmpfname, "w");
    fwrite($handle, "writing to tempfile");
    fclose($handle);

    // do something here

    unlink($tmpfname);
    ?>

### 注释

> 注意: 如果 PHP 不能在指定的 `directory`参数中创建文件，则退回到系统默认值。在 NTFS 文件系统中，同样的情况也发生在 `directory` 中文件数超过 65534 个的时候。

### 参见

- tmpfile() - 建立一个临时文件
- sys_get_temp_dir() - 返回用于临时文件的目录
- unlink() - 删除文件

# tmpfile

(PHP 4, PHP 5, PHP 7, PHP 8)

tmpfile — 建立一个临时文件

### 说明

function tmpfile(): resource|false

以读写二进制（w+b）模式创建一个具有唯一文件名的临时文件，然后返回该文件的句柄。

文件在关闭后（例如，调用 fclose() 或 tmpfile() 返回的文件句柄已无引用的情况）或脚本运行结束后，会自动删除。

警告

如果脚本运行被意外终止，可能不会删除该临时文件。

### 参数

此函数没有参数。

### 返回值

返回新文件的句柄，类似于 fopen() 返回的文件句柄， 或者在失败时返回 `false`。

### 示例

示例 #1 tmpfile() 例子

    <?php
    $temp = tmpfile();
    fwrite($temp, "writing to tempfile");
    fseek($temp, 0);
    echo fread($temp, 1024);
    fclose($temp); // this removes the file
    ?>

以上示例会输出：

    writing to tempfile

### 参见

- tempnam() - 建立一个具有唯一文件名的文件
- sys_get_temp_dir() - 返回用于临时文件的目录

# touch

(PHP 4, PHP 5, PHP 7, PHP 8)

touch — 设定文件的访问和修改时间

### 说明

function touch(string `$filename`, ?int `$mtime` = `null`, ?int `$atime` = `null`): bool

尝试将由 `filename` 给出的文件的访问和修改时间设定为给出的 `mtime`。 注意访问时间总是会被修改的，不论有几个参数。

如果文件不存在，则会被创建。

### 参数

`filename`

  要设定的文件名。

`mtime`

  要设定的时间。如果参数 `mtime` 为 `null`，则会使用当前系统的 time()。

`atime`

  如果这个参数不是 `null`，则给定文件的访问时间会被设为 `atime`。 否则会设置为 `mtime`。 如果两个参数都是 `null`，则使用当前系统时间。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `mtime` 和 `atime` 现在可以为空。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 touch() 例子

    <?php
    if (touch($filename)) {
        echo $filename . ' modification time has been changed to present time';
    } else {
        echo 'Sorry, could not change modification time of ' . $filename;
    }
    ?>

示例 #2 使用 `mtime` 参数的 touch()

    <?php
    // This is the touch time, we'll set it to one hour in the past.
    $time = time() - 3600;

    // Touch the file
    if (!touch('some_file.txt', $time)) {
        echo 'Whoops, something went wrong...';
    } else {
        echo 'Touched file with success';
    }
    ?>

### 注释

> 注意: 注意：不同文件系统对时间的判断方法可能是不相同的。

# umask

(PHP 4, PHP 5, PHP 7, PHP 8)

umask — 改变当前的 umask

### 说明

function umask(?int `$mask` = `null`): int

umask() 将 PHP 的 umask 设定为 `mask` & 0777 并返回原来的 umask。当 PHP 被作为服务器模块使用时，在每个请求结束后 umask 会被恢复。

### 参数

`mask`

  The new umask.

### 返回值

如果 `mask` 为 `null`，umask() 仅返回当前的 umask，有参数则返回原来的 umask。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `mask` 现在可以为 null。

### 示例

示例 #1 umask() 例子

    <?php
    $old = umask(0);
    chmod("/path/some_dir/some_file.txt", 0755);
    umask($old);

    // Checking
    if ($old != umask()) {
        die('An error occurred while changing back the umask');
    }
    ?>

### 注释

> 注意:

> 在多线程的服务器上尽量避免使用这个函数。创建文件后要改变其权限最好还是使用 chmod()。使用 umask() 会导致并发程序和服务器发生不可预知的情况，因为它们是使用相同的 umask 的。

# unlink

(PHP 4, PHP 5, PHP 7, PHP 8)

unlink — 删除文件

### 说明

function unlink(string `$filename`, ?resource `$context` = `null`): bool

删除 `filename`。和 Unix C 的 unlink() 函数相似。 发生错误时会产生一个 `E_WARNING` 级别的错误。

### 参数

`filename`

  文件的路径。

  如果文件是符号链接，将会删除符号链接。在 Windows 上，删除目录的符号链接，必须使用 rmdir()。

`context`
  上下文流（context stream） resource。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
7.3.0 | 现在 Windows 也可以用 unlink() 删除文件句柄还在使用中的文件了，在此之前是无法删除的。 然而，还是无法重新创建文件，需要等到所有句柄都关闭才可以。

### 示例

示例 #1 基本的 unlink() 用法

    <?php
    $fh = fopen('test.html', 'a');
    fwrite($fh, '<h1>Hello world!</h1>');
    fclose($fh);

    unlink('test.html');
    ?>

### 参见

- rmdir() - 删除目录

## 目录

- basename — 返回路径中的文件名部分
- chgrp — 改变文件所属的组
- chmod — 改变文件模式
- chown — 改变文件的所有者
- clearstatcache — 清除文件状态缓存
- copy — 拷贝文件
- delete — 参见 unlink 或 unset
- dirname — 返回路径中的目录部分
- disk_free_space — 返回目录中的可用空间
- disk_total_space — 返回一个目录的磁盘总大小
- diskfreespace — disk_free_space 的别名
- fclose — 关闭一个已打开的文件指针
- fdatasync — 同步文件数据（不包含元数据）
- feof — 测试文件指针是否到了文件结束的位置
- fflush — 将缓冲内容输出到文件
- fgetc — 从文件指针中读取字符
- fgetcsv — 从文件指针中读入一行并解析 CSV 字段
- fgets — 从文件指针中读取一行
- fgetss — 从文件指针中读取一行并过滤掉 HTML 标记
- file — 把整个文件读入一个数组中
- file_exists — 检查文件或目录是否存在
- file_get_contents — 将整个文件读入一个字符串
- file_put_contents — 将数据写入文件
- fileatime — 取得文件的上次访问时间
- filectime — 取得文件的 inode 修改时间
- filegroup — 取得文件的组
- fileinode — 取得文件的 inode
- filemtime — 取得文件修改时间
- fileowner — 取得文件的所有者
- fileperms — 获取文件权限
- filesize — 取得文件大小
- filetype — 取得文件类型
- flock — 可移植的协同文件锁定
- fnmatch — 用模式匹配文件名
- fopen — 打开文件或者 URL
- fpassthru — 输出文件指针处的所有剩余数据
- fputcsv — 将行格式化为 CSV 并写入文件指针
- fputs — fwrite 的别名
- fread — 读取文件（可安全用于二进制文件）
- fscanf — 从文件中格式化输入
- fseek — 在文件指针中定位
- fstat — 通过已打开的文件指针取得文件信息
- fsync — 同步文件变更（包括元数据）
- ftell — 返回文件指针读/写的位置
- ftruncate — 将文件截断到指定的长度
- fwrite — 写入文件（可安全用于二进制文件）
- glob — 寻找与模式匹配的文件路径
- is_dir — 判断给定文件名是否是一个目录
- is_executable — 判断给定文件名是否可执行
- is_file — 判断给定文件名是否为一个正常的文件
- is_link — 判断给定文件名是否为一个符号连接
- is_readable — 判断给定文件名是否可读
- is_uploaded_file — 判断文件是否是通过 HTTP POST 上传的
- is_writable — 判断给定的文件名是否可写
- is_writeable — is_writable 的别名
- lchgrp — 修改符号链接的所有组
- lchown — 修改符号链接的所有者
- link — 建立一个硬连接
- linkinfo — 获取一个连接的信息
- lstat — 给出一个文件或符号连接的信息
- mkdir — 新建目录
- move_uploaded_file — 将上传的文件移动到新位置
- parse_ini_file — 解析一个配置文件
- parse_ini_string — 解析配置字符串
- pathinfo — 返回文件路径的信息
- pclose — 关闭进程文件指针
- popen — 打开进程文件指针
- readfile — 输出文件
- readlink — 返回符号连接指向的目标
- realpath — 返回规范化的绝对路径名
- realpath_cache_get — 获取真实目录缓存的详情
- realpath_cache_size — 获取真实路径缓冲区的大小
- rename — 重命名一个文件或目录
- rewind — 倒回文件指针的位置
- rmdir — 删除目录
- set_file_buffer — stream_set_write_buffer 的别名
- stat — 给出文件的信息
- symlink — 建立符号连接
- tempnam — 建立一个具有唯一文件名的文件
- tmpfile — 建立一个临时文件
- touch — 设定文件的访问和修改时间
- umask — 改变当前的 umask
- unlink — 删除文件

- 安装/配置
  - 运行时配置
  - 资源类型
- 预定义常量
- 文件系统函数
  - basename — 返回路径中的文件名部分
  - chgrp — 改变文件所属的组
  - chmod — 改变文件模式
  - chown — 改变文件的所有者
  - clearstatcache — 清除文件状态缓存
  - copy — 拷贝文件
  - delete — 参见 unlink 或 unset
  - dirname — 返回路径中的目录部分
  - disk_free_space — 返回目录中的可用空间
  - disk_total_space — 返回一个目录的磁盘总大小
  - diskfreespace — disk_free_space 的别名
  - fclose — 关闭一个已打开的文件指针
  - fdatasync — 同步文件数据（不包含元数据）
  - feof — 测试文件指针是否到了文件结束的位置
  - fflush — 将缓冲内容输出到文件
  - fgetc — 从文件指针中读取字符
  - fgetcsv — 从文件指针中读入一行并解析 CSV 字段
  - fgets — 从文件指针中读取一行
  - fgetss — 从文件指针中读取一行并过滤掉 HTML 标记
  - file — 把整个文件读入一个数组中
  - file_exists — 检查文件或目录是否存在
  - file_get_contents — 将整个文件读入一个字符串
  - file_put_contents — 将数据写入文件
  - fileatime — 取得文件的上次访问时间
  - filectime — 取得文件的 inode 修改时间
  - filegroup — 取得文件的组
  - fileinode — 取得文件的 inode
  - filemtime — 取得文件修改时间
  - fileowner — 取得文件的所有者
  - fileperms — 获取文件权限
  - filesize — 取得文件大小
  - filetype — 取得文件类型
  - flock — 可移植的协同文件锁定
  - fnmatch — 用模式匹配文件名
  - fopen — 打开文件或者 URL
  - fpassthru — 输出文件指针处的所有剩余数据
  - fputcsv — 将行格式化为 CSV 并写入文件指针
  - fputs — fwrite 的别名
  - fread — 读取文件（可安全用于二进制文件）
  - fscanf — 从文件中格式化输入
  - fseek — 在文件指针中定位
  - fstat — 通过已打开的文件指针取得文件信息
  - fsync — 同步文件变更（包括元数据）
  - ftell — 返回文件指针读/写的位置
  - ftruncate — 将文件截断到指定的长度
  - fwrite — 写入文件（可安全用于二进制文件）
  - glob — 寻找与模式匹配的文件路径
  - is_dir — 判断给定文件名是否是一个目录
  - is_executable — 判断给定文件名是否可执行
  - is_file — 判断给定文件名是否为一个正常的文件
  - is_link — 判断给定文件名是否为一个符号连接
  - is_readable — 判断给定文件名是否可读
  - is_uploaded_file — 判断文件是否是通过 HTTP POST 上传的
  - is_writable — 判断给定的文件名是否可写
  - is_writeable — is_writable 的别名
  - lchgrp — 修改符号链接的所有组
  - lchown — 修改符号链接的所有者
  - link — 建立一个硬连接
  - linkinfo — 获取一个连接的信息
  - lstat — 给出一个文件或符号连接的信息
  - mkdir — 新建目录
  - move_uploaded_file — 将上传的文件移动到新位置
  - parse_ini_file — 解析一个配置文件
  - parse_ini_string — 解析配置字符串
  - pathinfo — 返回文件路径的信息
  - pclose — 关闭进程文件指针
  - popen — 打开进程文件指针
  - readfile — 输出文件
  - readlink — 返回符号连接指向的目标
  - realpath — 返回规范化的绝对路径名
  - realpath_cache_get — 获取真实目录缓存的详情
  - realpath_cache_size — 获取真实路径缓冲区的大小
  - rename — 重命名一个文件或目录
  - rewind — 倒回文件指针的位置
  - rmdir — 删除目录
  - set_file_buffer — stream_set_write_buffer 的别名
  - stat — 给出文件的信息
  - symlink — 建立符号连接
  - tempnam — 建立一个具有唯一文件名的文件
  - tmpfile — 建立一个临时文件
  - touch — 设定文件的访问和修改时间
  - umask — 改变当前的 umask
  - unlink — 删除文件

# Inotify

# 简介

Inotify 扩展提供了一系列 inotify 函数： inotify_init()、 inotify_add_watch() 、 inotify_rm_watch()。

类似 C 语言里的 inotify_init() 函数会返回文件描述符，PHP 的 inotify_init()则返回 stream 资源。可以被标准的 Steam 函数使用，例如 stream_select()、 stream_set_blocking() 以及 fclose()。 inotify_read() 函数取代里 C 语言里读取 inotify 事件的那种方式。

# 安装/配置

## 目录

- 安装/配置
- 资源类型

## 安装/配置

此 » PECL 扩展未与 PHP 捆绑。

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/inotify.

## 资源类型

此扩展定义了 inotify_init() 返回的资源流。

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

Inotify 常量可用于 inotify_add_watch() 或由 inotify_read() 返回
`IN_ACCESS` (int)
  文件被访问（读）（*）
`IN_MODIFY` (int)
  文件被修改（*）
`IN_ATTRIB` (int)
  元数据变更（例如：权限、修改时间等）（*）
`IN_CLOSE_WRITE` (int)
  打开写入后关闭的文件（*）
`IN_CLOSE_NOWRITE` (int)
  未打开写入的文件被关闭（*）
`IN_OPEN` (int)
  文件被打开（*）
`IN_MOVED_TO` (int)
  文件被移动到监听目录（*）
`IN_MOVED_FROM` (int)
  文件移出监听目录（*）
`IN_CREATE` (int)
  在监听目录中创建文件或文件夹（*）
`IN_DELETE` (int)
  监听目录中删除文件或文件夹（*）
`IN_DELETE_SELF` (int)
  监听的文件或目录被删除
`IN_MOVE_SELF` (int)
  监听的文件或目录被移动
`IN_CLOSE` (int)
  与 IN_CLOSE_WRITE | IN_CLOSE_NOWRITE 相等
`IN_MOVE` (int)
  与 IN_MOVED_FROM | IN_MOVED_TO 相等
`IN_ALL_EVENTS` (int)
  以上所有常量的位掩码
`IN_UNMOUNT` (int)
  卸载包含监听对象的文件系统
`IN_Q_OVERFLOW` (int)
  事件队列溢出（此事件中监听描述符是 -1）
`IN_IGNORED` (int)
  监听被移除（通过 inotify_rm_watch() 显示移除，或者是文件被移动，或者文件系统被卸载）
`IN_ISDIR` (int)
  事件发生的主体是目录
`IN_ONLYDIR` (int)
  如果是目录，仅监听路径名（从 Linux 2.6.15 开始）
`IN_DONT_FOLLOW` (int)
  如果是符号链接，不引用路径名（从 Linux 2.6.15 开始）
`IN_MASK_ADD` (int)
  如果路径名存在，追加监听此路径的事件掩码（代替更换掩码）
`IN_ONESHOT` (int)
  路径触发一个监听事件后，从监听列表中移除。

> 注意: 以上标有星号 (*) 的事件可能发生在已监听目录的文件中。

# Inotify 函数

# inotify_add_watch

(PECL inotify >= 0.1.2)

inotify_add_watch — 添加监听到已初始化的 inotify 实例

### 说明

function inotify_add_watch(resource `$inotify_instance`, string `$pathname`, int `$mask`): int|false

inotify_add_watch() 为 `pathname` 指定的文件或目录添加新的监听，或修改已存在的监听。

在已监听的对象上使用 inotify_add_watch() 来替换当前的监听。（或）使用 `IN_MASK_ADD` 常量添加监听事件。

### 参数

`inotify_instance`
  inotify_init()返回的资源
`pathname`
  要监听的文件或目录
`mask`
  监听事件。详情见 预定义常量。

### 返回值

返回值是一个唯一的（inotify 实例范围内）监听描述符， 或者在失败时返回 `false`。

### 参见

- inotify_init() - 初始化 inotify 实例

# inotify_init

(PECL inotify >= 0.1.2)

inotify_init — 初始化 inotify 实例

### 说明

function inotify_init(): resource|false

初始化 inotify_add_watch() 使用的 inotify 实例

### 参数

此函数没有参数。

### 返回值

返回资源流或发生错误时返回 `false`。

### 示例

示例 #1 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);

    ?>

以上示例的输出类似于：

    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)
      ),
    );

### 参见

- inotify_add_watch() - 添加监听到已初始化的 inotify 实例
- inotify_rm_watch() - 移除 inotify 实例的监听
- inotify_queue_len() - 如果有待处理事件，返回大于零的数字
- inotify_read() - 从 inotify 实例读取事件
- fclose() - 关闭一个已打开的文件指针

# inotify_queue_len

(PECL inotify >= 0.1.2)

inotify_queue_len — 如果有待处理事件，返回大于零的数字

### 说明

function inotify_queue_len(resource `$inotify_instance`): int

可以通过此函数知道 inotify_read() 是否会阻塞。如果返回大于零的数字，表示有待处理的事件，inotify_read() 不会阻塞。

### 参数

`inotify_instance`
  inotify_init()返回的资源

### 返回值

如果有待处理事件，返回大于零的数字。

### 参见

- inotify_init() - 初始化 inotify 实例
- 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() - 为资源流设置阻塞或者阻塞模式

# inotify_read

(PECL inotify >= 0.1.2)

inotify_read — 从 inotify 实例读取事件

### 说明

function inotify_read(resource `$inotify_instance`): array

从 inotify 实例读取 inotify 事件。

### 参数

`inotify_instance`
  inotify_init()返回的资源

### 返回值

返回 inotify 事件数组。在没有待处理事件或 `inotify_instance` 非阻塞时返回 `false`。事件发生时都会返回包含以下键的数组：

- wd 是由 inotify_add_watch() 返回的监听描述符
- mask 是 events 的位掩码
- cookie 是连接相关事件（例如：`IN_MOVE_FROM` 和 `IN_MOVE_TO`）的唯一 id
- name 是文件名（例如：监听目录中被修改的文件）

### 参见

- inotify_init() - 初始化 inotify 实例
- 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() - 为资源流设置阻塞或者阻塞模式
- inotify_queue_len() - 如果有待处理事件，返回大于零的数字

# inotify_rm_watch

(PECL inotify >= 0.1.2)

inotify_rm_watch — 移除 inotify 实例的监听

### 说明

function inotify_rm_watch(resource `$inotify_instance`, int `$watch_descriptor`): bool

inotify_rm_watch() 移除 inotify_instance() 实例的 `watch_descriptor` 监听。

### 参数

`inotify_instance`
  inotify_init()返回的资源
`watch_descriptor`
  实例要移除的监听。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- inotify_init() - 初始化 inotify 实例

## 目录

- inotify_add_watch — 添加监听到已初始化的 inotify 实例
- inotify_init — 初始化 inotify 实例
- inotify_queue_len — 如果有待处理事件，返回大于零的数字
- inotify_read — 从 inotify 实例读取事件
- inotify_rm_watch — 移除 inotify 实例的监听

- 安装/配置
  - 安装/配置
  - 资源类型
- 预定义常量
- Inotify 函数
  - inotify_add_watch — 添加监听到已初始化的 inotify 实例
  - inotify_init — 初始化 inotify 实例
  - inotify_queue_len — 如果有待处理事件，返回大于零的数字
  - inotify_read — 从 inotify 实例读取事件
  - inotify_rm_watch — 移除 inotify 实例的监听

# xattr

# 简介

The xattr extension allows for the manipulation of extended attributes on a filesystem.

# 安装/配置

## 目录

- 需求
- 安装

## 需求

To use xattr, you will need libattr installed. It is available at » http://savannah.nongnu.org/projects/attr/.

> 注意:

> 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`.

## 安装

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/xattr.

PECL 扩展的 DLL 当前不可用。参见 在 Windows 上构建章节。

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`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 函数

# xattr_get

(PECL xattr >= 0.9.0)

xattr_get — Get an extended attribute

### 说明

function xattr_get(string `$filename`, string `$name`, int `$flags` = 0): string|false

This function gets the value of an extended attribute of a file.

扩展的属性有两种 不同的命名空间：user 和 root。user 命名空间对所有用户均有效，而 root 命名空间仅对拥有 root 权限的用户有效。 xattr 默认在 user 命名空间上操作，但可使用 `flags` 参数进行更改。

### 参数

`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.

### 返回值

Returns a string containing the value or `false` if the attribute doesn't exist.

### 示例

示例 #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 ... */

    ?>

### 参见

- 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

### 说明

function xattr_list(string `$filename`, int `$flags` = 0): array

This functions gets a list of names of extended attributes of a file.

扩展的属性有两种 不同的命名空间：user 和 root。user 命名空间对所有用户均有效，而 root 命名空间仅对拥有 root 权限的用户有效。 xattr 默认在 user 命名空间上操作，但可使用 `flags` 参数进行更改。

### 参数

`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.

### 返回值

This function returns an array with names of extended attributes.

### 示例

示例 #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);
    }

    ?>

### 参见

- xattr_get() - Get an extended attribute

# xattr_remove

(PECL xattr >= 0.9.0)

xattr_remove — Remove an extended attribute

### 说明

function xattr_remove(string `$filename`, string `$name`, int `$flags` = 0): bool

This function removes an extended attribute of a file.

扩展的属性有两种 不同的命名空间：user 和 root。user 命名空间对所有用户均有效，而 root 命名空间仅对拥有 root 权限的用户有效。 xattr 默认在 user 命名空间上操作，但可使用 `flags` 参数进行更改。

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    }
    ?>

### 参见

- 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

### 说明

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.

扩展的属性有两种 不同的命名空间：user 和 root。user 命名空间对所有用户均有效，而 root 命名空间仅对拥有 root 权限的用户有效。 xattr 默认在 user 命名空间上操作，但可使用 `flags` 参数进行更改。

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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'));
    ?>

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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).

### 示例

示例 #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 ... */
    }

    ?>

### 参见

- xattr_get() - Get an extended attribute
- xattr_list() - Get a list of extended attributes

## 目录

- 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

- 安装/配置
  - 需求
  - 安装
- 预定义常量
- xattr 函数
  - 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

# 简介

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.

# 安装/配置

## 目录

- 需求
- 安装

## 需求

To use xdiff, you will need libxdiff installed, available on the libxdiff homepage » http://www.xmailserver.org/xdiff-lib.html.

> 注意:

> You'll need at least libxdiff 0.7 for these functions to be aware of memory_limit.

## 安装

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/xdiff.

此扩展在 Windows 平台的二进制扩展 (DLL 文件) PECL 可以在 PECL 官方网站上下载。

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`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 函数

# xdiff_file_bdiff

(PECL xdiff >= 1.5.0)

xdiff_file_bdiff — Make binary diff of two files

### 说明

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().

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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');
    ?>

### 注释

> 注意:

> Both files will be loaded into memory so ensure that your memory_limit is set high enough.

### 参见

- 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

### 说明

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.

### 参数

`file`

  The path to the binary patch created by xdiff_string_bdiff() or xdiff_string_rabdiff() function.

### 返回值

Returns the size of file that would be created.

### 示例

示例 #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";
    ?>

### 参见

- 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

### 说明

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.

### 参数

`file`

  The original file.

`patch`

  The binary patch file.

`dest`

  Path of the resulting file.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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";
    }

    ?>

### 注释

> 注意:

> Both files (`file` and `patch`) will be loaded into memory so ensure that your memory_limit is set high enough.

### 参见

- 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

### 说明

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).

### 参数

`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).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

### 注释

> 注意:

> This function doesn't work well with binary files. To make diff of binary files use xdiff_file_bdiff()/xdiff_file_rabdiff() function.

### 参见

- xdiff_file_patch() - Patch a file with an unified diff

# xdiff_file_diff_binary

(PECL xdiff >= 0.2.0)

xdiff_file_diff_binary — 别名 xdiff_file_bdiff()

### 说明

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().

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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');
    ?>

### 注释

> 注意:

> Both files will be loaded into memory so ensure that your memory_limit is set high enough.

### 参见

- 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

### 说明

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.

### 参数

`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`.

### 返回值

Returns `true` if merge was successful, string with rejected chunks if it was not or `false` if an internal error happened.

### 示例

示例 #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;
    }
    ?>

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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.

### 示例

示例 #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;
    }

    ?>

示例 #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;
    }

    ?>

### 参见

- xdiff_file_diff() - Make unified diff of two files

# xdiff_file_patch_binary

(PECL xdiff >= 0.2.0)

xdiff_file_patch_binary — 别名 xdiff_file_bpatch()

### 说明

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().

### 参数

`file`

  The original file.

`patch`

  The binary patch file.

`dest`

  Path of the resulting file.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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";
    }

    ?>

### 注释

> 注意:

> Both files (`file` and `patch`) will be loaded into memory so ensure that your memory_limit is set high enough.

### 参见

- xdiff_string_patch_binary() - 别名 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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');
    ?>

### 注释

> 注意:

> Both files will be loaded into memory so ensure that your memory_limit is set high enough.

### 参见

- 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

### 说明

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().

### 参数

`old_data`

  First string with binary data. It acts as "old" data.

`new_data`

  Second string with binary data. It acts as "new" data.

### 返回值

Returns string with binary diff containing differences between "old" and "new" data or `false` if an internal error occurred.

### 参见

- 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

### 说明

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.

### 参数

`patch`

  The binary patch created by xdiff_string_bdiff() or xdiff_string_rabdiff() function.

### 返回值

Returns the size of file that would be created.

### 示例

示例 #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";
    ?>

### 参见

- 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

### 说明

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.

### 参数

`str`

  The original binary string.

`patch`

  The binary patch string.

### 返回值

Returns the patched string, or `false` on error.

### 参见

- 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

### 说明

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).

### 参数

`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).

### 返回值

Returns string with resulting diff or `false` if an internal error happened.

### 示例

示例 #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;
    }

    ?>

### 注释

> 注意:

> This function doesn't work well with binary strings. To make diff of binary strings use xdiff_string_bdiff()/xdiff_string_rabdiff().

### 参见

- xdiff_string_patch() - Patch a string with an unified diff

# xdiff_string_diff_binary

(PECL xdiff >= 0.2.0)

xdiff_string_diff_binary — 别名 xdiff_string_bdiff()

### 说明

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().

### 参数

`old_data`

  First string with binary data. It acts as "old" data.

`new_data`

  Second string with binary data. It acts as "new" data.

### 返回值

Returns string with result or `false` if an internal error happened.

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

Returns the merged string, `false` if an internal error happened, or `true` if merged string is empty.

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

Returns the patched string, or `false` on error.

### 示例

示例 #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;
    }

    ?>

### 参见

- xdiff_string_diff() - Make unified diff of two strings

# xdiff_string_patch_binary

(PECL xdiff >= 0.2.0)

xdiff_string_patch_binary — 别名 xdiff_string_bpatch()

### 说明

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().

### 参数

`str`

  The original binary string.

`patch`

  The binary patch string.

### 返回值

Returns the patched string, or `false` on error.

### 参见

- 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

### 说明

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.

### 参数

`old_data`

  The first string containing the "old" binary data.

`new_data`

  The second string containing the "new" binary data.

### 返回值

Returns a binary diff string containing the differences between the old and new data, 或者在失败时返回 `false`.

### 示例

示例 #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);
    ?>

### 参见

- 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

## 目录

- 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 — 别名 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 — 别名 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 — 别名 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 — 别名 xdiff_string_bpatch
- xdiff_string_rabdiff — Make a binary diff of two strings using the Rabin's polynomial fingerprinting algorithm

- 安装/配置
  - 需求
  - 安装
- 预定义常量
- xdiff 函数
  - 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 — 别名 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 — 别名 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 — 别名 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 — 别名 xdiff_string_bpatch
  - xdiff_string_rabdiff — Make a binary diff of two strings using the Rabin's polynomial fingerprinting algorithm

- 直接 IO
  - 安装/配置
  - 预定义常量
  - Direct IO 函数
- 目录
  - 预定义常量
  - Directory — Directory 类
  - 目录函数函数
- Fileinfo — 文件信息
  - 安装/配置
  - 预定义常量
  - Fileinfo 函数
  - finfo — finfo 类
- 文件系统
  - 安装/配置
  - 预定义常量
  - 文件系统函数
- Inotify
  - 安装/配置
  - 预定义常量
  - Inotify 函数
- xattr
  - 安装/配置
  - 预定义常量
  - xattr 函数
- xdiff
  - 安装/配置
  - 预定义常量
  - xdiff 函数

# 国际化与字符编码支持

# Enchant spelling library

# 简介

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)`

# 安装/配置

## 目录

- 需求
- 安装
- 资源类型

## 需求

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/.

## 安装

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.

> 注意: Additional setup on Windows
> 为了使此扩展生效， DLL 文件必须能在 Windows 系统的 PATH 指示的路径下找到。如何操作的信息，请参见题为“如何在 Windows 中将 PHP 目录加到 PATH 中”的FAQ。虽然将 DLL 文件从 PHP 文件夹复制到 Windows 系统目录也行，但不建议这样做。 此扩展需要下列文件在 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.

## 资源类型

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.

# 预定义常量

`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.

# 示例

示例 #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 函数

# enchant_broker_describe

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0)

enchant_broker_describe — Enumerates the Enchant providers

### 说明

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().

### 参数

`broker`
  An Enchant broker returned by enchant_broker_init().

### 返回值

Returns an array of available Enchant providers with their details.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `broker` expects an EnchantBroker instance now; previoulsy, a resource was expected.
8.0.0 | Prior to this version, the function returned `false` on failure.

### 示例

示例 #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);

    ?>

以上示例的输出类似于：

    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

### 说明

function enchant_broker_dict_exists(EnchantBroker `$broker`, string `$tag`): bool

Tells if a dictionary exists or not, using a non-empty tags

### 参数

`broker`
  An Enchant broker returned by enchant_broker_init().
`tag`
  non-empty tag in the LOCALE format, ex: us_US, ch_DE, etc.

### 返回值

Returns `true` when the tag exist or `false` when not.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `broker` expects an EnchantBroker instance now; previoulsy, a resource was expected.

### 示例

示例 #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";
    }
    ?>

### 参见

- 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

警告

本函数已自 PHP 8.0.0 起被废弃。强烈建议不要依赖本函数。

### 说明

#[\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.

### 参数

`broker`
  An Enchant broker returned by enchant_broker_init().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | This function has been deprecated in favor of unsetting the object.
8.0.0 | `broker` expects an EnchantBroker instance now; previoulsy, a resource was expected.

### 参见

- 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

警告

本函数已自 PHP 8.0.0 起被废弃。强烈建议不要依赖本函数。

### 说明

#[\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.

### 参数

`dictionary`
  An Enchant dictionary returned by enchant_broker_request_dict() or enchant_broker_request_pwl_dict().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | This function has been deprecated in favor of unsetting the object.
8.0.0 | `dictionary` expects a EnchantDictionary now; previously, a resource was expected.

### 参见

- 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

警告

本函数已自 PHP 8.0.0 起被废弃。强烈建议不要依赖本函数。

### 说明

#[\Deprecated]
function enchant_broker_get_dict_path(EnchantBroker `$broker`, int `$type`): string|false

Get the directory path for a given backend.

### 参数

`broker`
  An Enchant broker returned by enchant_broker_init().
`type`
  The type of the dictionaries, i.e. `ENCHANT_MYSPELL` or `ENCHANT_ISPELL`.

### 返回值

Returns the path of the dictionary directory on success 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | This function has been deprecated.
8.0.0 | `broker` expects an EnchantBroker instance now; previoulsy, a resource was expected.

### 注释

> 注意: This function is only available if the extension has been compiled with Enchant v1.

### 参见

- 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

### 说明

function enchant_broker_get_error(EnchantBroker `$broker`): string|false

Returns the last error which occurred in this broker.

### 参数

`broker`
  An Enchant broker returned by enchant_broker_init().

### 返回值

Return the msg string if an error was found or `false`

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `broker` expects an EnchantBroker instance now; previoulsy, a resource was expected.

# 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

### 说明

function enchant_broker_init(): EnchantBroker|false

### 参数

### 返回值

Returns a broker resource on success or `false`.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | On success, this function returns an EnchantBroker instance now; previously, a resource was returned.

### 参见

- 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

### 说明

function enchant_broker_list_dicts(EnchantBroker `$broker`): array

Returns a list of available dictionaries with their details.

### 参数

`broker`
  An Enchant broker returned by enchant_broker_init().

### 返回值

Returns an array of available dictionaries with their details.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `broker` expects an EnchantBroker instance now; previoulsy, a resource was expected.
8.0.0 | Prior to this version, the function returned `false` on failure.

### 示例

示例 #1 List all available dictionaries for one broker

    <?php
    $r = enchant_broker_init();
    $dicts = enchant_broker_list_dicts($r);
    print_r($dicts);
    ?>

以上示例的输出类似于：

    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
            )

    )

### 参见

- 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

### 说明

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", ...)

### 参数

`broker`
  An Enchant broker returned by enchant_broker_init().
`tag`
  A tag describing the locale, for example en_US, de_DE

### 返回值

Returns a dictionary resource on success 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `broker` expects an EnchantBroker instance now; previoulsy, a resource was expected.
8.0.0 | On success, this function returns an EnchantDictionary instance now; previously, a resource was returned.

### 示例

示例 #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);
    }
    ?>

### 参见

- 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

### 说明

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.

### 参数

`broker`
  An Enchant broker returned by enchant_broker_init().
`filename`
  Path to the PWL file. If there is no such file, a new one will be created if possible.

### 返回值

Returns a dictionary resource on success 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `broker` expects an EnchantBroker instance now; previoulsy, a resource was expected.
8.0.0 | On success, this function returns an EnchantDictionary instance now; previously, a resource was returned.

### 参见

- 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

警告

本函数已自 PHP 8.0.0 起被废弃。强烈建议不要依赖本函数。

### 说明

#[\Deprecated]
function enchant_broker_set_dict_path(EnchantBroker `$broker`, int `$type`, string `$path`): bool

Set the directory path for a given backend.

### 参数

`broker`
  An Enchant broker returned by enchant_broker_init().
`type`
  The type of the dictionaries, i.e. `ENCHANT_MYSPELL` or `ENCHANT_ISPELL`.
`path`
  The path of the dictionary directory.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | This function has been deprecated.
8.0.0 | `broker` expects an EnchantBroker instance now; previoulsy, a resource was expected.

### 注释

> 注意: This function is only available if the extension has been compiled with Enchant v1.

### 参见

- 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

### 说明

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.

### 参数

`broker`
  An Enchant broker returned by enchant_broker_init().
`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

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `broker` expects an EnchantBroker instance now; previoulsy, a resource was expected.

# enchant_dict_add

(PHP 8)

enchant_dict_add — Add a word to personal word list

### 说明

function enchant_dict_add(EnchantDictionary `$dictionary`, string `$word`): void

Add a word to personal word list of the given dictionary.

### 参数

`dictionary`
  An Enchant dictionary returned by enchant_broker_request_dict() or enchant_broker_request_pwl_dict().
`word`
  The word to add

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `dictionary` expects an EnchantDictionary instance now; previoulsy, a resource was expected.

### 示例

示例 #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);

    ?>

### 参见

- 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 — 别名 enchant_dict_add()

警告

该别名已在 PHP 8.0.0 中 废弃。

### 说明

此函数是该函数的别名： 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

### 说明

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.

### 参数

`dictionary`
  An Enchant dictionary returned by enchant_broker_request_dict() or enchant_broker_request_pwl_dict().
`word`
  The word to add

### 返回值

没有返回值。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `dictionary` expects an EnchantDictionary instance now; previoulsy, a resource was expected.

### 参见

- 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

### 说明

function enchant_dict_check(EnchantDictionary `$dictionary`, string `$word`): bool

If the word is correctly spelled return `true`, otherwise return `false`

### 参数

`dictionary`
  An Enchant dictionary returned by enchant_broker_request_dict() or enchant_broker_request_pwl_dict().
`word`
  The word to check

### 返回值

Returns `true` if the word is spelled correctly, `false` if not.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `dictionary` expects an EnchantDictionary instance now; previoulsy, a resource was expected.

# enchant_dict_describe

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_describe — Describes an individual dictionary

### 说明

function enchant_dict_describe(EnchantDictionary `$dictionary`): array

Returns the details of the dictionary.

### 参数

`dictionary`
  An Enchant dictionary returned by enchant_broker_request_dict() or enchant_broker_request_pwl_dict().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `dictionary` expects an EnchantDictionary instance now; previoulsy, a resource was expected.
8.0.0 | Prior to this version, the function returned `false` on failure.

### 示例

示例 #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);
    }
    ?>

以上示例的输出类似于：

    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

### 说明

function enchant_dict_get_error(EnchantDictionary `$dictionary`): string|false

Returns the last error of the current spelling-session

### 参数

`dictionary`
  An Enchant dictionary returned by enchant_broker_request_dict() or enchant_broker_request_pwl_dict().

### 返回值

Returns the error message as string or `false` if no error occurred.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `dictionary` expects an EnchantDictionary instance now; previoulsy, a resource was expected.

# enchant_dict_is_added

(PHP 8)

enchant_dict_is_added — Whether or not 'word' exists in this spelling-session

### 说明

function enchant_dict_is_added(EnchantDictionary `$dictionary`, string `$word`): bool

Tells whether or not a word already exists in the current session.

### 参数

`dictionary`
  An Enchant dictionary returned by enchant_broker_request_dict() or enchant_broker_request_pwl_dict().
`word`
  The word to lookup

### 返回值

Returns `true` if the word exists or `false`

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `dictionary` expects an EnchantDictionary instance now; previoulsy, a resource was expected.

### 参见

- 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 — 别名 enchant_dict_is_added()

警告

该别名已在 PHP 8.0.0 中 废弃。

### 说明

此函数是该函数的别名： 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

### 说明

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.

### 参数

`dictionary`
  An Enchant dictionary returned by enchant_broker_request_dict() or enchant_broker_request_pwl_dict().
`word`
  The word to check
`suggestions`
  If the word is not correctly spelled, this variable will contain an array of suggestions.

### 返回值

Returns `true` if the word is correctly spelled or `false`

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `dictionary` expects an EnchantDictionary instance now; previoulsy, a resource was expected.

### 示例

示例 #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);
    }
    ?>

以上示例的输出类似于：

    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
    )

### 参见

- enchant_dict_check() - Check whether a word is correctly spelled or not
- enchant_dict_suggest() - Suggest spellings for a word

# 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

### 说明

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.

### 参数

`dictionary`
  An Enchant dictionary returned by enchant_broker_request_dict() or enchant_broker_request_pwl_dict().
`misspelled`
  The word to fix
`correct`
  The correct word

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `dictionary` expects an EnchantDictionary instance now; previoulsy, a resource was expected.

# enchant_dict_suggest

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_suggest — Suggest spellings for a word

### 说明

function enchant_dict_suggest(EnchantDictionary `$dictionary`, string `$word`): array

### 参数

`dictionary`
  An Enchant dictionary returned by enchant_broker_request_dict() or enchant_broker_request_pwl_dict().
`word`
  Word to use for the suggestions.

### 返回值

Will returns an array of suggestions if the word is bad spelled.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `dictionary` expects an EnchantDictionary instance now; previoulsy, a resource was expected.

### 示例

示例 #1 A enchant_dict_suggest() example

    <?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);
        }
    }
    ?>

### 参见

- 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

## 目录

- 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 — 别名 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 — 别名 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 — Suggest spellings for a word

# The EnchantBroker class

(PHP 8)

## 简介

A fully opaque class which replaces `enchant_broker` resources as of PHP 8.0.0.

## 类摘要

final class EnchantBroker {
}

# The EnchantDictionary class

(PHP 8)

## 简介

A fully opaque class which replaces `enchant_dict` resources as of PHP 8.0.0.

## 类摘要

final class EnchantDictionary {
}

- 安装/配置
  - 需求
  - 安装
  - 资源类型
- 预定义常量
- 示例
- Enchant 函数
  - 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 — 别名 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 — 别名 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 — Suggest spellings for a word
- EnchantBroker — The EnchantBroker class
- EnchantDictionary — The EnchantDictionary class

# Determine gender of firstnames

# 简介

Gender PHP extension is a port of the gender.c program originally written by Joerg Michael. The main purpose is to find out the gender of firstnames. The current database contains >40000 firstnames from 54 countries.

# 安装/配置

## 目录

- 安装

## 安装

此 » PECL 扩展未与 PHP 捆绑。

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/gender.

# 示例

## 目录

- Usage example.

## Usage example.

Gender class usage example.

示例 #1 Usage example.

    <?php

    namespace Gender;

    $gender = new Gender;

    $name = "Milene";
    $country = Gender::FRANCE;

    $result = $gender->get($name, $country);

    $data = $gender->country($country);

    switch($result) {
        case Gender::IS_FEMALE:
            printf("The name %s is female in %s\n", $name, $data['country']);
        break;

        case Gender::IS_MOSTLY_FEMALE:
            printf("The name %s is mostly female in %s\n", $name, $data['country']);
        break;

        case Gender::IS_MALE:
            printf("The name %s is male in %s\n", $name, $data['country']);
        break;

        case Gender::IS_MOSTLY_MALE:
            printf("The name %s is mostly male in %s\n", $name, $data['country']);
        break;

        case Gender::IS_UNISEX_NAME:
            printf("The name %s is unisex in %s\n", $name, $data['country']);
        break;

        case Gender::IS_A_COUPLE:
            printf("The name %s is both male and female in %s\n", $name, $data['country']);
        break;

        case Gender::NAME_NOT_FOUND:
            printf("The name %s was not found for %s\n", $name, $data['country']);
        break;

        case Gender::ERROR_IN_NAME:
            echo "There is an error in the given name!\n";
        break;

        default:
            echo "An error occurred!\n";
        break;

    }

# The Gender\Gender class

(PECL gender >= 0.6.0)

## 简介

## 类摘要

class Gender\Gender {
/* 常量 */
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;
/* 方法 */
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
}

## 预定义常量

`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

### 说明

public function Gender\Gender::connect(string `$dsn`): bool

Connect to an external name dictionary. Currently only streams are supported.

### 参数

`dsn`
  DSN to open.

### 返回值

Boolean as success of failure.

# Gender\Gender::__construct

(PECL gender >= 0.6.0)

Gender\Gender::__construct — Construct the Gender object

### 说明

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.

### 参数

`dsn`
  DSN to open.

# Gender\Gender::country

(PECL gender >= 0.8.0)

Gender\Gender::country — Get textual country representation

### 说明

public function Gender\Gender::country(int `$country`): array|false

Returns the textual representation of a country from a Gender class constant.

### 参数

`country`
  A country ID specified by a Gender\Gender class constant.

### 返回值

Returns an array with the short and full names of the country on success 或者在失败时返回 `false`.

### 示例

示例 #1 Using Gender\Gender::country()

    $gender = new Gender\Gender;
    var_dump($gender->country(Gender\Gender::BRITAIN));

以上示例会输出：

    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

### 说明

public function Gender\Gender::get(string `$name`, int `$country` = ?): int

Get the gender of the name in a particular country.

### 参数

`name`
  Name to check.
`country`
  Country id identified by Gender class constant.

### 返回值

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

### 说明

public function Gender\Gender::isNick(string `$name0`, string `$name1`, int `$country` = ?): array

Check whether the name0 is a nick of the name1.

### 参数

`name0`
  Name to check.
`name1`
  Name to check.
`country`
  Country id identified by Gender class constant. If ommited ANY_COUNTRY is used.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# Gender\Gender::similarNames

(PECL gender >= 0.9.0)

Gender\Gender::similarNames — Get similar names

### 说明

public function Gender\Gender::similarNames(string `$name`, int `$country` = ?): array

Get similar names for the given name and country.

### 参数

`name`
  Name to check.
`country`
  Country id identified by Gender class constant. If ommited ANY_COUNTRY is used.

### 返回值

Returns an array with the similar names found.

## 目录

- 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

- 安装/配置
  - 安装
- 示例
  - Usage example.
- 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

# 简介

gettext函数实现了NLS (Native Language Support) API，他可以用来国际化您的PHP程序. 请参阅gettext的文档，为您的系统进行国际化功能的详尽的解释 或查看文档 » http://www.gnu.org/software/gettext/manual/gettext.html.

# 安装/配置

## 目录

- 需求
- 安装

## 需求

要使用这些函数，你必须从 » http://www.gnu.org/software/gettext/gettext.html 下载和安装 GNU gettext 包

## 安装

在构建PHP的时候要添加 GNU gettext 支持，你必须添加如下选项 --with-gettext[=DIR] DIR 表示 gettext 的安装目录，默认是/usr/local.

# Gettext 函数

# _

(PHP 4, PHP 5, PHP 7, PHP 8)

_ — 别名 gettext()

### 说明

此函数是该函数的别名： gettext().

# bind_textdomain_codeset

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

bind_textdomain_codeset — Specify or get the character encoding in which the messages from the DOMAIN message catalog will be returned

### 说明

function bind_textdomain_codeset(string `$domain`, ?string `$codeset` = `null`): string|false

bind_textdomain_codeset() allows to set or get the encoding in which messages from `domain` will be returned by gettext() and similar functions.

### 参数

`domain`

  The domain.

`codeset`

  The code set. If `null`, the currently set encoding is returned.

### 返回值

A string on success.

### 错误／异常

Throws a ValueError if `domain` is the empty string.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | Now throws a ValueError if `domain` is the empty string.
8.4.0 | `codeset` is optional now. Previously, the parameter always had to be specified.
8.0.3 | `codeset` is nullable now. Previously, it was not possible to retrieve the currently set encoding.

### 注释

> 注意:

> The bind_textdomain_codeset() information is maintained per process, not per thread.

# bindtextdomain

(PHP 4, PHP 5, PHP 7, PHP 8)

bindtextdomain — Sets or gets the path for a domain

### 说明

function bindtextdomain(string `$domain`, ?string `$directory` = `null`): string|false

The bindtextdomain() function sets or gets the path for a domain.

### 参数

`domain`

  The domain.

`directory`

  The directory path. An empty string means the current directory. If `null`, the currently set directory is returned.

### 返回值

The full pathname for the `domain` currently being set, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `directory` is optional now. Previously, the parameter always had to be specified.
8.0.3 | `directory` is nullable now. Previously, it was not possible to retrieve the currently set directory.

### 示例

示例 #1 bindtextdomain() example

    <?php

    $domain = 'myapp';
    echo bindtextdomain($domain, '/usr/share/myapp/locale');

    ?>

以上示例会输出：

    /usr/share/myapp/locale

### 注释

> 注意:

> The bindtextdomain() information is maintained per process, not per thread.

# dcgettext

(PHP 4, PHP 5, PHP 7, PHP 8)

dcgettext — Overrides the domain for a single lookup

### 说明

function dcgettext(string `$domain`, string `$message`, int `$category`): string

This function allows you to override the current domain for a single message lookup.

### 参数

`domain`

  The domain

`message`

  The message

`category`

  The category

### 返回值

A string on success.

### 参见

- gettext() - Lookup a message in the current domain

# dcngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

dcngettext — Plural version of dcgettext

### 说明

function dcngettext(
string `$domain`,
string `$singular`,
string `$plural`,
int `$count`,
int `$category`
): string

This function allows you to override the current domain for a single plural message lookup.

### 参数

`domain`

  The domain

`singular`

`plural`

`count`

`category`

### 返回值

A string on success.

### 参见

- ngettext() - Plural version of gettext

# dgettext

(PHP 4, PHP 5, PHP 7, PHP 8)

dgettext — Override the current domain

### 说明

function dgettext(string `$domain`, string `$message`): string

The dgettext() function allows you to override the current `domain` for a single message lookup.

### 参数

`domain`

  The domain

`message`

  The message

### 返回值

A string on success.

### 错误／异常

Throws a ValueError if `domain` is the empty string.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | Now throws a ValueError if `domain` is the empty string.

### 参见

- gettext() - Lookup a message in the current domain

# dngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

dngettext — Plural version of dgettext

### 说明

function dngettext(
string `$domain`,
string `$singular`,
string `$plural`,
int `$count`
): string

The dngettext() function allows you to override the current `domain` for a single plural message lookup.

### 参数

`domain`

  The domain

`singular`

`plural`

`count`

### 返回值

A string on success.

### 错误／异常

Throws a ValueError if `domain` is the empty string.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | Now throws a ValueError if `domain` is the empty string.

### 参见

- ngettext() - Plural version of gettext

# gettext

(PHP 4, PHP 5, PHP 7, PHP 8)

gettext — Lookup a message in the current domain

### 说明

function gettext(string `$message`): string

Looks up a message in the current domain.

### 参数

`message`

  The message being translated.

### 返回值

Returns a translated string if one is found in the translation table, or the submitted message if not found.

### 示例

示例 #1 gettext()-check

    <?php
    // Set language to German
    putenv('LC_ALL=de_DE');
    setlocale(LC_ALL, 'de_DE');

    // Specify location of translation tables
    bindtextdomain("myPHPApp", "./locale");

    // Choose domain
    textdomain("myPHPApp");

    // Translation is looking for in ./locale/de_DE/LC_MESSAGES/myPHPApp.mo now

    // Print a test message
    echo gettext("Welcome to My PHP Application");

    // Or use the alias _() for gettext()
    echo _("Have a nice day");
    ?>

### 注释

> 注意:

> You may use the underscore character '_' as an alias to this function.

> 注意:

> Setting a language isn't enough for some systems and the putenv() should be used to define the current locale.

### 参见

- _() - 别名 gettext
- setlocale() - 设置区域信息

# ngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ngettext — Plural version of gettext

### 说明

function ngettext(string `$singular`, string `$plural`, int `$count`): string

The plural version of gettext(). Some languages have more than one form for plural messages dependent on the count.

### 参数

`singular`

  The singular message ID.

`plural`

  The plural message ID.

`count`

  The number (e.g. item count) to determine the translation for the respective grammatical number.

### 返回值

Returns correct plural form of message identified by `singular` and `plural` for count `count`.

### 示例

示例 #1 ngettext() example

    <?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 — Sets the default domain

### 说明

function textdomain(?string `$domain` = `null`): string

This function sets the domain to search within when calls are made to gettext(), usually the named after an application.

### 参数

`domain`

  The new message domain, or `null` to get the current setting without changing it

### 返回值

If successful, this function returns the current message domain, after possibly changing it.

### 错误／异常

Throws a ValueError if `domain` is the empty string.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | Now throws a ValueError if `domain` is the empty string.
8.4.0 | `domain` is optional now. Previously, the parameter always had to be specified.

### 注释

> 注意:

> The textdomain() information is maintained per process, not per thread.

## 目录

- _ — 别名 gettext
- bind_textdomain_codeset — Specify or get the character encoding in which the messages from the DOMAIN message catalog will be returned
- bindtextdomain — Sets or gets the path for a domain
- dcgettext — Overrides the domain for a single lookup
- dcngettext — Plural version of dcgettext
- dgettext — Override the current domain
- dngettext — Plural version of dgettext
- gettext — Lookup a message in the current domain
- ngettext — Plural version of gettext
- textdomain — Sets the default domain

- 安装/配置
  - 需求
  - 安装
- Gettext 函数
  - _ — 别名 gettext
  - bind_textdomain_codeset — Specify or get the character encoding in which the messages from the DOMAIN message catalog will be returned
  - bindtextdomain — Sets or gets the path for a domain
  - dcgettext — Overrides the domain for a single lookup
  - dcngettext — Plural version of dcgettext
  - dgettext — Override the current domain
  - dngettext — Plural version of dgettext
  - gettext — Lookup a message in the current domain
  - ngettext — Plural version of gettext
  - textdomain — Sets the default domain

# iconv

# 简介

此模块包含了 iconv 字符集转换功能的接口。 使用此模块，你可以将一个本地字符集表达的字符串转换成另一种字符集，比如可以是 Unicode 字符集。 支持的字符集基于你系统上 iconv 的实现。 注意，在某些系统上 iconv 函数可能无法以你预期的那样工作。 在这种情况下，安装 » GNU libiconv 库将会是个不错的主意。 它最终将会产生更一致的结果。

这个扩展具有多种实用功能，来帮助您编写多语言脚本。 让我们看看以下章节，来探索新的功能。

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置

## 需求

如果你使用了最新的 POSIX 兼容系统，则不需要安装其他程序，因为系统提供的 C 语言标准函数库肯定支持 iconv。否则，你必须在系统上安装 » libiconv 函数库。

## 安装

默认已激活此扩展，但是它能够在编译时通过 --without-iconv 选项被禁用。

选项指令 --with-iconv[=DIR] 用于 PHP 编译时指定 iconv 在系统里的路径，否则会扫描默认路径。

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

Iconv 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
iconv.input_encoding | "" | `INI_ALL` | 在 PHP 5.6.0 中废弃。
iconv.output_encoding | "" | `INI_ALL` | 在 PHP 5.6.0 中废弃。
iconv.internal_encoding | "" | `INI_ALL` | 在 PHP 5.6.0 中废弃。

这是配置指令的简短说明。

警告

有些系统（比如 IBM AIX） 使用 "ISO8859-1" 来代替 "ISO-8859-1"，所以在配置选项和函数参数中必须使用这个值。

`iconv.input_encoding` string
  警告

  本特性已自 PHP 5.6.0 起废弃。强烈建议不要使用本特性。

  PHP 5.6 及以上的用户应该留空并以 input_encoding 取代。

`iconv.output_encoding` string
  警告

  本特性已自 PHP 5.6.0 起废弃。强烈建议不要使用本特性。

  PHP 5.6 及以上的用户应该留空并以 output_encoding 取代。

`iconv.internal_encoding` string
  警告

  本特性已自 PHP 5.6.0 起废弃。强烈建议不要使用本特性。

  PHP 5.6 及以上的用户应该留空并以 `default_charset` 取代。

# 预定义常量

它能够在运行时识别此扩展使用了哪种实现（implementation）。

`iconv` 实现常量
名称 | 类型 | 描述
--- | --- | ---
`ICONV_IMPL` | string | 实现（implementation）的名称
`ICONV_VERSION` | string | 实现（implementation）的版本

> 注意:

> 通过这些常量编写依赖于实现的脚本是极其不建议的。

以下常量同样有效：

其他 `iconv` 常量
名称 | 类型 | 描述
--- | --- | ---
`ICONV_MIME_DECODE_STRICT` | int | 使用于 iconv_mime_decode() 的位掩码
`ICONV_MIME_DECODE_CONTINUE_ON_ERROR` | int | 使用于 iconv_mime_decode() 的位掩码

# iconv 函数

# 参见

参见 GNU Recode functions。

# iconv

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv — 将字符串从一个字符编码转换到另一个字符编码

### 说明

function iconv(string `$from_encoding`, string `$to_encoding`, string `$string`): string|false

将 `string` 从 `from_encoding` 转换到 `to_encoding`。

### 参数

`from_encoding`

  用于解释 `string` 的当前编码。

`to_encoding`

  所需的结果编码。

  如果字符串 `//TRANSLIT` 追加到 `to_encoding` ，然后将启用转写（transliteration）功能。这意味着当字符不能被目标字符集所表示时，它可以通过一个或多个形似的字符来近似表达。 如果追加字符串 `//IGNORE`，不能以目标字符集表达的字符将被默默丢弃。否则，会导致 `E_NOTICE` 并返回 `false`。

  警告

  `//TRANSLIT` 运行细节高度依赖于系统的 iconv() 实现（参见 `ICONV_IMPL`）。 据悉，某些系统上的实现会直接忽略 `//TRANSLIT`，所以转换也有可能失败，`to_encoding` 会是不合格的。

`string`

  要转换的 string。

### 返回值

返回转换后的字符串， 或者在失败时返回 `false`。

### 示例

示例 #1 iconv() 示例

    <?php
    $text = "This is the Euro symbol '€'.";

    echo 'Original : ', $text, PHP_EOL;
    echo 'TRANSLIT : ', iconv("UTF-8", "ISO-8859-1//TRANSLIT", $text), PHP_EOL;
    echo 'IGNORE   : ', iconv("UTF-8", "ISO-8859-1//IGNORE", $text), PHP_EOL;
    echo 'Plain    : ', iconv("UTF-8", "ISO-8859-1", $text), PHP_EOL;

    ?>

以上示例的输出类似于：

    Original : This is the Euro symbol '€'.
    TRANSLIT : This is the Euro symbol 'EUR'.
    IGNORE   : This is the Euro symbol ''.
    Plain    :
    Notice: iconv(): Detected an illegal character in input string in .\iconv-example.php on line 7

### 注释

> 注意:

> 可用的字符编码和选项取决于已安装的 iconv 实现。如果当前系统不支持 `from_encoding` 或 `to_encoding` 的参数，则返回 `false`。

### 参见

- mb_convert_encoding() - 转换字符串，从一个字符编码到另一个字符编码
- 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 — 获取 iconv 扩展的内部配置变量

### 说明

function iconv_get_encoding(string `$type` = "all"): array|string|false

获取 iconv 扩展的内部配置变量。

### 参数

`type`

  选项 `type` 的值可以是：

  - all
  - input_encoding
  - output_encoding
  - internal_encoding

### 返回值

成功时返回当前内部配置变量的值， 或者在失败时返回 `false`。

如果省略了 `type`，或者设置为 "all"，iconv_get_encoding() 返回包含所有这些变量的数组。

### 示例

示例 #1 iconv_get_encoding() 示例

    <pre>
    <?php
    iconv_set_encoding("internal_encoding", "UTF-8");
    iconv_set_encoding("output_encoding", "ISO-8859-1");
    var_dump(iconv_get_encoding('all'));
    ?>
    </pre>

以上示例会输出：

    Array
    (
        [input_encoding] => ISO-8859-1
        [output_encoding] => ISO-8859-1
        [internal_encoding] => UTF-8
    )

### 参见

- iconv_set_encoding() - 为字符编码转换设定当前设置
- ob_iconv_handler() - 以输出缓冲处理程序转换字符编码

# iconv_mime_decode

(PHP 5, PHP 7, PHP 8)

iconv_mime_decode — 解码一个`MIME`头字段

### 说明

function iconv_mime_decode(string `$string`, int `$mode` = 0, ?string `$encoding` = `null`): string|false

解码一个`MIME`头字段.

### 参数

`string`

  编码头,是一个字符串.

`mode`

  `模式`决定了当iconv_mime_decode()遇到一个不规则的 `MIME`头字段时,对这个事件作出的行为.你可以指定以下位掩码的任意组合.

  可以在iconv_mime_decode()中使用的位掩码
  值 | 常量 | 描述
  --- | --- | ---
  1 | ICONV_MIME_DECODE_STRICT | 如果使用该位掩码,传入的头字段将会完全一致的按照» RFC2047的标准定义被解码. 这个选项默认是禁用的,因为有很多零散的邮件用户代理商不遵守标准规范并且不生成正确的`MIME`头.
  2 | ICONV_MIME_DECODE_CONTINUE_ON_ERROR | 如果使用该位掩码,iconv_mime_decode_headers() 将会试图忽略任何错误语法,并继续处理传入的头字段.

`encoding`

  可选的 `encoding` 参数,用指定的字符集表示结果。如果省略或为 `null`，iconv.internal_encoding 将会被默认使用。

### 返回值

如果解码成功,返回一个被解码的`MIME`字段, 如果在解码过程中出现一个错误,将返回`false` .

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `encoding` 现在可为 null。

### 示例

示例 #1 iconv_mime_decode()实例

    <?php
    //返回结果: "Subject: Prüfung Prüfung"
    echo iconv_mime_decode("Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=",
                           0, "ISO-8859-1");
    ?>

### 参见

- iconv_mime_decode_headers() - 一次性解码多个 MIME 头字段
- mb_decode_mimeheader() - 解码 MIME 头字段中的字符串
- imap_mime_header_decode() - Decode MIME header elements
- imap_base64() - Decode BASE64 encoded text
- imap_qprint() - Convert a quoted-printable string to an 8 bit string

# iconv_mime_decode_headers

(PHP 5, PHP 7, PHP 8)

iconv_mime_decode_headers — 一次性解码多个 `MIME` 头字段

### 说明

function iconv_mime_decode_headers(string `$headers`, int `$mode` = 0, ?string `$encoding` = `null`): array|false

一次性解码多个 `MIME` 头字段。

### 参数

`headers`

  编码过的头，是一个字符串。

`mode`

  `mode` 决定了 iconv_mime_decode_headers() 遇到畸形 `MIME` 头字段时的行为。 你可以指定为以下位掩码的任意组合。

  iconv_mime_decode_headers() 接受的位掩码
  值 | 常量 | 描述
  --- | --- | ---
  1 | ICONV_MIME_DECODE_STRICT | 如果设置了，给定的头将会以 » RFC2047 定义的标准完全一致。 这个选项默认禁用，因为大量有问题的邮件用户代理不遵循标准并产生不正确的 `MIME` 头。
  2 | ICONV_MIME_DECODE_CONTINUE_ON_ERROR | 如果设置了，iconv_mime_decode_headers() 尝试忽略任何语法错误并继续处理指定的头。

`encoding`

  可选参数 `encoding` 指定了字符集结果的表现。 如果省略或为 `null`，将使用 iconv.internal_encoding。

### 返回值

成功时返回 `headers` 指定的 `MIME` 头的整套关联数组，解码时出现错误则返回 `false`。

返回元素的每个键代表独立字段名，相应的元素代表一个字段值。如果有多个同一名称的字段，iconv_mime_decode_headers() 自动将他们按出现顺序结合成数字索引的数组。请注意，标头名称不区分大小写。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `encoding` 现在可为 null。

### 示例

示例 #1 iconv_mime_decode_headers() 示例

    <?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);
    ?>

以上示例会输出：

    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
            )

    )

### 参见

- iconv_mime_decode() - 解码一个MIME头字段
- mb_decode_mimeheader() - 解码 MIME 头字段中的字符串
- imap_mime_header_decode() - Decode MIME header elements
- imap_base64() - Decode BASE64 encoded text
- imap_qprint() - Convert a quoted-printable string to an 8 bit string

# iconv_mime_encode

(PHP 5, PHP 7, PHP 8)

iconv_mime_encode — Composes a `MIME` header field

### 说明

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.

### 参数

`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

### 返回值

Returns an encoded `MIME` field on success, or `false` if an error occurs during the encoding.

### 示例

示例 #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);
    ?>

### 参见

- imap_binary() - Convert an 8bit string to a base64 string
- mb_encode_mimeheader() - 为 MIME 头编码字符串
- imap_8bit() - Convert an 8bit string to a quoted-printable string
- quoted_printable_encode() - 将 8-bit 字符串转换成 quoted-printable 字符串

# iconv_set_encoding

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv_set_encoding — 为字符编码转换设定当前设置

### 说明

function iconv_set_encoding(string `$type`, string `$encoding`): bool

将 `type` 设置的值从内部配置变量更改为 `encoding`。

### 参数

`type`

  `type` 的值可以是以下其中任意一个：

  - input_encoding
  - output_encoding
  - internal_encoding
`encoding`

  字符集。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 iconv_set_encoding() 示例

    <?php
    iconv_set_encoding("internal_encoding", "UTF-8");
    iconv_set_encoding("output_encoding", "ISO-8859-1");
    ?>

### 参见

- iconv_get_encoding() - 获取 iconv 扩展的内部配置变量
- ob_iconv_handler() - 以输出缓冲处理程序转换字符编码

# iconv_strlen

(PHP 5, PHP 7, PHP 8)

iconv_strlen — 返回字符串的字符数统计

### 说明

function iconv_strlen(string `$string`, ?string `$encoding` = `null`): int|false

和 strlen() 不同的是，iconv_strlen() 统计了给定的字节序列 `string` 中出现字符数的统计，基于指定的字符集，其产生的结果不一定和字符字节数相等。

### 参数

`string`

  该字符串。

`encoding`

  如果 `encoding` 参数省略或为 `null`，假设 `string` 的编码为 iconv.internal_encoding。

### 返回值

返回 `str` 字符数的统计，是整型。如果编码期间出现错误，为 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `encoding` 现在可为 null。

### 参见

- grapheme_strlen() - Get string length in grapheme units
- mb_strlen() - 获取字符串的长度
- strlen() - 获取字符串长度

# iconv_strpos

(PHP 5, PHP 7, PHP 8)

iconv_strpos — Finds position of first occurrence of a needle within a haystack

### 说明

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`.

### 参数

`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.

### 返回值

Returns the numeric position of the first occurrence of `needle` in `haystack`.

If `needle` is not found, iconv_strpos() will return `false`.

警告

此函数可能返回布尔值 `false`，但也可能返回等同于 `false` 的非布尔值。请阅读 布尔类型章节以获取更多信息。应使用 === 运算符来测试此函数的返回值。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `encoding` is nullable now.
7.1.0 | Support for negative `offset`s has been added.

### 参见

- strpos() - 查找字符串首次出现的位置
- iconv_strrpos() - Finds the last occurrence of a needle within a haystack
- mb_strpos() - 查找字符串在另一个字符串中首次出现的位置

# iconv_strrpos

(PHP 5, PHP 7, PHP 8)

iconv_strrpos — Finds the last occurrence of a needle within a haystack

### 说明

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`.

### 参数

`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.

### 返回值

Returns the numeric position of the last occurrence of `needle` in `haystack`.

If `needle` is not found, iconv_strrpos() will return `false`.

警告

此函数可能返回布尔值 `false`，但也可能返回等同于 `false` 的非布尔值。请阅读 布尔类型章节以获取更多信息。应使用 === 运算符来测试此函数的返回值。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `encoding` is nullable now.

### 参见

- strrpos() - 计算指定字符串在目标字符串中最后一次出现的位置
- iconv_strpos() - Finds position of first occurrence of a needle within a haystack
- mb_strrpos() - 查找字符串在一个字符串中最后出现的位置

# iconv_substr

(PHP 5, PHP 7, PHP 8)

iconv_substr — 截取字符串的部分

### 说明

function iconv_substr(
string `$string`,
int `$offset`,
?int `$length` = `null`,
?string `$encoding` = `null`
): string|false

根据 `offset` 和 `length` 参数指定 `string` 截取的部分。

### 参数

`string`

  原始字符串。

`offset`

  如果 `offset` 是非负数，iconv_substr() 从 `string` 开头第 `offset` 个字符开始截出部分，从 0 开始计数。

  如果 `offset` 是负数，iconv_substr() 从 `string` 末尾向前 `offset` 个字符开始截取。

`length`

  如果指定了 `length` 并且是正数，返回的值从 `offset` 截取部分，最多包含 `length` 个字符（取决于 `string` 的长度）。

  如果传入了负数的 `length`， iconv_substr() 将从第 `offset` 个字符到离末尾 `length` 个字符截出 `string` 的部分。 如果 `offset` 也是负数，则开始位置计算规则的解释见以上。

`encoding`

  如果省略了参数 `encoding`，`string` 的编码被认定为 iconv.internal_encoding。

  注意，`offset` 和 `length` 参数总是被认为字符表现的偏移，基于 `encoding` 检测到的字符集进行统计计算，而相对应的 substr() 则是基于字节的位移来计算。

### 返回值

返回 `offset` 和 `length` 参数指定的 `string` 的部分。

如果 `string` 比 `offset` 字符数更短，将会返回 `false`。 如果 `string` 是 `offset` 个字符的长度，将返回空字符串。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `length` 和 `encoding` 现在可为 null。
7.0.11 | 如果 `string` 等于 `offset` 个字符，将返回空字符串。之前的版本里，这种情况会返回 `false`。

### 参见

- substr() - 返回字符串的子串
- mb_substr() - 获取部分字符串
- mb_strcut() - 获取字符的一部分

# ob_iconv_handler

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

ob_iconv_handler — 以输出缓冲处理程序转换字符编码

### 说明

function ob_iconv_handler(string `$contents`, int `$status`): string

将字符编码从 `internal_encoding` 转换到 `output_encoding`。

`internal_encoding` 和 `output_encoding` 应当在 php.ini 文件或 iconv_set_encoding() 中定义。

### 参数

关于处理程序参数的信息，参见 ob_start()。

### 返回值

关于处理程序返回值的信息，参见 ob_start()。

### 示例

示例 #1 ob_iconv_handler() 例子：

    <?php
    iconv_set_encoding("internal_encoding", "UTF-8");
    iconv_set_encoding("output_encoding", "ISO-8859-1");
    ob_start("ob_iconv_handler"); // 开始输出缓冲
    ?>

### 参见

- iconv_get_encoding() - 获取 iconv 扩展的内部配置变量
- iconv_set_encoding() - 为字符编码转换设定当前设置
- 输出控制函数

## 目录

- iconv — 将字符串从一个字符编码转换到另一个字符编码
- iconv_get_encoding — 获取 iconv 扩展的内部配置变量
- iconv_mime_decode — 解码一个MIME头字段
- iconv_mime_decode_headers — 一次性解码多个 MIME 头字段
- iconv_mime_encode — Composes a MIME header field
- iconv_set_encoding — 为字符编码转换设定当前设置
- iconv_strlen — 返回字符串的字符数统计
- 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 — 截取字符串的部分
- ob_iconv_handler — 以输出缓冲处理程序转换字符编码

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
- 预定义常量
- iconv 函数
  - iconv — 将字符串从一个字符编码转换到另一个字符编码
  - iconv_get_encoding — 获取 iconv 扩展的内部配置变量
  - iconv_mime_decode — 解码一个MIME头字段
  - iconv_mime_decode_headers — 一次性解码多个 MIME 头字段
  - iconv_mime_encode — Composes a MIME header field
  - iconv_set_encoding — 为字符编码转换设定当前设置
  - iconv_strlen — 返回字符串的字符数统计
  - 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 — 截取字符串的部分
  - ob_iconv_handler — 以输出缓冲处理程序转换字符编码

# Internationalization Functions

# 简介

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

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置

## 需求

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.

## 安装

--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.

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

Intl 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
intl.default_locale |  | `INI_ALL` |
intl.error_level | 0 | `INI_ALL` |
intl.use_exceptions | 0 | `INI_ALL` | Available since PECL 3.0.0a1

这是配置指令的简短说明。

`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`.

# 预定义常量

`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.

# 示例

## 目录

- 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.

> 注意:

> All input strings must be in UTF-8 encoding. All output strings are also in UTF-8.

示例 #1 Example of using the procedural API

    <?php
    $coll  = collator_create('en_US');
    $result = collator_compare($coll, "string#1", "string#2");
    ?>

示例 #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)

## 简介

Provides string comparison capability with support for appropriate locale-sensitive sort orderings.

## 类摘要

class Collator {
/* 常量 */
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;
/* 方法 */
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
}

## 预定义常量

`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`

  示例 #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`

  示例 #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`

  示例 #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`

  示例 #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

## 更新日志

版本 | 说明
--- | ---
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

### 说明

面向对象风格

public function Collator::asort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

过程化风格

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().

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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 );
    ?>

以上示例会输出：

    array (
      'c' => '7',
      'b' => '50',
      'a' => '100',
    )array (
      'a' => '100',
      'b' => '50',
      'c' => '7',
    )

### 参见

- 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

### 说明

面向对象风格

public function Collator::compare(string `$string1`, string `$string2`): int|false

过程化风格

function collator_compare(Collator `$object`, string `$string1`, string `$string2`): int|false

Compare two Unicode strings according to collation rules.

### 参数

`object`

  Collator object.

`string1`

  The first string to compare.

`string2`

  The second string to compare.

### 返回值

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.
警告

此函数可能返回布尔值 `false`，但也可能返回等同于 `false` 的非布尔值。请阅读 布尔类型章节以获取更多信息。应使用 === 运算符来测试此函数的返回值。

### 示例

示例 #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";
    }
    ?>

以上示例会输出：

s1 is greater than s2

示例 #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";
    }

以上示例会输出：

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.

### 参见

- 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

### 说明

public function Collator::__construct(string `$locale`)

Creates a new instance of Collator.

### 参数

`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.

### 错误／异常

Returns an "empty" object on error. Use intl_get_error_code() and/or intl_get_error_message() to know what happened.

### 示例

示例 #1 Collator::__construct() example

    <?php
    $coll = new Collator('en_CA');
    ?>

### 参见

- 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

### 说明

面向对象风格

public static function Collator::create(string `$locale`): ?Collator

过程化风格

function collator_create(string `$locale`): ?Collator

The strings will be compared using the options already specified.

### 参数

`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.

### 返回值

Return new instance of Collator object, or `null` on error.

### 示例

示例 #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 );
    }
    ?>

### 参见

- 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

### 说明

面向对象风格

public function Collator::getAttribute(int `$attribute`): int|false

过程化风格

function collator_get_attribute(Collator `$object`, int `$attribute`): int|false

Get a value of an integer collator attribute.

### 参数

`object`

  Collator object.

`attribute`

  Attribute to get value for.

### 返回值

Attribute value, 或者在失败时返回 `false`.

### 示例

示例 #1 collator_get_attribute() example

    <?php
    $coll = collator_create( 'en_CA' );
    $val = collator_get_attribute( $coll, Collator::NUMERIC_COLLATION );
    if( $val === false )
    {
        // Handle error.
    }
    ?>

### 参见

- 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

### 说明

面向对象风格

public function Collator::getErrorCode(): int|false

过程化风格

function collator_get_error_code(Collator `$object`): int|false

### 参数

`object`

  Collator object.

### 返回值

Error code returned by the last Collator API function call, 或者在失败时返回 `false`.

### 示例

示例 #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() );
    ?>

### 参见

- 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

### 说明

面向对象风格

public function Collator::getErrorMessage(): string|false

过程化风格

function collator_get_error_message(Collator `$object`): string|false

Retrieves the message for the last error.

### 参数

`object`

  Collator object.

### 返回值

Description of an error occurred in the last Collator API function call, 或者在失败时返回 `false`.

### 示例

示例 #1 collator_get_error_message() example

    <?php
    $coll = collator_create( 'lt' );
    if( collator_compare( $coll, 'y', 'k' ) === false ) {
        echo collator_get_error_message( $coll );
    }
    ?>

### 参见

- 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

### 说明

面向对象风格

public function Collator::getLocale(int `$type`): string|false

过程化风格

function collator_get_locale(Collator `$object`, int `$type`): string|false

Get collector locale name.

### 参数

`object`

  Collator object.

`type`

  You can choose between valid and actual locale ( `Locale::VALID_LOCALE` and `Locale::ACTUAL_LOCALE`, respectively).

### 返回值

Real locale name from which the collation data comes. If the collator was instantiated from rules or an error occurred, returns `false`.

### 示例

示例 #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 );
    ?>

以上示例会输出：

    Requested locale name: en_US_California
    Valid locale name: en_US
    Actual locale name: en

### 参见

- 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

### 说明

面向对象风格

public function Collator::getSortKey(string `$string`): string|false

过程化风格

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.

### 参数

`object`

  Collator object.

`string`

  The string to produce the key from.

### 返回值

Returns the collation key for the string, 或者在失败时返回 `false`.

警告

此函数可能返回布尔值 `false`，但也可能返回等同于 `false` 的非布尔值。请阅读 布尔类型章节以获取更多信息。应使用 === 运算符来测试此函数的返回值。

### 示例

示例 #1 collator_get_sort_key() example

    <?php

    $s1 = 'Hello';

    $coll = collator_create('en_US');
    $res  = collator_get_sort_key($coll, $s1);

    echo bin2hex($res);
    ?>

以上示例的输出类似于：

3832404046010901dc08

示例 #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);
    ?>

以上示例的输出类似于：

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"
}
}

### 参见

- 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

### 说明

面向对象风格

public function Collator::getStrength(): int

过程化风格

function collator_get_strength(Collator `$object`): int

### 参数

`object`

  Collator object.

### 返回值

Returns current collation strength, 或者在失败时返回 `false`.

### 示例

示例 #1 collator_get_strength() example

    <?php
    $coll     = collator_create( 'en_US' );
    $strength = collator_get_strength( $coll );
    ?>

### 参见

- 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

### 说明

面向对象风格

public function Collator::setAttribute(int `$attribute`, int `$value`): bool

过程化风格

function collator_set_attribute(Collator `$object`, int `$attribute`, int `$value`): bool

### 参数

`object`

  Collator object.

`attribute`

  Attribute.

`value`

  Attribute value.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 collator_set_attribute() example

    <?php
    $coll = collator_create('en_CA');
    collator_set_attribute($coll, Collator::NORMALIZATION_MODE, Collator::ON);
    ?>

### 参见

- 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

### 说明

面向对象风格

public function Collator::setStrength(int `$strength`): true

过程化风格

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.

   > 注意:

   > 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.

### 参数

`object`

  Collator object.

`strength`

  Strength to set.

  Possible values are:

  - `Collator::PRIMARY`

  - `Collator::SECONDARY`

  - `Collator::TERTIARY`

  - `Collator::QUATERNARY`

  - `Collator::IDENTICAL`

  - `Collator::DEFAULT_STRENGTH`

### 返回值

总是返回 `true`。

### 示例

示例 #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 );
    ?>

以上示例会输出：

    array (
      0 => 'ao',
      1 => 'Ao',
      2 => 'aò',
    )
    array (
      0 => 'aò',
      1 => 'Ao',
      2 => 'ao',
    )

### 参见

- 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

### 说明

面向对象风格

public function Collator::sort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

过程化风格

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() .

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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 );
    ?>

以上示例会输出：

    array (
      0 => 'at',
      1 => 'às',
      2 => 'as',
    )array (
      0 => 'as',
      1 => 'às',
      2 => 'at',
    )

### 参见

- 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

### 说明

面向对象风格

public function Collator::sortWithSortKeys(array `&$array`): bool

过程化风格

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.

### 参数

`object`

  Collator object.

`array`

  Array of strings to sort

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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 );
    ?>

以上示例会输出：

    array (
      0 => 'Kopfe',
      1 => 'Kypper',
      2 => 'Köpfe',
    )

### 参见

- Collator constants
- collator_sort() - Sort array using specified collator
- collator_asort() - Sort array maintaining index association

## 目录

- 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)

## 简介

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.

## 类摘要

class NumberFormatter {
/* 常量 */
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;
/* 方法 */
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
}

## 预定义常量

## 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`
  别名 `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`
  别名 `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.

## 参见

- » ICU formatting documentation
- » ICU number formatters
- » ICU decimal formatters
- » ICU rule-based number formatters

## 更新日志

版本 | 说明
--- | ---
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

### 说明

面向对象风格 (method)

public static function NumberFormatter::create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter

过程化风格

function numfmt_create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter

面向对象风格 (constructor):

public function NumberFormatter::__construct(string `$locale`, int `$style`, ?string `$pattern` = `null`)

Creates a number formatter.

### 参数

`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.

### 返回值

Returns NumberFormatter object or `null` on error.

### 错误／异常

A ValueError is thrown if `locale` is invalid.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | A ValueError is thrown if `locale` is invalid.
8.0.0 | `pattern` is nullable now.

### 示例

示例 #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";
    ?>

示例 #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";
    ?>

以上示例会输出：

    1.234.567,891
    millicentoquarantadue

### 参见

- 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

### 说明

面向对象风格

public function NumberFormatter::format(int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false

过程化风格

function numfmt_format(NumberFormatter `$formatter`, int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false

Format a numeric value according to the formatter rules.

### 参数

`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.

### 返回值

Returns the string containing formatted value, or `false` on error.

### 示例

示例 #1 numfmt_format() example

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    $data = numfmt_format($fmt, 1234567.891234567890000);
    var_dump($data);
    ?>

示例 #2 OO example

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $data = $fmt->format(1234567.891234567890000);
    var_dump($data);
    ?>

以上示例会输出：

    string(13) "1.234.567,891"

### 注释

> 注意:

> 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().

### 参见

- 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

### 说明

面向对象风格

public function NumberFormatter::formatCurrency(float `$amount`, string `$currency`): string|false

过程化风格

function numfmt_format_currency(NumberFormatter `$formatter`, float `$amount`, string `$currency`): string|false

Format the currency value according to the formatter rules.

### 参数

`formatter`

  NumberFormatter object.

`amount`

  The numeric currency value.

`currency`

  The 3-letter ISO 4217 currency code indicating the currency to use.

### 返回值

String representing the formatted currency value, 或者在失败时返回 `false`.

### 示例

示例 #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";
    ?>

示例 #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";
    ?>

以上示例会输出：

    1.234.567,89 €
    1.234.567,89 RUR
    1 234 567,89€
    1 234 567,89р.

### 注释

> 注意:

> 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().

### 参见

- 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

### 说明

面向对象风格

public function NumberFormatter::getAttribute(int `$attribute`): int|float|false

过程化风格

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.

### 参数

`formatter`

  NumberFormatter object.

`attribute`

  Attribute specifier - one of the numeric attribute constants.

### 返回值

Return attribute value on success, or `false` on error.

### 示例

示例 #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";
    ?>

示例 #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";
    ?>

以上示例会输出：

    Digits: 3
    1.234.567,891
    Digits: 2
    1.234.567,89

### 参见

- 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

### 说明

面向对象风格

public function NumberFormatter::getErrorCode(): int

过程化风格

function numfmt_get_error_code(NumberFormatter `$formatter`): int

Get error code from the last function performed by the formatter.

### 参数

`formatter`

  NumberFormatter object.

### 返回值

Returns error code from last formatter call.

### 示例

示例 #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';
    }
    ?>

示例 #2 OO example

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $fmt->format(1234567.891234567890000);
    if (intl_is_failure($fmt->getErrorCode())) {
        echo 'Formatter error';
    }
    ?>

### 参见

- 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

### 说明

面向对象风格

public function NumberFormatter::getErrorMessage(): string

过程化风格

function numfmt_get_error_message(NumberFormatter `$formatter`): string

Get error message from the last function performed by the formatter.

### 参数

`formatter`

  NumberFormatter object.

### 返回值

Returns error message from last formatter call.

### 示例

示例 #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));
    ?>

示例 #2 OO example

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $fmt->format(1234567.891234567890000);
    var_dump(numfmt_get_error_message($fmt));
    ?>

### 参见

- 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

### 说明

面向对象风格

public function NumberFormatter::getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

过程化风格

function numfmt_get_locale(NumberFormatter `$formatter`, int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Get formatter locale name.

### 参数

`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.

### 返回值

The locale name used to create the formatter, or `false` on failure.

### 示例

示例 #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 );
    ?>

以上示例会输出：

    Requested locale name: fr_FR_PARIS
    Valid locale name: fr_FR
    Actual locale name: fr

### 参见

- 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

### 说明

面向对象风格

public function NumberFormatter::getPattern(): string|false

过程化风格

function numfmt_get_pattern(NumberFormatter `$formatter`): string|false

Extract pattern used by the formatter.

### 参数

`formatter`

  NumberFormatter object.

### 返回值

Pattern string that is used by the formatter, or `false` if an error happens.

### 示例

示例 #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";
    ?>

示例 #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";
    ?>

以上示例会输出：

    Pattern: #,##0.###
    1.234.567,891
    Pattern: #0.# kg
    1234567,9 kg

### 参见

- 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

### 说明

面向对象风格

public function NumberFormatter::getSymbol(int `$symbol`): string|false

过程化风格

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.

### 参数

`formatter`

  NumberFormatter object.

`symbol`

  Symbol specifier, one of the format symbol constants.

### 返回值

The symbol string or `false` on error.

### 示例

示例 #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";
    ?>

示例 #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";
    ?>

以上示例会输出：

    Sep: .
    1.234.567,891
    Sep: *
    1*234*567,891

### 参见

- 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

### 说明

面向对象风格

public function NumberFormatter::getTextAttribute(int `$attribute`): string|false

过程化风格

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`.

### 参数

`formatter`

  NumberFormatter object.

`attribute`

  Attribute specifier - one of the text attribute constants.

### 返回值

Return attribute value on success, or `false` on error.

### 示例

示例 #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";
    ?>

示例 #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";
    ?>

以上示例会输出：

    Prefix: -
    -1.234.567,891
    Prefix: MINUS
    MINUS1.234.567,891

### 参见

- 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

### 说明

面向对象风格

public function NumberFormatter::parse(string `$string`, int `$type` = `NumberFormatter::TYPE_DOUBLE`, int `&$offset` = `null`): int|float|false

过程化风格

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.

### 参数

`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.

### 返回值

The value of the parsed number or `false` on error.

### 示例

示例 #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";
    ?>

示例 #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";
    ?>

以上示例会输出：

    1234567.891
    1234567

### 参见

- 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

### 说明

面向对象风格

public function NumberFormatter::parseCurrency(string `$string`, string `&$currency`, int `&$offset` = `null`): float|false

过程化风格

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.

### 参数

`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.

### 返回值

The parsed numeric value or `false` on error.

### 示例

示例 #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";
    ?>

示例 #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";
    ?>

以上示例会输出：

    We have 1234567.89 in USD

### 参见

- 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

### 说明

面向对象风格

public function NumberFormatter::setAttribute(int `$attribute`, int|float `$value`): bool

过程化风格

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.

### 参数

`formatter`

  NumberFormatter object.

`attribute`

  Attribute specifier - one of the numeric attribute constants.

`value`

  The attribute value.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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";
    ?>

示例 #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";
    ?>

以上示例会输出：

    Digits: 3
    1.234.567,891
    Digits: 2
    1.234.567,89

示例 #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)
    ?>

以上示例会输出：

    Default rounding mode:
    3.79
    3.78

    With ROUND_DOWN (truncate):
    3.78
    3.78

### 参见

- 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

### 说明

面向对象风格

public function NumberFormatter::setPattern(string `$pattern`): bool

过程化风格

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.

### 参数

`formatter`

  NumberFormatter object.

`pattern`

  Pattern in syntax described in » ICU DecimalFormat documentation.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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";
    ?>

示例 #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";
    ?>

以上示例会输出：

    Pattern: #,##0.###
    1.234.567,891
    Pattern: #0.# kg
    1234567,9 kg

### 参见

- 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

### 说明

面向对象风格

public function NumberFormatter::setSymbol(int `$symbol`, string `$value`): bool

过程化风格

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.

### 参数

`formatter`

  NumberFormatter object.

`symbol`

  Symbol specifier, one of the format symbol constants.

`value`

  Text for the symbol.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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";
    ?>

示例 #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";
    ?>

以上示例会输出：

    Sep: .
    1.234.567,891
    Sep: *
    1*234*567,891

### 参见

- 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

### 说明

面向对象风格

public function NumberFormatter::setTextAttribute(int `$attribute`, string `$value`): bool

过程化风格

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`.

### 参数

`formatter`

  NumberFormatter object.

`attribute`

  Attribute specifier - one of the text attribute constants.

`value`

  Text for the attribute value.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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";
    ?>

示例 #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";
    ?>

以上示例会输出：

    Prefix: -
    -1.234.567,891
    Prefix: MINUS
    MINUS1.234.567,891

### 参见

- 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::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)

## 简介

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.

## 类摘要

class Locale {
/* 常量 */
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;
/* 方法 */
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
}

## 预定义常量

`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

## 参见

- » 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

## 更新日志

版本 | 说明
--- | ---
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

### 说明

面向对象风格

public static function Locale::acceptFromHttp(string `$header`): string|false

过程化风格

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.

### 参数

`header`

  The string containing the "Accept-Language" header according to format in RFC 2616.

### 返回值

The corresponding locale identifier.

Returns `false` when the length of `header` exceeds `INTL_MAX_LOCALE_LEN`.

### 示例

示例 #1 locale_accept_from_http() example

    <?php
    $locale = locale_accept_from_http($_SERVER['HTTP_ACCEPT_LANGUAGE']);
    echo $locale;
    ?>

示例 #2 OO example

    <?php
    $locale = Locale::acceptFromHttp($_SERVER['HTTP_ACCEPT_LANGUAGE']);
    echo $locale;
    ?>

以上示例会输出：

    en_US

### 参见

- 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

### 说明

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`).

### 参数

`locale`
  Original locale string.

### 返回值

Canonicalized locale string.

当 `locale` 的长度超过 `INTL_MAX_LOCALE_LEN` 时返回 `null`。

### 示例

示例 #1 locale_canonicalize() example

    echo Locale::canonicalize('en-US.utf8') . "\n";
    echo Locale::canonicalize('totally-not-valid') . "\n";

以上示例的输出类似于：

    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

### 说明

面向对象风格

public static function Locale::composeLocale(array `$subtags`): string|false

过程化风格

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.

### 参数

`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.

  > 注意:

  > 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.

### 返回值

The corresponding locale identifier, or `false` when `subtags` is empty.

### 示例

示例 #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);
    ?>

示例 #2 OO example

    <?php
    $arr = array(
        'language'=>'en' ,
        'script'  =>'Hans',
        'region'  =>'CN',
        'variant2'=>'rozaj',
        'variant1'=>'nedis',
        'private1'=>'prv1',
        'private2'=>'prv2',
    );
    echo Locale::composeLocale($arr);
    ?>

以上示例会输出：

    Locale: en_Hans_CN_nedis_rozaj_x_prv1_prv2

示例 #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;
    ?>

以上示例会输出：

    en_a_b_c_Hans_CN
    en_a_b_c_d_Hans_CN

### 参见

- 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

### 说明

面向对象风格

public static function Locale::filterMatches(string `$languageTag`, string `$locale`, bool `$canonicalize` = `false`): ?bool

过程化风格

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

### 参数

`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.

### 返回值

`true` if `locale` matches `languageTag` `false` otherwise.

当 `locale` 的长度超过 `INTL_MAX_LOCALE_LEN` 时返回 `null`。

### 示例

示例 #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";
    ?>

示例 #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";
    ?>

以上示例会输出：

    Does not match; Matches

### 参见

- 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

### 说明

面向对象风格

public static function Locale::getAllVariants(string `$locale`): ?array

过程化风格

function locale_get_all_variants(string `$locale`): ?array

Gets the variants for the input locale

### 参数

`locale`

  The locale to extract the variants from

### 返回值

The array containing the list of all variants subtag for the locale or `null` if not present

当 `locale` 的长度超过 `INTL_MAX_LOCALE_LEN` 时返回 `null`。

### 示例

示例 #1 locale_get_all_variants() example

    <?php
    $arr = locale_get_all_variants('sl_IT_NEDIS_ROJAZ_1901');
    var_export( $arr );
    ?>

示例 #2 OO example

    <?php
     $arr = Locale::getAllVariants('sl_IT_NEDIS_ROJAZ_1901');
     var_export( $arr );
    ?>

以上示例会输出：

    array (
        0 => 'NEDIS',
        1 => 'ROJAZ',
        2 => '1901',
    )

### 参见

- 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'

### 说明

面向对象风格

public static function Locale::getDefault(): string

过程化风格

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().

### 参数

### 返回值

The current runtime locale

### 示例

示例 #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();
    ?>

示例 #2 OO example

    <?php
    ini_set('intl.default_locale', 'de-DE');
    echo Locale::getDefault();
    echo '; ';
    Locale::setDefault('fr');
    echo Locale::getDefault();
    ?>

以上示例会输出：

    de-DE; fr

### 参见

- 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

### 说明

面向对象风格

public static function Locale::getDisplayLanguage(string `$locale`, ?string `$displayLocale` = `null`): string|false

过程化风格

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.

### 参数

`locale`

  The locale to return a display language for

`displayLocale`

  Optional format locale to use to display the language name

### 返回值

Display name of the language for the `locale` in the format appropriate for `displayLocale`, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `displayLocale` is nullable now.

### 示例

示例 #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');
    ?>

示例 #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');
    ?>

以上示例会输出：

    Slovenian;
    slov\xc3\xa8ne;
    Slowenisch

### 参见

- 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

### 说明

面向对象风格

public static function Locale::getDisplayName(string `$locale`, ?string `$displayLocale` = `null`): string|false

过程化风格

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.

### 参数

`locale`

  The locale to return a display name for.

`displayLocale`

  optional format locale

### 返回值

Display name of the locale in the format appropriate for `displayLocale`, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `displayLocale` is nullable now.

### 示例

示例 #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');
    ?>

示例 #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');
    ?>

以上示例会输出：

    Slovenian (Latin, Italy, Natisone dialect);
    slov\xc3\xa8ne (latin, Italie, dialecte de Natisone;
    Slowenisch (Lateinisch, Italien, NEDIS)

### 参见

- 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

### 说明

面向对象风格

public static function Locale::getDisplayRegion(string `$locale`, ?string `$displayLocale` = `null`): string|false

过程化风格

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.

### 参数

`locale`

  The locale to return a display region for.

`displayLocale`

  Optional format locale to use to display the region name

### 返回值

Display name of the region for the `locale` in the format appropriate for `displayLocale`, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `displayLocale` is nullable now.

### 示例

示例 #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');
    ?>

示例 #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');
    ?>

以上示例会输出：

    Italy;
    Italie;
    Italien

### 参见

- 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

### 说明

面向对象风格

public static function Locale::getDisplayScript(string `$locale`, ?string `$displayLocale` = `null`): string|false

过程化风格

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.

### 参数

`locale`

  The locale to return a display script for

`displayLocale`

  Optional format locale to use to display the script name

### 返回值

Display name of the script for the `locale` in the format appropriate for `displayLocale`, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `displayLocale` is nullable now.

### 示例

示例 #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');
    ?>

示例 #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');
    ?>

以上示例会输出：

    Latin;
    latin;
    Lateinisch

### 参见

- 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

### 说明

面向对象风格

public static function Locale::getDisplayVariant(string `$locale`, ?string `$displayLocale` = `null`): string|false

过程化风格

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.

### 参数

`locale`

  The locale to return a display variant for

`displayLocale`

  Optional format locale to use to display the variant name

### 返回值

Display name of the variant for the `locale` in the format appropriate for `displayLocale`, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `displayLocale` is nullable now.

### 示例

示例 #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');
    ?>

示例 #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');
    ?>

以上示例会输出：

    Natisone dialect;
    dialecte de Natisone;
    NEDIS

### 参见

- 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

### 说明

面向对象风格

public static function Locale::getKeywords(string `$locale`): array|false|null

过程化风格

function locale_get_keywords(string `$locale`): array|false|null

Gets the keywords for the input locale.

### 参数

`locale`

  The locale to extract the keywords from

### 返回值

Associative array containing the keyword-value pairs for this locale

当 `locale` 的长度超过 `INTL_MAX_LOCALE_LEN` 时返回 `null`。

### 示例

示例 #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";
        }
    }
    ?>

示例 #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";
        }
    }
    ?>

以上示例会输出：

    collation = PHONEBOOK
    currency = EUR

### 参见

- 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

### 说明

面向对象风格

public static function Locale::getPrimaryLanguage(string `$locale`): ?string

过程化风格

function locale_get_primary_language(string `$locale`): ?string

Gets the primary language for the input locale

### 参数

`locale`

  The locale to extract the primary language code from

### 返回值

The language code associated with the language.

当 `locale` 的长度超过 `INTL_MAX_LOCALE_LEN` 时返回 `null`。

### 示例

示例 #1 locale_get_primary_language() example

    <?php
    echo locale_get_primary_language('zh-Hant');
    ?>

示例 #2 OO example

    <?php
    echo Locale::getPrimaryLanguage('zh-Hant');
    ?>

以上示例会输出：

    zh

### 参见

- 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

### 说明

面向对象风格

public static function Locale::getRegion(string `$locale`): ?string

过程化风格

function locale_get_region(string `$locale`): ?string

Gets the region for the input locale.

### 参数

`locale`

  The locale to extract the region code from

### 返回值

The region subtag for the locale or `null` if not present

当 `locale` 的长度超过 `INTL_MAX_LOCALE_LEN` 时返回 `null`。

### 示例

示例 #1 locale_get_region() example

    <?php
    echo locale_get_region('de-CH-1901');
    ?>

示例 #2 OO example

    <?php
    echo Locale::getRegion('de-CH-1901');
    ?>

以上示例会输出：

    CH

### 参见

- 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

### 说明

面向对象风格

public static function Locale::getScript(string `$locale`): ?string

过程化风格

function locale_get_script(string `$locale`): ?string

Gets the script for the input locale.

### 参数

`locale`

  The locale to extract the script code from

### 返回值

The script subtag for the locale or `null` if not present

### 示例

示例 #1 locale_get_script() example

    <?php
    echo locale_get_script('sr-Cyrl');
    ?>

示例 #2 OO example

    <?php
    echo Locale::getScript('sr-Cyrl');
    ?>

以上示例会输出：

    Cyrl

### 参见

- 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

### 说明

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.

### 参数

`locale`
  The locale identifier. If empty, the default locale is used.

### 返回值

Returns `true` if the locale uses a right-to-left writing system, or `false` otherwise.

### 更新日志

版本 | 说明
--- | ---
8.5.0 | Added Locale::isRightToLeft().

### 示例

示例 #1 Checking text direction for a locale

    <?php

    var_dump(Locale::isRightToLeft('en-US'));
    var_dump(Locale::isRightToLeft('ar'));

以上示例会输出：

    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

### 说明

面向对象风格

public static function Locale::lookup(
array `$languageTag`,
string `$locale`,
bool `$canonicalize` = `false`,
?string `$defaultLocale` = `null`
): ?string

过程化风格

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.

### 参数

`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.

### 返回值

The closest matching language tag or default value.

当 `locale` 的长度超过 `INTL_MAX_LOCALE_LEN` 时返回 `null`。

### 更新日志

版本 | 说明
--- | ---
7.4.0 | `defaultLocale` is nullable now.

### 示例

示例 #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');
    ?>

示例 #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');
    ?>

以上示例会输出：

    de_de_1996

### 参见

- 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

### 说明

面向对象风格

public static function Locale::parseLocale(string `$locale`): ?array

过程化风格

function locale_parse(string `$locale`): ?array

Returns a key-value array of locale ID subtag elements.

### 参数

`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.

### 返回值

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`.

### 示例

示例 #1 locale_parse() example

    <?php
    $arr = locale_parse('sl-Latn-IT-nedis');
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value , ";
        }
    }
    ?>

示例 #2 OO example

    <?php
    $arr = Locale::parseLocale('sl-Latn-IT-nedis');
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value , ";
        }
    }
    ?>

以上示例会输出：

    language : sl , script : Latn , region : IT , variant0 : NEDIS ,

### 参见

- 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

### 说明

面向对象风格

public static function Locale::setDefault(string `$locale`): true

过程化风格

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.

### 参数

`locale`

  Is a BCP 47 compliant language tag.

### 返回值

Returns `true`.

### 示例

示例 #1 locale_set_default() example

    <?php
    locale_set_default('de-DE');
    echo locale_get_default();
    ?>

示例 #2 OO example

    <?php
    Locale::setDefault('de-DE');
    echo Locale::getDefault();
    ?>

以上示例会输出：

    de-DE

### 参见

- locale_get_default() - Gets the default locale value from the INTL global 'default_locale'

## 目录

- 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)

## 简介

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.

## 类摘要

class Normalizer {
/* 常量 */
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;
/* 方法 */
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
}

## 预定义常量

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

## 参见

- » Unicode Normalization
- » Unicode Normalization FAQ
- » ICU User Guide - Normalization
- » ICU API Reference - Normalization

## 更新日志

版本 | 说明
--- | ---
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

### 说明

面向对象风格

public static function Normalizer::getRawDecomposition(string `$string`, int `$form` = `Normalizer::FORM_C`): ?string

过程化风格

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.

### 参数

`string`

  The input string, which should be a single, UTF-8 encoded, code point.

### 返回值

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.

### 示例

示例 #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;
    ?>

以上示例会输出：

    ---------------------
    '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)

### 参见

- 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

### 说明

面向对象风格

public static function Normalizer::isNormalized(string `$string`, int `$form` = `Normalizer::FORM_C`): bool

过程化风格

function normalizer_is_normalized(string `$string`, int `$form` = `Normalizer::FORM_C`): bool

Checks if the provided string is already in the specified normalization form.

### 参数

`string`

  The input string to normalize

`form`

  One of the normalization forms.

### 返回值

`true` if normalized, `false` otherwise or if there an error

### 示例

示例 #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";
    ?>

示例 #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";
    ?>

以上示例会输出：

    not normalized; normalized

### 参见

- 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

### 说明

面向对象风格

public static function Normalizer::normalize(string `$string`, int `$form` = `Normalizer::FORM_C`): string|false

过程化风格

function normalizer_normalize(string `$string`, int `$form` = `Normalizer::FORM_C`): string|false

Normalizes the input provided and returns the normalized string

### 参数

`string`

  The input string to normalize

`form`

  One of the normalization forms.

### 返回值

The normalized string or `false` if an error occurred.

### 示例

示例 #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);
    ?>

示例 #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);
    ?>

以上示例会输出：

    %C3%85 %C3%85

### 参见

- normalizer_is_normalized() - Checks if the provided string is already in the specified normalization form

## 目录

- 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)

## 简介

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.

## 类摘要

class MessageFormatter {
/* 方法 */
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
}

## 参见

- » 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

### 说明

面向对象风格 (method)

public static function MessageFormatter::create(string `$locale`, string `$pattern`): ?MessageFormatter

面向对象风格 (constructor):

public function MessageFormatter::__construct(string `$locale`, string `$pattern`)

过程化风格

function msgfmt_create(string `$locale`, string `$pattern`): ?MessageFormatter

Constructs a new Message Formatter

### 参数

`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.

### 返回值

The formatter object, or `null` on failure.

### 错误／异常

When invoked as constructor, on failure an IntlException is thrown.

### 示例

示例 #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));
    ?>

示例 #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));
    ?>

以上示例会输出：

    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

### 参见

- 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

### 说明

面向对象风格

public function MessageFormatter::format(array `$values`): string|false

过程化风格

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

### 参数

`formatter`

  The message formatter

`values`

  Arguments to insert into the format string

### 返回值

The formatted string, or `false` if an error occurred

### 示例

示例 #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));
    ?>

示例 #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));
    ?>

以上示例会输出：

    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

### 参见

- 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

### 说明

面向对象风格

public static function MessageFormatter::formatMessage(string `$locale`, string `$pattern`, array `$values`): string|false

过程化风格

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.

### 参数

`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

### 返回值

The formatted pattern string or `false` if an error occurred

### 示例

示例 #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";

示例 #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";

以上示例会输出：

    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

示例 #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));

以上示例会输出：

    123,45 CA$
    123,45 $

### 参见

- 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

### 说明

面向对象风格

public function MessageFormatter::getErrorCode(): int

过程化风格

function msgfmt_get_error_code(MessageFormatter `$formatter`): int

Get the error code from last operation.

### 参数

`formatter`

  The message formatter

### 返回值

The error code, one of UErrorCode values. Initial value is U_ZERO_ERROR.

### 参见

- 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

### 说明

面向对象风格

public function MessageFormatter::getErrorMessage(): string

过程化风格

function msgfmt_get_error_message(MessageFormatter `$formatter`): string

Get the error text from the last operation.

### 参数

`formatter`

  The message formatter

### 返回值

Description of the last error.

### 示例

示例 #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";
    }
    ?>

示例 #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";
    }
    ?>

以上示例会输出：

    ERROR: msgfmt_format: not enough parameters: U_ILLEGAL_ARGUMENT_ERROR (1)

### 参见

- 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

### 说明

面向对象风格

public function MessageFormatter::getLocale(): string

过程化风格

function msgfmt_get_locale(MessageFormatter `$formatter`): string

Get the locale for which the formatter was created.

### 参数

`formatter`

  The formatter resource

### 返回值

The locale name

### 示例

示例 #1 msgfmt_get_locale() example

    <?php
    $fmt = msgfmt_create('en_US', "Number {0,number}");
    echo msgfmt_get_locale($fmt);
    ?>

示例 #2 OO example

    <?php
    $fmt = new MessageFormatter('en_US', "Number {0,number}");
    echo $fmt->getLocale();
    ?>

以上示例会输出：

    en_US

### 参见

- 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

### 说明

面向对象风格

public function MessageFormatter::getPattern(): string|false

过程化风格

function msgfmt_get_pattern(MessageFormatter `$formatter`): string|false

Get the pattern used by the formatter

### 参数

`formatter`

  The message formatter

### 返回值

The pattern string for this message formatter, 或者在失败时返回 `false`.

### 示例

示例 #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";
    ?>

示例 #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";
    ?>

以上示例会输出：

    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

### 参见

- 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

### 说明

面向对象风格

public function MessageFormatter::parse(string `$string`): array|false

过程化风格

function msgfmt_parse(MessageFormatter `$formatter`, string `$string`): array|false

Parses input string and return any extracted items as an array.

### 参数

`formatter`

  The message formatter

`string`

  The string to parse

### 返回值

An array containing the items extracted, or `false` on error

### 示例

示例 #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);
    ?>

示例 #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);
    ?>

以上示例会输出：

    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )
    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )

### 参见

- 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

### 说明

面向对象风格

public static function MessageFormatter::parseMessage(string `$locale`, string `$pattern`, string `$message`): array|false

过程化风格

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.

### 参数

`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`.

### 返回值

An array containing items extracted, or `false` on error

### 示例

示例 #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);
    ?>

示例 #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);
    ?>

以上示例会输出：

    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )
    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )

### 参见

- 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

### 说明

面向对象风格

public function MessageFormatter::setPattern(string `$pattern`): bool

过程化风格

function msgfmt_set_pattern(MessageFormatter `$formatter`, string `$pattern`): bool

Set the pattern used by the formatter

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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";
    ?>

示例 #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";
    ?>

以上示例会输出：

    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

### 参见

- msgfmt_create() - Constructs a new Message Formatter
- msgfmt_get_pattern() - Get the pattern used by the formatter

## 目录

- 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)

## 简介

## 类摘要

class IntlCalendar {
/* 常量 */
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;
/* 方法 */
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
}

## 预定义常量

`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).

## 更新日志

版本 | 说明
--- | ---
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

### 说明

面向对象风格

public function IntlCalendar::add(int `$field`, int `$value`): bool

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。
`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`.

### 返回值

Returns `true` on success 或者在失败时返回 `false`.

### 示例

示例 #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";

以上示例会输出：

    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

### 说明

面向对象风格

public function IntlCalendar::after(IntlCalendar `$other`): bool

过程化风格

function intlcal_after(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Returns whether this objectʼs time succeeds the argumentʼs time.

### 参数

`calendar`
  IntlCalendar 实例。
`other`

  The calendar whose time will be checked against the primary objectʼs time.

### 返回值

Returns `true` if this objectʼs current time is after that of the `calendar` argumentʼs time. Returns `false` otherwise.

On failure `false` is also returned. To detect error conditions use intl_get_error_code(), or set up Intl to throw exceptions.

### 示例

示例 #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

### 说明

面向对象风格

public function IntlCalendar::before(IntlCalendar `$other`): bool

过程化风格

function intlcal_before(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Returns whether this objectʼs time precedes the argumentʼs time.

### 参数

`calendar`
  IntlCalendar 实例。
`other`

  The calendar whose time will be checked against the primary objectʼs time.

### 返回值

Returns `true` if this objectʼs current time is before that of the `calendar` argumentʼs time. Returns `false` otherwise.

On failure `false` is also returned. To detect error conditions use intl_get_error_code(), or set up Intl to throw exceptions.

# IntlCalendar::clear

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::clear — Clear a field or all fields

### 说明

面向对象风格

public function IntlCalendar::clear(?int `$field` = `null`): true

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。
`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.2.0 | 现在返回类型为 `true`；之前是 bool。

### 示例

示例 #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";

以上示例会输出：

    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

### 说明

private function IntlCalendar::__construct()

A private constructor for disallowing instantiation with the new operator.

Call IntlCalendar::createInstance() instead.

### 参数

此函数没有参数。

# IntlCalendar::createInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::createInstance — Create a new IntlCalendar

### 说明

面向对象风格

public static function IntlCalendar::createInstance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar

过程化风格

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().

### 参数

`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.

### 返回值

The created IntlCalendar instance or `null` on failure.

### 示例

示例 #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));

以上示例会输出：

    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"

### 参见

- 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

### 说明

面向对象风格

public function IntlCalendar::equals(IntlCalendar `$other`): bool

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。
`other`

  The calendar to compare with the primary object.

### 返回值

Returns `true` if the current time of both this and the passed in IntlCalendar object are the same, or `false` otherwise.

On failure `false` is also returned. To detect error conditions use intl_get_error_code(), or set up Intl to throw exceptions.

### 示例

示例 #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

### 说明

面向对象风格

public function IntlCalendar::fieldDifference(float `$timestamp`, int `$field`): int|false

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。
`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`.

### 返回值

Returns a (signed) difference of time in the unit associated with the specified field 或者在失败时返回 `false`.

### 示例

示例 #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";

以上示例会输出：

    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

### 说明

面向对象风格

public static function IntlCalendar::fromDateTime(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar

过程化风格

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).

### 参数

`datetime`

  A DateTime object or a string that can be passed to DateTime::__construct().

### 返回值

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.

### 示例

示例 #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";

以上示例会输出：

    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

### 说明

面向对象风格

public function IntlCalendar::get(int `$field`): int|false

过程化风格

function intlcal_get(IntlCalendar `$calendar`, int `$field`): int|false

Gets the value for a specific field.

### 参数

`calendar`
  IntlCalendar 实例。
`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

### 返回值

An integer with the value of the time field.

### 示例

示例 #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";
    }

以上示例会输出：

    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

### 说明

面向对象风格

public function IntlCalendar::getActualMaximum(int `$field`): int|false

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。
`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

### 返回值

An int representing the maximum value in the units associated with the given `field` 或者在失败时返回 `false`.

### 示例

示例 #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

以上示例会输出：

    int(28)
    int(29)

### 参见

- 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

### 说明

面向对象风格

public function IntlCalendar::getActualMinimum(int `$field`): int|false

过程化风格

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().

### 参数

`calendar`
  IntlCalendar 实例。
`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

### 返回值

An int representing the minimum value in the fieldʼs unit 或者在失败时返回 `false`.

### 参见

- 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

### 说明

面向对象风格

public static function IntlCalendar::getAvailableLocales(): array

过程化风格

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.

### 参数

此函数没有参数。

### 返回值

An array of strings, one for each locale.

### 示例

示例 #1 IntlCalendar::getAvailableLocales()

    <?php
    print_r(IntlCalendar::getAvailableLocales());

以上示例会输出：

    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

### 说明

面向对象风格

public function IntlCalendar::getDayOfWeekType(int `$dayOfWeek`): int|false

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。
`dayOfWeek`

  One of the constants `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY`.

### 返回值

Returns one of the constants `IntlCalendar::DOW_TYPE_WEEKDAY`, `IntlCalendar::DOW_TYPE_WEEKEND`, `IntlCalendar::DOW_TYPE_WEEKEND_OFFSET` or `IntlCalendar::DOW_TYPE_WEEKEND_CEASE` 或者在失败时返回 `false`.

### 示例

示例 #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";
    }
    ?>

以上示例会输出：

    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

### 说明

面向对象风格 (method):

public function IntlCalendar::getErrorCode(): int|false

过程化风格:

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.

### 参数

`calendar`

  The calendar object, on the procedural style interface.

### 返回值

An ICU error code indicating either success, failure or a warning. Returns `false` on failure.

### 示例

示例 #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()
    );

以上示例会输出：

    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"

### 参见

- 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

### 说明

面向对象风格 (method):

public function IntlCalendar::getErrorMessage(): string|false

过程化风格:

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.

### 参数

`calendar`

  The calendar object, on the procedural style interface.

### 返回值

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.

### 示例

示例 #1 IntlCalendar::getErrorMessage()

    <?php
    $cal = IntlCalendar::createInstance('UTC', 'en_US');
    var_dump($cal->getErrorMessage());

    $cal->getWeekendTransition(IntlCalendar::DOW_WEDNESDAY);
    var_dump($cal->getErrorMessage());

以上示例会输出：

    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

### 说明

面向对象风格

public function IntlCalendar::getFirstDayOfWeek(): int|false

过程化风格

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().

### 参数

`calendar`
  IntlCalendar 实例。

### 返回值

One of the constants `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY` 或者在失败时返回 `false`.

### 示例

示例 #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

以上示例会输出：

    int(2)
    int(5)
    int(1)
    int(6)

### 参见

- 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

### 说明

面向对象风格

public function IntlCalendar::getGreatestMinimum(int `$field`): int|false

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。
`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

### 返回值

An int representing a field value, in the fieldʼs unit, 或者在失败时返回 `false`.

# IntlCalendar::getKeywordValuesForLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getKeywordValuesForLocale — Get set of locale keyword values

### 说明

面向对象风格

public static function IntlCalendar::getKeywordValuesForLocale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false

过程化风格

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.

### 参数

`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.

### 返回值

An iterator that yields strings with the locale keyword values 或者在失败时返回 `false`.

### 示例

示例 #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)));

以上示例会输出：

    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

### 说明

面向对象风格

public function IntlCalendar::getLeastMaximum(int `$field`): int|false

过程化风格

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().

### 参数

`calendar`
  IntlCalendar 实例。
`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

### 返回值

An int representing a field value in the fieldʼs unit 或者在失败时返回 `false`.

### 示例

示例 #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
    );

以上示例会输出：

    int(28)
    int(30)
    int(31)

### 参见

- 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

### 说明

面向对象风格

public function IntlCalendar::getLocale(int `$type`): string|false

过程化风格

function intlcal_get_locale(IntlCalendar `$calendar`, int `$type`): string|false

Returns the locale used by this calendar object.

### 参数

`calendar`
  IntlCalendar 实例。
`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.

### 返回值

A locale string 或者在失败时返回 `false`.

### 示例

示例 #1 IntlCalendar::getLocale()

    <?php
    $cal = IntlCalendar::createInstance(IntlTimeZone::getGMT(), 'en_US_CALIFORNIA');
    var_dump(
        $cal->getLocale(Locale::ACTUAL_LOCALE),
        $cal->getLocale(Locale::VALID_LOCALE)
    );

以上示例会输出：

    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

### 说明

面向对象风格

public function IntlCalendar::getMaximum(int `$field`): int|false

过程化风格

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().

### 参数

`calendar`
  IntlCalendar 实例。
`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

### 返回值

An int representing a field value in the fieldʼs unit 或者在失败时返回 `false`.

### 参见

- 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

### 说明

面向对象风格

public function IntlCalendar::getMinimalDaysInFirstWeek(): int|false

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。

### 返回值

An int representing a number of days 或者在失败时返回 `false`.

### 示例

示例 #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"));

以上示例会输出：

    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

### 说明

面向对象风格

public function IntlCalendar::getMinimum(int `$field`): int|false

过程化风格

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).

### 参数

`calendar`
  IntlCalendar 实例。
`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

### 返回值

An int representing a value for the given field in the fieldʼs unit 或者在失败时返回 `false`.

# IntlCalendar::getNow

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getNow — Get number representing the current time

### 说明

面向对象风格

public static function IntlCalendar::getNow(): float

过程化风格

function intlcal_get_now(): float

The number of milliseconds that have passed since the reference date. This number is derived from the system time.

### 参数

此函数没有参数。

### 返回值

A float representing a number of milliseconds since the epoch, not counting leap seconds.

### 示例

示例 #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";

以上示例会输出：

    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

### 说明

面向对象风格

public function IntlCalendar::getRepeatedWallTimeOption(): int

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。

### 返回值

One of the constants `IntlCalendar::WALLTIME_FIRST` or `IntlCalendar::WALLTIME_LAST`.

### 示例

示例 #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.));

以上示例会输出：

    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"

### 参见

- 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

### 说明

面向对象风格

public function IntlCalendar::getSkippedWallTimeOption(): int

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。

### 返回值

One of the constants `IntlCalendar::WALLTIME_FIRST`, `IntlCalendar::WALLTIME_LAST` or `IntlCalendar::WALLTIME_NEXT_VALID`.

### 示例

示例 #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));

以上示例会输出：

    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"

### 参见

- 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

### 说明

面向对象风格

public function IntlCalendar::getTime(): float|false

过程化风格

function intlcal_get_time(IntlCalendar `$calendar`): float|false

Returns the time associated with this object, expressed as the number of milliseconds since the epoch.

### 参数

`calendar`
  IntlCalendar 实例。

### 返回值

A float representing the number of milliseconds elapsed since the reference time (1 Jan 1970 00:00:00 UTC), 或者在失败时返回 `false`

### 示例

示例 #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

以上示例会输出：

    float(1367362800000)
    bool(true)

### 参见

- 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

### 说明

面向对象风格

public function IntlCalendar::getTimeZone(): IntlTimeZone|false

过程化风格

function intlcal_get_time_zone(IntlCalendar `$calendar`): IntlTimeZone|false

Returns the IntlTimeZone object associated with this calendar.

### 参数

`calendar`
  IntlCalendar 实例。

### 返回值

An IntlTimeZone object corresponding to the one used internally in this object. Returns `false` on failure.

### 示例

示例 #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());

以上示例会输出：

    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
    )

### 参见

- 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

### 说明

面向对象风格

public function IntlCalendar::getType(): string

过程化风格

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'`.

### 参数

`calendar`
  IntlCalendar 实例。

### 返回值

A string representing the calendar type, such as `'gregorian'`, `'islamic'`, etc.

### 示例

示例 #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());

以上示例会输出：

    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

### 说明

面向对象风格

public function IntlCalendar::getWeekendTransition(int `$dayOfWeek`): int|false

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。
`dayOfWeek`

  One of the constants `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY`.

### 返回值

The number of milliseconds into the day at which the weekend begins or ends 或者在失败时返回 `false`.

### 示例

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

### 说明

面向对象风格

public function IntlCalendar::inDaylightTime(): bool

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。

### 返回值

Returns `true` if the date is in Daylight Savings Time, `false` otherwise.

On failure `false` is also returned. To detect error conditions use intl_get_error_code(), or set up Intl to throw exceptions.

### 示例

示例 #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

### 说明

面向对象风格

public function IntlCalendar::isEquivalentTo(IntlCalendar `$other`): bool

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。
`other`

  The other calendar against which the comparison is to be made.

### 返回值

Assuming there are no argument errors, returns `true` if the calendars are equivalent except possibly for their set time.

### 示例

示例 #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)

以上示例会输出：

    bool(true)
    bool(false)
    int(2)
    int(1)

### 参见

- 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

### 说明

面向对象风格

public function IntlCalendar::isLenient(): bool

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。

### 返回值

A bool representing whether the calendar is set to lenient mode.

### 示例

示例 #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

以上示例会输出：

    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

### 说明

面向对象风格

public function IntlCalendar::isSet(int `$field`): bool

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。
`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

### 返回值

Assuming there are no argument errors, returns `true` if the field is set.

### 示例

See the example on IntlCalendar::clear().

### 参见

- 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

### 说明

面向对象风格

public function IntlCalendar::isWeekend(?float `$timestamp` = `null`): bool

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。
`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.

### 返回值

A bool indicating whether the given or this objectʼs time occurs in a weekend.

On failure `false` is also returned. To detect error conditions use intl_get_error_code(), or set up Intl to throw exceptions.

### 示例

示例 #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

### 参见

- 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

### 说明

面向对象风格

public function IntlCalendar::roll(int `$field`, int|bool `$value`): bool

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。
`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`).

### 返回值

Returns `true` on success or `false` on failure.

### 示例

示例 #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"

以上示例会输出：

    string(20) "01/07/2013, 00:00:00"
    string(20) "01/06/2013, 00:00:00"

### 参见

- 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

### 说明

面向对象风格

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

过程化风格

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.

### 参数

`cal`
  IntlCalendar 实例。
`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`.

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.2.0 | 现在返回类型为 `true`；之前是 bool。
8.4.0 | This had been deprecated in favor of the methods IntlCalendar::setDate() and IntlCalendar::setDateTime().

### 示例

示例 #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));

以上示例会输出：

    string(20) "01/07/2011, 00:00:00"
    string(20) "01/07/2012, 00:00:00"

### 参见

- 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

### 说明

public function IntlCalendar::setDate(int `$year`, int `$month`, int `$dayOfMonth`): void

Sets a date fields to the given value.

### 参数

`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`.

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

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.

### 参数

`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`.

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

面向对象风格

public function IntlCalendar::setFirstDayOfWeek(int `$dayOfWeek`): true

过程化风格

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`.

### 参数

`calendar`
  IntlCalendar 实例。
`dayOfWeek`

  One of the constants `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY`.

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.2.0 | 现在返回类型为 `true`；之前是 bool。

### 示例

示例 #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";

以上示例会输出：

    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

### 说明

面向对象风格

public function IntlCalendar::setLenient(bool `$lenient`): true

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。
`lenient`

  Use `true` to activate the lenient mode; `false` otherwise.

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.2.0 | 现在返回类型为 `true`；之前是 bool。

### 示例

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

### 说明

面向对象风格

public function IntlCalendar::setMinimalDaysInFirstWeek(int `$days`): true

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。
`days`

  The number of minimal days to set.

### 返回值

总是返回 `true`。

### 错误／异常

ValueError if `days` is out of range (less than `1` or more than `7`).

### 更新日志

版本 | 说明
--- | ---
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

### 说明

面向对象风格

public function IntlCalendar::setRepeatedWallTimeOption(int `$option`): true

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。
`option`

  One of the constants `IntlCalendar::WALLTIME_FIRST` or `IntlCalendar::WALLTIME_LAST`.

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.2.0 | 现在返回类型为 `true`；之前是 bool。

### 示例

See the example on IntlCalendar::getRepeatedWallTimeOption().

### 参见

- 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

### 说明

面向对象风格

public function IntlCalendar::setSkippedWallTimeOption(int `$option`): true

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。
`option`

  One of the constants `IntlCalendar::WALLTIME_FIRST`, `IntlCalendar::WALLTIME_LAST` or `IntlCalendar::WALLTIME_NEXT_VALID`.

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.2.0 | 现在返回类型为 `true`；之前是 bool。

### 示例

See the example on IntlCalendar::getSkippedWallTimeOption().

### 参见

- 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

### 说明

面向对象风格

public function IntlCalendar::setTime(float `$timestamp`): bool

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。
`timestamp`

  An instant represented by the number of number of milliseconds between such instant and the epoch, ignoring leap seconds.

### 返回值

Returns `true` on success and `false` on failure.

### 示例

示例 #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";

以上示例会输出：

    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

### 说明

面向对象风格

public function IntlCalendar::setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

过程化风格

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.

### 参数

`calendar`
  IntlCalendar 实例。
`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.

### 返回值

Returns `true` on success and `false` on failure.

### 示例

示例 #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";

以上示例会输出：

    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

### 说明

面向对象风格

public function IntlCalendar::toDateTime(): DateTime|false

过程化风格

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).

### 参数

`calendar`
  IntlCalendar 实例。

### 返回值

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.

### 示例

示例 #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);

以上示例会输出：

    DateTime Object
    (
        [date] => 2013-07-02 00:29:13
        [timezone_type] => 3
        [timezone] => Europe/Lisbon
    )

### 参见

- 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() - 返回新的 DateTime 对象

## 目录

- 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)

## 简介

## 类摘要

class IntlGregorianCalendar extends IntlCalendar {
/* 继承的常量 */
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;
/* 方法 */
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
/* 继承的方法 */
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

### 说明

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` = ?
)

警告

本函数还未编写文档，仅有参数列表。

### 参数

`tz`

`locale`

`timeZoneOrYear`

`localeOrMonth`

`dayOfMonth`

`hour`

`minute`

`second`

### 更新日志

版本 | 说明
--- | ---
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

### 说明

public static function IntlGregorianCalendar::createFromDate(int `$year`, int `$month`, int `$dayOfMonth`): static

Creates a new IntlGregorianCalendar instance from date.

### 参数

`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`.

### 返回值

Returns a new IntlGregorianCalendar instance.

### 示例

示例 #1 IntlGregorianCalendar::createFromDate() example

    <?php

    $intlCalendar = IntlGregorianCalendar::createFromDate(2023, 11, 23);
    var_dump($intlCalendar);
    ?>

以上示例的输出类似于：

    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)
      }
    }

### 参见

- 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

### 说明

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.

### 参数

`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`.

### 返回值

Returns a new IntlGregorianCalendar instance.

### 示例

示例 #1 IntlGregorianCalendar::createFromDateTime() example

    <?php

    $intlCalendar = IntlGregorianCalendar::createFromDateTime(2023, 11, 23, 12, 00);
    var_dump($intlCalendar);
    ?>

以上示例的输出类似于：

    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)
      }
    }

### 参见

- 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

### 说明

public function IntlGregorianCalendar::getGregorianChange(): float

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function IntlGregorianCalendar::isLeapYear(int `$year`): bool

警告

本函数还未编写文档，仅有参数列表。

### 参数

`year`

### 返回值

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

### 说明

public function IntlGregorianCalendar::setGregorianChange(float `$timestamp`): bool

警告

本函数还未编写文档，仅有参数列表。

### 参数

`timestamp`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

## 目录

- 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)

## 简介

## 类摘要

class IntlTimeZone {
/* 常量 */
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;
/* 方法 */
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
}

## 预定义常量

`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

## 更新日志

版本 | 说明
--- | ---
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

### 说明

private function IntlTimeZone::__construct()

### 参数

此函数没有参数。

# 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

### 说明

面向对象风格 (method):

public static function IntlTimeZone::countEquivalentIDs(string `$timezoneId`): int|false

过程化风格:

function intltz_count_equivalent_ids(string `$timezoneId`): int|false

警告

本函数还未编写文档，仅有参数列表。

### 参数

`timezoneId`

### 返回值

# 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

### 说明

面向对象风格 (method):

public static function IntlTimeZone::createDefault(): IntlTimeZone

过程化风格:

function intltz_create_default(): IntlTimeZone

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# 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

### 说明

面向对象风格 (method):

public static function IntlTimeZone::createEnumeration(string|int|null `$countryOrRawOffset` = `null`): IntlIterator|false

过程化风格:

function intltz_create_enumeration(string|int|null `$countryOrRawOffset` = `null`): IntlIterator|false

警告

本函数还未编写文档，仅有参数列表。

### 参数

`countryOrRawOffset`

### 返回值

# 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

### 说明

面向对象风格 (method):

public static function IntlTimeZone::createTimeZone(string `$timezoneId`): ?IntlTimeZone

过程化风格:

function intltz_create_time_zone(string `$timezoneId`): ?IntlTimeZone

警告

本函数还未编写文档，仅有参数列表。

### 参数

`timezoneId`

### 返回值

# 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

### 说明

面向对象风格 (method):

public static function IntlTimeZone::createTimeZoneIDEnumeration(int `$type`, ?string `$region` = `null`, ?int `$rawOffset` = `null`): IntlIterator|false

过程化风格:

function intltz_create_time_zone_id_enumeration(int `$type`, ?string `$region` = `null`, ?int `$rawOffset` = `null`): IntlIterator|false

警告

本函数还未编写文档，仅有参数列表。

### 参数

`type`

`region`

`rawOffset`

### 返回值

Returns IntlIterator 或者在失败时返回 `false`.

# 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

### 说明

面向对象风格 (method):

public static function IntlTimeZone::fromDateTimeZone(DateTimeZone `$timezone`): ?IntlTimeZone

过程化风格:

function intltz_from_date_time_zone(DateTimeZone `$timezone`): ?IntlTimeZone

警告

本函数还未编写文档，仅有参数列表。

### 参数

`timezone`

### 返回值

# 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

### 说明

面向对象风格 (method):

public static function IntlTimeZone::getCanonicalID(string `$timezoneId`, bool `&$isSystemId` = `null`): string|false

过程化风格:

function intltz_get_canonical_id(string `$timezoneId`, bool `&$isSystemId` = `null`): string|false

警告

本函数还未编写文档，仅有参数列表。

### 参数

`timezoneId`

`isSystemId`

### 返回值

# 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

### 说明

面向对象风格 (method):

public function IntlTimeZone::getDisplayName(bool `$dst` = `false`, int `$style` = `IntlTimeZone::DISPLAY_LONG`, ?string `$locale` = `null`): string|false

过程化风格:

function intltz_get_display_name(
IntlTimeZone `$timezone`,
bool `$dst` = `false`,
int `$style` = `IntlTimeZone::DISPLAY_LONG`,
?string `$locale` = `null`
): string|false

警告

本函数还未编写文档，仅有参数列表。

### 参数

`dst`

`style`

`locale`

### 返回值

# 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

### 说明

面向对象风格 (method):

public function IntlTimeZone::getDSTSavings(): int

过程化风格:

function intltz_get_dst_savings(IntlTimeZone `$timezone`): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# 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

### 说明

面向对象风格 (method):

public static function IntlTimeZone::getEquivalentID(string `$timezoneId`, int `$offset`): string|false

过程化风格:

function intltz_get_equivalent_id(string `$timezoneId`, int `$offset`): string|false

警告

本函数还未编写文档，仅有参数列表。

### 参数

`timezoneId`

`offset`

### 返回值

# 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

### 说明

面向对象风格 (method):

public function IntlTimeZone::getErrorCode(): int|false

过程化风格:

function intltz_get_error_code(IntlTimeZone `$timezone`): int|false

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# 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

### 说明

面向对象风格 (method):

public function IntlTimeZone::getErrorMessage(): string|false

过程化风格:

function intltz_get_error_message(IntlTimeZone `$timezone`): string|false

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# 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

### 说明

面向对象风格 (method):

public static function IntlTimeZone::getGMT(): IntlTimeZone

过程化风格:

function intltz_get_gmt(): IntlTimeZone

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# IntlTimeZone::getIanaID

# intltz_get_iana_id

(PHP 8 >= 8.4.0)

IntlTimeZone::getIanaID -- intltz_get_iana_id — Translate a timezone identifier to its IANA equivalent

### 说明

面向对象风格 (method):

public static function IntlTimeZone::getIanaID(string `$timezoneId`): string|false

过程化风格:

function intltz_get_iana_id(string `$timezoneId`): string|false

Translates a timezone identifier to its IANA equivalent. For example, `"GMT"` returns `"Etc/GMT"`, and `"US/Eastern"` returns `"America/New_York"`.

> 注意: This function requires ICU version >= 74.

### 参数

`timezoneId`
  The timezone identifier to translate.

### 返回值

Returns the IANA timezone identifier as a string, or `false` on failure.

### 参见

- 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

### 说明

面向对象风格 (method):

public function IntlTimeZone::getID(): string|false

过程化风格:

function intltz_get_id(IntlTimeZone `$timezone`): string|false

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# 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

### 说明

面向对象风格 (method):

public static function IntlTimeZone::getIDForWindowsID(string `$timezoneId`, ?string `$region` = `null`): string|false

过程化风格:

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").

> 注意: This function requires ICU version ≥ 52.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`timezoneId`

`region`

### 返回值

Returns the system timezone 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `region` is now nullable.

### 参见

- 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

### 说明

面向对象风格 (method):

public function IntlTimeZone::getOffset(
float `$timestamp`,
bool `$local`,
int `&$rawOffset`,
int `&$dstOffset`
): bool

过程化风格:

function intltz_get_offset(
IntlTimeZone `$timezone`,
float `$timestamp`,
bool `$local`,
int `&$rawOffset`,
int `&$dstOffset`
): bool

警告

本函数还未编写文档，仅有参数列表。

### 参数

`timestamp`

`local`

`rawOffset`

`dstOffset`

### 返回值

# 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

### 说明

面向对象风格 (method):

public function IntlTimeZone::getRawOffset(): int

过程化风格:

function intltz_get_raw_offset(IntlTimeZone `$timezone`): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# 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

### 说明

面向对象风格 (method):

public static function IntlTimeZone::getRegion(string `$timezoneId`): string|false

过程化风格:

function intltz_get_region(string `$timezoneId`): string|false

警告

本函数还未编写文档，仅有参数列表。

### 参数

`timezoneId`

### 返回值

Return region 或者在失败时返回 `false`.

# 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

### 说明

面向对象风格 (method):

public static function IntlTimeZone::getTZDataVersion(): string|false

过程化风格:

function intltz_get_tz_data_version(): string|false

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# IntlTimeZone::getUnknown

# intltz_get_unknown

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::getUnknown -- intltz_get_unknown — Get the "unknown" time zone

### 说明

面向对象风格 (method):

public static function IntlTimeZone::getUnknown(): IntlTimeZone

过程化风格:

function intltz_get_unknown(): IntlTimeZone

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

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

### 说明

面向对象风格 (method):

public static function IntlTimeZone::getWindowsID(string `$timezoneId`): string|false

过程化风格:

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").

> 注意: This function requires ICU version ≥ 52.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`timezoneId`

### 返回值

Returns the Windows timezone 或者在失败时返回 `false`.

### 参见

- 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

### 说明

面向对象风格 (method):

public function IntlTimeZone::hasSameRules(IntlTimeZone `$other`): bool

过程化风格:

function intltz_has_same_rules(IntlTimeZone `$timezone`, IntlTimeZone `$other`): bool

警告

本函数还未编写文档，仅有参数列表。

### 参数

`other`

### 返回值

# 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

### 说明

面向对象风格 (method):

public function IntlTimeZone::toDateTimeZone(): DateTimeZone|false

过程化风格:

function intltz_to_date_time_zone(IntlTimeZone `$timezone`): DateTimeZone|false

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# 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

### 说明

面向对象风格 (method):

public function IntlTimeZone::useDaylightTime(): bool

过程化风格:

function intltz_use_daylight_time(IntlTimeZone `$timezone`): bool

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

## 目录

- 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 — Translate a timezone identifier to its IANA equivalent
- 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)

## 简介

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 {
/* 常量 */
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;
/* 方法 */
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
}

## 更新日志

版本 | 说明
--- | ---
8.4.0 | Added `IntlDateFormatter::PATTERN`.

## 参见

- » ICU Date formatter

- » ICU Date formats

## 预定义常量

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

## 更新日志

版本 | 说明
--- | ---
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

### 说明

面向对象风格

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

面向对象风格 (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`
)

过程化风格

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.

### 参数

`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/.

### 返回值

The created IntlDateFormatter or `null` in case of failure.

### 错误／异常

A ValueError is thrown if `locale` is invalid.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | A ValueError is thrown if `locale` is invalid.
8.1.0 | Parameters `dateType` and `timeType` are now optional.

### 示例

示例 #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);
    ?>

示例 #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);
    ?>

示例 #3 Example of invalid locale handling

    <?php
    try {
        $fmt = new IntlDateFormatter(
            'invalid_locale',
            IntlDateFormatter::FULL,
            IntlDateFormatter::FULL,
            'dunno',
            IntlDateFormatter::GREGORIAN,
        );
    } catch (\Error $e) {
        // ...
    }
    ?>

以上示例会输出：

    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

### 参见

- 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

### 说明

面向对象风格

public function IntlDateFormatter::format(IntlCalendar|DateTimeInterface|array|string|int|float `$datetime`): string|false

过程化风格

function datefmt_format(IntlDateFormatter `$formatter`, IntlCalendar|DateTimeInterface|array|string|int|float `$datetime`): string|false

Formats the time value as a string.

### 参数

`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.

### 返回值

The formatted string or, if an error occurred, `false`.

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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);
    ?>

示例 #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);
    ?>

以上示例会输出：

    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

示例 #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";

以上示例会输出：

    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

### 参见

- 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

### 说明

面向对象风格

public static function IntlDateFormatter::formatObject(IntlCalendar|DateTimeInterface `$datetime`, array|int|string|null `$format` = `null`, ?string `$locale` = `null`): string|false

过程化风格

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.

### 参数

`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.

### 返回值

A string with result 或者在失败时返回 `false`.

### 示例

示例 #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";

以上示例会输出：

    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

### 说明

面向对象风格

public function IntlDateFormatter::getCalendar(): int|false

过程化风格

function datefmt_get_calendar(IntlDateFormatter `$formatter`): int|false

### 参数

`formatter`

  The formatter resource

### 返回值

The calendar type being used by the formatter. Either `IntlDateFormatter::TRADITIONAL` or `IntlDateFormatter::GREGORIAN`. Returns `false` on failure.

### 示例

示例 #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);
    ?>

示例 #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();

    ?>

示例 #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) {
        // ...
    }
    ?>

以上示例会输出：

    calendar of the formatter is : 1
    Now calendar of the formatter is : 0

### 参见

- 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

### 说明

面向对象风格

public function IntlDateFormatter::getDateType(): int|false

过程化风格

function datefmt_get_datetype(IntlDateFormatter `$formatter`): int|false

Returns date type used by the formatter.

### 参数

`formatter`

  The formatter resource.

### 返回值

The current date type value of the formatter, 或者在失败时返回 `false`.

### 示例

示例 #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);

    ?>

示例 #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);

    ?>

以上示例会输出：

    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

### 参见

- 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

### 说明

面向对象风格

public function IntlDateFormatter::getErrorCode(): int

过程化风格

function datefmt_get_error_code(IntlDateFormatter `$formatter`): int

Returns the error code from the last formatting operation.

### 参数

`formatter`

  The formatter resource.

### 返回值

The error code, one of UErrorCode values. Initial value is U_ZERO_ERROR.

### 示例

示例 #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)
    );
    ?>

示例 #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()
    );
    ?>

以上示例会输出：

    ERROR: U_ZERO_ERROR (0)

### 参见

- 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

### 说明

面向对象风格

public function IntlDateFormatter::getErrorMessage(): string

过程化风格

function datefmt_get_error_message(IntlDateFormatter `$formatter`): string

Get the error text from the last operation.

### 参数

`formatter`

  The formatter resource.

### 返回值

Description of the last error.

### 示例

示例 #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)
    );
    ?>

示例 #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()
    );
    ?>

以上示例会输出：

    ERROR: U_ZERO_ERROR (0)

### 参见

- 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

### 说明

面向对象风格

public function IntlDateFormatter::getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

过程化风格

function datefmt_get_locale(IntlDateFormatter `$formatter`, int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Get locale used by the formatter.

### 参数

`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.

### 返回值

The locale of this formatter, 或者在失败时返回 `false`.

### 示例

示例 #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);

    ?>

示例 #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);

    ?>

以上示例会输出：

    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

### 参见

- 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

### 说明

面向对象风格

public function IntlDateFormatter::getPattern(): string|false

过程化风格

function datefmt_get_pattern(IntlDateFormatter `$formatter`): string|false

Get pattern used by the formatter.

### 参数

`formatter`

  The formatter resource.

### 返回值

The pattern string being used to format/parse, 或者在失败时返回 `false`.

### 示例

示例 #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);

    ?>

示例 #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);
    ?>

以上示例会输出：

    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

### 参见

- 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

### 说明

面向对象风格

public function IntlDateFormatter::getTimeType(): int|false

过程化风格

function datefmt_get_timetype(IntlDateFormatter `$formatter`): int|false

Return time type used by the formatter.

### 参数

`formatter`

  The formatter resource.

### 返回值

The current date type value of the formatter, 或者在失败时返回 `false`.

### 示例

示例 #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);

    ?>

示例 #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);

    ?>

以上示例会输出：

    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

### 参见

- 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

### 说明

面向对象风格

public function IntlDateFormatter::getTimeZoneId(): string|false

过程化风格

function datefmt_get_timezone_id(IntlDateFormatter `$formatter`): string|false

Get the timezone-id used for the IntlDateFormatter.

### 参数

`formatter`

  The formatter resource.

### 返回值

ID string for the time zone used by this formatter, 或者在失败时返回 `false`.

### 示例

示例 #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);

    ?>

示例 #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();

    ?>

以上示例会输出：

    timezone_id of the formatter is: America/Los_Angeles
    Now timezone_id of the formatter is: Europe/Madrid

### 参见

- 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

### 说明

面向对象风格

public function IntlDateFormatter::getCalendarObject(): IntlCalendar|false|null

过程化风格

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.

### 参数

此函数没有参数。

### 返回值

A copy of the internal calendar object used by this formatter, or `null` if none has been set, 或者在失败时返回 `false`.

### 示例

示例 #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)
    );

以上示例会输出：

    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"

### 参见

- 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

### 说明

面向对象风格

public function IntlDateFormatter::getTimeZone(): IntlTimeZone|false

过程化风格

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.

### 参数

此函数没有参数。

### 返回值

The associated IntlTimeZone object 或者在失败时返回 `false`.

### 示例

示例 #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";

以上示例会输出：

    object(IntlTimeZone)#4 (4) {
      ["valid"]=>
      bool(true)
      ["id"]=>
      string(13) "Europe/Madrid"
      ["rawOffset"]=>
      int(3600000)
      ["currentOffset"]=>
      int(7200000)
    }
    Spain Time
    Europe/Lisbon
    Europe/Lisbon

### 参见

- 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

### 说明

面向对象风格

public function IntlDateFormatter::isLenient(): bool

过程化风格

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.

### 参数

`formatter`

  The formatter resource.

### 返回值

`true` if parser is lenient, `false` if parser is strict. By default the parser is lenient.

### 示例

示例 #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();
    }

    ?>

示例 #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();
    }

    ?>

以上示例会输出：

    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

### 参见

- 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

### 说明

面向对象风格

public function IntlDateFormatter::localtime(string `$string`, int `&$offset` = `null`): array|false

过程化风格

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.

### 参数

`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.

### 返回值

Localtime compatible array of integers : contains 24 hour clock value in tm_hour field, 或者在失败时返回 `false`.

### 示例

示例 #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 , ";
        }
    }

    ?>

示例 #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 , ";
        }
    }

    ?>

以上示例会输出：

    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 ,

### 参见

- 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

### 说明

面向对象风格

public function IntlDateFormatter::parse(string `$string`, int `&$offset` = `null`): int|float|false

过程化风格

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.

### 参数

`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.

### 返回值

Timestamp of parsed value, or `false` if value cannot be parsed.

### 示例

示例 #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
    );
    ?>

示例 #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');
    ?>

以上示例会输出：

    First parsed output is 630201600
    Second parsed output is 630201600

### 参见

- 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

### 说明

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`.

### 参数

`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.

### 返回值

Timestamp of parsed value, or `false` if value cannot be parsed.

### 示例

示例 #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');
    ?>

以上示例会输出：

    630201600

### 参见

- 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

### 说明

面向对象风格

public function IntlDateFormatter::setCalendar(IntlCalendar|int|null `$calendar`): bool

过程化风格

function datefmt_set_calendar(IntlDateFormatter `$formatter`, IntlCalendar|int|null `$calendar`): bool

Sets the calendar or calendar type used by the formatter.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
PECL intl 3.0.0 | It became possible to pass an IntlCalendar object.

### 示例

示例 #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);
    ?>

示例 #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();
    ?>

以上示例会输出：

    calendar of the formatter is : 1
    Now calendar of the formatter is : 0

示例 #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";

以上示例会输出：

    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

### 参见

- 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

### 说明

面向对象风格

public function IntlDateFormatter::setLenient(bool `$lenient`): void

过程化风格

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.

### 参数

`formatter`

  The formatter resource

`lenient`

  Sets whether the parser is lenient or not, default is `true` (lenient).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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();
    }

    ?>

示例 #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();
    }

    ?>

以上示例会输出：

    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

### 参见

- 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

### 说明

面向对象风格

public function IntlDateFormatter::setPattern(string `$pattern`): bool

过程化风格

function datefmt_set_pattern(IntlDateFormatter `$formatter`, string `$pattern`): bool

Set the pattern used for the IntlDateFormatter.

### 参数

`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/.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。 Bad formatstrings are usually the cause of the failure.

### 示例

示例 #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;
    ?>

示例 #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;
    ?>

以上示例会输出：

    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

### 参见

- 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

### 说明

面向对象风格

public function IntlDateFormatter::setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

过程化风格

function datefmt_set_timezone(IntlDateFormatter `$formatter`, IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Sets the timezone used for the IntlDateFormatter. object.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | This function now returns `true` on success; previously it returns `null`.

### 示例

示例 #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());

以上示例会输出：

    NULL
        Europe/Amsterdam
    IntlTimeZone
        Europe/Lisbon
    DateTimeZone
        Europe/Paris
    String
        Europe/Rome
    IntlTimeZone Object
    (
        [valid] => 1
        [id] => GMT+00:30
        [rawOffset] => 1800000
        [currentOffset] => 1800000
    )

### 参见

- IntlDateFormatter::getTimeZone() - Get formatterʼs timezone

## 目录

- 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)

## 简介

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.

## 类摘要

class ResourceBundle implements IteratorAggregate, Countable {
/* 方法 */
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
}

## 更新日志

版本 | 说明
--- | ---
8.0.0 | ResourceBundle implements IteratorAggregate now. Previously, Traversable was implemented instead.
7.4.0 | ResourceBundle implements Countable now.

## 参见

- » 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

### 说明

面向对象风格

public function ResourceBundle::count(): int

过程化风格

function resourcebundle_count(ResourceBundle `$bundle`): int

Get the number of elements in the bundle.

### 参数

`bundle`

  ResourceBundle object.

### 返回值

Returns number of elements in the bundle.

### 示例

示例 #1 resourcebundle_count() example

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo resourcebundle_count($r);
    ?>

示例 #2 OO example

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/myapp");
    echo $r->count();
    ?>

以上示例会输出：

    42

### 参见

- 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

### 说明

面向对象风格 (method)

public static function ResourceBundle::create(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`): ?ResourceBundle

过程化风格

function resourcebundle_create(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`): ?ResourceBundle

面向对象风格 (constructor):

public function ResourceBundle::__construct(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`)

Creates a resource bundle.

### 参数

`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.

### 返回值

Returns ResourceBundle object or `null` on error.

### 示例

示例 #1 resourcebundle_create() example

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo $r['teststring'];
    ?>

示例 #2 ResourceBundle::create() example

    <?php
    $r = ResourceBundle::create( 'es', "/usr/share/data/myapp");
    echo $r['teststring'];
    ?>

以上示例会输出：

    ¡Hola, mundo!

### 参见

- 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

### 说明

面向对象风格

public function ResourceBundle::get(string|int `$index`, bool `$fallback` = `true`): ResourceBundle|array|string|int|null

过程化风格

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.

### 参数

`bundle`

  ResourceBundle object.

`index`

  Data index, must be string or integer.

`fallback`

  Whether locale should match exactly or fallback to parent locale is allowed.

### 返回值

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.

### 错误／异常

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.

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #1 resourcebundle_get() example

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo resourcebundle_get($r, 'somestring');
    ?>

示例 #2 OO example

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/myapp");
    echo $r->get('somestring');
    ?>

以上示例会输出：

    ?Hola, mundo!

### 参见

- 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

### 说明

面向对象风格

public function ResourceBundle::getErrorCode(): int

过程化风格

function resourcebundle_get_error_code(ResourceBundle `$bundle`): int

Get error code from the last function performed by the bundle object.

### 参数

`bundle`

  ResourceBundle object.

### 返回值

Returns error code from last bundle object call.

### 示例

示例 #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");
    }
    ?>

示例 #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_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

### 说明

面向对象风格

public function ResourceBundle::getErrorMessage(): string

过程化风格

function resourcebundle_get_error_message(ResourceBundle `$bundle`): string

Get error message from the last function performed by the bundle object.

### 参数

`bundle`

  ResourceBundle object.

### 返回值

Returns error message from last bundle object's call.

### 示例

示例 #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));
    }
    ?>

示例 #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));
    }
    ?>

### 参见

- 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

### 说明

面向对象风格

public static function ResourceBundle::getLocales(string `$bundle`): array|false

过程化风格

function resourcebundle_locales(string `$bundle`): array|false

Get available locales from ResourceBundle name.

### 参数

`bundle`

  Path of ResourceBundle for which to get available locales, or empty string for default locales list.

### 返回值

Returns the list of locales supported by the bundle, or `false` on failure.

### 示例

示例 #1 resourcebundle_locales() example

    <?php
    $bundle = "/user/share/data/myapp";
    echo join(PHP_EOL, resourcebundle_locales($bundle));
    ?>

以上示例的输出类似于：

    es
    root

示例 #2 OO example

    <?php
    $bundle = "/usr/share/data/myapp";
    $r = new ResourceBundle( 'es', $bundle);
    echo join("\n", $r->getLocales($bundle));
    ?>

以上示例的输出类似于：

    es
    root

### 参见

- resourcebundle_get() - Get data from the bundle

## 目录

- 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)

## 简介

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.

## 类摘要

class Spoofchecker {
/* 常量 */
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;
/* 方法 */
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
}

## 预定义常量

`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

## 更新日志

版本 | 说明
--- | ---
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

### 说明

public function Spoofchecker::areConfusable(string `$string1`, string `$string2`, int `&$errorCode` = `null`): bool

Checks whether two given strings can easily be mistaken.

### 参数

`string1`

  First string to check.

`string2`

  Second string to check.

`errorCode`

  This variable is set by-reference to int containing an error, if there was any.

### 返回值

Returns `true` if two given strings can be confused, `false` otherwise.

### 示例

示例 #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

### 说明

public function Spoofchecker::__construct()

Creates new instance of Spoofchecker.

### 参数

此函数没有参数。

# 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

### 说明

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.

### 参数

`string`

  String to test.

`errorCode`

  This variable is set by-reference to int containing an error, if there was any.

### 返回值

Returns `true` if there are suspicious characters, `false` otherwise.

### 示例

示例 #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

### 说明

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.

### 参数

`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`.

### 返回值

No value is returned.

### 错误／异常

Throws a ValueError if `pattern` is not a valid character set pattern, or if `patternOptions` is not a valid combination of options.

### 示例

示例 #1 Spoofchecker::setAllowedChars() example

    <?php
    $checker = new Spoofchecker();
    $checker->setAllowedChars('[a-z0-9]');

    var_dump($checker->isSuspicious('hello'));
    var_dump($checker->isSuspicious('héllo'));
    ?>

以上示例会输出：

    bool(false)
    bool(true)

### 参见

- 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

### 说明

public function Spoofchecker::setAllowedLocales(string `$locales`): void

警告

本函数还未编写文档，仅有参数列表。

### 参数

`locales`

### 返回值

# Spoofchecker::setChecks

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::setChecks — Set the checks to run

### 说明

public function Spoofchecker::setChecks(int `$checks`): void

Sets the checks that will be performed by SpoofChecker::isSuspicious().

### 参数

`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.

### 返回值

没有返回值。

# Spoofchecker::setRestrictionLevel

(PHP 7 >= 7.3.0, PHP 8)

Spoofchecker::setRestrictionLevel — Set the restriction level

### 说明

public function Spoofchecker::setRestrictionLevel(int `$level`): void

Sets the restriction level of SpoofChecker::isSuspicious().

### 参数

`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`.

### 返回值

没有返回值。

## 目录

- 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)

## 简介

Transliterator provides transliteration of strings.

## 类摘要

class Transliterator {
/* 常量 */
public const int FORWARD;
public const int REVERSE;
/* 属性 */
public readonly string $id;
/* 方法 */
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
}

## 属性

id

## 预定义常量

`Transliterator::FORWARD` int

`Transliterator::REVERSE` int

## 更新日志

版本 | 说明
--- | ---
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

### 说明

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.

### 参数

此函数没有参数。

### 参见

- 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

### 说明

面向对象风格

public static function Transliterator::create(string `$id`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

过程化风格

function transliterator_create(string `$id`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Opens a Transliterator by ID.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`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.

### 返回值

Returns a Transliterator object on success, or `null` on failure.

### 参见

- 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

### 说明

面向对象风格

public static function Transliterator::createFromRules(string `$rules`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

过程化风格

function transliterator_create_from_rules(string `$rules`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Creates a Transliterator from rules.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`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.

### 返回值

Returns a Transliterator object on success, or `null` on failure.

### 参见

- 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

### 说明

面向对象风格

public function Transliterator::createInverse(): ?Transliterator

过程化风格

function transliterator_create_inverse(Transliterator `$transliterator`): ?Transliterator

Opens the inverse transliterator.

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

Returns a Transliterator object on success, or `null` on failure

### 参见

- 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

### 说明

面向对象风格

public function Transliterator::getErrorCode(): int

过程化风格

function transliterator_get_error_code(Transliterator `$transliterator`): int

Gets the last error code for this transliterator.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`transliterator`

### 返回值

The error code on success, or `false` if none exists, or on failure.

### 参见

- 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

### 说明

面向对象风格

public function Transliterator::getErrorMessage(): string

过程化风格

function transliterator_get_error_message(Transliterator `$transliterator`): string

Gets the last error message for this transliterator.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`transliterator`

### 返回值

The error message on success, or `false` if none exists, or on failure.

### 参见

- 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

### 说明

面向对象风格

public static function Transliterator::listIDs(): array|false

过程化风格

function transliterator_list_ids(): array|false

Returns an array with the registered transliterator IDs.

### 参数

此函数没有参数。

### 返回值

An array of registered transliterator IDs on success, 或者在失败时返回 `false`.

### 示例

示例 #1 Retrieving the registered transliterator IDs

    <?php
    print_r(Transliterator::listIDs());
    ?>

以上示例的输出类似于：

    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
    )

### 参见

- 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

### 说明

面向对象风格

public function Transliterator::transliterate(string `$string`, int `$start` = 0, int `$end` = -1): string|false

过程化风格

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.

### 参数

`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.

### 返回值

The transformed string on success, 或者在失败时返回 `false`.

### 示例

示例 #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";
    ?>

以上示例的输出类似于：

    お早うございます
    1
    \uD834\uDD1E
    𝄞

### 参见

- Transliterator::getErrorMessage() - Get last error message
- Transliterator::__construct() - Private constructor to deny instantiation

## 目录

- 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)

## 简介

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, …}`.

## 类摘要

class IntlBreakIterator implements IteratorAggregate {
/* 常量 */
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;
/* 方法 */
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
}

## 预定义常量

`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

## 更新日志

版本 | 说明
--- | ---
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

### 说明

private function IntlBreakIterator::__construct()

IntlBreakIterator instances should be created by using one of the static factory methods.

### 参数

此函数没有参数。

### 返回值

### 参见

- 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

### 说明

public static function IntlBreakIterator::createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator

警告

本函数还未编写文档，仅有参数列表。

### 参数

`locale`

### 返回值

# IntlBreakIterator::createCodePointInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createCodePointInstance — Create break iterator for boundaries of code points

### 说明

public static function IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# IntlBreakIterator::createLineInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createLineInstance — Create break iterator for logically possible line breaks

### 说明

public static function IntlBreakIterator::createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator

警告

本函数还未编写文档，仅有参数列表。

### 参数

`locale`

### 返回值

# IntlBreakIterator::createSentenceInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createSentenceInstance — Create break iterator for sentence breaks

### 说明

public static function IntlBreakIterator::createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator

警告

本函数还未编写文档，仅有参数列表。

### 参数

`locale`

### 返回值

# IntlBreakIterator::createTitleInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createTitleInstance — Create break iterator for title-casing breaks

### 说明

public static function IntlBreakIterator::createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator

警告

本函数还未编写文档，仅有参数列表。

### 参数

`locale`

### 返回值

# IntlBreakIterator::createWordInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createWordInstance — Create break iterator for word breaks

### 说明

public static function IntlBreakIterator::createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator

警告

本函数还未编写文档，仅有参数列表。

### 参数

`locale`

### 返回值

# IntlBreakIterator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::current — Get index of current position

### 说明

public function IntlBreakIterator::current(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# IntlBreakIterator::first

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::first — Set position to the first character in the text

### 说明

public function IntlBreakIterator::first(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# IntlBreakIterator::following

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::following — Advance the iterator to the first boundary following specified offset

### 说明

public function IntlBreakIterator::following(int `$offset`): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

`offset`

### 返回值

# 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

### 说明

面向对象风格 (method):

public function IntlBreakIterator::getErrorCode(): int

过程化风格:

function intl_get_error_code(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# 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

### 说明

面向对象风格 (method):

public function IntlBreakIterator::getErrorMessage(): string

过程化风格:

function intl_get_error_message(): string

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# IntlBreakIterator::getLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getLocale — Get the locale associated with the object

### 说明

public function IntlBreakIterator::getLocale(int `$type`): string|false

警告

本函数还未编写文档，仅有参数列表。

### 参数

`type`

### 返回值

# IntlBreakIterator::getPartsIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getPartsIterator — Create iterator for navigating fragments between boundaries

### 说明

public function IntlBreakIterator::getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator

警告

本函数还未编写文档，仅有参数列表。

### 参数

`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.

### 返回值

# IntlBreakIterator::getText

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getText — Get the text being scanned

### 说明

public function IntlBreakIterator::getText(): ?string

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# IntlBreakIterator::isBoundary

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::isBoundary — Tell whether an offset is a boundaryʼs offset

### 说明

public function IntlBreakIterator::isBoundary(int `$offset`): bool

警告

本函数还未编写文档，仅有参数列表。

### 参数

`offset`

### 返回值

# IntlBreakIterator::last

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::last — Set the iterator position to index beyond the last character

### 说明

public function IntlBreakIterator::last(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# IntlBreakIterator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::next — Advance the iterator the next boundary

### 说明

public function IntlBreakIterator::next(?int `$offset` = `null`): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

`offset`

### 返回值

# IntlBreakIterator::preceding

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::preceding — Set the iterator position to the first boundary before an offset

### 说明

public function IntlBreakIterator::preceding(int `$offset`): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

`offset`

### 返回值

# IntlBreakIterator::previous

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::previous — Set the iterator position to the boundary immediately before the current

### 说明

public function IntlBreakIterator::previous(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# IntlBreakIterator::setText

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::setText — Set the text being scanned

### 说明

public function IntlBreakIterator::setText(string `$text`): bool

警告

本函数还未编写文档，仅有参数列表。

### 参数

`text`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | This method now returns `false` on failure; previously it returns `null`.

## 目录

- 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)

## 简介

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.

## 类摘要

class IntlRuleBasedBreakIterator extends IntlBreakIterator {
/* 继承的常量 */
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;
/* 方法 */
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
/* 继承的方法 */
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

### 说明

public function IntlRuleBasedBreakIterator::__construct(string `$rules`, bool `$compiled` = `false`)

警告

本函数还未编写文档，仅有参数列表。

### 参数

`rules`

`compiled`

### 返回值

# IntlRuleBasedBreakIterator::getBinaryRules

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getBinaryRules — Get the binary form of compiled rules

### 说明

public function IntlRuleBasedBreakIterator::getBinaryRules(): string|false

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# IntlRuleBasedBreakIterator::getRules

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRules — Get the rule set used to create this object

### 说明

public function IntlRuleBasedBreakIterator::getRules(): string|false

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# 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

### 说明

public function IntlRuleBasedBreakIterator::getRuleStatus(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# 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

### 说明

public function IntlRuleBasedBreakIterator::getRuleStatusVec(): array|false

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

## 目录

- 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)

## 简介

This break iterator identifies the boundaries between UTF-8 code points.

## 类摘要

class IntlCodePointBreakIterator extends IntlBreakIterator {
/* 继承的常量 */
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;
/* 方法 */
public function getLastCodePoint(): int
/* 继承的方法 */
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

### 说明

public function IntlCodePointBreakIterator::getLastCodePoint(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

## 目录

- IntlCodePointBreakIterator::getLastCodePoint — Get last code point passed over after advancing or receding the iterator

# The IntlDatePatternGenerator class

(PHP 8 >= 8.1.0)

## 简介

Generates localized date and/or time format pattern strings suitable for use in IntlDateFormatter.

## 类摘要

class IntlDatePatternGenerator {
/* 方法 */
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

### 说明

public static function IntlDatePatternGenerator::create(?string `$locale` = `null`): ?IntlDatePatternGenerator
public function IntlDatePatternGenerator::__construct(?string `$locale` = `null`)

Creates a new IntlDatePatternGenerator instance.

### 参数

`locale`

  The locale. If `null` is passed, uses the ini setting intl.default_locale.

### 返回值

Returns an IntlDatePatternGenerator instance on success, or `null` on failure.

# IntlDatePatternGenerator::getBestPattern

(PHP 8 >= 8.1.0)

IntlDatePatternGenerator::getBestPattern — Determines the most suitable date/time format

### 说明

public function IntlDatePatternGenerator::getBestPattern(string `$skeleton`): string|false

Determines which date/time format is most suitable for a particular locale.

### 参数

`skeleton`

  The skeleton.

### 返回值

Returns an ICU date/time pattern accepted by IntlDateFormatter on success, 或者在失败时返回 `false`.

### 示例

示例 #1 IntlDatePatternGenerator::getBestPattern() example

    <?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');
    ?>

以上示例会输出：

    de: 24.04.2021
    en: 04/24/2021

## 目录

- IntlDatePatternGenerator::create — Creates a new IntlDatePatternGenerator instance
- IntlDatePatternGenerator::getBestPattern — Determines the most suitable date/time format

# The IntlPartsIterator class

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## 简介

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().

## 类摘要

class IntlPartsIterator extends IntlIterator {
/* 常量 */
public const int KEY_SEQUENTIAL;
public const int KEY_LEFT;
public const int KEY_RIGHT;
/* 方法 */
public function getBreakIterator(): IntlBreakIterator
/* 继承的方法 */
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
}

## 预定义常量

`IntlPartsIterator::KEY_SEQUENTIAL` int

`IntlPartsIterator::KEY_LEFT` int

`IntlPartsIterator::KEY_RIGHT` int

## 更新日志

版本 | 说明
--- | ---
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

### 说明

public function IntlPartsIterator::getBreakIterator(): IntlBreakIterator

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

## 目录

- IntlPartsIterator::getBreakIterator — Get IntlBreakIterator backing this parts iterator

# The UConverter class

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

## 简介

## 类摘要

class UConverter {
/* 常量 */
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;
/* 方法 */
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
}

## 预定义常量

`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

## 更新日志

版本 | 说明
--- | ---
8.4.0 | The class constants are now typed.

# UConverter::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::__construct — Create UConverter object

### 说明

public function UConverter::__construct(?string `$destination_encoding` = `null`, ?string `$source_encoding` = `null`)

警告

本函数还未编写文档，仅有参数列表。

### 参数

`destination_encoding`

`source_encoding`

### 返回值

# UConverter::convert

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::convert — Convert string from one charset to another

### 说明

public function UConverter::convert(string `$str`, bool `$reverse` = `false`): string|false

警告

本函数还未编写文档，仅有参数列表。

### 参数

`str`

`reverse`

### 返回值

# UConverter::fromUCallback

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::fromUCallback — Default "from" callback function

### 说明

public function UConverter::fromUCallback(
int `$reason`,
array `$source`,
int `$codePoint`,
int `&$error`
): string|int|array|null

警告

本函数还未编写文档，仅有参数列表。

### 参数

`reason`

`source`

`codePoint`

`error`

### 返回值

# UConverter::getAliases

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getAliases — Get the aliases of the given name

### 说明

public static function UConverter::getAliases(string `$name`): array|false|null

警告

本函数还未编写文档，仅有参数列表。

### 参数

`name`

### 返回值

# UConverter::getAvailable

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getAvailable — Get the available canonical converter names

### 说明

public static function UConverter::getAvailable(): array

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# UConverter::getDestinationEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getDestinationEncoding — Get the destination encoding

### 说明

public function UConverter::getDestinationEncoding(): string|false|null

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# UConverter::getDestinationType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getDestinationType — Get the destination converter type

### 说明

public function UConverter::getDestinationType(): int|false|null

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# 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

### 说明

public function UConverter::getErrorCode(): int

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# UConverter::getErrorMessage

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getErrorMessage — Get last error message on the object

### 说明

public function UConverter::getErrorMessage(): ?string

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# UConverter::getSourceEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSourceEncoding — Get the source encoding

### 说明

public function UConverter::getSourceEncoding(): string|false|null

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# UConverter::getSourceType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSourceType — Get the source converter type

### 说明

public function UConverter::getSourceType(): int|false|null

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# UConverter::getStandards

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getStandards — Get standards associated to converter names

### 说明

public static function UConverter::getStandards(): ?array

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# UConverter::getSubstChars

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSubstChars — Get substitution chars

### 说明

public function UConverter::getSubstChars(): string|false|null

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# UConverter::reasonText

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::reasonText — Get string representation of the callback reason

### 说明

public static function UConverter::reasonText(int `$reason`): string

警告

本函数还未编写文档，仅有参数列表。

### 参数

`reason`

### 返回值

# UConverter::setDestinationEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setDestinationEncoding — Set the destination encoding

### 说明

public function UConverter::setDestinationEncoding(string `$encoding`): bool

警告

本函数还未编写文档，仅有参数列表。

### 参数

`encoding`

### 返回值

# UConverter::setSourceEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setSourceEncoding — Set the source encoding

### 说明

public function UConverter::setSourceEncoding(string `$encoding`): bool

警告

本函数还未编写文档，仅有参数列表。

### 参数

`encoding`

### 返回值

# UConverter::setSubstChars

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setSubstChars — Set the substitution chars

### 说明

public function UConverter::setSubstChars(string `$chars`): bool

警告

本函数还未编写文档，仅有参数列表。

### 参数

`chars`

### 返回值

# UConverter::toUCallback

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::toUCallback — Default "to" callback function

### 说明

public function UConverter::toUCallback(
int `$reason`,
string `$source`,
string `$codeUnits`,
int `&$error`
): string|int|array|null

警告

本函数还未编写文档，仅有参数列表。

### 参数

`reason`

`source`

`codeUnits`

`error`

### 返回值

# 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

### 说明

public static function UConverter::transcode(
string `$str`,
string `$toEncoding`,
string `$fromEncoding`,
?array `$options` = `null`
): string|false

Converts `str` from `fromEncoding` to `toEncoding`.

### 参数

`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.

### 返回值

Returns the converted string 或者在失败时返回 `false`.

### 示例

示例 #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";
    ?>

以上示例会输出：

    005a006f00eb
    5a6fc3ab

示例 #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";
    ?>

以上示例会输出：

    fffd

示例 #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";
    ?>

以上示例会输出：

    1a
    3f
    3f

### 参见

- mb_convert_encoding() - 转换字符串，从一个字符编码到另一个字符编码
- iconv() - 将字符串从一个字符编码转换到另一个字符编码

## 目录

- 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 函数

# 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

### 说明

过程化风格

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.

### 参数

`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.

### 返回值

A string starting at offset `offset` and ending on a default grapheme cluster boundary that conforms to the `size` and `type` specified, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
7.1.0 | Support for negative `offset`s has been added.

### 示例

示例 #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));

    ?>

以上示例会输出：

    o%CC%88

### 参见

- 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

### 说明

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).

### 参数

`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.

### 返回值

grapheme_str_split() returns an array of strings, 或者在失败时返回 `false`.

### 错误／异常

If `length` is less than `1`, a ValueError will be thrown.

### 参见

- str_split() - 将字符串转换为数组
- mb_str_split() - 指定多字节字符串，返回其字符数组
- » 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

### 说明

过程化风格

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

### 参数

`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`
  要使用的区域设置。

### 返回值

Returns the position as an integer. If `needle` is not found, grapheme_stripos() will return `false`.

### 更新日志

版本 | 说明
--- | ---
8.5.0 | 已新增可选参数 `locale`。
7.1.0 | Support for negative `offset`s has been added.

### 示例

示例 #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);

    ?>

以上示例会输出：

    2

### 参见

- 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

### 说明

过程化风格

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`.

### 参数

`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`
  要使用的区域设置。

### 返回值

Returns the portion of `haystack`, or `false` if `needle` is not found.

### 更新日志

版本 | 说明
--- | ---
8.5.0 | 已新增可选参数 `locale`。

### 示例

示例 #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));

    ?>

以上示例会输出：

    o%CC%88a%CC%8A

### 参见

- 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

### 说明

过程化风格

function grapheme_strlen(string `$string`): int|false|null

Get string length in grapheme units (not bytes or characters)

### 参数

`string`

  The string being measured for length. It must be a valid UTF-8 string.

### 返回值

The length of the string on success, `null` or `false` on failure.

### 示例

示例 #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);

    ?>

以上示例会输出：

    6

### 参见

- » Unicode Text Segmentation: Grapheme Cluster Boundaries
- iconv_strlen() - 返回字符串的字符数统计
- mb_strlen() - 获取字符串的长度
- strlen() - 获取字符串长度

# 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

### 说明

过程化风格

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

### 参数

`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`
  要使用的区域设置。

### 返回值

Returns the position as an integer. If `needle` is not found, grapheme_strpos() will return `false`.

### 更新日志

版本 | 说明
--- | ---
8.5.0 | 已新增可选参数 `locale`。
7.1.0 | Support for negative `offset`s has been added.

### 示例

示例 #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);

    ?>

以上示例会输出：

    2

### 参见

- 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

### 说明

过程化风格

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

### 参数

`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`
  要使用的区域设置。

### 返回值

Returns the position as an integer. If `needle` is not found, grapheme_strripos() will return `false`.

### 更新日志

版本 | 说明
--- | ---
8.5.0 | 已新增可选参数 `locale`。

### 示例

示例 #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);

    ?>

以上示例会输出：

    2

### 参见

- 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

### 说明

过程化风格

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

### 参数

`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`
  要使用的区域设置。

### 返回值

Returns the position as an integer. If `needle` is not found, grapheme_strrpos() will return `false`.

### 更新日志

版本 | 说明
--- | ---
8.5.0 | 已新增可选参数 `locale`。

### 示例

示例 #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);
    ?>

以上示例会输出：

    2

### 参见

- 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

### 说明

过程化风格

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).

### 参数

`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`
  要使用的区域设置。

### 返回值

Returns the portion of `haystack`, or `false` if `needle` is not found.

### 更新日志

版本 | 说明
--- | ---
8.5.0 | 已新增可选参数 `locale`。

### 示例

示例 #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));

    ?>

以上示例会输出：

    o%CC%88a%CC%8A

### 参见

- 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

### 说明

过程化风格

function grapheme_substr(
string `$string`,
int `$offset`,
?int `$length` = `null`,
string `$locale` = ""
): string|false

Return part of a string

### 参数

`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`
  要使用的区域设置。

### 返回值

Returns the extracted part of `string`, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.5.0 | 已新增可选参数 `locale`。
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.

### 示例

示例 #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 ));
    ?>

以上示例会输出：

    a%CC%8Abco%CC%88

### 参见

- 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

## 目录

- 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 函数

# idn_to_ascii

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.2, PECL idn >= 0.1)

idn_to_ascii — 将域名转换为 IDNA ASCII 格式

### 说明

过程化风格

function idn_to_ascii(
string `$domain`,
int `$flags` = `IDNA_DEFAULT`,
int `$variant` = `INTL_IDNA_VARIANT_UTS46`,
array `&$idna_info` = `null`
): string|false

该函数可以将 Unicode 域名转换为 IDNA ASCII 兼容格式，并转为小写。

### 参数

`domain`

  要转换的域，必须使用 UTF-8 编码。

`flags`

  转换选项 — IDNA_* 开头的常量（除 IDNA_ERROR_* 开头的常量）。

`variant`

  对于 IDNA 2003 是 `INTL_IDNA_VARIANT_2003` (自 PHP 7.2.0 起已弃用)， 对于 UTS #46 是 `INTL_IDNA_VARIANT_UTS46` (仅 ICU 4.6 起可用)。

`idna_info`

  仅当 `INTL_IDNA_VARIANT_UTS46` 用于 `variant` 时，才可以使用该参数。 在这种情况下，它将用这些键组成的数组来填充： `'result'` 键，转换结果（有可能是一个非法结果）； `'isTransitionalDifferent'` 键，布尔值，指示使用 UTS #46 的过滤机制是否会改变结果； `'errors'` 键，是 IDNA_ERROR_* 常量集里一个常量对应的 int 。

### 返回值

IDNA ASCII 兼容格式编码的域名， 或者在失败时返回 `false`

### 更新日志

版本 | 说明
--- | ---
7.4.0 | 现在 `variant` 的默认值为 `INTL_IDNA_VARIANT_UTS46` ， 而不是已弃用的 `INTL_IDNA_VARIANT_2003` 。
7.2.0 | `INTL_IDNA_VARIANT_2003` 已被弃用； 可以使用 `INTL_IDNA_VARIANT_UTS46` 代替。

### 示例

示例 #1 idn_to_ascii() 示例

    <?php

    echo idn_to_ascii('täst.de');

    ?>

以上示例会输出：

    xn--tst-qla.de

示例 #2 所有 ASCII 域名仅会转换为小写形式

    <?php

    var_dump(idn_to_ascii('Example.com'));

    ?>

以上示例会输出：

    string(11) "example.com"

### 参见

- idn_to_utf8() - 将域名从 IDNA ASCII 转换为 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 — 将域名从 IDNA ASCII 转换为 Unicode

### 说明

过程化风格

function idn_to_utf8(
string `$domain`,
int `$flags` = `IDNA_DEFAULT`,
int `$variant` = `INTL_IDNA_VARIANT_UTS46`,
array `&$idna_info` = `null`
): string|false

该函数将 Unicode 域名从 IDNA ASCII 兼容格式转换为 纯 Unicode（UTF-8 编码）。

### 参数

`domain`

  要转换的 IDNA ASCII 兼容格式的域名。

`flags`

  转换选项 — IDNA_* 开头的常量（除 IDNA_ERROR_* 开头的常量）。

`variant`

  对于 IDNA 2003 是 `INTL_IDNA_VARIANT_2003` (自 PHP 7.2.0 起已弃用)， 对于 UTS #46 是 `INTL_IDNA_VARIANT_UTS46` (仅 ICU 4.6 起可用)。

`idna_info`

  仅当 `INTL_IDNA_VARIANT_UTS46` 用于 `variant` 时，才可以使用该参数。 在这种情况下，它将用这些键组成的数组来填充： `'result'` 键，转换结果（有可能是一个非法结果）； `'isTransitionalDifferent'` 键，布尔值，指示使用 UTS #46 的过滤机制是否会改变结果； `'errors'` 键，是 IDNA_ERROR_* 常量集里一个常量对应的 int 。

### 返回值

UTF-8 编码的 Unicode 域名， 或者在失败时返回 `false`

### 更新日志

版本 | 说明
--- | ---
7.4.0 | 现在 `variant` 的默认值为 `INTL_IDNA_VARIANT_UTS46` ， 而不是已弃用的 `INTL_IDNA_VARIANT_2003` 。
7.2.0 | `INTL_IDNA_VARIANT_2003` 已被弃用； 可以使用 `INTL_IDNA_VARIANT_UTS46` 代替。

### 示例

示例 #1 idn_to_utf8() 示例

    <?php

    echo idn_to_utf8('xn--tst-qla.de');

    ?>

以上示例会输出：

    täst.de

### 参见

- idn_to_ascii() - 将域名转换为 IDNA ASCII 格式

## 目录

- idn_to_ascii — 将域名转换为 IDNA ASCII 格式
- idn_to_utf8 — 将域名从 IDNA ASCII 转换为 Unicode

# IntlChar

(PHP 7, PHP 8)

## 简介

IntlChar provides access to a number of utility methods that can be used to access information about Unicode characters.

The methods and constants adhere closely to the names and behavior used by the underlying ICU library.

## 类摘要

class IntlChar {
/* 常量 */
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_IDS_UNARY_OPERATOR;
public const int PROPERTY_ID_COMPAT_MATH_START;
public const int PROPERTY_ID_COMPAT_MATH_CONTINUE;
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;
/* 方法 */
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
}

## 预定义常量

`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_IDS_UNARY_OPERATOR` int
  For programmatic determination of Ideographic Description Sequences. Available as of PHP 8.4.0.
`IntlChar::PROPERTY_ID_COMPAT_MATH_START` int
  Used in mathematical identifier profile in UAX 31. Available as of PHP 8.4.0.
`IntlChar::PROPERTY_ID_COMPAT_MATH_CONTINUE` int
  Used in mathematical identifier profile in UAX 31. Available as of PHP 8.4.0.
`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

## 更新日志

版本 | 说明
--- | ---
8.4.0 | Added `IntlChar::PROPERTY_IDS_UNARY_OPERATOR`, `IntlChar::PROPERTY_ID_COMPAT_MATH_START`, `IntlChar::PROPERTY_ID_COMPAT_MATH_CONTINUE`.
8.4.0 | The class constants are now typed.
7.0.6 | The `IntlChar::NO_NUMERIC_VALUE` constant was added.

# IntlChar::charAge

(PHP 7, PHP 8)

IntlChar::charAge — Get the "age" of the code point

### 说明

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.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

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.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::charage("\u{2603}"));
    var_dump(IntlChar::charage("\u{1F576}"));
    ?>

以上示例会输出：

    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)
    }

### 参见

- 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

### 说明

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.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

The decimal digit value of `codepoint`, or `-1` if it is not a decimal digit character. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::charDigitValue("1"));
    var_dump(IntlChar::charDigitValue("\u{0662}"));
    var_dump(IntlChar::charDigitValue("\u{0E53}"));
    ?>

以上示例会输出：

    int(1)
    int(2)
    int(3)

### 参见

- 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

### 说明

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).

> 注意:

> Some unassigned code points have bidi values of R or AL because they are in blocks that are reserved for Right-To-Left scripts.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

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.

### 示例

示例 #1 Testing different code points

    <?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);
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`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`

### 返回值

The Unicode value of the code point with the given name (as an int), or `null` if there is no such code point.

### 示例

示例 #1 Testing different code points

    <?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"));
    ?>

以上示例会输出：

    int(65)
    int(9731)
    int(9843)
    NULL

### 参见

- 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

### 说明

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.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

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.

返回类型是 int，如果代码点作为 UTF-8 string 传递，则会返回 string 。失败时返回 `null`。

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::charMirror("A"));
    var_dump(IntlChar::charMirror("<"));
    var_dump(IntlChar::charMirror("("));
    ?>

以上示例会输出：

    string(1) "A"
    string(1) ">"
    string(2) ")"

### 参见

- 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

### 说明

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.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\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`

### 返回值

The corresponding name, or an empty string if there is no name for this character, or `null` if there is no such code point.

### 示例

示例 #1 Testing different code points

    <?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}"));
    ?>

以上示例会输出：

    string(9) "FULL STOP"
    string(9) "FULL STOP"
    string(7) "SNOWMAN"
    string(0) ""

### 参见

- 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

### 说明

public static function IntlChar::charType(int|string `$codepoint`): ?int

Returns the general category value for the code point.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

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`

### 示例

示例 #1 Testing different code points

    <?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);
    ?>

以上示例会输出：

    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

### 说明

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().

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

A string containing the single character specified by the Unicode code point value, or `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    $values = ["A", 63, 123, 9731];
    foreach ($values as $value) {
        var_dump(IntlChar::chr($value));
    }
    ?>

以上示例会输出：

    string(1) "A"
    string(1) "?"
    string(1) "{"
    string(3) "☃"

### 参见

- IntlChar::ord() - Return Unicode code point value of character
- mb_chr() - 按 Unicode 码位值返回字符
- chr() - 从数字生成单字节字符串

# IntlChar::digit

(PHP 7, PHP 8)

IntlChar::digit — Get the decimal digit value of a code point for a given radix

### 说明

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.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)
`base`

  The radix (defaults to `10`).

### 返回值

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.

警告

此函数可能返回布尔值 `false`，但也可能返回等同于 `false` 的非布尔值。请阅读 布尔类型章节以获取更多信息。应使用 === 运算符来测试此函数的返回值。

### 示例

示例 #1 Testing different code points

    <?php

    var_dump(IntlChar::digit("0"));
    var_dump(IntlChar::digit("3"));

    var_dump(IntlChar::digit("A", 16));
    var_dump(IntlChar::digit("A"));

    ?>

以上示例会输出：

    int(0)
    int(3)
    int(10)
    bool(false)

### 参见

- 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

### 说明

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.

### 参数

`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`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | This method now returns `false` on failure; previously it returns `null`.

### 示例

示例 #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);
    });
    ?>

以上示例会输出：

    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

### 参见

- 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

### 说明

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.

### 参数

`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)

### 返回值

没有返回值。

### 示例

示例 #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);
    });
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)
`options`

  Either `IntlChar::FOLD_CASE_DEFAULT` (default) or `IntlChar::FOLD_CASE_EXCLUDE_SPECIAL_I`.

### 返回值

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

### 说明

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.

### 参数

`digit`

  The number to convert to a character.

`base`

  The radix (defaults to `10`).

### 返回值

The character representation (as a int) of the specified digit in the specified radix.

### 示例

示例 #1 Testing different code points

    <?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));
    ?>

以上示例会输出：

    int(48)
    int(51)
    int(51)
    int(0)
    int(97)

### 参见

- 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

### 说明

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.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns the paired bracket code point, or `codepoint` itself if there is no such mapping. Returns `null` on failure.

返回类型是 int，如果代码点作为 UTF-8 string 传递，则会返回 string 。失败时返回 `null`。

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::getBidiPairedBracket(91));
    var_dump(IntlChar::getBidiPairedBracket('['));
    ?>

以上示例会输出：

    int(93)
    string(1) "]"

### 注释

> 注意:

> This method is available as of ICU version 52.

### 参见

- 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

### 说明

public static function IntlChar::getBlockCode(int|string `$codepoint`): ?int

Returns the Unicode allocation block that contains the character.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns the block value for `codepoint`. See the `IntlChar::BLOCK_CODE_*` constants for possible return values. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?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);
    ?>

以上示例会输出：

    bool(true)
    bool(true)
    bool(true)

# IntlChar::getCombiningClass

(PHP 7, PHP 8)

IntlChar::getCombiningClass — Get the combining class of a code point

### 说明

public static function IntlChar::getCombiningClass(int|string `$codepoint`): ?int

Returns the combining class of the code point.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns the combining class of the character. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::getCombiningClass("A"));
    var_dump(IntlChar::getCombiningClass("\u{0334}"));
    var_dump(IntlChar::getCombiningClass("\u{0358}"));
    ?>

以上示例会输出：

    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

### 说明

public static function IntlChar::getFC_NFKC_Closure(int|string `$codepoint`): string|false|null

Gets the FC_NFKC_Closure property string for a character.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns the FC_NFKC_Closure property string for the `codepoint`, or an empty string if there is none. Returns `null` or `false` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::getFC_NFKC_Closure("\u{2121}"));
    var_dump(IntlChar::getFC_NFKC_Closure("\u{1D2D}"));
    ?>

以上示例会输出：

    string(3) "tel"
    string(2) "æ"

# IntlChar::getIntPropertyMaxValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyMaxValue — Get the max value for a Unicode property

### 说明

public static function IntlChar::getIntPropertyMaxValue(int `$property`): int

Gets the maximum value for an enumerated/integer/binary Unicode property.

### 参数

`property`
  The Unicode property to lookup (see the `IntlChar::PROPERTY_*` constants).

### 返回值

The maximum value returned by IntlChar::getIntPropertyValue() for a Unicode property. `<=0` if the property selector is out of range.

### 示例

示例 #1 Testing different properties

    <?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
    ?>

以上示例会输出：

    int(22)
    int(166)
    int(1)
    int(-1)

### 参见

- 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

### 说明

public static function IntlChar::getIntPropertyMinValue(int `$property`): int

Gets the minimum value for an enumerated/integer/binary Unicode property.

### 参数

`property`
  The Unicode property to lookup (see the `IntlChar::PROPERTY_*` constants).

### 返回值

The minimum value returned by IntlChar::getIntPropertyValue() for a Unicode property. `0` if the property selector is out of range.

### 示例

示例 #1 Testing different properties

    <?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
    ?>

以上示例会输出：

    int(0)
    int(0)
    int(0)
    int(0)

### 参见

- 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

### 说明

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.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)
`property`
  The Unicode property to lookup (see the `IntlChar::PROPERTY_*` constants).

### 返回值

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.

### 示例

示例 #1 Testing different properties

    <?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);
    ?>

以上示例会输出：

    bool(true)
    bool(true)
    bool(true)

### 参见

- 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

### 说明

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`.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

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.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::getNumericValue("4"));
    var_dump(IntlChar::getNumericValue("x"));
    var_dump(IntlChar::getNumericValue("\u{216C}"));
    ?>

以上示例会输出：

    float(4)
    float(-123456789)
    float(50)

# IntlChar::getPropertyEnum

(PHP 7, PHP 8)

IntlChar::getPropertyEnum — Get the property constant value for a given property name

### 说明

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().

### 参数

`alias`

  The property name to be matched. The name is compared using "loose matching" as described in PropertyAliases.txt.

### 返回值

Returns an `IntlChar::PROPERTY_` constant value, or `IntlChar::PROPERTY_INVALID_CODE` if the given name does not match any property.

### 示例

示例 #1 Testing different properties

    <?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);
    ?>

以上示例会输出：

    bool(true)
    bool(true)
    bool(true)
    bool(true)

### 参见

- IntlChar::getPropertyName() - Get the Unicode name for a property

# IntlChar::getPropertyName

(PHP 7, PHP 8)

IntlChar::getPropertyName — Get the Unicode name for a property

### 说明

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().

### 参数

`property`
  The Unicode property to lookup (see the `IntlChar::PROPERTY_*` constants).

  `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`.

### 返回值

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.

### 示例

示例 #1 Testing different properties

    <?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));
    ?>

以上示例会输出：

    string(10) "Bidi_Class"
    string(2) "bc"
    string(10) "Bidi_Class"
    bool(false)

### 参见

- 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

### 说明

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.

> 注意:

> 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"

### 参数

`property`
  The Unicode property to lookup (see the `IntlChar::PROPERTY_*` constants).

  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.

### 返回值

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.

### 示例

示例 #1 Testing different properties

    <?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);
    ?>

以上示例会输出：

    bool(true)
    bool(true)
    bool(true)
    bool(true)

# IntlChar::getPropertyValueName

(PHP 7, PHP 8)

IntlChar::getPropertyValueName — Get the Unicode name for a property value

### 说明

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.

> 注意:

> 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"

### 参数

`property`
  The Unicode property to lookup (see the `IntlChar::PROPERTY_*` constants).

  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`.

### 返回值

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.

### 示例

示例 #1 Testing different properties

    <?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));
    ?>

以上示例会输出：

    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

### 说明

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]`.

### 参数

此函数没有参数。

### 返回值

An array containing the Unicode version number.

### 示例

示例 #1 Testing different properties

    <?php
    var_dump(IntlChar::getUnicodeVersion());
    ?>

以上示例会输出：

    array(4) {
      [0]=>
      int(7)
      [1]=>
      int(0)
      [2]=>
      int(0)
      [3]=>
      int(0)
    }

### 参见

- 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

### 说明

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.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)
`property`
  The Unicode property to lookup (see the `IntlChar::PROPERTY_*` constants).

### 返回值

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.

### 示例

示例 #1 Testing different properties

    <?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));
    ?>

以上示例会输出：

    bool(true)
    bool(true)
    bool(false)
    bool(false)
    bool(false)
    bool(true)

### 参见

- 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

### 说明

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).

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` is an alphanumeric character, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::isalnum("A"));
    var_dump(IntlChar::isalnum("1"));
    var_dump(IntlChar::isalnum("\u{2603}"));
    ?>

以上示例会输出：

    bool(true)
    bool(true)
    bool(false)

### 参见

- IntlChar::isalpha() - Check if code point is a letter character
- IntlChar::isdigit() - Check if code point is a digit character
- ctype_alnum() - 检测字母数字式字符

# IntlChar::isalpha

(PHP 7, PHP 8)

IntlChar::isalpha — Check if code point is a letter character

### 说明

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).

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` is a letter character, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::isalpha("A"));
    var_dump(IntlChar::isalpha("1"));
    var_dump(IntlChar::isalpha("\u{2603}"));
    ?>

以上示例会输出：

    bool(true)
    bool(false)
    bool(false)

### 参见

- IntlChar::isalnum() - Check if code point is an alphanumeric character
- IntlChar::isdigit() - Check if code point is a digit character
- ctype_alpha() - 检测字母字符

# IntlChar::isbase

(PHP 7, PHP 8)

IntlChar::isbase — Check if code point is a base character

### 说明

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).

> 注意:

> 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.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` is a base character, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::isbase("A"));
    var_dump(IntlChar::isbase("1"));
    var_dump(IntlChar::isbase("\u{2603}"));
    ?>

以上示例会输出：

    bool(true)
    bool(true)
    bool(false)

### 参见

- 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

### 说明

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).

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` is either a "blank" or "horizontal space" character, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::isblank("A"));
    var_dump(IntlChar::isblank(" "));
    var_dump(IntlChar::isblank("\t"));
    ?>

以上示例会输出：

    bool(false)
    bool(true)
    bool(true)

### 参见

- 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

### 说明

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)

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` is a control character, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::iscntrl("A"));
    var_dump(IntlChar::iscntrl(" "));
    var_dump(IntlChar::iscntrl("\n"));
    var_dump(IntlChar::iscntrl("\u{200e}"));
    ?>

以上示例会输出：

    bool(false)
    bool(false)
    bool(true)
    bool(true)

### 参见

- IntlChar::isprint() - Check if code point is a printable character
- `IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT`
- ctype_cntrl() - 检测控制字符

# IntlChar::isdefined

(PHP 7, PHP 8)

IntlChar::isdefined — Check whether the code point is defined

### 说明

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).

> 注意:

> Note that non-character code points (e.g., U+FDD0) are not "defined" (they are Cn), but surrogate code points are "defined" (Cs).

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` is a defined character, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::isdefined("A"));
    var_dump(IntlChar::isdefined(" "));
    var_dump(IntlChar::isdefined("\u{FDD0}"));
    ?>

以上示例会输出：

    bool(true)
    bool(true)
    bool(false)

### 参见

- 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

### 说明

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.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` is a digit character, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::isdigit("A"));
    var_dump(IntlChar::isdigit("1"));
    var_dump(IntlChar::isdigit("\t"));
    ?>

以上示例会输出：

    bool(false)
    bool(true)
    bool(false)

### 参见

- 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() - 检测数字字符

# IntlChar::isgraph

(PHP 7, PHP 8)

IntlChar::isgraph — Check if code point is a graphic character

### 说明

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).

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` is a "graphic" character, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::isgraph("A"));
    var_dump(IntlChar::isgraph("1"));
    var_dump(IntlChar::isgraph("\u{2603}"));
    var_dump(IntlChar::isgraph("\n"));
    ?>

以上示例会输出：

    bool(true)
    bool(true)
    bool(true)
    bool(false)

### 参见

- ctype_graph() - 检测除空格外的任何打印字符

# IntlChar::isIDIgnorable

(PHP 7, PHP 8)

IntlChar::isIDIgnorable — Check if code point is an ignorable character

### 说明

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).

> 注意:

> Note that Unicode just recommends to ignore Cf (format controls).

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` is ignorable in identifiers, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::isIDIgnorable("A"));
    var_dump(IntlChar::isIDIgnorable(" "));
    var_dump(IntlChar::isIDIgnorable("\u{007F}"));
    ?>

以上示例会输出：

    bool(false)
    bool(false)
    bool(true)

### 参见

- 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

### 说明

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).

> 注意:

> 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().

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` is the code point may occur in an identifier, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::isIDPart("A"));
    var_dump(IntlChar::isIDPart("$"));
    var_dump(IntlChar::isIDPart("\n"));
    var_dump(IntlChar::isIDPart("\u{2603}"));
    ?>

以上示例会输出：

    bool(true)
    bool(false)
    bool(false)
    bool(false)

### 参见

- 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

### 说明

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).

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` may start an identifier, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::isIDStart("A"));
    var_dump(IntlChar::isIDStart("$"));
    var_dump(IntlChar::isIDStart("\n"));
    var_dump(IntlChar::isIDStart("\u{2603}"));
    ?>

以上示例会输出：

    bool(true)
    bool(false)
    bool(false)
    bool(false)

### 参见

- 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

### 说明

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").

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` is an ISO control code, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::isISOControl(" "));
    var_dump(IntlChar::isISOControl("\n"));
    var_dump(IntlChar::isISOControl("\u{200e}"));
    ?>

以上示例会输出：

    bool(false)
    bool(true)
    bool(false)

### 参见

- 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

### 说明

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).

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` may occur in a Java identifier, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::isJavaIDPart("A"));
    var_dump(IntlChar::isJavaIDPart("$"));
    var_dump(IntlChar::isJavaIDPart("\n"));
    var_dump(IntlChar::isJavaIDPart("\u{2603}"));
    ?>

以上示例会输出：

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### 参见

- 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

### 说明

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).

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` may start a Java identifier, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::isJavaIDStart("A"));
    var_dump(IntlChar::isJavaIDStart("$"));
    var_dump(IntlChar::isJavaIDStart("\n"));
    var_dump(IntlChar::isJavaIDStart("\u{2603}"));
    ?>

以上示例会输出：

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### 参见

- 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

### 说明

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).

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` is a space character according to Java, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?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}"));
    ?>

以上示例会输出：

    bool(false)
    bool(true)
    bool(false)
    bool(false)
    bool(true)

### 参见

- 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

### 说明

public static function IntlChar::islower(int|string `$codepoint`): ?bool

Determines whether the specified code point has the general category "Ll" (lowercase letter).

> 注意:

> This misses some characters that are also lowercase but have a different general category value. In order to include those, use IntlChar::isULowercase().

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` is an Ll lowercase letter, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::islower("A"));
    var_dump(IntlChar::islower("a"));
    var_dump(IntlChar::islower("Φ"));
    var_dump(IntlChar::islower("φ"));
    var_dump(IntlChar::islower("1"));
    ?>

以上示例会输出：

    bool(false)
    bool(true)
    bool(false)
    bool(true)
    bool(false)

### 参见

- 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() - 检测小写字符

# IntlChar::isMirrored

(PHP 7, PHP 8)

IntlChar::isMirrored — Check if code point has the Bidi_Mirrored property

### 说明

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.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` has the Bidi_Mirrored property, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::isMirrored("A"));
    var_dump(IntlChar::isMirrored("<"));
    var_dump(IntlChar::isMirrored("("));
    ?>

以上示例会输出：

    bool(false)
    bool(true)
    bool(true)

### 参见

- 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

### 说明

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).

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` is a printable character, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::isprint("A"));
    var_dump(IntlChar::isprint(" "));
    var_dump(IntlChar::isprint("\n"));
    var_dump(IntlChar::isprint("\u{200e}"));
    ?>

以上示例会输出：

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### 参见

- IntlChar::iscntrl() - Check if code point is a control character
- `IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT`
- ctype_print() - 检测可打印字符

# IntlChar::ispunct

(PHP 7, PHP 8)

IntlChar::ispunct — Check if code point is punctuation character

### 说明

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).

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` is a punctuation character, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::ispunct("."));
    var_dump(IntlChar::ispunct(","));
    var_dump(IntlChar::ispunct("\n"));
    var_dump(IntlChar::ispunct("$"));

以上示例会输出：

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### 参见

- ctype_punct() - 检测可打印的字符是不是不包含空白、数字和字母

# IntlChar::isspace

(PHP 7, PHP 8)

IntlChar::isspace — Check if code point is a space character

### 说明

public static function IntlChar::isspace(int|string `$codepoint`): ?bool

Determines if the specified character is a space character or not.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` is a space character, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?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}"));
    ?>

以上示例会输出：

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    bool(true)

### 参见

- 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() - 检测空白字符

# IntlChar::istitle

(PHP 7, PHP 8)

IntlChar::istitle — Check if code point is a titlecase letter

### 说明

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).

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` is a titlecase letter, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?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("Α"));
    ?>

以上示例会输出：

    bool(false)
    bool(true)
    bool(false)
    bool(true)
    bool(false)
    bool(false)

### 参见

- 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

### 说明

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)`

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` has the Alphabetic Unicode property, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::isUAlphabetic("A"));
    var_dump(IntlChar::isUAlphabetic("1"));
    var_dump(IntlChar::isUAlphabetic("\u{2603}"));
    ?>

以上示例会输出：

    bool(true)
    bool(false)
    bool(false)

### 参见

- 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

### 说明

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)`

> 注意:

> This is different than IntlChar::islower() and will return `true` for more characters.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` has the Lowercase Unicode property, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::isULowercase("A"));
    var_dump(IntlChar::isULowercase("a"));
    var_dump(IntlChar::isULowercase("Φ"));
    var_dump(IntlChar::isULowercase("φ"));
    var_dump(IntlChar::isULowercase("1"));
    ?>

以上示例会输出：

    bool(false)
    bool(true)
    bool(false)
    bool(true)
    bool(false)

### 参见

- 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)

### 说明

public static function IntlChar::isupper(int|string `$codepoint`): ?bool

Determines whether the specified code point has the general category "Lu" (uppercase letter).

> 注意:

> This misses some characters that are also uppercase but have a different general category value. In order to include those, use IntlChar::isUUppercase().

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` is an Lu uppercase letter, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::isupper("A"));
    var_dump(IntlChar::isupper("a"));
    var_dump(IntlChar::isupper("Φ"));
    var_dump(IntlChar::isupper("φ"));
    var_dump(IntlChar::isupper("1"));
    ?>

以上示例会输出：

    bool(true)
    bool(false)
    bool(true)
    bool(false)
    bool(false)

### 参见

- 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() - 检测大写字符

# IntlChar::isUUppercase

(PHP 7, PHP 8)

IntlChar::isUUppercase — Check if code point has the Uppercase Unicode property

### 说明

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)`

> 注意:

> This is different than IntlChar::isupper() and will return `true` for more characters.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` has the Uppercase Unicode property, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::isUUppercase("A"));
    var_dump(IntlChar::isUUppercase("a"));
    var_dump(IntlChar::isUUppercase("Φ"));
    var_dump(IntlChar::isUUppercase("φ"));
    var_dump(IntlChar::isUUppercase("1"));
    ?>

以上示例会输出：

    bool(true)
    bool(false)
    bool(true)
    bool(false)
    bool(false)

### 参见

- 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

### 说明

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)`

> 注意:

> This is different from both IntlChar::isspace() and IntlChar::isWhitespace().

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` has the White_Space Unicode property, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?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}"));
    ?>

以上示例会输出：

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    bool(true)

### 参见

- 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

### 说明

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.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` is a whitespace character according to ICU, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?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}"));
    ?>

以上示例会输出：

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    bool(false)

### 参见

- 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

### 说明

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`.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns `true` if `codepoint` is a hexadecimal character, `false` if not. Returns `null` on failure.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::isxdigit("A"));
    var_dump(IntlChar::isxdigit("1"));
    var_dump(IntlChar::isxdigit("\u{2603}"));
    ?>

以上示例会输出：

    bool(true)
    bool(true)
    bool(false)

### 注释

> 注意:

> In order to narrow the definition of hexadecimal digits to only ASCII characters use:

>     <?php
>     $isASCIIHexadecimal = IntlChar::ord($codepoint) <= 0x7F && IntlChar::isxdigit($codepoint);
>     ?>

### 参见

- IntlChar::isdigit() - Check if code point is a digit character
- ctype_xdigit() - 检测字符是否只包含十六进制字符

# IntlChar::ord

(PHP 7, PHP 8)

IntlChar::ord — Return Unicode code point value of character

### 说明

public static function IntlChar::ord(int|string `$character`): ?int

Returns the Unicode code point value of the given character.

This function complements IntlChar::chr().

### 参数

`character`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns the Unicode code point value as an integer.

### 示例

示例 #1 Testing different code points

    <?php
    var_dump(IntlChar::ord("A"));
    var_dump(IntlChar::ord(" "));
    var_dump(IntlChar::ord("\u{2603}"));
    ?>

以上示例会输出：

    int(65)
    int(32)
    int(9731)

### 参见

- IntlChar::chr() - Return Unicode character by code point value
- mb_ord() - 获取字符的 Unicode 码位值
- ord() - 转换字符串第一个字节为 0-255 之间的值

# IntlChar::tolower

(PHP 7, PHP 8)

IntlChar::tolower — Make Unicode character lowercase

### 说明

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.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns the Simple_Lowercase_Mapping of the code point, if any; otherwise the code point itself. Returns `null` on failure.

返回类型是 int，如果代码点作为 UTF-8 string 传递，则会返回 string 。失败时返回 `null`。

### 示例

示例 #1 Testing different code points

    <?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")));
    ?>

以上示例会输出：

    string(1) "a"
    string(1) "a"
    string(2) "φ"
    string(2) "φ"
    string(1) "1"
    int(97)
    int(97)

### 参见

- IntlChar::totitle() - Make Unicode character titlecase
- IntlChar::toupper() - Make Unicode character uppercase
- mb_strtolower() - 使字符串小写

# IntlChar::totitle

(PHP 7, PHP 8)

IntlChar::totitle — Make Unicode character titlecase

### 说明

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.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns the Simple_Titlecase_Mapping of the code point, if any; otherwise the code point itself. Returns `null` on failure.

返回类型是 int，如果代码点作为 UTF-8 string 传递，则会返回 string 。失败时返回 `null`。

### 示例

示例 #1 Testing different code points

    <?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")));
    ?>

以上示例会输出：

    string(1) "ǅ"
    string(1) "ǅ"
    string(2) "Φ"
    string(2) "φ"
    string(1) "1"
    string(1) "ᾼ"
    int(65)

### 参见

- 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() - 对字符串进行大小写转换

# IntlChar::toupper

(PHP 7, PHP 8)

IntlChar::toupper — Make Unicode character uppercase

### 说明

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.

### 参数

`codepoint`
  The int codepoint value (e.g. `0x2603` for U+2603 SNOWMAN), or the character encoded as a UTF-8 string (e.g. `"\u{2603}"`)

### 返回值

Returns the Simple_Uppercase_Mapping of the code point, if any; otherwise the code point itself.

返回类型是 int，如果代码点作为 UTF-8 string 传递，则会返回 string 。失败时返回 `null`。

### 示例

示例 #1 Testing different code points

    <?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")));
    ?>

以上示例会输出：

    string(1) "A"
    string(1) "A"
    string(2) "Φ"
    string(2) "Φ"
    string(1) "1"
    int(65)
    int(65)

### 参见

- IntlChar::tolower() - Make Unicode character lowercase
- IntlChar::totitle() - Make Unicode character titlecase
- mb_strtoupper() - 使字符串大写

## 目录

- 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)

## 简介

This class is used for generating exceptions when errors occur inside intl functions. Such exceptions are only generated when intl.use_exceptions is enabled.

## 类摘要

class IntlException extends Exception {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 继承的方法 */
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)

## 简介

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.

## 类摘要

class IntlIterator implements Iterator {
/* 方法 */
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

### 说明

public function IntlIterator::current(): mixed

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# IntlIterator::key

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::key — Get the current key

### 说明

public function IntlIterator::key(): mixed

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# IntlIterator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::next — Move forward to the next element

### 说明

public function IntlIterator::next(): void

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# IntlIterator::rewind

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::rewind — Rewind the iterator to the first element

### 说明

public function IntlIterator::rewind(): void

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

# IntlIterator::valid

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::valid — Check if current position is valid

### 说明

public function IntlIterator::valid(): bool

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

## 目录

- 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 函数

# 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

### 说明

function intl_error_name(int `$errorCode`): string

Return ICU error code name.

### 参数

`errorCode`

  ICU error code.

### 返回值

The returned string will be the same as the name of the error code constant.

### 示例

示例 #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 ) );
    ?>

以上示例的输出类似于：

    Symbolic name for -128 is U_USING_FALLBACK_WARNING.

### 参见

- 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

### 说明

function intl_get_error_code(): int

Useful to handle errors occurred in static methods when there's no object to get error code from.

### 参数

此函数没有参数。

### 返回值

Error code returned by the last API function call.

### 示例

示例 #1 intl_get_error_code() example

    <?php
    $coll = collator_create( '<bad_param>' );
    if( !$coll ) {
        handle_error( intl_get_error_code() );
    }
    ?>

### 参见

- 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

### 说明

function intl_get_error_message(): string

Get error message from last internationalization function called.

### 参数

此函数没有参数。

### 返回值

Description of an error occurred in the last API function call.

### 示例

示例 #1 intl_get_error_message() example

    <?php
    if( Collator::getAvailableLocales() === false ) {
        show_error( intl_get_error_message() );
    }
    ?>

### 参见

- 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

### 说明

function intl_is_failure(int `$errorCode`): bool

### 参数

`errorCode`

  is a value that returned by functions: intl_get_error_code(), collator_get_error_code() .

### 返回值

`true` if it the code indicates some failure, and `false` in case of success or a warning.

### 示例

示例 #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 );
    ?>

以上示例的输出类似于：

    false
    false
    true

### 参见

- intl_get_error_code() - Get the last error code
- collator_get_error_code() - Get collator's last error code
- Collator-getErrorCode()

## 目录

- 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

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
- 预定义常量
- 示例
  - 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 — Translate a timezone identifier to its IANA equivalent
  - 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 — Determines the most suitable date/time format
- IntlPartsIterator — The IntlPartsIterator class
  - IntlPartsIterator::getBreakIterator — Get IntlBreakIterator backing this parts iterator
- UConverter — The UConverter class
  - 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 函数
  - 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 函数
  - idn_to_ascii — 将域名转换为 IDNA ASCII 格式
  - idn_to_utf8 — 将域名从 IDNA ASCII 转换为 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 函数
  - 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

# 多字节字符串

# 简介

虽然许多语言每个必要字符都能一对一映射到 8 比特（bit）的值，但也有好几种语言需要非常多的字符来书面通讯，以至于它们的编码范围不能仅仅包含在一个字节里（一个字节 Byte 由 8 比特 bit 构成。每一比特仅能包含两种不同的值： 1 或 0。所以，一字节仅能够表示 256 种不同的值，即 2 的八次方）。 开发多字节字符编码方案是为了在基于字节的常规编码系统中表达超过 256 个字符。

在你操作（trim、split、splice 等等）多字节编码的字符串的时候，由于在这种编码方案下，两个或多个连续字节可能只表达了一个字符，所以你需要使用专门的函数。 否则，当你将不能检测多字节字符串的函数应用到这个字符串的时候，它可能无法检测多字节字符的起始位置，并以乱码字符串结尾，基本丢失了它原来的意思。

`mbstring` 提供了针对多字节字符串的函数，能够帮你处理 PHP 中的多字节编码。 除此以外，`mbstring` 还能在可能的字符编码之间相互进行编码转换。 为了方便起见，`mbstring` 设计成了处理基于 Unicode 的编码，类似 UTF-8、UCS-2 及诸多单字节的编码（在 支持的编码 列出了）。

# 安装/配置

## 目录

- 安装
- 运行时配置

## 安装

`mbstring` 不是一个默认扩展。这意味着它默认没有被激活。 你必须在 `configure` 选项中显式激活该模块。 详情参见安装这一节。

以下是涉及到 `mbstring` 的相关配置选项。

- --enable-mbstring：激活 `mbstring` 函数。 要使用 `mbstring` 函数必须启用这个选项。

  libmbfl 对 `mbstring` 是必要的。libmbfl 被捆绑到了 `mbstring`。在 PHP 7.3.0 之前，如果系统已安装 libmbfl，--with-libmbfl[=DIR] 可以指定使用已安装的库。

- --disable-mbregex：禁用正则表达式函数中多字节字符的支持。

  Oniguruma 对于支持多字节字符的正则表达式函数是必需的。自 PHP 7.4.0 起，pkg-config 用于检测 libonig 库。在 PHP 7.4.0 之前，Oniguruma 与 `mbstring` 捆绑，但可以通过传递 --with-onig[=DIR] 来对已安装的 libonig 库进行构建。

  可以通过指定 --disable-mbregex-backtrack 来禁用多字节正则表达式回溯检查。

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

mbstring 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
mbstring.language | "neutral" | `INI_ALL` |
mbstring.detect_order | NULL | `INI_ALL` |
mbstring.http_input | "pass" | `INI_ALL` | 已弃用
mbstring.http_output | "pass" | `INI_ALL` | 已弃用
mbstring.internal_encoding | NULL | `INI_ALL` | 已弃用
mbstring.substitute_character | NULL | `INI_ALL` |
mbstring.func_overload | "0" | `INI_SYSTEM` | 自 PHP 7.2.0 起弃用，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` | 自 PHP 7.4.0 起可用。
mbstring.regex_stack_limit | "100000" | `INI_ALL` | 自 PHP 7.3.5 起可用。

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`mbstring.language` string

  mbstring 使用了国家默认语言设置（NLS）。 注意，该选项自动地定义了 `mbstring.internal_encoding` 和 `mbstring.internal_encoding`，在 php.ini 里应当放置在 `mbstring.language` 之后。

`mbstring.encoding_translation` bool

  为传入的 HTTP 查询启用透明字符编码过滤器，将检测和转换输入的编码为内部字符编码（internal character encoding）。

`mbstring.internal_encoding` string
  警告

  本过时特性将肯定会在未来被移除。

  定义内部字符的默认编码。

  用户应该将此选项留空，并设置 `default_charset` 作为代替。

`mbstring.http_input` string
  警告

  本过时特性将肯定会在未来被移除。

  定义 HTTP 输入字符的默认编码。

  用户应该将此选项留空，并设置 `default_charset` 作为代替。

`mbstring.http_output` string
  警告

  本过时特性将肯定会在未来被移除。

  定义 HTTP 输出字符的默认编码。

  用户应该将此选项留空，并设置 `default_charset` 作为代替。

`mbstring.detect_order` string

  定义字符编码的默认检测顺序。参见 mb_detect_order()。

`mbstring.substitute_character` string

  为无效编码的字符定义替代字符。 参见 mb_substitute_character() ，查看支持的值。

`mbstring.func_overload` string
  警告

  本特性自 PHP 7.2.0 起废弃，并且自 PHP 8.0.0 起被移除。 强烈建议不要使用本特性。

  用 mbstring 对应的函数覆盖单字节版本的函数集。更多信息参见函数的覆盖。

  该设置仅能通过 php.ini 文件来修改。

`mbstring.http_output_conv_mimetypes` string

`mbstring.strict_detection` bool

  使用严格的编码检测。有关描述和示例，参见 mb_detect_encoding()。

`mbstring.regex_retry_limit` int

  Limits the amount of backtracking that may be performed during one mbregex match.

  此设置仅在链接的 oniguruma >= 6.8.0 时生效。

`mbstring.regex_stack_limit` int

  限制 mbstring 正则表达式的栈深度。

根据 » HTML4.01 规范，允许 Web 浏览器以页面不同的字符编码来提交表单。参见用 mb_http_input() 来检测浏览器使用的字符编码。

尽管流行的浏览器能够根据给出的 HTML 文档合理猜测正确的编码，但如果能通过 header() 函数在 HTTP 的 `Content-Type` 头内或 ini 的 default_charset 里设置适当的 `charset` 参数则会更佳。

示例 #1 php.ini 设置例子

    ; 设置默认语言
    mbstring.language        = Neutral; 设置默认语言 Neutral(UTF-8) (默认的值)
    mbstring.language        = English; 设置默认语言为 English
    mbstring.language        = Japanese; 设置默认语言为 Japanese

    ;; 设置内部的默认编码
    ;; 注意：请确保这个编码能被 PHP 所处理
    mbstring.internal_encoding    = UTF-8  ; 设置内部的默认编码为 UTF-8

    ;; 启用 HTTP 输入编码的转换
    mbstring.encoding_translation = On

    ;; 设置 HTTP 输入的默认编码
    ;; 注意：脚本不能修改 http_input 的设置
    mbstring.http_input           = pass    ; 不转换
    mbstring.http_input           = auto    ; 设置 HTTP 输入为 auto
                                    ; "auto" 会根据 mbstring.language 自动扩展
    mbstring.http_input           = SJIS    ; 设置 HTTP 输入编码为 SJIS
    mbstring.http_input           = UTF-8,SJIS,EUC-JP ; 指定顺序

    ;; 设置 HTTP 输出的默认编码
    mbstring.http_output          = pass    ; 不转换
    mbstring.http_output          = UTF-8   ; 设置 HTTP 输出编码为 UTF-8

    ;; 设置字符编码的默认检测顺序
    mbstring.detect_order         = auto    ; Set detect order to auto
    mbstring.detect_order         = ASCII,JIS,UTF-8,SJIS,EUC-JP ; Specify order

    ;; 设置默认的替代字符
    mbstring.substitute_character = 12307   ; 指定 Unicode 值
    mbstring.substitute_character = none    ; 不打印字符
    mbstring.substitute_character = long    ; Long 的例子： U+3000,JIS+7E7E

示例 #2 php.ini 里 `EUC-JP` 用户的设置

    ;; 禁用输出缓冲
    output_buffering      = Off

    ;; 设置 HTTP header 字符编码
    default_charset       = EUC-JP

    ;; 设置默认语言为 Japanese
    mbstring.language = Japanese

    ;; 启用 HTTP 输入编码的转换
    mbstring.encoding_translation = On

    ;; 启用 HTTP 输入转换的编码为 auto
    mbstring.http_input   = auto

    ;; 转换 HTTP 输出的编码为 EUC-JP
    mbstring.http_output  = EUC-JP

    ;; 设置内部编码为 EUC-JP
    mbstring.internal_encoding = EUC-JP

    ;; 不要打印无效的字符
    mbstring.substitute_character = none

示例 #3 php.ini 里 `SJIS` 用户的设置

    ;; 启用输出缓冲
    output_buffering     = On

    ;; 设置 mb_output_handler 来启用输出编码的转换
    output_handler       = mb_output_handler

    ;; 设置 HTTP header 的字符编码
    default_charset      = Shift_JIS

    ;; 设置默认语言为 Japanese
    mbstring.language = Japanese

    ;; 设置 http 输入转换的编码为 auto
    mbstring.http_input  = auto

    ;; 转换成 SJIS
    mbstring.http_output = SJIS

    ;; 设置内部变量为 EUC-JP
    mbstring.internal_encoding = EUC-JP

    ;; 不要打印无效的字符
    mbstring.substitute_character = none

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`MB_OVERLOAD_MAIL` (int)
  自 PHP 8.0.0 起已删除。
`MB_OVERLOAD_STRING` (int)
  自 PHP 8.0.0 起已删除。
`MB_OVERLOAD_REGEX` (int)
  自 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)
  Oniguruma 版本，例如 `6.9.4`。自 PHP 7.4 起可用。

# 支持编码的摘要

支持编码的摘要
IANA 字符集注册表内的名称 | 相关字符集 | 描述 | 额外的说明
--- | --- | --- | ---
ISO-10646-UCS-4 | ISO 10646 | 31位编码空间的通用字符集，以 ISO/IEC 10646 标准化为 UCS-4。 它和最新的 Unicode 代码映射表保持同步。 | 如果在编码转化程序中使用了这个名字，转换器将尝试识别前缀的 BOM头（字节顺序标记），即表示后续字节的字节序。
ISO-10646-UCS-4 | UCS-4 | 参见以上。 | 和 `UCS-4` 相比较，字符串总是设为大端序（big endian）的形式。
ISO-10646-UCS-4 | UCS-4 | 参见以上。 | 和 `UCS-4` 相比较，字符串总是设为小端序（little endian）的形式。
ISO-10646-UCS-2 | UCS-2 | 16位编码空间的通用字符集，以 ISO/IEC 10646 标准化为 UCS-2。它和最新的 Unicode 代码映射表保持同步。 | 如果在编码转化程序中使用了这个名字，转换器将尝试识别前缀的 BOM头（字节顺序标记），即表示后续字节的字节序。
ISO-10646-UCS-2 | UCS-2 | 参见以上。 | 和 `UCS-2` 相比较，字符串总是设为大端序（big endian）的形式。
ISO-10646-UCS-2 | UCS-2 | 参见以上。 | 和 `UCS-2` 相比较，字符串总是设为小端序（little endian）的形式。
UTF-32 | Unicode | 32 位单位宽度的 Unicode 转换格式，涉及到了 Unicode 字符集标准。该编码方案和 UCS-4 没有完全相同，因为 Unicode 编码空间限制为 21 位的值。 | 如果在编码转化程序中使用了这个名字，转换器将尝试识别前缀的 BOM头（字节顺序标记），即表示后续字节的字节序。
UTF-32BE | Unicode | 参见以上 | 和 `UTF-32` 相比较，字符串总是设为大端序（big endian）的形式。
UTF-32LE | Unicode | 参见以上 | 和 `UTF-32` 相比较，字符串总是设为小端序（little endian）的形式。
UTF-16 | Unicode | 16 位单位宽度的 Unicode 转换格式。值得一记的是，UTF-16 的规格不再和 UCS-2 一样， 因为 Unicode 2.0 引入了代理机制（surrogate mechanism），UTF-16 现在指向了 21 位的编码空间。 | 如果在编码转化程序中使用了这个名字，转换器将尝试识别前缀的 BOM头（字节顺序标记），即表示后续字节的字节序。
UTF-16BE | Unicode | 参见以上。 | 和 `UTF-16` 相比较，字符串总是设为大端序（big endian）的形式。
UTF-16LE | Unicode | 参见以上。 | 和 `UTF-16` 相比较，字符串总是设为小端序（little endian）的形式。
UTF-8 | Unicode / UCS | 8 位单位宽度的 Unicode 转换格式。 | none
UTF-7 | Unicode | 一种邮件安全的 Unicode 转换格式，规格是 » RFC2152。 | none
(none) | Unicode | UTF-7 的一种变体，其规格在 » IMAP 协议 中用到了。 | none
US-ASCII (首选 MIME 名称) / iso-ir-6 / ANSI_X3.4-1986 / ISO_646.irv:1991 / ASCII / ISO646-US / us / IBM367 / CP367 / csASCII | ASCII / ISO 646 | 美国标准代码（American Standard Code）是一种常用的 7-bit 信息交换编码。同样，标准化为 ISO 646 国际标准。 | (none)
EUC-JP (首选 MIME 名称) / Extended_UNIX_Code_Packed_Format_for_Japanese / csEUCPkdFmtJapanese | US-ASCII / JIS X0201:1997 (半角假名部分) / JIS X0208:1990 / JIS X0212:1990 的复合 | 就像你所看到的，名字来源于扩展 Extended UNIX Code Packed Format for Japanese 的缩写，该编码常用于 UNIX 或类似平台。原始编码方案 Extended UNIX Code 基于 ISO 2022 而设计。 | EUC-JP 涉及的字符集和 IBM932 / CP932 是不一样的，后者使用于 OS/2® 和 Microsoft® Windows®。 这些平台上的信息交换，使用 EUCJP-WIN 来代替。
Shift_JIS (首选 MIME 名称) / MS_Kanji / csShift_JIS | JIS X0201:1997 / JIS X0208:1997 的复合 | 80 年代初，个人日文文字处理软件进入了市场之时，为了兼容传统编码方案 JIS X 0201:1976，开发了 Shift_JIS。 根据 IANA 对 Shift_JIS 编码集的定义，和 IBM932 / CP932 稍有不同。但 "SJIS"、"Shift_JIS" 的名称常被错误得指向这些编码集。 | 要使用 CP932，使用 SJIS-WIN 作为替代。
(none) | JIS X0201:1997 / JIS X0208:1997 / IBM extensions / NEC extensions 的复合 | 虽然此 "encoding" 使用了 EUC-JP 同样的方案，一些字符集有所不同。 也就是说，一些编码映射到了和 EUC-JP 不同的字符。 | none
Windows-31J / csWindows31J | JIS X0201:1997 / JIS X0208:1997 / IBM extensions / NEC extensions 的符合 | 虽然此 "encoding" 使用了 Shift_JIS 同样的方案，一些字符集有所不同。 也就是说，一些编码映射到了和 Shift_JIS 不同的字符。 | (none)
ISO-2022-JP (首选 MIME 名称) / 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 |  |  |

# 日文字符多字节编码基础

日文字符只能使用多字节编码，而且，编码规范取决于平台和字符的使用 目的（text purpose)。跟糟糕的是，编码规范之间还稍有差异。为了开发 出适应日文环境的Web应用，开发人员必须对编码规范有个清晰的认识，确保 使用了合适的编码规范。

- 存储一个日文字符最大需要6个字节空间
- 多数日文多字节字符是单字节字符出现频率的两倍。这些字符被称为 "zen-kaku"，在日文中代表的意思是"full width"。 其它窄一些的字符被称作"han-kaku"，意思是"half width"。 字符实际显示的宽度，取决于显示时使用的字体。
- 有些字符编码采用ISO-2022定义的转码序列（shift sequences) 来转换特殊的编码 空间(`00h` to `7fh`)。
- 在SMTP/NNTP协议应用中 建议 采用ISO-2022-JP编码，并且头部和实体部分，应该按照 RFC要求重新编码。虽然这些并不是强制性要求，但最好还是按这个建议做，因为几款 流行的客户端不支持其他的编码方式。
- 手机服务页面，例如» i-mode或者» EZweb 应该 使用Shift_JIS编码。
- Emoji 已经可以支持像 » i-mode 或者 » EZweb 这样的手机服务。

# HTTP 输入和输出

HTTP 输入/输出字符编码转换同样也适用于二进制数据。 如果 HTTP 输入/输出用到了二进制数据，用户应当控制字符的编码转换。

> 注意:

> 如果 HTML 表单的 `enctype` 属性设置为 `multipart/form-data`，并且 php.ini 里的 `mbstring.encoding_translation` 设置为 On， POST 的变量以及上传文件的名称也将会被转换到内部字符编码。 不过，转换不会应用于查询（query）的键。

- HTTP 输入

  在 PHP 脚本里无法控制 HTTP 输入字符的转换。 要禁用 HTTP 输入字符的转换，必须要在 php.ini 里设置。

  示例 #1 在 php.ini 中禁用 HTTP 输入转换

      ;; 禁用 HTTP 输入转换
      mbstring.http_input = pass
      ;;禁用 HTTP 输入转换
      mbstring.encoding_translation = Off

  当 PHP 以 Apache 模块运行。这些设置还可以通过 httpd.conf 内每个虚拟主机（Virtual Host）指令或每个目录下的 .htaccess 来覆盖（override）。 详情参见配置这一节，以及 Apache 手册。

- HTTP 输出

  输出字符编码转换的使用有几种方式。 一种是使用 php.ini，另一种是使用 ob_start()，以 mb_output_handler() 作为 `ob_start` 的回调函数。

示例 #2 php.ini 设置例子

    ;; 为所有 PHP 页面启用输出字符编码的转换

    ;; 启用输出缓冲
    output_buffering    = On

    ;; 设置 mb_output_handler 来进行输出的转换
    output_handler      = mb_output_handler

示例 #3 脚本例子

    <?php

    // 仅为此页面启用输出字符编码的转换

    // 设置 HTTP 输出字符编码为 SJIS
    mb_http_output('SJIS');

    // 开始缓冲并指定 "mb_output_handler" 为回调函数
    ob_start('mb_output_handler');

    ?>

# 支持的字符编码

当前 `mbstring` 模块支持以下的字符编码。这些字符编码中的任意一个都能指定到 `mbstring` 函数中的 `encoding` 参数。

该 PHP 扩展支持的字符编码有以下几种：

- 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（别名：MacJapanese）
- SJIS-Mobile#DOCOMO（别名：SJIS-DOCOMO）
- SJIS-Mobile#KDDI（别名：SJIS-KDDI）
- SJIS-Mobile#SOFTBANK（别名：SJIS-SOFTBANK）
- UTF-8-Mobile#DOCOMO（别名：UTF-8-DOCOMO）
- UTF-8-Mobile#KDDI-A
- UTF-8-Mobile#KDDI-B（别名：UTF-8-KDDI）
- UTF-8-Mobile#SOFTBANK（别名：UTF-8-SOFTBANK）
- ISO-2022-JP-MOBILE#KDDI（别名：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（别名：HTML）
- 7bit
- 8bit
- EUC-CN*
- CP936
- GB18030
- 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*
- ArmSCII-8（别名：ArmSCII8）

* 表示该编码也可以在正则表达式中使用。

任何接受编码名称的 php.ini 条目同样也可以使用 "`auto`" 和 "`pass`" 的值。 接受编码名的 `mbstring` 函数同样也可以使用值 "`auto`"。

如果设置了 "`pass`"，将不会对字符的编码进行转化。

如果设置了 "`auto`"，它将扩展成 NLS 中定义的每个字符编码列表。 比如，假设 NLS 设置为 `Japanese`，值将会认为是 "`ASCII,JIS,UTF-8,EUC-JP,SJIS`"。

参见 mb_detect_order()

# 函数重载功能

警告

本特性自 PHP 7.2.0 起废弃，并且自 PHP 8.0.0 起被移除。 强烈建议不要使用本特性。

你也许常常会发现现存的 PHP 应用很难运行在多字节环境下。 发生这种情况的原因是大多数那种 PHP 应用使用了标准的字符串函数，类似 substr()，已知无法处理多字节编码的字符串。

mbstring 支持一个“函数重载”功能，将对应的多字节版本重载到标准字符处理函数上，例如你能够让这类应用在不修改代码的前提下添加多字节的处理能力。 比如，启用函数重载后，mb_substr() 将会代替 substr() 被调用。 在很多情况下这个功能允许让仅支持单字节编码的应用简单地和多字节环境对接。

要使用函数重载功能，设置 php.ini 里的 `mbstring.func_overload` 为正值，就是表示为重载函数分类的位掩码组合。 要重载 mail() 函数需要设置它为 1。字符串函数设置为 2，正则表达式函数为 4。 例如，当它设置为 7， mail、strings 和 正则表达式函数将都会被重载。 以下列表显示了重载的函数。

被重载的函数
mbstring.func_overload 的值 | 原始函数 | 重载后的函数
--- | --- | ---
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()

> 注意:

> 不推荐每个目录的范围（context）内使用函数重载选项，因为还无法确定在生产环境中是否稳定，也许会导致不确定的行为。

# PHP字符编码的要求

以下类型的编码能够被 PHP 安全地使用。

- 单字节编码

  - ASCII兼容（ISO646 兼容），在 `00h` 到 `7fh` 的范围内映射字符集。

- 多字节编码，

  - ASCII兼容，在 `00h` 到 `7fh` 的范围内映射字符集。
  - 不使用 ISO2022 转义序列（escape sequences）。
  - 单个字符以任意复合字节表达、不使用 `00h` 到 `7fh` 的值。

有几个不太可能用 PHP 运行的字符编码例子。

    JIS, SJIS, ISO-2022-JP, BIG-5

虽然用任何其中一个编码来编写 PHP 脚本可能无法工作，尤其是这些编码的字符串以标识符（identifier）和字符（literal）出现， 但通过设置 `mbstring` 透明地过滤编码的函数，你几乎可以避免传入的 HTTP 查询使用这些编码。

> 注意:

> 我们极度不赞成在内部编码中使用 SJIS、BIG5、CP936、CP949 和 GB18030，除非你熟悉解析器（parser）、扫描器（scanner）和该字符编码。

> 注意:

> 当你用 PHP 连接到一个数据库，为了易用性和性能，推荐在数据库和`内部编码`使用一致的字符编码。

> 如果你使用的是 PostgreSQL，数据库里使用的编码和 PHP 里使用的编码可以是不同的，因为它支持字符集在前端和后端之间进行自动转换。

# 多字节字符串 函数

# 参考资料

多字节字符编码方案和他们相关的问题相当复杂，超越了本文档的范围。 关于这些话题的更多信息请参考以下 URL 和其他资源。

- Unicode materials

  » http://www.unicode.org/

- Japanese/Korean/Chinese 字符信息

  » 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 — 检查字符串在指定的编码里是否有效

### 说明

function mb_check_encoding(array|string|null `$value` = `null`, ?string `$encoding` = `null`): bool

检查指定字节流在指定编码中是否有效。如果 `value` 是 array 类型，则递归验证所有键和值。它能有效避免所谓的“无效编码攻击（Invalid Encoding Attack）”。

### 参数

`value`

  要检查的字节流或 array。如果省略了这个参数，此函数会检查所有来自最初请求所有的输入。

  警告

  自 PHP 8.1.0 起，禁止省略此参数或传递 `null`。

`encoding`

  期望的编码。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 弃用使用 `null` 作为 `value` 或不带参数调用此函数。
8.0.0 | `value` 和 `encoding` 现在可以为 null。
7.2.0 | 此函数现在也接受 array 作为 `value`。之前仅支持 string。

# mb_chr

(PHP 7 >= 7.2.0, PHP 8)

mb_chr — 按 Unicode 码位值返回字符

### 说明

function mb_chr(int `$codepoint`, ?string `$encoding` = `null`): string|false

返回一个含有由 Unicode 码位值所指定的字符的字符串，以指定的编码进行编码。

此函数与 mb_ord() 互补。

### 参数

`codepoint`

  一个 Unicode 码位值，例如 `128024` 是 U+1F418 ELEPHANT

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

如果可以用所指定的编码表示，则返回含有所请求的字符的字符串， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `encoding` 可以为 null。

### 示例

示例 #1 Testing different code points

    <?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'));
    }
    ?>

以上示例会输出：

    string(1) "A"
    string(1) "A"
    string(1) "?"
    string(1) "?"
    string(3) "€"
    bool(false)
    string(4) "🐘"
    bool(false)

### 参见

- mb_internal_encoding() - 设置/获取内部字符编码
- mb_ord() - 获取字符的 Unicode 码位值
- IntlChar::ord() - Return Unicode code point value of character
- chr() - 从数字生成单字节字符串

# mb_convert_case

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_convert_case — 对字符串进行大小写转换

### 说明

function mb_convert_case(string `$string`, int `$mode`, ?string `$encoding` = `null`): string

对一个 string 进行大小写转换，转换模式由 `mode` 指定。

### 参数

`string`

  要被转换的 string。

`mode`

  转换的模式。它可以是 `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`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

按 `mode` 指定的模式转换 `string` 大小写后的版本。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | 为希腊字母 Sigma 实现了条件性大小写规则， 仅适用于 `MB_CASE_LOWER` 和 `MB_CASE_TITLE` 模式， 不适用于 `MB_CASE_LOWER_SIMPLE` 和 `MB_CASE_TITLE_SIMPLE`。
7.3.0 | 添加对 `MB_CASE_FOLD`、`MB_CASE_UPPER_SIMPLE`、`MB_CASE_LOWER_SIMPLE`、`MB_CASE_TITLE_SIMPLE` 和 `MB_CASE_FOLD_SIMPLE` 作为 `mode` 的支持。

### 示例

示例 #1 mb_convert_case() 示例

    <?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;
    ?>

示例 #2 非拉丁 UTF-8 文本的 mb_convert_case() 示例

    <?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;
    ?>

### 注释

和类似 strtolower()、strtoupper() 的标准大小写转换函数相比，大小写转换的执行根据 Unicode 字符属性的基础。因此函数的行为不受语言环境（locale）设置的影响，能够转换任意具有“字母”属性的字符，例如元音变音A（Ä）。

更多关于 Unicode 属性的信息，请查看 » http://www.unicode.org/reports/tr21/。

### 参见

- mb_strtolower() - 使字符串小写
- mb_strtoupper() - 使字符串大写
- strtolower() - 将字符串转化为小写
- strtoupper() - 将字符串转化为大写
- ucfirst() - 将字符串的首字母转换为大写
- ucwords() - 将字符串中每个单词的首字母转换为大写

# mb_convert_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_encoding — 转换字符串，从一个字符编码到另一个字符编码

### 说明

function mb_convert_encoding(array|string `$string`, string `$to_encoding`, array|string|null `$from_encoding` = `null`): array|string|false

转换 string 从 `from_encoding` 或当前内部编码转换到 `to_encoding`。 当参数 `string` 是 array 时，将递归转换它所有的 string 值。

### 参数

`string`

  要转换的 string 或 array。

`to_encoding`

  所需的结果编码。

`from_encoding`

  当前用于解释 `string` 的编码。可以将多个编码指定为 array 或逗号分隔列表，在这种情况下，将使用与 mb_detect_encoding() 相同的算法来猜测正确的编码。

  如果 `from_encoding` 被省略或为 `null`，则将使用 mbstring.internal_encoding 设置，否则使用 default_charset 设置。

  有关 `to_encoding` 和 `from_encoding` 的有效值，请参阅支持的编码。

### 返回值

编码后的 string。 成功时返回编码后的 string 或 array， 或者在失败时返回 `false`。

### 错误／异常

当 `to_encoding` 或 `from_encoding` 为无效的编码时， PHP 8.0.0 起将抛出 ValueError； 而在 PHP 8.0.0 之前的版本里，会产生一个 `E_WARNING`。

### 更新日志

版本 | 说明
--- | ---
8.2.0 | mb_convert_encoding() 将不再返回以下非文本编码：`"Base64"`、`"QPrint"`、`"UUencode"`、`"HTML entities"`、`"7 bit"` 和 `"8 bit"`。
8.0.0 | 现在，当 `to_encoding` 为无效编码时， mb_convert_encoding() 会抛出 ValueError。
8.0.0 | 现在，当 `from_encoding` 为无效编码时， mb_convert_encoding() 会抛出 ValueError。
8.0.0 | 现在 `from_encoding` 可以传入 null。
7.2.0 | 现在该函数的 `string` 参数同时能接受 array 类型。 在此之前，仅支持 string。

### 示例

示例 #1 mb_convert_encoding() 示例

    <?php
    /* 转换内部编码为 SJIS */
    $str = mb_convert_encoding($str, "SJIS");

    /* 将 EUC-JP 转换成 UTF-7 */
    $str = mb_convert_encoding($str, "UTF-7", "EUC-JP");

    /* 从 JIS, eucjp-win, sjis-win 中自动检测编码，并转换 str 到 UCS-2LE */
    $str = mb_convert_encoding($str, "UCS-2LE", "JIS, eucjp-win, sjis-win");

    /* 如果 mbstring.language 是 "Japanese"，"auto" 扩展成 "ASCII,JIS,UTF-8,EUC-JP,SJIS" */
    $str = mb_convert_encoding($str, "EUC-JP", "auto");
    ?>

### 参见

- mb_detect_order() - 设置/获取 字符编码的检测顺序
- UConverter::transcode() - Convert a string from one character encoding to another
- iconv() - 将字符串从一个字符编码转换到另一个字符编码

# 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)

### 说明

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.

### 参数

`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`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

The converted string.

### 错误／异常

Throws a ValueError if the combination of different `mode`s is invalid. For example `"sS"`.

### 更新日志

版本 | 说明
--- | ---
8.2.0 | A ValueError is now thrown if the combination of different `mode`s is invalid.
8.0.0 | 现在 `encoding` 可以为 null。

### 示例

示例 #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";
    ?>

以上示例会输出：

    やまだ はなこ
    コウザバンゴウ 0123456

# mb_convert_variables

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_variables — 转换一个或多个变量的字符编码

### 说明

function mb_convert_variables(
string `$to_encoding`,
array|string `$from_encoding`,
mixed `&$var`,
mixed `&...$vars`
): string|false

将变量 `var` 和 `vars` 的编码从 `from_encoding` 转换成编码 `to_encoding`。

mb_convert_variables() 会拼接变量数组或对象中的字符串来检测编码，因为短字符串的检测往往会失败。因此，不能在一个数组或对象中混合使用编码。

### 参数

`to_encoding`

  将 string 转换成这个编码。

`from_encoding`

  `from_encoding` 可以指定为一个 array 或者逗号分隔的 string，它将尝试根据 `from-coding` 来检测编码。 当省略了 `from_encoding`，将使用 `detect_order`。

`var`

  `var` 是要转换的变量的引用。 参数可以接受 String、Array 和 Object 的类型。 mb_convert_variables() 假设所有的参数都具有同样的编码。

`vars`

  额外的 `var`。

### 返回值

成功时返回转换前的字符编码，失败时返回 `false`。

### 示例

示例 #1 mb_convert_variables() 示例

    <?php
    /* 转换变量 $post1、$post2 编码为内部（internal）编码 */
    $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 — 解码 MIME 头字段中的字符串

### 说明

function mb_decode_mimeheader(string `$string`): string

解码 MIME 头中编码过的 string `string`。

### 参数

`string`

  要解码的 string。

### 返回值

以内部（internal）字符编码解码的 string。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | 根据 » RFC 2047 规范，将下划线转换为空格。

### 参见

- mb_encode_mimeheader() - 为 MIME 头编码字符串

# mb_decode_numericentity

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_decode_numericentity — 根据 HTML 数字字符串解码成字符

### 说明

function mb_decode_numericentity(string `$string`, array `$map`, ?string `$encoding` = `null`): string

将 string 的数字字符串引用按指定的字符块转换成 `string`。

### 参数

`string`

  要解码的 string。

`map`

  `map` 是 array，指定了要转换的代码区域。

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

转换后的 string。

### 错误／异常

如果 `map` 不是 ints 的列表，抛出 ValueError。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 如果 `map` 不是 ints 的列表， mb_decode_numericentity() 现在抛出 ValueError。
8.0.0 | 现在 `encoding` 可以为 null。

### 示例

示例 #1 `map` 示例

    <?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.
    ?>

示例 #2 `map` 示例，转义 JavaScript 字符串

    <?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));

### 参见

- 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 — 检测字符的编码

### 说明

function mb_detect_encoding(string `$string`, array|string|null `$encodings` = `null`, bool `$strict` = `false`): string|false

从候选列表中检测 string `string` 最可能的字符编码。

自 PHP 8.1 起，此函数使用启发式检测指定列表中最有可能正确的有效文本编码，且可能不按照提供的 `encodings` 顺序进行检测。

对预期（intended）字符编码的自动检测不可能永远完全可靠；没有额外的信息，就类似于在没有密钥的情况下解码已编码的字符串。最好使用与数据一起存储或传输的字符编码表示，例如“Content-Type” HTTP 头。

此函数适用于多字节编码，但并非所有字节顺序都构成有效字符串。如果输入字符串包含这样的顺序，则将会拒绝该编码。

警告

# 结果不准确

此函数的名称具有误导性，它执行的是“猜测”而不是“检测”。

猜测结果远非准确，因此无法使用此函数准确检测正确的字符编码。

### 参数

`string`

  要检测的 string。

`encodings`

  尝试的字符编码列表。该列表可以指定为字符串数组，或以逗号分隔的单个字符串。

  如果省略 `encodings` 被或为 `null`，则将使用当前的 detect_order（使用 mbstring.detect_order 配置选项或 mb_detect_order() 函数设置）。

`strict`

  控制 `string` 在列出的所有 `encodings` 中无效时的行为。如果 `strict` 设置为 `false`，将返回最接近的匹配编码；如果 `strict` 设置为 `true`，将返回 `false`。

  可以使用 mbstring.strict_detection 配置选项设置 `strict` 的默认值。

### 返回值

检测到的字符编码，如果字符串在任何列出的编码中均无效，则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.2.0 | mb_detect_encoding() 将不再返回以下非文本编码：`"Base64"`、`"QPrint"`、`"UUencode"`、`"HTML entities"`、`"7 bit"` 和 `"8 bit"`。

### 示例

示例 #1 mb_detect_encoding() 示例

    <?php

    $str = "\x95\xB6\x8E\x9A\x83\x52\x81\x5B\x83\x68";

    // 使用当前的 detect_order 来检测字符编码
    var_dump(mb_detect_encoding($str));

    // “auto”将根据 mbstring.language 来扩展
    var_dump(mb_detect_encoding($str, "auto"));

    // 通过以逗号分隔的列表指定“encodings”参数
    var_dump(mb_detect_encoding($str, "JIS, eucjp-win, sjis-win"));

    // 使用数组指定“encodings”参数
    $encodings = [
      "ASCII",
      "JIS",
      "EUC-JP"
    ];
    var_dump(mb_detect_encoding($str, $encodings));
    ?>

以上示例会输出：

    string(5) "ASCII"
    string(5) "ASCII"
    string(8) "SJIS-win"
    string(5) "ASCII"

示例 #2 `strict` 参数的影响

    <?php
    // 'áéóú' 在 ISO-8859-1 中的编码
    $str = "\xE1\xE9\xF3\xFA";

    // 该字符串不是有效的 ASCII 或 UTF-8，但 UTF-8 被认为是更接近的匹配
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], false));
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], true));

    // 如果找到有效编码，则严格参数不会更改结果
    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));
    ?>

以上示例会输出：

    string(5) "UTF-8"
    bool(false)
    string(10) "ISO-8859-1"
    string(10) "ISO-8859-1"

在某些情况下，相同的字节顺序可能会在多种字符编码中形成有效的字符串，并且无法知道其意图是哪种解释。例如，在众多字符编码中，字节序列“\xC4\xA2”可能是：

- "Ä¢" (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

示例 #3 匹配多个编码时顺序的影响

    <?php
    $str = "\xC4\xA2";

    // 该字符串在所有三种编码中均有效，但返回的可能并不总是列表中的第一个编码
    var_dump(mb_detect_encoding($str, ['UTF-8']));
    var_dump(mb_detect_encoding($str, ['UTF-8', 'ISO-8859-1', 'ISO-8859-5'])); // 自 php8.1 起返回 ISO-8859-1 而不是 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']));
    ?>

以上示例会输出：

    string(5) "UTF-8"
    string(10) "ISO-8859-1"
    string(10) "ISO-8859-1"
    string(10) "ISO-8859-5"

### 参见

- mb_detect_order() - 设置/获取 字符编码的检测顺序

# mb_detect_order

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_detect_order — 设置/获取 字符编码的检测顺序

### 说明

function mb_detect_order(array|string|null `$encoding` = `null`): array|bool

为编码列表 `encoding` 设置自动检测字符编码的顺序。

### 参数

`encoding`

  `encoding` 是一个 array 或者逗号分隔的字符编码列表。 参见支持的编码。

  如果省略 `encoding` 或为 `null`，它将返回当前字符编码检测顺序的数组。

  该设置会影响 mb_detect_encoding() 和 mb_send_mail()。

  `mbstring` 当前实现了以下编码检测筛选器。 如有以下编码列表的无效字节序列，编码的检测将会失败。

  `UTF-8`, `UTF-7`, `ASCII`, `EUC-JP`,`SJIS`, `eucJP-win`, `SJIS-win`, `JIS`, `ISO-2022-JP`

  对于 `ISO-8859-*`，`mbstring` 总是检测为 `ISO-8859-*`。

  对于 `UTF-16`、`UTF-32`、 `UCS2` 和 `UCS4`，编码检测总是会失败。

### 返回值

设置编码检测顺序时候，成功时返回 `true`，识别时候返回 `false`。

在获取编码检测顺序的时候，会返回排序过的编码数组。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `encoding` 可以为 null。

### 示例

示例 #1 mb_detect_order() 示例

    <?php
    /* 为检测顺序设置枚举列表 */
    mb_detect_order("eucjp-win,sjis-win,UTF-8");

    /* 通过数组设置检测顺序 */
    $ary[] = "ASCII";
    $ary[] = "JIS";
    $ary[] = "EUC-JP";
    mb_detect_order($ary);

    /* 显示当前的检测顺序 */
    echo implode(", ", mb_detect_order());
    ?>

示例 #2 案例展示了无效的检测顺序

    ; 总是检测为 ISO-8859-1
    detect_order = ISO-8859-1, UTF-8

    ; 总是检测为 UTF-8，由于 ASCII/UTF-7 的值对  UTF-8 是有效的
    detect_order = UTF-8, ASCII, UTF-7

### 参见

- mb_internal_encoding() - 设置/获取内部字符编码
- mb_http_input() - 检测 HTTP 输入字符编码
- mb_http_output() - 设置/获取 HTTP 输出字符编码
- mb_send_mail() - 发送编码过的邮件

# mb_encode_mimeheader

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_encode_mimeheader — 为 MIME 头编码字符串

### 说明

function mb_encode_mimeheader(
string `$string`,
?string `$charset` = `null`,
?string `$transfer_encoding` = `null`,
string `$newline` = "\r\n",
int `$indent` = 0
): string

按 MIME 头编码方案将指定的字符串 `string` 进行编码。

### 参数

`string`

  要编码的 string。 它的编码应该和 mb_internal_encoding() 一样。

`charset`

  `charset` 指定了 `str` 的字符集名。 其默认值由当前的 NLS 设置（`mbstring.language`）来确定。

`transfer_encoding`

  `transfer_encoding` 指定了 MIME 的编码方案。 它可以是 `"B"`（Base64）也可以是 `"Q"`（Quoted-Printable）。 如果未设置，将回退为 `"B"`。

`newline`

  `newline` 指定了 EOL（行尾）标记，使 mb_encode_mimeheader() 执行了一个换行（» RFC 文档中规定，超过长度的一行将换成多行，当前该长度硬式编码为 74 个字符）。 如果没有设定，则回退为 `"\r\n"` (CRLF)。

`indent`

  首行缩进（header 里 `string` 前的字符数目）。

### 返回值

转换后的字符串版本以 ASCII 形式表达。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | 使用 Quoted-Printable 编码时，不再丢弃 `NUL`（0）字节， 而是编码为 `=00`。
8.0.0 | `charset` 和 `transfer_encoding` 现在可以为空。

### 示例

示例 #1 mb_encode_mimeheader() 例子

    <?php
    $name = "太郎"; // kanji
    $mbox = "kru";
    $doma = "gtinn.mon";
    $addr = '"' . addcslashes(mb_encode_mimeheader($name, "UTF-7", "Q"), '"') . '" <' . $mbox . "@" . $doma . ">";
    echo $addr;
    ?>

以上示例会输出：

    "=?UTF-7?Q?+WSqQzg-?=" <kru@gtinn.mon>

### 注释

> 注意:

> 这个函数没有设计成据更高级上下文的中断点来换行（单词边界等）。 这个特性将导致意外的空格可能会让原始字符串看上去很乱。

### 参见

- mb_decode_mimeheader() - 解码 MIME 头字段中的字符串

# mb_encode_numericentity

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_encode_numericentity — Encode character to HTML numeric string reference

### 说明

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.

### 参数

`string`

  The string being encoded.

`map`

  `map` is array specifies code area to convert.

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。
`hex`

  Whether the returned entity reference should be in hexadecimal notation (otherwise it is in decimal notation).

### 返回值

The converted string.

### 错误／异常

Throws a ValueError if `map` is not a list of ints.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | mb_encode_numericentity() now throws a ValueError if `map` is not a list of ints.
8.0.0 | 现在 `encoding` 可以为 null。

### 示例

示例 #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.
    ?>

示例 #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"));
    ?>

以上示例会输出：

    string(46) "&#97;&#65;&#230;&#198;&#12354;&#12450;&#40509;"
    string(28) "aA&#230;&#198;あア&#40509;"

### 参见

- mb_decode_numericentity() - 根据 HTML 数字字符串解码成字符

# mb_encoding_aliases

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mb_encoding_aliases — Get aliases of a known encoding type

### 说明

function mb_encoding_aliases(string `$encoding`): array

Returns an array of aliases for a known `encoding` type.

### 参数

`encoding`

  The encoding type being checked, for aliases.

### 返回值

Returns a numerically indexed array of encoding aliases.

### 错误／异常

Throws a ValueError if `encoding` is unknown.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | If the `encoding` is unknown, a ValueError is now thrown; previously an `E_WARNING` was emitted, and the function returned `false`.

### 示例

示例 #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";

    }
    ?>

以上示例的输出类似于：

    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
    )

### 参见

- mb_list_encodings() - 返回所有支持编码的数组

# mb_ereg

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg — Regular expression match with multibyte support

### 说明

function mb_ereg(string `$pattern`, string `$string`, array `&$matches` = `null`): bool

Executes the regular expression match with multibyte support.

### 参数

`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.

### 返回值

Returns whether `pattern` matches `string`.

### 更新日志

版本 | 说明
--- | ---
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.

### 注释

> 注意: mb_regex_encoding() 指定的内部编码或字符编码将会当作此函数用的字符编码。

### 参见

- 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

### 说明

function mb_ereg_match(string `$pattern`, string `$string`, ?string `$options` = `null`): bool

A regular expression match for a multibyte string

> 注意: `pattern` is only matched at the beginning of `string`.

### 参数

`pattern`

  The regular expression pattern.

`string`

  The string being evaluated.

`options`

  The search option. See mb_regex_set_options() for explanation.

### 返回值

Returns `true` if `string` matches the regular expression `pattern`, `false` if not.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `options` is nullable now.

### 注释

> 注意: mb_regex_encoding() 指定的内部编码或字符编码将会当作此函数用的字符编码。

### 参见

- 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

### 说明

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`

### 参数

`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.

### 返回值

The resultant string on success, or `false` on error. If `string` is not valid for the current encoding, `null` is returned.

### 更新日志

版本 | 说明
--- | ---
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.

### 注释

> 注意: mb_regex_encoding() 指定的内部编码或字符编码将会当作此函数用的字符编码。

警告

处理非信任的输入时从不使用 `e` 修饰符，就不会转码（即调用 preg_replace()）。不注意这些会很可能会导致应用程序引发远程代码执行的漏洞。

### 参见

- 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

### 说明

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`.

### 参数

`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.

### 返回值

The resultant string on success, or `false` on error. If `string` is not valid for the current encoding, `null` is returned.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `options` is nullable now.
7.1.0 | The function checks whether `string` is valid for the current encoding.

### 示例

示例 #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);

    ?>

以上示例会输出：

    April fools day is 04/01/2003
    Last christmas was 12/24/2002

示例 #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);
    ?>

### 注释

> 注意: mb_regex_encoding() 指定的内部编码或字符编码将会当作此函数用的字符编码。

### 参见

- 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

### 说明

function mb_ereg_search(?string `$pattern` = `null`, ?string `$options` = `null`): bool

Performs a multibyte regular expression match for a predefined multibyte string.

### 参数

`pattern`

  The search pattern.

`options`

  The search option. See mb_regex_set_options() for explanation.

### 返回值

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.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `pattern` and `options` are nullable now.

### 注释

> 注意: mb_regex_encoding() 指定的内部编码或字符编码将会当作此函数用的字符编码。

### 参见

- 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

### 说明

function mb_ereg_search_getpos(): int

Returns the start point for the next regular expression match.

### 参数

此函数没有参数。

### 返回值

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.

### 注释

> 注意: mb_regex_encoding() 指定的内部编码或字符编码将会当作此函数用的字符编码。

### 参见

- 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

### 说明

function mb_ereg_search_getregs(): array|false

Retrieve the result from the last multibyte regular expression match

### 参数

此函数没有参数。

### 返回值

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.

### 注释

> 注意: mb_regex_encoding() 指定的内部编码或字符编码将会当作此函数用的字符编码。

### 参见

- 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

### 说明

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().

### 参数

`string`

  The search string.

`pattern`

  The search pattern.

`options`

  The search option. See mb_regex_set_options() for explanation.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `pattern` and `options` are nullable now.

### 注释

> 注意: mb_regex_encoding() 指定的内部编码或字符编码将会当作此函数用的字符编码。

### 参见

- 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

### 说明

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.

### 参数

`pattern`

  The search pattern.

`options`

  The search option. See mb_regex_set_options() for explanation.

### 返回值

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.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `pattern` and `options` are nullable now.

### 注释

> 注意: mb_regex_encoding() 指定的内部编码或字符编码将会当作此函数用的字符编码。

### 参见

- 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

### 说明

function mb_ereg_search_regs(?string `$pattern` = `null`, ?string `$options` = `null`): array|false

Returns the matched part of a multibyte regular expression.

### 参数

`pattern`

  The search pattern.

`options`

  The search option. See mb_regex_set_options() for explanation.

### 返回值

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.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `pattern` and `options` are nullable now.

### 注释

> 注意: mb_regex_encoding() 指定的内部编码或字符编码将会当作此函数用的字符编码。

### 参见

- 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

### 说明

function mb_ereg_search_setpos(int `$offset`): bool

mb_ereg_search_setpos() sets the starting point of a match for mb_ereg_search().

### 参数

`offset`

  The position to set. If it is negative, it counts from the end of the string.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
7.1.0 | Support for negative `offset`s has been added.

### 注释

> 注意: mb_regex_encoding() 指定的内部编码或字符编码将会当作此函数用的字符编码。

### 参见

- 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

### 说明

function mb_eregi(string `$pattern`, string `$string`, array `&$matches` = `null`): bool

Executes the case insensitive regular expression match with multibyte support.

### 参数

`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.

### 返回值

Returns whether `pattern` matches `string`.

### 更新日志

版本 | 说明
--- | ---
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.

### 注释

> 注意: mb_regex_encoding() 指定的内部编码或字符编码将会当作此函数用的字符编码。

### 参见

- 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

### 说明

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`.

### 参数

`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.

### 返回值

The resultant string or `false` on error. If `string` is not valid for the current encoding, `null` is returned.

### 更新日志

版本 | 说明
--- | ---
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.

### 注释

> 注意: mb_regex_encoding() 指定的内部编码或字符编码将会当作此函数用的字符编码。

警告

处理非信任的输入时从不使用 `e` 修饰符，就不会转码（即调用 preg_replace()）。不注意这些会很可能会导致应用程序引发远程代码执行的漏洞。

### 参见

- 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 — 获取 mbstring 的内部设置

### 说明

function mb_get_info(string `$type` = "all"): array|string|int|false|null

mb_get_info() 返回 mbstring 参数的内部设定。

### 参数

`type`

  如果没有设定 `type` 或者将其设定为 `"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"` 和 `"strict_detection"`。

  如果 `type` 设定为类似 `"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"` 或 `"strict_detection"`，将返回该参数的设置。

### 返回值

如果没有指定 `type` 将返回类型信息的数组，否则将返回指定 `type` 的信息。 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 参数 `type` 中的 `"func_overload"` 和 `"func_overload_list"` 不再被支持。

### 参见

- mb_regex_encoding() - Set/Get character encoding for multibyte regex
- mb_http_output() - 设置/获取 HTTP 输出字符编码

# mb_http_input

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_http_input — 检测 HTTP 输入字符编码

### 说明

function mb_http_input(?string `$type` = `null`): array|string|false

检测 HTTP 输入字符的编码。

### 参数

`type`

  设置的字符串指定了输入类型。 `"G"` 是 GET，`"P"` 是 POST，`"C"` 是 COOKIE，`"S"` 是 string，`"L"` 是 list，以及 `"I"` 是整个列表（将会返回 array）。 如果省略了 type，它将返回最后处理的一种输入类型。

### 返回值

每个 `type` 的字符编码名称，如果 `type` 是 `"I"` 时为字符编码名称数组。 如果 mb_http_input() 没有处理过任何指定的 HTTP 输入，它将返回 `false`。

### 错误／异常

如果 `type` 无效，抛出 ValueError。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 如果 `type` 无效，mb_http_input() 现在抛出 ValueError。
8.0.0 | `type` 现在可为 null。

### 参见

- mb_internal_encoding() - 设置/获取内部字符编码
- mb_http_output() - 设置/获取 HTTP 输出字符编码
- mb_detect_order() - 设置/获取 字符编码的检测顺序

# mb_http_output

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_http_output — 设置/获取 HTTP 输出字符编码

### 说明

function mb_http_output(?string `$encoding` = `null`): string|bool

设置/获取 HTTP 输出字符编码。此函数被调用之后输出的内容会被转换成 `encoding`。

### 参数

`encoding`

  如果设置了 `encoding`，mb_http_output() 设置 HTTP 输出字符编码为 `encoding`。

  如果省略了 `encoding`，mb_http_output() 返回当前的 HTTP 输出字符编码。

### 返回值

如果省略了 `encoding`，mb_http_output() 返回当前的 HTTP 输出字符编码。 否则成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

如果 `encoding` 包含空字节，抛出 ValueError。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 如果 `encoding` 包含空字节， mb_http_output() 现在抛出 ValueError。
8.0.0 | 现在 `encoding` 可以为 null。

### 参见

- mb_internal_encoding() - 设置/获取内部字符编码
- mb_http_input() - 检测 HTTP 输入字符编码
- mb_detect_order() - 设置/获取 字符编码的检测顺序

# mb_internal_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_internal_encoding — 设置/获取内部字符编码

### 说明

function mb_internal_encoding(?string `$encoding` = `null`): string|bool

设置/获取内部字符编码

### 参数

`encoding`

  `encoding` 字符编码名称使用于 HTTP 输入字符编码转换、HTTP 输出字符编码转换、mbstring 模块系列函数字符编码转换的默认编码。内部编码与多字节正则表达式的编码完全不同。

### 返回值

如果设置了 `encoding`，则成功时返回 `true`， 或者在失败时返回 `false`。 在这种情况下，多字节正则表达式的字符编码不会改变。 如果省略了 `encoding`，则返回当前的字符编码名称。

### 错误／异常

从 PHP 8.0.0 起，如果 `encoding` 的值是无效编码，则会抛出 ValueError。在 PHP 8.0.0 之前，会发出 `E_WARNING`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `encoding` 可以为 null。
8.0.0 | 如果 `encoding` 是无效编码，现在抛出 ValueError。以前发出的是 `E_WARNING`。

### 示例

示例 #1 mb_internal_encoding() 示例

    <?php
    /* 设置内部字符编码为 UTF-8 */
    mb_internal_encoding("UTF-8");

    /* 显示当前的内部字符编码*/
    echo mb_internal_encoding();
    ?>

### 参见

- mb_http_input() - 检测 HTTP 输入字符编码
- mb_http_output() - 设置/获取 HTTP 输出字符编码
- mb_detect_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 — 设置/获取当前的语言

### 说明

function mb_language(?string `$language` = `null`): string|bool

设置/获取当前的语言。

### 参数

`language`

  用于编码邮件信息。下表列出了有效的语言。 mb_send_mail() 使用了该设置来对邮件进行编码。

  语言 | 字符 | 编码 | 别名
  --- | --- | --- | ---
  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
  简体中文/zh-cn | HZ | BASE64 |
  繁体中文/zh-tw | BIG-5 | BASE64 |

### 返回值

如果设置了 `language`，并且 `language` 是有效的，它将返回 `true`。否则将返回 `false`。 当省略了 `language` 或为 `null` 时，将返回语言名称的 string。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `language` 现在可为 null。

### 参见

- mb_send_mail() - 发送编码过的邮件

# mb_lcfirst

(PHP 8 >= 8.4.0)

mb_lcfirst — Make a string's first character lowercase

### 说明

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.

### 参数

`string`
  The input string.
`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

Returns the resulting string.

### 参见

- mb_ucfirst() - Make a string's first character uppercase
- lcfirst() - 使字符串的第一个字符小写

# mb_list_encodings

(PHP 5, PHP 7, PHP 8)

mb_list_encodings — 返回所有支持编码的数组

### 说明

function mb_list_encodings(): array

返回所有支持编码的数组。

### 参数

此函数没有参数。

### 返回值

返回一个数字索引数组。

### 错误／异常

该函数不会触发任何错误。

### 示例

示例 #1 mb_list_encodings() 例子

    <?php

    print_r(mb_list_encodings());

    ?>

以上示例的输出类似于：

    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
    )

### 参见

- 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

### 说明

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)，普通空格。
- `"\t"` (Unicode U+0009)，制表符。
- `"\n"`（Unicode U+000A)，新行（换行）。
- `"\r"`（Unicode U+000D），回车。
- `"\0"`（Unicode U+0000），NUL 字节。
- `"\v"`（Unicode U+000B），垂直制表符。
- `"\f"`（Unicode U+000C），换页符。
- `"\u00A0"`（Unicode U+00A0），NO-BREAK SPACE。
- `"\u1680"`（Unicode U+1680），OGHAM SPACE MARK。
- `"\u2000"`（Unicode U+2000），EN QUAD。
- `"\u2001"`（Unicode U+2001），EM QUAD。
- `"\u2002"`（Unicode U+2002），EN SPACE。
- `"\u2003"`（Unicode U+2003），EM SPACE。
- `"\u2004"`（Unicode U+2004），THREE-PER-EM SPACE。
- `"\u2005"`（Unicode U+2005），FOUR-PER-EM SPACE。
- `"\u2006"`（Unicode U+2006），SIX-PER-EM SPACE。
- `"\u2007"`（Unicode U+2007），FIGURE SPACE。
- `"\u2008"`（Unicode U+2008），PUNCTUATION SPACE。
- `"\u2009"`（Unicode U+2009），THIN SPACE。
- `"\u200A"`（Unicode U+200A），HAIR SPACE。
- `"\u2028"`（Unicode U+2028），LINE SEPARATOR。
- `"\u2029"`（Unicode U+2029），PARAGRAPH SEPARATOR。
- `"\u202F"`（Unicode U+202F），NARROW NO-BREAK SPACE。
- `"\u205F"`（Unicode U+205F），MEDIUM MATHEMATICAL SPACE。
- `"\u3000"`（Unicode U+3000），IDEOGRAPHIC SPACE。
- `"\u0085"`（Unicode U+0085），NEXT LINE (NEL)。
- `"\u180E"`（Unicode U+180E），MONGOLIAN VOWEL SEPARATOR。

### 参数

`string`
  The input string.
`characters`
  可选，也可以使用 `characters` 参数指定要删除的字符。只需列出所有需要删除的字符即可。
`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

This function returns a string with whitespace stripped from the beginning of `string`.

### 参见

- 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() - 删除字符串开头的空白字符（或其他字符）

# mb_ord

(PHP 7 >= 7.2.0, PHP 8)

mb_ord — 获取字符的 Unicode 码位值

### 说明

function mb_ord(string `$string`, ?string `$encoding` = `null`): int|false

返回所给定的字符的 Unicode 码位值。

此函数与 mb_chr() 互补。

### 参数

`string`

  一个字符串。

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

`string` 第一个字符的 Unicode 码位值， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `encoding` 可以为 null。

### 示例

示例 #1 一个基础的 mb_ord() 示例

    <?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"));
    ?>

以上示例会输出：

int(65)
int(128024)
int(128)
int(8364)

### 参见

- mb_internal_encoding() - 设置/获取内部字符编码
- mb_chr() - 按 Unicode 码位值返回字符
- IntlChar::ord() - Return Unicode code point value of character
- ord() - 转换字符串第一个字节为 0-255 之间的值

# mb_output_handler

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_output_handler — 在输出缓冲中转换字符编码的回调函数

### 说明

function mb_output_handler(string `$string`, int `$status`): string

mb_output_handler() 是一个 ob_start() 回调函数。 mb_output_handler() 将输出缓冲中的字符从内部字符编码转换为 HTTP 输出的字符编码。

### 参数

`string`

  输出缓冲的内容。

`status`

  输出缓冲的状态。

### 返回值

转换后的 string。

### 示例

示例 #1 mb_output_handler() 示例

    <?php
    mb_http_output("UTF-8");
    ob_start("mb_output_handler");
    ?>

### 注释

> 注意:

> 如果你想要输出二进制数据，比如图片，必须在任何二进制数据发送到客户端之前使用 header() 来设置 Content-Type: 头。（例如 header("Content-Type: image/png")）。 如果 Content-Type: 头已发送，输出字符编码的转换将不会执行。

> 注意，如果发送了 'Content-Type: text/*'，则内容被认为是文本，将发生转换。

### 参见

- ob_start() - 打开输出控制缓冲

# mb_parse_str

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_parse_str — 解析 GET/POST/COOKIE 数据并设置全局变量

### 说明

function mb_parse_str(string `$string`, array `&$result`): bool

解析 GET/POST/COOKIE 数据并设置全局变量。 由于 PHP 不提供原始 POST/COOKIE 数据，目前它仅能够用于 GET 数据。 它解析了 URL 编码过的数据，检测其编码，并转换编码为内部编码，然后设置其值为 array 的 `result` 或者全局变量。

### 参数

`string`

  URL 编码过的数据。

`result`

  一个 array，包含解码过的、编码转换后的值。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 第二个参数不再可选。
7.2.0 | 弃用在没有第二个参数的时候调用 mb_parse_str()。

### 参见

- mb_detect_order() - 设置/获取 字符编码的检测顺序
- mb_internal_encoding() - 设置/获取内部字符编码

# mb_preferred_mime_name

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_preferred_mime_name — 获取 MIME 字符串

### 说明

function mb_preferred_mime_name(string `$encoding`): string|false

获取指定编码的 MIME 字符 string。

### 参数

`encoding`

  要检查的字符串。

### 返回值

字符编码 `encoding` 的 MIME `charset` string，如果指定 `encoding` 没有首选字符集，则为 `false`。

### 示例

示例 #1 mb_preferred_mime_name() 示例

    <?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

### 说明

function mb_regex_encoding(?string `$encoding` = `null`): string|bool

Set/Get character encoding for a multibyte regex.

### 参数

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

If `encoding` is set, then 成功时返回 `true`， 或者在失败时返回 `false`。 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.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `encoding` 可以为 null。

### 参见

- mb_internal_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

### 说明

function mb_regex_set_options(?string `$options` = `null`): string

Sets the default options described by `options` for multibyte regex functions.

### 参数

`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 | 更新日志
  --- | --- | ---
  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

  > 注意:

  > 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

### 返回值

The previous options. If `options` is omitted or `null`, it returns the string that describes the current options.

### 更新日志

版本 | 说明
--- | ---
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`.

### 参见

- mb_split() - 使用正则表达式分割多字节字符串
- 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

### 说明

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)，普通空格。
- `"\t"` (Unicode U+0009)，制表符。
- `"\n"`（Unicode U+000A)，新行（换行）。
- `"\r"`（Unicode U+000D），回车。
- `"\0"`（Unicode U+0000），NUL 字节。
- `"\v"`（Unicode U+000B），垂直制表符。
- `"\f"`（Unicode U+000C），换页符。
- `"\u00A0"`（Unicode U+00A0），NO-BREAK SPACE。
- `"\u1680"`（Unicode U+1680），OGHAM SPACE MARK。
- `"\u2000"`（Unicode U+2000），EN QUAD。
- `"\u2001"`（Unicode U+2001），EM QUAD。
- `"\u2002"`（Unicode U+2002），EN SPACE。
- `"\u2003"`（Unicode U+2003），EM SPACE。
- `"\u2004"`（Unicode U+2004），THREE-PER-EM SPACE。
- `"\u2005"`（Unicode U+2005），FOUR-PER-EM SPACE。
- `"\u2006"`（Unicode U+2006），SIX-PER-EM SPACE。
- `"\u2007"`（Unicode U+2007），FIGURE SPACE。
- `"\u2008"`（Unicode U+2008），PUNCTUATION SPACE。
- `"\u2009"`（Unicode U+2009），THIN SPACE。
- `"\u200A"`（Unicode U+200A），HAIR SPACE。
- `"\u2028"`（Unicode U+2028），LINE SEPARATOR。
- `"\u2029"`（Unicode U+2029），PARAGRAPH SEPARATOR。
- `"\u202F"`（Unicode U+202F），NARROW NO-BREAK SPACE。
- `"\u205F"`（Unicode U+205F），MEDIUM MATHEMATICAL SPACE。
- `"\u3000"`（Unicode U+3000），IDEOGRAPHIC SPACE。
- `"\u0085"`（Unicode U+0085），NEXT LINE (NEL)。
- `"\u180E"`（Unicode U+180E），MONGOLIAN VOWEL SEPARATOR。

### 参数

`string`
  The input string.
`characters`
  可选，也可以使用 `characters` 参数指定要删除的字符。只需列出所有需要删除的字符即可。
`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

Returns the modified string.

### 参见

- 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() - 去除字符串末尾的空白字符（或者其他字符）

# mb_scrub

(PHP 7 >= 7.2.0, PHP 8)

mb_scrub — Replace ill-formed byte sequences with the substitute character

### 说明

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.

### 参数

`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.

### 返回值

The string result with invalid byte sequences replaced.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `encoding` 可以为 null。

# mb_send_mail

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_send_mail — 发送编码过的邮件

### 说明

function mb_send_mail(
string `$to`,
string `$subject`,
string `$message`,
array|string `$additional_headers` = [],
?string `$additional_params` = `null`
): bool

发送邮件。邮件头和内容根据 mb_language() 设置来转换编码。 这是 mail() 的一个包装器函数，所以详情参见 mail()。

### 参数

`to`

  被发送到该邮件地址。可通过逗号分隔地址的 `to` 来指定多个收件人。 该参数不会被自动编码。

`subject`

  邮件标题。

`message`

  邮件消息。

`additional_headers`（可选）

  要插入到电子邮件标头末尾的 string 或 array。

  这通常用于添加额外的标头（发件人、抄送和密件抄送）。多个额外的标头应该用 CRLF（\r\n）分隔。验证参数不会被攻击者注入不需要的标头。

  如果传递 array，则其键是标头名称，其值是相应的标头值。

  > 注意:

  > 发送邮件时，邮件必须包含 `From` 标头。这可以使用 `additional_headers` 参数设置，或者可以在 php.ini 中设置默认值。

  > 如果不这样做，将导致类似于 `Warning: mail(): "sendmail_from" not set in php.ini or custom "From:" header missing` 的错误消息。`From` 标头还设置了 Windows 下的 `Return-Path`。

  > 注意:

  > 如果未收到消息，请尝试仅使用 LF（\n）。一些 Unix 邮件传输代理（最著名的是 » qmail）自动将 LF 替换为 CRLF（如果使用 CRLF，这会导致两个 CR）。这应该是最后的手段，因为它不符合 » RFC 2822。

`additional_params`

  `additional_params` 是一个 MTA 命令行参数。在使用 sendmail 时对设置正确的返回路径头很有帮助。

  该参数由 escapeshellcmd() 内部转义以防止命令执行。escapeshellcmd() 阻止命令执行，但允许添加额外的参数。出于安全原因，应该验证此参数。

  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.

  Web 服务器运行的用户应作为受信任的用户添加到 sendmail 配置中，以防止在使用此方法设置信封发件人（-f）时将“X-Warning”标头添加到邮件中。对于 sendmail 用户，此文件为 /etc/mail/trusted-users。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `additional_params` 现在可为 null。
7.2.0 | `additional_headers` 参数现在也接受 array。

### 参见

- mail() - 发送邮件
- mb_encode_mimeheader() - 为 MIME 头编码字符串
- mb_language() - 设置/获取当前的语言

# mb_split

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_split — 使用正则表达式分割多字节字符串

### 说明

function mb_split(string `$pattern`, string `$string`, int `$limit` = -1): array|false

使用正则表达式 `pattern` 分割多字节 `string` 并返回结果 array。

### 参数

`pattern`

  正则表达式。

`string`

  待分割的 string。

`limit`
  如果指定了可选参数 `limit`，将最多分割为 `limit` 个元素。

### 返回值

结果为 array， 或者在失败时返回 `false`。

### 注释

> 注意: The character encoding specified by mb_regex_encoding() will be used as the character encoding for this function by default.

### 参见

- mb_regex_encoding() - Set/Get character encoding for multibyte regex
- mb_ereg() - Regular expression match with multibyte support
- explode() - 使用一个字符串分割另一个字符串

# mb_str_pad

(PHP 8 >= PHP 8.3.0)

mb_str_pad — Pad a multibyte string to a certain length with another multibyte string

### 说明

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.

### 参数

`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`

  > 注意:

  > 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`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

Returns the padded string.

### 示例

示例 #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 — 指定多字节字符串，返回其字符数组

### 说明

function mb_str_split(string `$string`, int `$length` = 1, ?string `$encoding` = `null`): array

此函数将返回一个字符串数组，这是一个支持字符变长编码以及 1、2、4 字节字符定长编码版本的 str_split()。 如果指定了 `length` 参数，则将字符串按指定的字符长度（而不是字节长度）拆分为块。 可以选择指定 `encoding` 参数，这样是很好的做法。

### 参数

`string`

  要拆分为单个字符或块的字符串。

`length`

  如果指定，则返回的数组中的每个元素将会由多个字符而不是单个字符组成。

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

  一个字符串，用于指定一种受支持的编码。

### 返回值

mb_str_split() 返回字符串数组。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `encoding` 可以为 null。
8.0.0 | 此函数在失败时不再返回 `false`。

### 参见

- str_split() - 将字符串转换为数组
- grapheme_str_split() - Split a string into an array
- explode() - 使用一个字符串分割另一个字符串

# mb_strcut

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strcut — 获取字符的一部分

### 说明

function mb_strcut(
string `$string`,
int `$start`,
?int `$length` = `null`,
?string `$encoding` = `null`
): string

mb_strcut() 和 mb_substr() 类似，都是从字符串中提取子字符串，但是按字节数来执行，而不是字符个数。 如果截断位置位于多字节字符两个字节的中间，将于该字符的第一个字节开始执行。 这也是和 substr() 函数的不同之处，后者简单地将字符串在字节之间截断，这将导致一个畸形的字节序列。

### 参数

`string`

  要截断的 string。

`start`

  如果 `start` 不是负数，返回的字符串会从 `string` 的第 `start` 字节位置开始，从 0 开始计数。举个例子，字符串 '`abcdef`'，字节位置 `0` 的字符是 '`a`'，字节位置 `2` 的字符是 '`c`'，以此类推。

  如果 `start` 是负数，返回的字符串是从 `string` 末尾倒数第 `start` 个字节开始的。但是，如果负 `start` 大于字符串的长度，则返回的部分将从 `string` 的开头开始。

`length`

  字节长度。如果省略或传递 `NULL`，则将所有字节提取到字符串的末尾。

  如果 `length` 为负数，则返回的字符串将在从 `string` 末尾倒数的第 `length` 个字节处结束。但是，如果负 `length` 大于 `start` 位置之后的字符数，则返回空字符串。

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

mb_strcut() 根据 `start` 和 `length` 参数返回 `string` 的一部分。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `encoding` 可以为 null。

### 参见

- mb_substr() - 获取部分字符串
- mb_internal_encoding() - 设置/获取内部字符编码

# mb_strimwidth

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strimwidth — 获取按指定宽度截断的字符串

### 说明

function mb_strimwidth(
string `$string`,
int `$start`,
int `$width`,
string `$trim_marker` = "",
?string `$encoding` = `null`
): string

将 string `string` 截断到指定 `width`。其中半角字符计为 `1`，全角字符计为 `2`。有关东亚字符宽度的详细信息，请参阅 » http://www.unicode.org/reports/tr11/。

### 参数

`string`

  要截断的 string。

`start`

  开始位置的偏移。从这些字符数开始的截取字符串。（默认是 0 个字符） 如果 start 是负数，就是字符串结尾处的字符数。

`width`

  所需修剪的宽度。如果指定负宽度，则从字符串末尾开始计数。

  > 注意:

  > 从 PHP 8.3.0 起，传递负宽度已被弃用。

`trim_marker`

  当字符串被截断的时候，将此字符串添加到截断后的末尾。

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

截断后的 string。如果设置了 `trim_marker`，还将结尾处的字符替换为 `trim_marker` ，并符合 `width` 的宽度。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | 将负的 `width` 传递给 mb_strimwidth() 现已废弃。
8.0.0 | 现在 `encoding` 可以为 null。
7.1.0 | 支持负数的 `start` 和 `width`。

### 示例

示例 #1 mb_strimwidth() 示例

    <?php
    echo mb_strimwidth("Hello World", 0, 10, "...");
    // 输出 Hello W...
    ?>

### 参见

- mb_strwidth() - 返回字符串的宽度
- mb_internal_encoding() - 设置/获取内部字符编码

# mb_stripos

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_stripos — 大小写不敏感地查找字符串在另一个字符串中首次出现的位置

### 说明

function mb_stripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

mb_stripos() 返回 `needle` 在字符串 `haystack` 中首次出现位置的数值。 和 mb_strpos() 不同的是，mb_stripos() 是大小写不敏感的。 如果 `needle` 没找到，它将返回 `false`。

### 参数

`haystack`

  在这个字符串中查找获取 `needle` 首次出现的位置

`needle`

  在 `haystack` 中查找这个字符串

`offset`

  `haystack` 里开始搜索的位置。如果是负数，就从字符串的尾部开始统计。

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

返回字符串 `haystack` 中 `needle` 首次出现位置的数值。 如果没有找到 `needle`，它将返回 `false`。

### 错误／异常

- 如果 `offset` 大于 `haystack` 的长度，则会抛出 ValueError 异常。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `needle` 接受空字符串。
8.0.0 | 现在 `encoding` 可以为 null。
7.1.0 | 支持 `offset` 使用负数。

### 参见

- stripos() - 查找字符串首次出现的位置（不区分大小写）
- strpos() - 查找字符串首次出现的位置
- mb_strpos() - 查找字符串在另一个字符串中首次出现的位置

# mb_stristr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_stristr — 大小写不敏感地查找字符串在另一个字符串里的首次出现

### 说明

function mb_stristr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

mb_strstr() 查找了 `needle` 在 `haystack` 中首次的出现并返回 `haystack` 的一部分。 和 mb_strstr() 不同的是，mb_stristr() 是大小写不敏感的。 如果 `needle` 没有找到，它将返回 `false`。

### 参数

`haystack`

  要获取 `needle` 首次出现的字符串。

`needle`

  在 `haystack` 中查找这个字符串。

`before_needle`

  决定这个函数返回 `haystack` 的哪一部分。 如果设置为 `true`，它返回 `haystack` 中从开始到 `needle` 出现位置的所有字符（不包括 needle）。 如果设置为 `false`，它返回 `haystack` 中 `needle` 出现位置到最后的所有字符（包括了 needle）。

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

返回 `haystack` 的一部分，或者 `needle` 没找到则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `needle` 接受空字符串。
8.0.0 | 现在 `encoding` 可以为 null。

### 参见

- stristr() - strstr 函数的忽略大小写版本
- strstr() - 查找字符串的首次出现
- mb_strstr() - 查找字符串在另一个字符串里的首次出现

# mb_strlen

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strlen — 获取字符串的长度

### 说明

function mb_strlen(string `$string`, ?string `$encoding` = `null`): int

获取一个 string 的长度。

### 参数

`string`

  要检查长度的 string。

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

返回具有 `encoding` 编码的 string `string` 包含的字符数。 多字节的字符被计为 1。

### 错误／异常

如果 encoding 未知，则会生成 `E_WARNING` 级别的错误。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `encoding` 可以为 null。

### 参见

- mb_internal_encoding() - 设置/获取内部字符编码
- grapheme_strlen() - Get string length in grapheme units
- iconv_strlen() - 返回字符串的字符数统计
- strlen() - 获取字符串长度

# mb_strpos

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strpos — 查找字符串在另一个字符串中首次出现的位置

### 说明

function mb_strpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

查找 `needle` 在 `haystack` 中首次出现的位置。

基于字符数执行一个多字节安全的 strpos() 操作。 第一个字符的位置是 0，第二个字符的位置是 1，以此类推。

### 参数

`haystack`

  要在这个字符串里获取 `needle` 首次出现的位置。

`needle`

  在 `haystack` 中查找这个字符串。 和 strpos() 不同的是，数字的值不会被当做字符的顺序值。

`offset`

  搜索位置的偏移。如果没有提供该参数，将会使用 0。负数的 offset 会从字符串尾部开始统计。

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

返回 string 的 `haystack` 中 `needle` 首次出现位置的数值。 如果没有找到 `needle`，它将返回 `false`。

### 错误／异常

- 如果 `offset` 大于 `haystack` 的长度，则会抛出 ValueError 异常。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `needle` 接受空字符串。
8.0.0 | 现在 `encoding` 可以为 null。
7.1.0 | 支持负数的 `offset`。

### 参见

- mb_internal_encoding() - 设置/获取内部字符编码
- strpos() - 查找字符串首次出现的位置

# mb_strrchr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strrchr — 查找指定字符在另一个字符串中最后一次的出现

### 说明

function mb_strrchr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

mb_strrchr() 查找了 `needle` 在 `haystack` 中最后一次出现的位置，并返回 `haystack` 的部分。 如果没有找到 `needle`，它将返回 `false`。

### 参数

`haystack`

  在该字符串中查找 `needle` 最后出现的位置。

`needle`

  在 `haystack` 中查找这个字符串。

`before_needle`

  决定这个函数返回 `haystack` 的哪一部分。 如果设置为 `true`，它将返回的字符是从 `haystack` 的开始到 `needle` 最后出现的位置。 如果设置为 `false`，它将返回的字符是从 `needle` 最后出现的位置到 `haystack` 的末尾。

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

返回 `haystack` 的一部分，或者在没有找到 `needle` 时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `needle` 接受空字符串。
8.0.0 | 现在 `encoding` 可以为 null。

### 参见

- strrchr() - 查找指定字符在字符串中的最后一次出现
- mb_strstr() - 查找字符串在另一个字符串里的首次出现
- mb_strrichr() - 大小写不敏感地查找指定字符在另一个字符串中最后一次的出现

# mb_strrichr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strrichr — 大小写不敏感地查找指定字符在另一个字符串中最后一次的出现

### 说明

function mb_strrichr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

mb_strrichr() 大小写不敏感地查找指定 `needle` 在 `haystack` 中最后一次的出现，并返回 `haystack` 的一部分。 和 mb_strrchr() 不同的是，mb_strrichr() 是大小写不敏感的。 如果 `needle` 没有找到，它将返回 `false`。

### 参数

`haystack`

  在该字符串中查找 `needle` 的最后出现位置。

`needle`

  在 `needle` 中查找该字符串。

`before_needle`

  决定这个函数返回 `haystack` 的哪一部分。 如果设置为 `true`，它将返回的字符是从 `haystack` 的开始到 `needle` 最后出现的位置。 如果设置为 `false`，它将返回的字符是从 `needle` 最后出现的位置到 `haystack` 的末尾。

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

返回 `haystack` 的一部分。或者在没有找到 `needle` 时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `needle` 接受空字符串。
8.0.0 | 现在 `encoding` 可以为 null。

### 参见

- mb_stristr() - 大小写不敏感地查找字符串在另一个字符串里的首次出现
- mb_strrchr() - 查找指定字符在另一个字符串中最后一次的出现

# mb_strripos

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strripos — 大小写不敏感地在字符串中查找一个字符串最后出现的位置

### 说明

function mb_strripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

mb_strripos() 基于字符数执行一个多字节安全的 strripos() 操作。 `needle` 的位置是从 `haystack` 的开始进行统计的。 第一个字符的位置是 0，第二个字符的位置是 1。 和 mb_strrpos() 不同的是，mb_strripos() 是大小写不敏感的。

### 参数

`haystack`

  查找 `needle` 在这个字符串中最后出现的位置。

`needle`

  在 `haystack` 中查找这个字符串。

`offset`

  可以指定从 `haystack` 的任意字符位置开始搜索。负值将在 `haystack` 结尾前的某个点停止搜索。

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

返回字符串 `haystack` 中 `needle` 最后出现位置的数值。 如果没有找到 `needle`，它将返回 `false`。

### 错误／异常

- 如果 `offset` 大于 `haystack` 的长度，则会抛出 ValueError 异常。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `needle` 接受空字符串。
8.0.0 | 现在 `encoding` 可以为 null。

### 参见

- strripos() - 计算指定字符串在目标字符串中最后一次出现的位置（不区分大小写）
- strrpos() - 计算指定字符串在目标字符串中最后一次出现的位置
- mb_strrpos() - 查找字符串在一个字符串中最后出现的位置

# mb_strrpos

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strrpos — 查找字符串在一个字符串中最后出现的位置

### 说明

function mb_strrpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

基于字符数执行一个多字节安全的 strrpos() 操作。 `needle` 的位置是从 `haystack` 的开始进行统计的。 第一个字符的位置是 0，第二个字符的位置是 1。

### 参数

`haystack`

  查找 `needle` 在这个 string 中最后出现的位置。

`needle`

  在 `haystack` 中查找这个 string。

`offset`
  可以指定从 `haystack` 的任意字符位置开始搜索。负值将在 `haystack` 结尾前的某个点停止搜索。
`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

返回 string 的 `haystack` 中，`needle` 最后出现位置的数值。 如果没有找到 `needle`，它将返回 `false`。

### 错误／异常

- If `offset` is greater than the length of `haystack`, a ValueError will be thrown.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `needle` 接受空字符串。
8.0.0 | 已经删除将 `encoding` 作为第三个参数而不是 `offset` 传递。
8.0.0 | 现在 `encoding` 可以为 null。

### 参见

- mb_strpos() - 查找字符串在另一个字符串中首次出现的位置
- mb_internal_encoding() - 设置/获取内部字符编码
- strrpos() - 计算指定字符串在目标字符串中最后一次出现的位置

# mb_strstr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strstr — 查找字符串在另一个字符串里的首次出现

### 说明

function mb_strstr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

mb_strstr() 查找了 `needle` 在 `haystack` 中首次的出现并返回 `haystack` 的一部分。 如果 `needle` 没有找到，它将返回 `false`。

### 参数

`haystack`

  要获取 `needle` 首次出现的字符串。

`needle`

  在 `haystack` 中查找这个字符串。

`before_needle`

  决定这个函数返回 `haystack` 的哪一部分。 如果设置为 `true`，它返回 `haystack` 中从开始到 `needle` 出现位置的所有字符（不包括 needle）。 如果设置为 `false`，它返回 `haystack` 中 `needle` 出现位置到最后的所有字符（包括了 needle）。

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

返回 `haystack` 的一部分，或者 `needle` 没找到则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `needle` 接受空字符串。
8.0.0 | 现在 `encoding` 可以为 null。

### 参见

- stristr() - strstr 函数的忽略大小写版本
- strstr() - 查找字符串的首次出现
- mb_stristr() - 大小写不敏感地查找字符串在另一个字符串里的首次出现

# mb_strtolower

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_strtolower — 使字符串小写

### 说明

function mb_strtolower(string `$string`, ?string `$encoding` = `null`): string

返回所有字母字符转换成小写的 `string`。

### 参数

`string`

  要被小写的 string。

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

所有字母字符已被转换成小写的 `string`。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | 为希腊字母 sigma 实现了条件性大小写规则。

### 示例

示例 #1 mb_strtolower() 示例

    <?php
    $str = "Mary Had A Little Lamb and She LOVED It So";
    $str = mb_strtolower($str);
    echo $str; // 输出： mary had a little lamb and she loved it so
    ?>

示例 #2 非拉丁 UTF-8 文本的 mb_strtolower() 例子

    <?php
    $str = "Τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός";
    $str = mb_strtolower($str, 'UTF-8');
    echo $str; // 输出 τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός
    ?>

### 注释

和 strtolower() 不同的是，“字母”字符的检测是根据字符的 Unicode 属性。因此函数的行为不会受语言设置的影响，能偶转换任意具有“字母”属性的字符，例如元音变音 A（ä）。

更多关于 Unicode 属性的信息，请参见 » http://www.unicode.org/reports/tr21/。

### 参见

- mb_strtoupper() - 使字符串大写
- mb_convert_case() - 对字符串进行大小写转换
- strtolower() - 将字符串转化为小写

# mb_strtoupper

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_strtoupper — 使字符串大写

### 说明

function mb_strtoupper(string `$string`, ?string `$encoding` = `null`): string

将所有的字母字符转化成大写并返回 `string`。

### 参数

`string`

  要大写的 string。

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

`string` 里所有的字母都转换成大写的。

### 示例

示例 #1 mb_strtoupper() 示例

    <?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
    ?>

示例 #2 非拉丁 UTF-8 文本的 mb_strtoupper() 示例

    <?php
    $str = "Τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός";
    $str = mb_strtoupper($str, 'UTF-8');
    echo $str; // 打印了 ΤΆΧΙΣΤΗ ΑΛΏΠΗΞ ΒΑΦΉΣ ΨΗΜΈΝΗ ΓΗ, ΔΡΑΣΚΕΛΊΖΕΙ ΥΠΈΡ ΝΩΘΡΟΎ ΚΥΝΌΣ
    ?>

### 注释

和 strtoupper() 不同的是，“字母”是通过 Unicode 字符属性来确定的。 因此这个函数不会受语言环境（locale）设置影响，能够转化任何具有“字母”属性的字符，例如 a 变音符号（ä）。

更多 Unicode 属性的信息，请参见 » http://www.unicode.org/reports/tr21/。

### 参见

- mb_strtolower() - 使字符串小写
- mb_convert_case() - 对字符串进行大小写转换
- strtoupper() - 将字符串转化为大写

# mb_strwidth

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strwidth — 返回字符串的宽度

### 说明

function mb_strwidth(string `$string`, ?string `$encoding` = `null`): int

返回 string 类型 `string` 的宽度，其中半角字符计为 `1`，全角字符计为 `2`。有关东亚字符宽度的详细信息，请参见 » http://www.unicode.org/reports/tr11/。

全角字符是： `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`。 其它所有字符都是半角字符。

### 参数

`string`

  待解码的 string。

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

string `string` 的宽度。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `encoding` 可以为 null。

### 示例

示例 #1 mb_strwidth() 示例

    <?php
    var_dump(
        mb_strwidth('a'),       // 拉丁文小写字母 A
        mb_strwidth("\u{ff41}") // 全角拉丁文小写字母 A
    );
    ?>

以上示例会输出：

    int(1)
    int(2)

### 参见

- mb_strimwidth() - 获取按指定宽度截断的字符串
- mb_internal_encoding() - 设置/获取内部字符编码

# mb_substitute_character

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_substitute_character — 设置/获取替代字符

### 说明

function mb_substitute_character(string|int|null `$substitute_character` = `null`): string|int|bool

当输入字符的编码是无效的，或者字符代码不存在于输出的字符编码中时，可以为其指定一个替代字符。 无效字符可以被替换为 `"none"`（不输出）、string 或者 int 值（Unicode 字符代码的值）。

该设置会影响 mb_convert_encoding()、 mb_convert_variables()、 mb_output_handler()、 mb_scrub() 和 mb_send_mail()。

### 参数

`substitute_character`

  指定 Unicode 值为一个 int，或者是以下 string 中的一个：

  - `"none"`：不输出
  - `"long"`：输出字符代码的值（比如：`U+3000`、`JIS+7E7E`）
  - `"entity"`：输出字符的实体（比如：`&#x200;`）

### 返回值

如果设置了 `substitute_character`，在成功时返回 `true`，失败时返回 `false`。 如果没有设置 `substitute_character`，它将返回当前设置。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 不再支持将空字符串传递给 `substitute_character`；应该传递 `"none"`。
8.0.0 | 现在 `encoding` 可以为 null。

### 示例

示例 #1 mb_substitute_character() 示例

    <?php
    /* 设置为 Unicode U+3013 (GETA MARK) */
    mb_substitute_character(0x3013);

    /* 设置十六进制格式 */
    mb_substitute_character("long");

    /* 显示当前设置 */
    echo mb_substitute_character();
    ?>

# mb_substr

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_substr — 获取部分字符串

### 说明

function mb_substr(
string `$string`,
int `$start`,
?int `$length` = `null`,
?string `$encoding` = `null`
): string

根据字符数执行一个多字节安全的 substr() 操作。 位置是从 `string` 的开始位置进行计数。 第一个字符的位置是 0。第二个字符的位置是 1，以此类推。

### 参数

`string`

  从该 string 中提取子字符串。

`start`

  如果 `start` 不是负数，返回的字符串会从 `string` 第 `start` 的位置开始，从 0 开始计数。举个例子，字符串 '`abcdef`'，位置 `0` 的字符是 '`a`'，位置 `2` 的字符是 '`c`'，以此类推。

  如果 `start` 是负数，返回的字符串是从 `string` 末尾处第 `start` 个字符开始的。

`length`

  `string` 中要使用的最大字符数。如果省略了此参数或者传入了 `NULL`，则会提取到字符串的尾部。

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

mb_substr() 函数根据 `start` 和 `length` 参数返回 `string` 中指定的部分。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `encoding` 可以为 null。

### 参见

- mb_strcut() - 获取字符的一部分
- mb_internal_encoding() - 设置/获取内部字符编码

# mb_substr_count

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_substr_count — 统计字符串出现的次数

### 说明

function mb_substr_count(string `$haystack`, string `$needle`, ?string `$encoding` = `null`): int

统计子字符串 `needle` 出现在字符串 `haystack` 中的次数。

### 参数

`haystack`

  要检查的字符串。

`needle`

  待查找的字符串。

`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

子字符串 `needle` 出现在 string `haystack` 中的次数。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `encoding` 可以为 null。

### 示例

示例 #1 mb_substr_count() 示例

    <?php
    echo mb_substr_count("This is a test", "is"); // 输出 2
    ?>

### 参见

- mb_strpos() - 查找字符串在另一个字符串中首次出现的位置
- mb_substr() - 获取部分字符串
- substr_count() - 计算字串出现的次数

# mb_trim

(PHP 8 >= 8.4.0)

mb_trim — Strip whitespace (or other characters) from the beginning and end of a string

### 说明

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)，普通空格。
- `"\t"` (Unicode U+0009)，制表符。
- `"\n"`（Unicode U+000A)，新行（换行）。
- `"\r"`（Unicode U+000D），回车。
- `"\0"`（Unicode U+0000），NUL 字节。
- `"\v"`（Unicode U+000B），垂直制表符。
- `"\f"`（Unicode U+000C），换页符。
- `"\u00A0"`（Unicode U+00A0），NO-BREAK SPACE。
- `"\u1680"`（Unicode U+1680），OGHAM SPACE MARK。
- `"\u2000"`（Unicode U+2000），EN QUAD。
- `"\u2001"`（Unicode U+2001），EM QUAD。
- `"\u2002"`（Unicode U+2002），EN SPACE。
- `"\u2003"`（Unicode U+2003），EM SPACE。
- `"\u2004"`（Unicode U+2004），THREE-PER-EM SPACE。
- `"\u2005"`（Unicode U+2005），FOUR-PER-EM SPACE。
- `"\u2006"`（Unicode U+2006），SIX-PER-EM SPACE。
- `"\u2007"`（Unicode U+2007），FIGURE SPACE。
- `"\u2008"`（Unicode U+2008），PUNCTUATION SPACE。
- `"\u2009"`（Unicode U+2009），THIN SPACE。
- `"\u200A"`（Unicode U+200A），HAIR SPACE。
- `"\u2028"`（Unicode U+2028），LINE SEPARATOR。
- `"\u2029"`（Unicode U+2029），PARAGRAPH SEPARATOR。
- `"\u202F"`（Unicode U+202F），NARROW NO-BREAK SPACE。
- `"\u205F"`（Unicode U+205F），MEDIUM MATHEMATICAL SPACE。
- `"\u3000"`（Unicode U+3000），IDEOGRAPHIC SPACE。
- `"\u0085"`（Unicode U+0085），NEXT LINE (NEL)。
- `"\u180E"`（Unicode U+180E），MONGOLIAN VOWEL SEPARATOR。

### 参数

`string`
  The string that will be trimmed.
`characters`
  可选，也可以使用 `characters` 参数指定要删除的字符。只需列出所有需要删除的字符即可。
`encoding`
  `encoding` 参数为字符编码。如果省略或是 `null`，则使用内部字符编码。

### 返回值

The trimmed string.

### 参见

- 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() - 去除字符串首尾处的空白字符（或者其他字符）

# mb_ucfirst

(PHP 8 >= 8.4.0)

mb_ucfirst — Make a string's first character uppercase

### 说明

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.

### 参数

`string`
  The input string.
`encoding`
  The string encoding.

### 返回值

Returns the resulting string.

### 注释

> 注意:

> 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/.

### 参见

- mb_lcfirst() - Make a string's first character lowercase
- mb_convert_case() - 对字符串进行大小写转换
- ucfirst() - 将字符串的首字母转换为大写

## 目录

- mb_check_encoding — 检查字符串在指定的编码里是否有效
- mb_chr — 按 Unicode 码位值返回字符
- mb_convert_case — 对字符串进行大小写转换
- mb_convert_encoding — 转换字符串，从一个字符编码到另一个字符编码
- mb_convert_kana — Convert "kana" one from another ("zen-kaku", "han-kaku" and more)
- mb_convert_variables — 转换一个或多个变量的字符编码
- mb_decode_mimeheader — 解码 MIME 头字段中的字符串
- mb_decode_numericentity — 根据 HTML 数字字符串解码成字符
- mb_detect_encoding — 检测字符的编码
- mb_detect_order — 设置/获取 字符编码的检测顺序
- mb_encode_mimeheader — 为 MIME 头编码字符串
- 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 — 获取 mbstring 的内部设置
- mb_http_input — 检测 HTTP 输入字符编码
- mb_http_output — 设置/获取 HTTP 输出字符编码
- mb_internal_encoding — 设置/获取内部字符编码
- mb_language — 设置/获取当前的语言
- mb_lcfirst — Make a string's first character lowercase
- mb_list_encodings — 返回所有支持编码的数组
- mb_ltrim — Strip whitespace (or other characters) from the beginning of a string
- mb_ord — 获取字符的 Unicode 码位值
- mb_output_handler — 在输出缓冲中转换字符编码的回调函数
- mb_parse_str — 解析 GET/POST/COOKIE 数据并设置全局变量
- mb_preferred_mime_name — 获取 MIME 字符串
- 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 — 发送编码过的邮件
- mb_split — 使用正则表达式分割多字节字符串
- mb_str_pad — Pad a multibyte string to a certain length with another multibyte string
- mb_str_split — 指定多字节字符串，返回其字符数组
- mb_strcut — 获取字符的一部分
- mb_strimwidth — 获取按指定宽度截断的字符串
- mb_stripos — 大小写不敏感地查找字符串在另一个字符串中首次出现的位置
- mb_stristr — 大小写不敏感地查找字符串在另一个字符串里的首次出现
- mb_strlen — 获取字符串的长度
- mb_strpos — 查找字符串在另一个字符串中首次出现的位置
- mb_strrchr — 查找指定字符在另一个字符串中最后一次的出现
- mb_strrichr — 大小写不敏感地查找指定字符在另一个字符串中最后一次的出现
- mb_strripos — 大小写不敏感地在字符串中查找一个字符串最后出现的位置
- mb_strrpos — 查找字符串在一个字符串中最后出现的位置
- mb_strstr — 查找字符串在另一个字符串里的首次出现
- mb_strtolower — 使字符串小写
- mb_strtoupper — 使字符串大写
- mb_strwidth — 返回字符串的宽度
- mb_substitute_character — 设置/获取替代字符
- mb_substr — 获取部分字符串
- mb_substr_count — 统计字符串出现的次数
- mb_trim — Strip whitespace (or other characters) from the beginning and end of a string
- mb_ucfirst — Make a string's first character uppercase

- 安装/配置
  - 安装
  - 运行时配置
- 预定义常量
- 支持编码的摘要
- 日文字符多字节编码基础
- HTTP 输入和输出
- 支持的字符编码
- 函数重载功能
- PHP字符编码的要求
- 多字节字符串 函数
  - mb_check_encoding — 检查字符串在指定的编码里是否有效
  - mb_chr — 按 Unicode 码位值返回字符
  - mb_convert_case — 对字符串进行大小写转换
  - mb_convert_encoding — 转换字符串，从一个字符编码到另一个字符编码
  - mb_convert_kana — Convert "kana" one from another ("zen-kaku", "han-kaku" and more)
  - mb_convert_variables — 转换一个或多个变量的字符编码
  - mb_decode_mimeheader — 解码 MIME 头字段中的字符串
  - mb_decode_numericentity — 根据 HTML 数字字符串解码成字符
  - mb_detect_encoding — 检测字符的编码
  - mb_detect_order — 设置/获取 字符编码的检测顺序
  - mb_encode_mimeheader — 为 MIME 头编码字符串
  - 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 — 获取 mbstring 的内部设置
  - mb_http_input — 检测 HTTP 输入字符编码
  - mb_http_output — 设置/获取 HTTP 输出字符编码
  - mb_internal_encoding — 设置/获取内部字符编码
  - mb_language — 设置/获取当前的语言
  - mb_lcfirst — Make a string's first character lowercase
  - mb_list_encodings — 返回所有支持编码的数组
  - mb_ltrim — Strip whitespace (or other characters) from the beginning of a string
  - mb_ord — 获取字符的 Unicode 码位值
  - mb_output_handler — 在输出缓冲中转换字符编码的回调函数
  - mb_parse_str — 解析 GET/POST/COOKIE 数据并设置全局变量
  - mb_preferred_mime_name — 获取 MIME 字符串
  - 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 — 发送编码过的邮件
  - mb_split — 使用正则表达式分割多字节字符串
  - mb_str_pad — Pad a multibyte string to a certain length with another multibyte string
  - mb_str_split — 指定多字节字符串，返回其字符数组
  - mb_strcut — 获取字符的一部分
  - mb_strimwidth — 获取按指定宽度截断的字符串
  - mb_stripos — 大小写不敏感地查找字符串在另一个字符串中首次出现的位置
  - mb_stristr — 大小写不敏感地查找字符串在另一个字符串里的首次出现
  - mb_strlen — 获取字符串的长度
  - mb_strpos — 查找字符串在另一个字符串中首次出现的位置
  - mb_strrchr — 查找指定字符在另一个字符串中最后一次的出现
  - mb_strrichr — 大小写不敏感地查找指定字符在另一个字符串中最后一次的出现
  - mb_strripos — 大小写不敏感地在字符串中查找一个字符串最后出现的位置
  - mb_strrpos — 查找字符串在一个字符串中最后出现的位置
  - mb_strstr — 查找字符串在另一个字符串里的首次出现
  - mb_strtolower — 使字符串小写
  - mb_strtoupper — 使字符串大写
  - mb_strwidth — 返回字符串的宽度
  - mb_substitute_character — 设置/获取替代字符
  - mb_substr — 获取部分字符串
  - mb_substr_count — 统计字符串出现的次数
  - 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

# 简介

警告

This extension is DEPRECATED and UNBUNDLED as of PHP 8.4.0.

These functions allow you to check the spelling of a word and offer suggestions.

# 安装/配置

## 目录

- 需求
- 安装
- 资源类型

## 需求

To compile PHP with pspell support, you need the aspell library, available from » http://aspell.net/.

## 安装

## PHP 8.4

此扩展已被移至 » PECL 资源库；不再与 PHP 捆绑，从 PHP 8.4.0

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/pspell.

## PHP < 8.4

To enable this extension compile PHP with the --with-pspell[=dir] option.

> 注意: Note to Win32 Users

> 为了使此扩展生效， DLL 文件必须能在 Windows 系统的 PATH 指示的路径下找到。如何操作的信息，请参见题为“如何在 Windows 中将 PHP 目录加到 PATH 中”的FAQ。虽然将 DLL 文件从 PHP 文件夹复制到 Windows 系统目录也行，但不建议这样做。 此扩展需要下列文件在 PATH 路径中： aspell-15.dll from the bin folder of the aspell installation.

> Win32 support requires at least aspell version 0.50.

## 资源类型

Prior to PHP 8.1.0, there were two resource types used in this extension. The first one is the dictionary link identifier, the second is a resource which holds pspell config.

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`PSPELL_FAST` (int)
`PSPELL_NORMAL` (int)
`PSPELL_BAD_SPELLERS` (int)
`PSPELL_RUN_TOGETHER` (int)

# Pspell 函数

# pspell_add_to_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_add_to_personal — Add the word to a personal wordlist

### 说明

function pspell_add_to_personal(PSpell\Dictionary `$dictionary`, string `$word`): bool

pspell_add_to_personal() adds a word to the personal wordlist. If you used pspell_new_config() with pspell_config_personal() to open the dictionary, you can save the wordlist later with pspell_save_wordlist().

### 参数

`dictionary`
  An PSpell\Dictionary instance.
`word`

  The added word.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The `dictionary` parameter expects an PSpell\Dictionary instance now; previously, a resource was expected.

### 示例

示例 #1 pspell_add_to_personal()

    <?php
    $pspell_config = pspell_config_create("en");
    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);
    ?>

### 注释

> 注意:

> This function will not work unless you have pspell .11.2 and aspell .32.5 or later.

# pspell_add_to_session

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_add_to_session — Add the word to the wordlist in the current session

### 说明

function pspell_add_to_session(PSpell\Dictionary `$dictionary`, string `$word`): bool

pspell_add_to_session() adds a word to the wordlist associated with the current session. It is very similar to pspell_add_to_personal()

### 参数

`dictionary`
  An PSpell\Dictionary instance.
`word`

  The added word.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The `dictionary` parameter expects an PSpell\Dictionary instance now; previously, a resource was expected.

# pspell_check

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_check — Check a word

### 说明

function pspell_check(PSpell\Dictionary `$dictionary`, string `$word`): bool

pspell_check() checks the spelling of a word.

### 参数

`dictionary`
  An PSpell\Dictionary instance.
`word`

  The tested word.

### 返回值

Returns `true` if the spelling is correct, `false` if not.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The `dictionary` parameter expects an PSpell\Dictionary instance now; previously, a resource was expected.

### 示例

示例 #1 pspell_check() Example

    <?php
    $pspell = pspell_new("en");

    if (pspell_check($pspell, "testt")) {
        echo "This is a valid spelling";
    } else {
        echo "Sorry, wrong spelling";
    }
    ?>

# pspell_clear_session

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_clear_session — Clear the current session

### 说明

function pspell_clear_session(PSpell\Dictionary `$dictionary`): bool

pspell_clear_session() clears the current session. The current wordlist becomes blank, and, for example, if you try to save it with pspell_save_wordlist(), nothing happens.

### 参数

`dictionary`
  An PSpell\Dictionary instance.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The `dictionary` parameter expects an PSpell\Dictionary instance now; previously, a resource was expected.

### 示例

示例 #1 pspell_add_to_personal() Example

    <?php
    $pspell_config = pspell_config_create("en");
    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" will not be saved
    ?>

# pspell_config_create

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_create — Create a config used to open a dictionary

### 说明

function pspell_config_create(
string `$language`,
string `$spelling` = "",
string `$jargon` = "",
string `$encoding` = ""
): PSpell\Config

Create a config used to open a dictionary.

pspell_config_create() has a very similar syntax to pspell_new(). In fact, using pspell_config_create() immediately followed by pspell_new_config() will produce the exact same result. However, after creating a new config, you can also use pspell_config_*() functions before calling pspell_new_config() to take advantage of some advanced functionality.

For more information and examples, check out inline manual pspell website:» http://aspell.net/.

### 参数

`language`

  The language parameter is the language code which consists of the two letter ISO 639 language code and an optional two letter ISO 3166 country code after a dash or underscore.

`spelling`

  The spelling parameter is the requested spelling for languages with more than one spelling such as English. Known values are 'american', 'british', and 'canadian'.

`jargon`

  The jargon parameter contains extra information to distinguish two different words lists that have the same language and spelling parameters.

`encoding`

  The encoding parameter is the encoding that words are expected to be in. Valid values are 'utf-8', 'iso8859-*', 'koi8-r', 'viscii', 'cp1252', 'machine unsigned 16', 'machine unsigned 32'. This parameter is largely untested, so be careful when using.

### 返回值

Returns an PSpell\Config instance.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | Returns an PSpell\Config instance now; previously, a resource was returned.

### 示例

示例 #1 pspell_config_create()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_personal($pspell_config, "en");
    ?>

# pspell_config_data_dir

(PHP 5, PHP 7, PHP 8)

pspell_config_data_dir — Location of language data files

### 说明

function pspell_config_data_dir(PSpell\Config `$config`, string `$directory`): bool

警告

本函数还未编写文档，仅有参数列表。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The `config` parameter expects an PSpell\Config instance now; previously, a resource was expected.

# pspell_config_dict_dir

(PHP 5, PHP 7, PHP 8)

pspell_config_dict_dir — Location of the main word list

### 说明

function pspell_config_dict_dir(PSpell\Config `$config`, string `$directory`): bool

警告

本函数还未编写文档，仅有参数列表。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The `config` parameter expects an PSpell\Config instance now; previously, a resource was expected.

# pspell_config_ignore

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_ignore — Ignore words less than N characters long

### 说明

function pspell_config_ignore(PSpell\Config `$config`, int `$min_length`): bool

pspell_config_ignore() should be used on a config before calling pspell_new_config(). This function allows short words to be skipped by the spell checker.

### 参数

`config`
  An PSpell\Config instance.
`min_length`

  Words less than `min_length` characters will be skipped.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The `config` parameter expects an PSpell\Config instance now; previously, a resource was expected.

### 示例

示例 #1 pspell_config_ignore()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_ignore($pspell_config, 5);
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "abcd");    //will not result in an error
    ?>

# pspell_config_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_mode — Change the mode number of suggestions returned

### 说明

function pspell_config_mode(PSpell\Config `$config`, int `$mode`): bool

pspell_config_mode() should be used on a config before calling pspell_new_config(). This function determines how many suggestions will be returned by pspell_suggest().

### 参数

`config`
  An PSpell\Config instance.
`mode`

  The mode parameter is the mode in which spellchecker will work. There are several modes available:

  - `PSPELL_FAST` - Fast mode (least number of suggestions)
  - `PSPELL_NORMAL` - Normal mode (more suggestions)
  - `PSPELL_BAD_SPELLERS` - Slow mode (a lot of suggestions)

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The `config` parameter expects an PSpell\Config instance now; previously, a resource was expected.

### 示例

示例 #1 pspell_config_mode() Example

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_mode($pspell_config, PSPELL_FAST);
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "thecat");
    ?>

# pspell_config_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_personal — Set a file that contains personal wordlist

### 说明

function pspell_config_personal(PSpell\Config `$config`, string `$filename`): bool

Set a file that contains personal wordlist. The personal wordlist will be loaded and used in addition to the standard one after you call pspell_new_config(). The file is also the file where pspell_save_wordlist() will save personal wordlist to.

pspell_config_personal() should be used on a config before calling pspell_new_config().

### 参数

`config`
  An PSpell\Config instance.
`filename`

  The personal wordlist. If the file does not exist, it will be created. The file should be writable by whoever PHP runs as (e.g. nobody).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The `config` parameter expects an PSpell\Config instance now; previously, a resource was expected.

### 示例

示例 #1 pspell_config_personal()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "thecat");
    ?>

### 注释

> 注意:

> This function will not work unless you have pspell .11.2 and aspell .32.5 or later.

# pspell_config_repl

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_repl — Set a file that contains replacement pairs

### 说明

function pspell_config_repl(PSpell\Config `$config`, string `$filename`): bool

Set a file that contains replacement pairs.

The replacement pairs improve the quality of the spellchecker. When a word is misspelled, and a proper suggestion was not found in the list, pspell_store_replacement() can be used to store a replacement pair and then pspell_save_wordlist() to save the wordlist along with the replacement pairs.

pspell_config_repl() should be used on a config before calling pspell_new_config().

### 参数

`config`
  An PSpell\Config instance.
`filename`

  The file should be writable by whoever PHP runs as (e.g. nobody).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The `config` parameter expects an PSpell\Config instance now; previously, a resource was expected.

### 示例

示例 #1 pspell_config_repl()

    <?php
    $pspell_config = pspell_config_create("en");
    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, "thecat");
    ?>

### 注释

> 注意:

> This function will not work unless you have pspell .11.2 and aspell .32.5 or later.

# pspell_config_runtogether

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_runtogether — Consider run-together words as valid compounds

### 说明

function pspell_config_runtogether(PSpell\Config `$config`, bool `$allow`): bool

This function determines whether run-together words will be treated as legal compounds. That is, "thecat" will be a legal compound, although there should be a space between the two words. Changing this setting only affects the results returned by pspell_check(); pspell_suggest() will still return suggestions.

pspell_config_runtogether() should be used on a config before calling pspell_new_config().

### 参数

`config`
  An PSpell\Config instance.
`allow`

  `true` if run-together words should be treated as legal compounds, `false` otherwise.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The `config` parameter expects an PSpell\Config instance now; previously, a resource was expected.

### 示例

示例 #1 pspell_config_runtogether()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_runtogether($pspell_config, true);
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "thecat");
    ?>

# pspell_config_save_repl

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_save_repl — Determine whether to save a replacement pairs list along with the wordlist

### 说明

function pspell_config_save_repl(PSpell\Config `$config`, bool `$save`): bool

pspell_config_save_repl() determines whether pspell_save_wordlist() will save the replacement pairs along with the wordlist. Usually there is no need to use this function because if pspell_config_repl() is used, the replacement pairs will be saved by pspell_save_wordlist() anyway, and if it is not, the replacement pairs will not be saved.

pspell_config_save_repl() should be used on a config before calling pspell_new_config().

### 参数

`config`
  An PSpell\Config instance.
`save`

  `true` if replacement pairs should be saved, `false` otherwise.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The `config` parameter expects an PSpell\Config instance now; previously, a resource was expected.

### 注释

> 注意:

> This function will not work unless you have pspell .11.2 and aspell .32.5 or later.

# pspell_new

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new — Load a new dictionary

### 说明

function pspell_new(
string `$language`,
string `$spelling` = "",
string `$jargon` = "",
string `$encoding` = "",
int `$mode` = 0
): PSpell\Dictionary|false

pspell_new() opens up a new dictionary and returns an PSpell\Dictionary instance for use in other pspell functions.

For more information and examples, check out inline manual pspell website:» http://aspell.net/.

### 参数

`language`

  The language parameter is the language code which consists of the two letter ISO 639 language code and an optional two letter ISO 3166 country code after a dash or underscore.

`spelling`

  The spelling parameter is the requested spelling for languages with more than one spelling such as English. Known values are 'american', 'british', and 'canadian'.

`jargon`

  The jargon parameter contains extra information to distinguish two different words lists that have the same language and spelling parameters.

`encoding`

  The encoding parameter is the encoding that words are expected to be in. Valid values are 'utf-8', 'iso8859-*', 'koi8-r', 'viscii', 'cp1252', 'machine unsigned 16', 'machine unsigned 32'. This parameter is largely untested, so be careful when using.

`mode`

  The mode parameter is the mode in which spellchecker will work. There are several modes available:

  - `PSPELL_FAST` - Fast mode (least number of suggestions)
  - `PSPELL_NORMAL` - Normal mode (more suggestions)
  - `PSPELL_BAD_SPELLERS` - Slow mode (a lot of suggestions)
  - `PSPELL_RUN_TOGETHER` - Consider run-together words as legal compounds. That is, "thecat" will be a legal compound, although there should be a space between the two words. Changing this setting only affects the results returned by pspell_check(); pspell_suggest() will still return suggestions.
  Mode is a bitmask constructed from different constants listed above. However, `PSPELL_FAST`, `PSPELL_NORMAL` and `PSPELL_BAD_SPELLERS` are mutually exclusive, so you should select only one of them.

### 返回值

Returns an PSpell\Dictionary instance on success, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | Returns an PSpell\Dictionary instance now; previously, a resource was returned.

### 示例

示例 #1 pspell_new()

    <?php
    $pspell = pspell_new("en", "", "", "",
                         (PSPELL_FAST|PSPELL_RUN_TOGETHER));
    ?>

# pspell_new_config

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new_config — Load a new dictionary with settings based on a given config

### 说明

function pspell_new_config(PSpell\Config `$config`): PSpell\Dictionary|false

pspell_new_config() opens up a new dictionary with settings specified in a `config`, created with pspell_config_create() and modified with pspell_config_*() functions. This method provides you with the most flexibility and has all the functionality provided by pspell_new() and pspell_new_personal().

### 参数

`config`

  The `config` parameter is the one returned by pspell_config_create() when the config was created.

### 返回值

Returns an PSpell\Dictionary instance on success, 或者在失败时返回 `false`

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The `config` parameter expects an PSpell\Config instance now; previously, a resource was expected.
8.1.0 | Returns an PSpell\Dictionary instance now; previously, a resource was returned.

### 示例

示例 #1 pspell_new_config()

    <?php
    $pspell_config = pspell_config_create("en");
    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 — Load a new dictionary with personal wordlist

### 说明

function pspell_new_personal(
string `$filename`,
string `$language`,
string `$spelling` = "",
string `$jargon` = "",
string `$encoding` = "",
int `$mode` = 0
): PSpell\Dictionary|false

pspell_new_personal() opens up a new dictionary with a personal wordlist. The wordlist can be modified and saved with pspell_save_wordlist(), if desired. However, the replacement pairs are not saved. In order to save replacement pairs, you should create a config using pspell_config_create(), set the personal wordlist file with pspell_config_personal(), set the file for replacement pairs with pspell_config_repl(), and open a new dictionary with pspell_new_config().

For more information and examples, check out inline manual pspell website:» http://aspell.net/.

### 参数

`filename`

  The file where words added to the personal list will be stored. It should be an absolute filename beginning with '/' because otherwise it will be relative to $HOME, which is "/root" for most systems, and is probably not what you want.

`language`

  The language code which consists of the two letter ISO 639 language code and an optional two letter ISO 3166 country code after a dash or underscore.

`spelling`

  The requested spelling for languages with more than one spelling such as English. Known values are 'american', 'british', and 'canadian'.

`jargon`

  Extra information to distinguish two different words lists that have the same language and spelling parameters.

`encoding`

  The encoding that words are expected to be in. Valid values are `utf-8`, `iso8859-*`, `koi8-r`, `viscii`, `cp1252`, `machine unsigned 16`, `machine unsigned 32`.

`mode`

  The mode in which spellchecker will work. There are several modes available:

  - `PSPELL_FAST` - Fast mode (least number of suggestions)
  - `PSPELL_NORMAL` - Normal mode (more suggestions)
  - `PSPELL_BAD_SPELLERS` - Slow mode (a lot of suggestions)
  - `PSPELL_RUN_TOGETHER` - Consider run-together words as legal compounds. That is, "thecat" will be a legal compound, although there should be a space between the two words. Changing this setting only affects the results returned by pspell_check(); pspell_suggest() will still return suggestions.
  Mode is a bitmask constructed from different constants listed above. However, `PSPELL_FAST`, `PSPELL_NORMAL` and `PSPELL_BAD_SPELLERS` are mutually exclusive, so you should select only one of them.

### 返回值

Returns an PSpell\Dictionary instance on success, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | Returns an PSpell\Dictionary instance now; previously, a resource was returned.

### 示例

示例 #1 pspell_new_personal()

    <?php
    $pspell = pspell_new_personal ("/var/dictionaries/custom.pws",
            "en", "", "", "", PSPELL_FAST|PSPELL_RUN_TOGETHER);
    ?>

# pspell_save_wordlist

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_save_wordlist — Save the personal wordlist to a file

### 说明

function pspell_save_wordlist(PSpell\Dictionary `$dictionary`): bool

pspell_save_wordlist() saves the personal wordlist from the current session. The location of files to be saved specified with pspell_config_personal() and (optionally) pspell_config_repl().

### 参数

`dictionary`
  An PSpell\Dictionary instance.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The `dictionary` parameter expects an PSpell\Dictionary instance now; previously, a resource was expected.

### 示例

示例 #1 pspell_add_to_personal()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/tmp/dicts/newdict");
    $pspell = pspell_new_config($pspell_config);

    pspell_add_to_personal($pspell, "Vlad");
    pspell_save_wordlist($pspell);
    ?>

### 注释

> 注意:

> This function will not work unless you have pspell .11.2 and aspell .32.5 or later.

# pspell_store_replacement

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_store_replacement — Store a replacement pair for a word

### 说明

function pspell_store_replacement(PSpell\Dictionary `$dictionary`, string `$misspelled`, string `$correct`): bool

pspell_store_replacement() stores a replacement pair for a word, so that replacement can be returned by pspell_suggest() later. In order to be able to take advantage of this function, you have to use pspell_new_personal() to open the dictionary. In order to permanently save the replacement pair, you have to use pspell_config_personal() and pspell_config_repl() to set the path where to save your custom wordlists, and then use pspell_save_wordlist() for the changes to be written to disk.

### 参数

`dictionary`
  An PSpell\Dictionary instance.
`misspelled`

  The misspelled word.

`correct`

  The fixed spelling for the `misspelled` word.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The `dictionary` parameter expects an PSpell\Dictionary instance now; previously, a resource was expected.

### 示例

示例 #1 pspell_store_replacement()

    <?php
    $pspell_config = pspell_config_create("en");
    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, $misspelled, $correct);
    pspell_save_wordlist($pspell);
    ?>

### 注释

> 注意:

> This function will not work unless you have pspell .11.2 and aspell .32.5 or later.

# pspell_suggest

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_suggest — Suggest spellings of a word

### 说明

function pspell_suggest(PSpell\Dictionary `$dictionary`, string `$word`): array|false

pspell_suggest() returns an array of possible spellings for the given word.

### 参数

`dictionary`
  An PSpell\Dictionary instance.
`word`

  The tested word.

### 返回值

Returns an array of possible spellings.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The `dictionary` parameter expects an PSpell\Dictionary instance now; previously, a resource was expected.

### 示例

示例 #1 pspell_suggest() example

    <?php
    $pspell = pspell_new("en");

    if (!pspell_check($pspell, "testt")) {
        $suggestions = pspell_suggest($pspell, "testt");

        foreach ($suggestions as $suggestion) {
            echo "Possible spelling: $suggestion<br />";
        }
    }
    ?>

## 目录

- pspell_add_to_personal — Add the word to a personal wordlist
- pspell_add_to_session — Add the word to the wordlist in the current session
- pspell_check — Check a word
- pspell_clear_session — Clear the current session
- pspell_config_create — Create a config used to open a dictionary
- pspell_config_data_dir — Location of language data files
- pspell_config_dict_dir — Location of the main word list
- pspell_config_ignore — Ignore words less than N characters long
- pspell_config_mode — Change the mode number of suggestions returned
- pspell_config_personal — Set a file that contains personal wordlist
- pspell_config_repl — Set a file that contains replacement pairs
- pspell_config_runtogether — Consider run-together words as valid compounds
- pspell_config_save_repl — Determine whether to save a replacement pairs list along with the wordlist
- pspell_new — Load a new dictionary
- pspell_new_config — Load a new dictionary with settings based on a given config
- pspell_new_personal — Load a new dictionary with personal wordlist
- pspell_save_wordlist — Save the personal wordlist to a file
- pspell_store_replacement — Store a replacement pair for a word
- pspell_suggest — Suggest spellings of a word

# The PSpell\Dictionary class

(PHP 8 >= 8.1.0)

## 简介

A fully opaque class which replaces a `pspell` resource as of PHP 8.1.0.

## 类摘要

final class PSpell\Dictionary {
}

# The PSpell\Config class

(PHP 8 >= 8.1.0)

## 简介

A fully opaque class which replaces a `pspell config` resource as of PHP 8.1.0.

## 类摘要

final class PSpell\Config {
}

- 安装/配置
  - 需求
  - 安装
  - 资源类型
- 预定义常量
- Pspell 函数
  - pspell_add_to_personal — Add the word to a personal wordlist
  - pspell_add_to_session — Add the word to the wordlist in the current session
  - pspell_check — Check a word
  - pspell_clear_session — Clear the current session
  - pspell_config_create — Create a config used to open a dictionary
  - pspell_config_data_dir — Location of language data files
  - pspell_config_dict_dir — Location of the main word list
  - pspell_config_ignore — Ignore words less than N characters long
  - pspell_config_mode — Change the mode number of suggestions returned
  - pspell_config_personal — Set a file that contains personal wordlist
  - pspell_config_repl — Set a file that contains replacement pairs
  - pspell_config_runtogether — Consider run-together words as valid compounds
  - pspell_config_save_repl — Determine whether to save a replacement pairs list along with the wordlist
  - pspell_new — Load a new dictionary
  - pspell_new_config — Load a new dictionary with settings based on a given config
  - pspell_new_personal — Load a new dictionary with personal wordlist
  - pspell_save_wordlist — Save the personal wordlist to a file
  - pspell_store_replacement — Store a replacement pair for a word
  - pspell_suggest — Suggest spellings of a word
- PSpell\Dictionary — The PSpell\Dictionary class
- PSpell\Config — The PSpell\Config class

# GNU Recode

# 简介

警告

此扩展已无人维护。

This module contains an interface to the GNU Recode library. The GNU Recode library converts files between various coded character sets and surface encodings. When this cannot be achieved exactly, it may get rid of the offending characters or fall back on approximations. The library recognises or produces nearly 150 different character sets and is able to convert files between almost any pair. Most » RFC 1345 character sets are supported.

> 注意: This extension is unbundled and moved to » PECL as of PHP 7.4.0. Consider to use the Multibyte String or iconv extensions instead.

> 注意: 此扩展在 Windows 平台上不可用。

# 安装/配置

## 目录

- 需求
- 安装

## 需求

You must have GNU Recode 3.5 or higher installed on your system. You can download the package from » http://directory.fsf.org/All_GNU_Packages/recode.html.

警告

The Recode library version 3.6 adds weird characters behind converted strings under certain circumstances. Thus it's safer to use Recode v3.5 or one of the available alternatives like the iconv or mbstring extension.

## 安装

## PHP 7.4

此扩展已被移至 » PECL 资源库；不再与 PHP 捆绑，从 PHP 7.4.0

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/recode.

## PHP < 7.4

To be able to use the functions defined in this module you must compile your PHP interpreter using the --with-recode[=DIR] option.

警告

Crashes and startup problems of PHP may be encountered when loading the recode as extension after loading any extension of mysql or imap. Loading the recode before those extension has proved to fix the problem. This is due a technical problem that both the c-client library used by imap and recode have their own `hash_lookup()` function and both mysql and recode have their own `hash_insert` function.

警告

IMAP，recode，和 YAZ 扩展不能同时使用，因为它们共享了相同 的内部符号。注意：Yaz 2.0 及以上版本不存在此问题。

# Recode 函数

# recode

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode — 别名 recode_string()

### 说明

此函数是该函数的别名： recode_string().

# recode_file

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode_file — Recode from file to file according to recode request

### 说明

function recode_file(string `$request`, resource `$input`, resource `$output`): bool

Recode the file referenced by file handle `input` into the file referenced by file handle `output` according to the recode `request`.

### 参数

`request`
  The desired recode request type
`input`
  A local file handle resource for the `input`
`output`
  A local file handle resource for the `output`

### 返回值

Returns `false`, if unable to comply, `true` otherwise.

### 示例

示例 #1 Basic recode_file() example

    <?php
    $input = fopen('input.txt', 'r');
    $output = fopen('output.txt', 'w');
    recode_file("us..flat", $input, $output);
    ?>

### 注释

This function does not currently process file handles referencing remote files (URLs). Both file handles must refer to local files.

### 参见

- fopen() - 打开文件或者 URL

# recode_string

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode_string — Recode a string according to a recode request

### 说明

function recode_string(string `$request`, string `$string`): string

Recode the string `string` according to the recode request `request`.

### 参数

`request`
  The desired recode request type
`string`
  The string to be recoded

### 返回值

Returns the recoded string or `false`, if unable to perform the recode request.

### 示例

示例 #1 Basic recode_string() example

    <?php
    echo recode_string("us..flat", "The following character has a diacritical mark: á");
    ?>

### 注释

A simple recode request may be "lat1..iso646-de".

### 参见

- The GNU Recode documentation of your installation for detailed instructions about recode requests.
- mb_convert_encoding() - 转换字符串，从一个字符编码到另一个字符编码
- UConverter::transcode() - Convert a string from one character encoding to another
- iconv() - 将字符串从一个字符编码转换到另一个字符编码

## 目录

- recode — 别名 recode_string
- recode_file — Recode from file to file according to recode request
- recode_string — Recode a string according to a recode request

- 安装/配置
  - 需求
  - 安装
- Recode 函数
  - recode — 别名 recode_string
  - recode_file — Recode from file to file according to recode request
  - recode_string — Recode a string according to a recode request

- Enchant — Enchant spelling library
  - 安装/配置
  - 预定义常量
  - 示例
  - Enchant 函数
  - EnchantBroker — The EnchantBroker class
  - EnchantDictionary — The EnchantDictionary class
- Gender — Determine gender of firstnames
  - 安装/配置
  - 示例
  - Gender\Gender — The Gender\Gender class
- Gettext
  - 安装/配置
  - Gettext 函数
- iconv
  - 安装/配置
  - 预定义常量
  - iconv 函数
- intl — Internationalization Functions
  - 安装/配置
  - 预定义常量
  - 示例
  - 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 — The UConverter class
  - Grapheme 函数
  - IDN 函数
  - IntlChar
  - IntlException — Exception class for intl errors
  - IntlIterator — The IntlIterator class
  - intl 函数
- 多字节字符串
  - 安装/配置
  - 预定义常量
  - 支持编码的摘要
  - 日文字符多字节编码基础
  - HTTP 输入和输出
  - 支持的字符编码
  - 函数重载功能
  - PHP字符编码的要求
  - 多字节字符串 函数
- Pspell
  - 安装/配置
  - 预定义常量
  - Pspell 函数
  - PSpell\Dictionary — The PSpell\Dictionary class
  - PSpell\Config — The PSpell\Config class
- Recode — GNU Recode
  - 安装/配置
  - Recode 函数

# 图像生成和处理

# 可交换图像信息

# 简介

通过使用 exif 扩展，你可以操作图像元数据。 例如：你可以使用 exif 相关的函数从数码相机拍摄的图片文件中读取元数据。 通常 JPEG 和 TIFF 格式的图像文件都包含元数据。

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置

## 需求

必须使用 `--enable-exif` 选项编译 PHP。 如果要提供对 EXIF 标签中元数据的多字节文字支持，需要通过使用 `--enable-mbstring` 选项编译 PHP 来启用 mbstring 扩展。 exif 不需要其他额外的 PHP 库就可以直接使用。

## 安装

使用 --enable-exif 选项 配置 PHP 来启用 exif 支持。

Windows 用户必须在 php.ini 中启用 php_mbstring.dll 和 php_exif.dll 扩展。 请确保在 php.ini 中保持正确的顺序： php_mbstring.dll 必须在 php_exif.dll 之前 加载。

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

当 mbstring 模块可用时，exif 支持用户注释中的 Unicode 和 JIS 字符编码的自动转换。这是通过先用指定字符集将注释解码，把结果再用另一个符合你的 `HTTP` 输出的字符集编码来实现的。

Exif configuration options
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
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` |

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`exif.encode_unicode` string
  `exif.encode_unicode` 定义了 UNICODE 用户注释被处理的字符集。默认为 ISO-8859-15，可用于大多数非亚洲国家。本设置可以为空或者必须为一个 mbstring 所支持的编码。如果为空，则使用当前 mbstring 内部使用的编码。
`exif.decode_unicode_motorola` string
  `exif.decode_unicode_motorola` 定义了 Unicode 编码的用户注释的图像内部字符集，如果图像是摩托罗拉字节顺序（big-endian）的话。本设置不能为空但可以指定一个 mbstring 支持的编码列表。默认为 UCS-2BE。
`exif.decode_unicode_intel` string
  `exif.decode_unicode_intel` 定义了 Unicode 编码的用户注释的图像内部字符集，如果图像是英特尔字节顺序（little-endian）的话。本设置不能为空但可以指定一个 mbstring 支持的编码列表。默认为 UCS-2LE。
`exif.encode_jis` string
  `exif.encode_jis` 定义了 JIS 用户注释被处理的字符集。默认为空值，迫使函数使用当前 mbstring 使用的内部编码。
`exif.decode_jis_motorola` string
  `exif.decode_jis_motorola` 定义了 JIS 编码的用户注释的图像内部字符集，如果图像是摩托罗拉字节顺序（big-endian）的话。本设置不能为空但可以指定一个 mbstring 支持的编码列表。默认为 JIS。
`exif.decode_jis_intel` string
  `exif.decode_jis_intel` 定义了 JIS 编码的用户注释的图像内部字符集，如果图像是英特尔字节顺序（litle-endian）的话。本设置不能为空但可以指定一个 mbstring 支持的编码列表。默认为 JIS。

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`EXIF_USE_MBSTRING` (int)
  如果启用了 mbstring，这个常量的值为 `1`， 否则为 `0`。

exif_imagetype() 列出几个相关的内建变量。

# Exif 函数

# exif_imagetype

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

exif_imagetype — 判断一个图像的类型

### 说明

function exif_imagetype(string `$filename`): int|false

exif_imagetype() 读取一个图像的第一个字节并检查其签名。

本函数可用来避免调用其它 exif 函数用到了不支持的文件类型上或和 $_SERVER['HTTP_ACCEPT'] 结合使用来检查浏览器是否可以显示某个指定的图像。

### 参数

`filename`
  被检查的图像文件名。

### 返回值

如果发现了恰当的签名则返回一个对应的常量，否则返回 `false`。返回值和 getimagesize() 返回的数组中的索引 2 的值是一样的，但本函数快得多。

定义有以下常量，并代表了 exif_imagetype() 可能的返回值：

图像类型常量
值 | 常量
--- | ---
1 | `IMAGETYPE_GIF`
2 | `IMAGETYPE_JPEG`
3 | `IMAGETYPE_PNG`
4 | `IMAGETYPE_SWF`
5 | `IMAGETYPE_PSD`
6 | `IMAGETYPE_BMP`
7 | `IMAGETYPE_TIFF_II`（小端字节顺序）
8 | `IMAGETYPE_TIFF_MM`（大端字节顺序）
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`

> 注意: 如果无法从文件中读取足够的字节来确定图像类型，exif_imagetype() 将发出 `E_NOTICE` 并返回 `false`。

### 更新日志

版本 | 说明
--- | ---
7.1.0 | 新增 WebP 支持。
8.1.0 | 新增 AVIF 支持。

### 示例

示例 #1 exif_imagetype() 示例

    <?php

    if (exif_imagetype("image.gif") != IMAGETYPE_GIF) {
        echo "The picture is not a gif";
    }

    ?>

### 参见

- image_type_to_mime_type() - 取得 getimagesize、exif_read_data、exif_thumbnail、exif_imagetype 所返回的图像类型的 MIME 类型
- getimagesize() - 取得图像大小

# exif_read_data

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_read_data — 从一个图片文件中读取 EXIF 头信息

### 说明

function exif_read_data(
resource|string `$file`,
?string `$required_sections` = `null`,
bool `$as_arrays` = `false`,
bool `$read_thumbnail` = `false`
): array|false

exif_read_data() 函数从一个图片文件中读取 EXIF 头信息。这样就可以读取数码相机产生的元数据。

EXIF 头信息往往存在于数码相机生成的 JPEG/TIFF 图片中，但不幸的是每个数码相机制造商的标记都不同，因此（编写代码时）不能依赖于某个特定的 Exif 头信息。

`Height` 和 `Width` 是用和 getimagesize() 一样的方法计算的，因此它们的值不能是任何返回的头信息的部分。此外 `html` 是一个可以用于普通的 HTML 中的 height/width 的文本字符串。

当一个 Exif 头信息包含有一个 Copyright 时注意它本身可以包含两个值。解决方案和 Exif 2.10 标准不一致，`COMPUTED` 区段会同时返回 `Copyright.Photographer` 和 `Copyright.Editor`，但是 `IFD0` 区段则包含有一个字节数组用 NULL 字符分隔开两个项目。或者只有第一项如果数据类型错误的话（Exif 的正常行为）。`COMPUTED` 也会包含 `Copyright`，要么是原始的版权字符串，要么是逗号分隔的摄像与编辑的版权信息。

`UserComment` 标记和 Copyright 有同样的问题。它也可以存储两个值，第一个是使用的编码方式，第二个是其值本身。如果这样则 `IFD` 区段仅包含编码方式或者一个字节数组。`COMPUTED` 区段将存储两个值到 `UserCommentEncoding` 和 `UserComment`。`UserComment` 在两种情况下都可用因此应该优先使用它而不是 `IFD0` 区段中的该值。

exif_read_data() 还会根据 EXIF 规范（» http://exif.org/Exif2-2.PDF，第 20 页）来验证 EXIF 数据。

### 参数

`file`
  图片文件的位置。这可以是一个文件路径（和往常一样，流封装也是支持的）， 或者是一个流式资源（stream resource）。
`required_sections`

  是需要存在于文件中的逗号分隔的区段列表用来产生结果数组。如果未找到所请求的区段则返回值为 `false`。

  FILE | FileName, FileSize, FileDateTime, SectionsFound
  COMPUTED | html，Width，Height，IsColor，可能有更多其它的。Height 和 Width 是用和 getimagesize() 一样的方法计算的，因此它们的值不能是任何返回的头信息的部分。此外 `html` 是一个可以用于普通的 HTML 中的 height/width 的文本字符串。
  ANY_TAG | 任何包含有标记的信息，例如 `IFD0`，`EXIF`，...
  IFD0 | 所有 IFD0 的标记数据。在标准的图像文件中这包含了图像大小及其它。
  THUMBNAIL | 如果有第二个 `IFD`，文件应该包含有缩略图。所有有关嵌入缩略图的标记信息都存储在本区。
  COMMENT | JPEG 图像的注释头信息。
  EXIF | EXIF 区段是 `IFD0` 的子区，包含有图像的更多详细信息。大多数内容都是数码相机相关的。

`as_arrays`
  指定了是否每个区段都成为一个数组。`required_sections` `COMPUTED`，`THUMBNAIL` 和`COMMENT` 区段总是成为数组，因为它们里面包含的名字和其它区段冲突。
`read_thumbnail`
  当设定为 `true` 时，读取缩略图本身。否则只读取标记数据。

### 返回值

返回一个关联数组，键名是头信息名，值为与其相应的值。如果没有可供返回的数据，exif_read_data() 将返回 `false`。

### 错误／异常

当遇到不支持的标签，或其他潜在的错误情况时，将抛出`E_WARNING` 与`E_NOTICE`等级的错误，但这个函数依然会尝试去读取所有可理解的信息。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `required_sections` 现在可以为空。
7.2.0 | `file` 参数现在起支持本地文件和流式资源。
7.2.0 | 新增了以下 EXIF 格式的支持： Samsung DJI Panasonic Sony Pentax Minolta Sigma/Foveon AGFA Kyocera Ricoh Epson

### 示例

示例 #1 exif_read_data() 例子

    <?php
    echo "test1.jpg:<br />\n";
    $exif = exif_read_data('tests/test1.jpg', 'IFD0');
    echo $exif===false ? "No header data found.<br />\n" : "Image contains headers<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";
        }
    }
    ?>

第一个调用失败了，因为图像没有头信息。

以上示例的输出类似于：

    test1.jpg:
    No header data found.
    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

示例 #2 exif_read_data() with streams available as of PHP 7.2.0

    <?php
    // Open a the file, this should be in binary mode
    $fp = fopen('/path/to/image.jpg', 'rb');

    if (!$fp) {
        echo 'Error: Unable to open image for reading';
        exit;
    }

    // Attempt to read the exif headers
    $headers = exif_read_data($fp);

    if (!$headers) {
        echo 'Error: Unable to read exif headers';
        exit;
    }

    // Print the 'COMPUTED' headers
    echo 'EXIF Headers:' . PHP_EOL;

    foreach ($headers['COMPUTED'] as $header => $value) {
        printf(' %s => %s%s', $header, $value, PHP_EOL);
    }
    ?>

以上示例的输出类似于：

    EXIF Headers:
     Height => 576
     Width => 1024
     IsColor => 1
     ByteOrderMotorola => 0
     ApertureFNumber => f/5.6
     UserComment =>
     UserCommentEncoding => UNDEFINED
     Copyright => Denis
     Thumbnail.FileType => 2
     Thumbnail.MimeType => image/jpeg

### 注释

> 注意: If mbstring is enabled, exif will attempt to process the unicode and pick a charset as specified by exif.decode_unicode_motorola and exif.decode_unicode_intel. The exif extension will not attempt to figure out the encoding on its own, and it is up to the user to properly specify the encoding for which to use for decoding by setting one of these two ini directives prior to calling exif_read_data().

> 注意: If the `file` is used to pass a stream to this function, then the stream must be seekable. Note that the file pointer position is not changed after this function returns.

### 参见

- exif_thumbnail() - 检索图像的嵌入式缩略图
- getimagesize() - 取得图像大小

# exif_tagname

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_tagname — 获取指定索引的头名称

### 说明

function exif_tagname(int `$index`): string|false

### 参数

`index`
  要查找的标签名称的 ID。

### 返回值

返回头名称。 如果 `index` 参数不是预定义的 EXIF 标签 id，则返回 `false`

### 示例

示例 #1 exif_tagname() 函数示例

    <?php
    echo "256: ".exif_tagname(256).PHP_EOL;
    echo "257: ".exif_tagname(257).PHP_EOL;
    ?>

以上示例会输出：

    256: ImageWidth
    257: ImageLength

### 参见

- exif_imagetype() - 判断一个图像的类型
- » EXIF 规范
- » EXIF 标签

# exif_thumbnail

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_thumbnail — 检索图像的嵌入式缩略图

### 说明

function exif_thumbnail(
resource|string `$file`,
int `&$width` = `null`,
int `&$height` = `null`,
int `&$image_type` = `null`
): string|false

exif_thumbnail() 读取图像的嵌入式缩略图。

如果想通过该函数发送缩略图，应该使用 header() 函数发送 mimetype 信息。

exif_thumbnail() 不能创建图像但能确定它的尺寸。在这种情况下，返回值是 `false`，但会设置 `width` 和 `height`。

### 参数

`file`
  图像文件的路径。可以是文件路径也可以是流 resource。
`width`
  返回缩略图的宽度。
`height`
  返回缩略图的高度。
`image_type`
  返回缩略图的图像类型。不是 TIFF 就是 JPEG。

### 返回值

返回嵌入式缩略图，如果图像不包含缩略图则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
7.2.0 | `file` 参数现在支持本地文件和流资源。

### 示例

示例 #1 exif_thumbnail() 示例

    <?php
    $image = exif_thumbnail('/path/to/image.jpg', $width, $height, $type);

    if ($image!==false) {
        header('Content-type: ' .image_type_to_mime_type($type));
        echo $image;
        exit;
    } else {
        // 没有可用的缩略图，这里处理错误
        echo 'No thumbnail available';
    }
    ?>

### 注释

> 注意: 如果传递流到此函数的 `file`，然后流必须是可寻找的。请注意，此函数返回后，文件指针位置不会改变。

### 参见

- exif_read_data() - 从一个图片文件中读取 EXIF 头信息
- image_type_to_mime_type() - 取得 getimagesize、exif_read_data、exif_thumbnail、exif_imagetype 所返回的图像类型的 MIME 类型

# read_exif_data

(PHP 4 >= 4.0.1, PHP 5, PHP 7)

read_exif_data — 别名 exif_read_data()

警告

该别名已在 PHP 7.2.0 中 废弃，并且自 PHP 8.0.0 起已被移除。

### 说明

此函数是该函数的别名： exif_read_data().

### 更新日志

版本 | 说明
--- | ---
7.2.0 | 这个函数别名被废弃。

## 目录

- exif_imagetype — 判断一个图像的类型
- exif_read_data — 从一个图片文件中读取 EXIF 头信息
- exif_tagname — 获取指定索引的头名称
- exif_thumbnail — 检索图像的嵌入式缩略图
- read_exif_data — 别名 exif_read_data

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
- 预定义常量
- Exif 函数
  - exif_imagetype — 判断一个图像的类型
  - exif_read_data — 从一个图片文件中读取 EXIF 头信息
  - exif_tagname — 获取指定索引的头名称
  - exif_thumbnail — 检索图像的嵌入式缩略图
  - read_exif_data — 别名 exif_read_data

# 图像处理和 GD

# 简介

PHP 并不仅限于创建 HTML 输出， 它也可以创建和处理包括 GIF， PNG， JPEG， WBMP 以及 XPM 在内的多种格式的图像。 更加方便的是，PHP 可以直接将图像数据流输出到浏览器。 要想在 PHP 中使用图像处理功能，你需要连带 GD 库一起来编译 PHP。 GD 库和 PHP 可能需要其他的库， 这取决于你要处理的图像格式。

你可以使用 PHP 中的图像函数来获取下列格式图像的大小： JPEG， GIF， PNG， SWF， TIFF 和 JPEG2000。

如果联合 exif 扩展 一起使用， 你可以操作存储在 JPEG 和 TIFF 图像文件头部的信息， 这样就就可以获取数码相机所产生的元数据。 exif 相关的函数不需要 GD 库亦可使用。

> 注意: 关于如何扩展图像处理能力，例如读取、写入以及修改， 请参考“需求”一节。 要想读取数码相机拍摄的图片的元数据， 你需要上面提到的 exif 扩展。

> 注意: getimagesize() 函数不需要 GD 扩展库。

警告

由于绑定的 GD 库使用 Zend 内存管理机制来分配内存， 所以所使用的内存大小不受 memory_limit 配置参数限制。

GD 库支持多种图像格式， 下标所列的是 GD 所支持的格式，请注意备图像格式对应的读取/写入支持的可用性。

GD 所支持的格式
格式 | 支持读取 | 支持写入 | 备注
--- | --- | --- | ---
JPEG | `true` | `true` |
PNG | `true` | `true` |
GIF | `true` | `true` |
XBM | `true` | `true` |
XPM | `true` | `false` |
WBMP | `true` | `true` |
WebP | `true` | `true` |
BMP | `true` | `true` | 从 PHP 7.2.0 开始支持

很遗憾的是，虽然上表中显示大部分图像格式都是支持读取和写入的， 但是不代表你的 PHP 环境在编译的时候是支持这些操作的。 要想检测 GD 库所支持的格式，请使用 gd_info() 函数， 更多信息请参考 “安装” 一章。

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置
- 资源类型

## 需求

如果拥有 GD 库（位于 » http://www.libgd.org/），还可以创建和处理图像。

可以处理的图像格式取决于安装的 GD 版本，以及 GD 可能需要访问这些图像格式的任何其他库。

> 注意: 需要 libgd-2.1.0 或更高版本。或者使用 PHP 中绑定的 GD 库。

> 注意: GD 库需要 zlib >= 1.2.0.4。

可能希望增强 GD 库以处理更多的图像格式。

支持的图像格式
图像格式 | 需要下载的库 | 备注
--- | --- | ---
`gif` |  |
`avif` |  |
`jpeg` | » http://www.ijg.org/ | 在编译 jpeg 时（编译 PHP 之前），必须在配置步骤使用 --enable-shared 选项。否则，当进入编译 PHP 的配置步骤时，会收到一条错误信息，说 `libjpeg.(a|so) not found`。
`png` | » http://www.libpng.org/pub/png/libpng.html |
`xpm` | » http://www.ibiblio.org/pub/Linux/libs/X/!INDEX.html | 如果你的系统中已经安装了 X-Environment，就可能已经有了这个库。
`webp` |  |

希望增强 GD 以处理不同的字体。» FreeType 2 库支持。

## 安装

要激活 GD 支持，配置 PHP 时加上 --with-gd[=DIR]，DIR 是 GD 的基本安装目录。要使用推荐的绑定的 GD 库版本，使用 --with-gd。要编译 GD 库，需要libpng 和 libjpeg。 自 PHP 7.4.0 起，--with-gd 变为 --enable-gd （是否启用扩展） 和 --with-external-gd （选择使用外部 libgd，而不是绑定的）。

在 Windows 中，需要将 GD 的 DLL 文件 php_gd.dll 作为一个扩展包含在 php.ini 中。 在 PHP 8.0.0 之前，DLL 被命名为 php_gd2.dll。

要增强 GD 的能力以处理更多的图像格式，在配置 PHP 时指定 `--with-XXXX` 的配置开关。

所支持的图像格式
图像格式 | 配置开关
--- | ---
`avif` | 要激活 avif 的支持，加上 --with-avif。 从 PHP 8.1.0 起可用。
`jpeg` | 要激活 jpeg 的支持，加上 --with-jpeg-dir=DIR。 支持 Jpeg 6b、7 或 8。 从 PHP 7.4.0 开始，使用 --with-jpeg 替代。
`png` | 要激活 png 的支持，加上 --with-png-dir=DIR。注意，libpng 需要 zlib library，因此配置中还要加上 --with-zlib-dir[=DIR]。 从 PHP 7.4.0 开始，--with-png-dir 和 --with-zlib-dir 已经移除。 需要安装 libpng 和 zlib。
`xpm` | 要激活 xpm 的支持，加上 --with-xpm-dir=DIR。 如果配置时提示找不到所需要的库，可以加上 X11 库的路径。 从 PHP 7.4.0 开始，使用 --with-xpm 替代。
`webp` | 要激活 xpm 的支持，加上 --with-webp-dir=DIR。 从 PHP 7.4.0 开始，使用 --with-webp 替代。

> 注意: 当把 PHP 和 libpng 一起编译时，必须使用和 GD 库连接的同一个版本。

要增强 GD 的能力以处理更多的字体，在配置 PHP 时指定 `--with-XXXX` 的配置开关。

所支持的字库
字库 | 配置开关
--- | ---
`FreeType 2` | 要激活 FreeType 2 的支持，加上 --with-freetype-dir=DIR。 从 PHP 7.4.0 开始使用 --with-freetype 代替，它依赖于 pkg-config。
`本地 TrueType 字符串函数` | 要激活本地 TrueType 字符串函数的支持，加上 --enable-gd-native-ttf。 （此选项无效，自 PHP 7.2.0 起已被删除。）

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

Image 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
gd.jpeg_ignore_warning | "1" | `INI_ALL` |

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`gd.jpeg_ignore_warning` bool

  Ignore warnings (but not errors) created by libjpeg(-turbo).

`gd.jpeg_ignore_warning` 变更日志
版本 | 说明
--- | ---
7.1.0 | gd.jpeg_ignore_warning 默认值从 0 变更为 1。

参见 exif 配置。

警告

图像处理函数相当占用内存，如果使用的时 GD 库的捆绑版本，请务必将 memory_limit 设置的足够高。

## 资源类型

本扩展定义了下列资源类型：

GD 库中定义的资源类型列表
名称 | 说明 | 备注
--- | --- | ---
`gd` | 图像资源，由 imagecreatefrompng() 等函数使用 | PHP 8.0.0 之前
`gd font` | 由 imageloadfont() 函数内部创建的字体资源 | PHP 8.0.0 之前

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`GD_VERSION` (string)
  PHP 编译所依据的 GD 版本。
`GD_MAJOR_VERSION` (int)
  PHP 编译所依据的 GD 大版本。
`GD_MINOR_VERSION` (int)
  PHP 编译所依据的 GD 小版本。
`GD_RELEASE_VERSION` (int)
  PHP 编译所依据的 GD 发布版本。
`GD_EXTRA_VERSION` (string)
  PHP 编译所依据的 GD 扩展版本（beta/rc..）。
`GD_BUNDLED` (int)
  当使用绑定版本的 GD 时，此值为 1，反之为 0。
`IMG_AVIF` (int)
  Used as a return value by imagetypes() （自 PHP 8.1.0 起可用）
`IMG_BMP` (int)
  Used as a return value by imagetypes()
`IMG_GIF` (int)
  Used as a return value by imagetypes()
`IMG_JPG` (int)
  Used as a return value by imagetypes()
`IMG_JPEG` (int)
  Used as a return value by imagetypes()

  > 注意:

  > 本常量值同 `IMG_JPG`

`IMG_PNG` (int)
  Used as a return value by imagetypes()
`IMG_TGA` (int)
  Used as a return value by imagetypes() （自 PHP 7.4.0 起可用）
`IMG_WBMP` (int)
  Used as a return value by imagetypes()
`IMG_XPM` (int)
  Used as a return value by imagetypes()
`IMG_WEBP` (int)
  Used as a return value by imagetypes() （自 PHP 7.0.10 起可用）
`IMG_WEBP_LOSSLESS` (int)
  （自 PHP 8.1.0 起可用）
`IMG_COLOR_TILED` (int)
  Special color option which can be used instead of a color allocated with imagecolorallocate() or imagecolorallocatealpha().
`IMG_COLOR_STYLED` (int)
  Special color option which can be used instead of a color allocated with imagecolorallocate() or imagecolorallocatealpha().
`IMG_COLOR_BRUSHED` (int)
  Special color option which can be used instead of a color allocated with imagecolorallocate() or imagecolorallocatealpha().
`IMG_COLOR_STYLEDBRUSHED` (int)
  Special color option which can be used instead of a color allocated with imagecolorallocate() or imagecolorallocatealpha().
`IMG_COLOR_TRANSPARENT` (int)
  Special color option which can be used instead of a color allocated with imagecolorallocate() or imagecolorallocatealpha().
`IMG_AFFINE_TRANSLATE` (int)
  An affine transformation type constant used by the imageaffinematrixget() function.
`IMG_AFFINE_SCALE` (int)
  An affine transformation type constant used by the imageaffinematrixget() function.
`IMG_AFFINE_ROTATE` (int)
  An affine transformation type constant used by the imageaffinematrixget() function.
`IMG_AFFINE_SHEAR_HORIZONTAL` (int)
  An affine transformation type constant used by the imageaffinematrixget() function.
`IMG_AFFINE_SHEAR_VERTICAL` (int)
  An affine transformation type constant used by the imageaffinematrixget() function.
`IMG_ARC_ROUNDED` (int)
  A style constant used by the imagefilledarc() function.

  > 注意:

  > 此常量值同 `IMG_ARC_PIE`

`IMG_ARC_PIE` (int)
  A style constant used by the imagefilledarc() function.
`IMG_ARC_CHORD` (int)
  A style constant used by the imagefilledarc() function.
`IMG_ARC_NOFILL` (int)
  A style constant used by the imagefilledarc() function.
`IMG_ARC_EDGED` (int)
  A style constant used by the imagefilledarc() function.
`IMG_GD2_RAW` (int)
  A type constant used by the imagegd2() function.
`IMG_GD2_COMPRESSED` (int)
  A type constant used by the imagegd2() function.
`IMG_EFFECT_REPLACE` (int)
  Alpha blending effect used by the imagelayereffect() function.
`IMG_EFFECT_ALPHABLEND` (int)
  Alpha blending effect used by the imagelayereffect() function.
`IMG_EFFECT_NORMAL` (int)
  Alpha blending effect used by the imagelayereffect() function.
`IMG_EFFECT_OVERLAY` (int)
  Alpha blending effect used by the imagelayereffect() function.
`IMG_EFFECT_MULTIPLY` (int)
  Alpha blending effect used by the imagelayereffect() function.
`IMG_FILTER_NEGATE` (int)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_GRAYSCALE` (int)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_BRIGHTNESS` (int)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_CONTRAST` (int)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_COLORIZE` (int)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_EDGEDETECT` (int)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_GAUSSIAN_BLUR` (int)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_SELECTIVE_BLUR` (int)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_EMBOSS` (int)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_MEAN_REMOVAL` (int)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_SMOOTH` (int)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_PIXELATE` (int)
  Special GD filter used by the imagefilter() function.
`IMG_FILTER_SCATTER` (int)
  Special GD filter used by the imagefilter() function. （自 PHP 7.4.0 版本可用）
`IMAGETYPE_GIF` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_JPEG` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_JPEG2000` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_PNG` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_SWF` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_PSD` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_BMP` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_WBMP` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_XBM` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_TIFF_II` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_TIFF_MM` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_IFF` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_JB2` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_JPC` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_JP2` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_JPX` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_SWC` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_ICO` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_WEBP` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions. (从 PHP 7.1.0 开始支持)
`IMAGETYPE_AVIF` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions. （自 PHP 8.1.0 起可用）
`IMAGETYPE_UNKNOWN` (int)
  Image type constant used by the image_type_to_mime_type() and image_type_to_extension() functions.
`IMAGETYPE_COUNT` (int)
  可用于 image_type_to_mime_type() 和 image_type_to_extension() 函数的图像类型常量编号（包括 unknown 类型）。
`PNG_NO_FILTER` (int)
  A special PNG filter, used by the imagepng() function.
`PNG_FILTER_NONE` (int)
  A special PNG filter, used by the imagepng() function.
`PNG_FILTER_SUB` (int)
  A special PNG filter, used by the imagepng() function.
`PNG_FILTER_UP` (int)
  A special PNG filter, used by the imagepng() function.
`PNG_FILTER_AVG` (int)
  A special PNG filter, used by the imagepng() function.
`PNG_FILTER_PAETH` (int)
  A special PNG filter, used by the imagepng() function.
`PNG_ALL_FILTERS` (int)
  A special PNG filter, used by the imagepng() function.
`IMG_FLIP_VERTICAL` (int)
  Used together with imageflip(), available as of PHP 5.5.0.
`IMG_FLIP_HORIZONTAL` (int)
  Used together with imageflip(), available as of PHP 5.5.0.
`IMG_FLIP_BOTH` (int)
  Used together with imageflip(), available as of PHP 5.5.0.
`IMG_BELL` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_BESSEL` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_BILINEAR_FIXED` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_BICUBIC` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_BICUBIC` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_BLACKMAN` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_BOX` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_BSPLINE` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_CATMULLROM` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_GAUSSIAN` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_GENERALIZED_CUBIC` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_HERMITE` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_HAMMING` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_HANNING` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_MITCHELL` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_POWER` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_QUADRATIC` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_SINC` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_NEAREST_NEIGHBOUR` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_WEIGHTED4` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_TRIANGLE` (int)
  Used together with imagesetinterpolation(), available as of PHP 5.5.0.
`IMG_CROP_BLACK` (int)
  裁剪出黑色背景。
`IMG_CROP_DEFAULT` (int)
  等同于 `IMG_CROP_TRANSPARENT`。在 PHP 7.4.0 之前，如果图像没有透明色，则捆绑的 libgd 将恢复为 `IMG_CROP_SIDES`。
`IMG_CROP_SIDES` (int)
  使用图像的 4 个角尝试检测要裁剪的背景。
`IMG_CROP_THRESHOLD` (int)
  使用指定 `threshold` 和 `color` 裁切图片。
`IMG_CROP_TRANSPARENT` (int)
  裁剪出透明背景。
`IMG_CROP_WHITE` (int)
  裁剪出白色背景。

# 示例

## 目录

- 使用 PHP 创建 PNG 图像
- 使用 Alpha 通道为图像加水印
- 使用 imagecopymerge 函数创建半透明水印

## 使用 PHP 创建 PNG 图像

示例 #1 使用 PHP 创建 PNG 图像

    <?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);

    ?>

本示例需要从带有 `<img src="button.php?text=text">` 标签的页面调用。 上述 button.php 脚本将 `"text"` 字符串绘制到一个图像上， 在本例中图像文件为 `"images/button1.png"`， 然后输出绘制后的图像。 当你需要经常修改图像上的文字时， 动态生成图像就可以省去了每次都重新制作图像的麻烦。

## 使用 Alpha 通道为图像加水印

示例 #1 使用 Alpha 通道为图像加水印

    <?php
    // 加载水印以及要加水印的图像
    $stamp = imagecreatefrompng('stamp.png');
    $im = imagecreatefromjpeg('photo.jpeg');

    // 设置水印图像的外边距，并且获取水印图像的尺寸
    $marge_right = 10;
    $marge_bottom = 10;
    $sx = imagesx($stamp);
    $sy = imagesy($stamp);

    // 利用图像的宽度和水印的外边距计算位置，并且将水印复制到图像上

    imagecopy($im, $stamp, imagesx($im) - $sx - $marge_right, imagesy($im) - $sy - $marge_bottom, 0, 0, imagesx($stamp), imagesy($stamp));

    // 输出
    header('Content-type: image/png');
    imagepng($im);
    ?>

本示例是为图像加水印以及版权信息的常见方式。 请注意，水印图像中所包含的 alpha 通道信息以及文本的抗锯齿效果， 都会在复制过程中保留。

## 使用 imagecopymerge() 函数创建半透明水印

示例 #1 使用 imagecopymerge() 函数创建半透明水印

    <?php
    // 加载要加水印的图像
    $im = imagecreatefromjpeg('photo.jpeg');

    // 首先我们从 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);

    // 设置水印图像的位置和大小
    $marge_right = 10;
    $marge_bottom = 10;
    $sx = imagesx($stamp);
    $sy = imagesy($stamp);

    // 以 50% 的透明度合并水印和图像
    imagecopymerge($im, $stamp, imagesx($im) - $sx - $marge_right, imagesy($im) - $sy - $marge_bottom, 0, 0, imagesx($stamp), imagesy($stamp), 50);

    // 将图像保存到文件
    imagepng($im, 'photo_stamp.png');

    ?>

本示例使用 imagecopymerge() 函数 来合并水印图像和原始图像。 我们可以控制水印的透明度，在本例中是 50% 的透明度。 在实际使用中， 使用半透明水印可以在不影响用户观看图像的前提下进行版权保护。

# GD 和图像处理 函数

# gd_info

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

gd_info — 取得当前安装的 GD 库的信息

### 说明

function gd_info(): array

获取当前安装的 GD 库的版本和功能的信息。

### 参数

此函数没有参数。

### 返回值

返回一个关联数组。

gd_info() 返回的数组元素
属性 | 含义
--- | ---
GD Version | 描述安装的 `libgd` 的版本的 string 值。
FreeType Support | bool 值。如果安装了 FreeType 支持则为 `true`。
FreeType Linkage | 描述 FreeType 链接方式的 string 值。 可能值为：'with freetype'、'with TTF library' 和 'with unknown library'。 仅当 `FreeType Support` 为 `true` 时才会有该属性。
GIF Read Support | bool 值。 如果支持 读取 `GIF` 图像， 则为 `true`。
GIF Create Support | bool 值。 如果支持 创建 `GIF` 图像， 则为 `true`。
JPEG Support | bool 值。 如果支持 `JPEG` 则为 `true`。
PNG Support | bool 值。 如果支持 `PNG` 则为 `true`。
WBMP Support | bool 值。 如果支持 `WBMP` 则为 `true`。
XBM Support | bool 值。 如果支持 `XBM` 则为 `true`。
WebP Support | bool 值。 如果支持 `WebP` 则为 `true`。
AVIF Support | bool 值。 如果支持 `AVIF` 则为 `true`。 从 PHP 8.1.0 开始可用。

### 示例

示例 #1 使用 gd_info()

    <?php
    var_dump(gd_info());
    ?>

以上示例的输出类似于：

    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)
    }

### 参见

- imagepng() - 将 PNG 图像输出到浏览器或文件
- imagejpeg() - 输出图象到浏览器或文件。
- imagegif() - 输出图象到浏览器或文件。
- imagewbmp() - 输出图象到浏览器或文件。
- imagewebp() - 将 WebP 格式的图像输出到浏览器或文件
- imageavif() - 输出图象到浏览器或文件。
- imagetypes() - 返回 PHP 内置支持的图像类型

# getimagesize

(PHP 4, PHP 5, PHP 7, PHP 8)

getimagesize — 取得图像大小

### 说明

function getimagesize(string `$filename`, array `&$image_info` = `null`): array|false

getimagesize() 函数将确定任何支持的指定图像文件的大小，并返回尺寸以及文件类型和 `height/width` 文本字符串，以在标准 HTML `IMG` 标签和对应的 HTTP 内容类型中使用。

getimagesize() 还可以在 `image_info` 参数中返回更多信息。

警告

此函数要求 `filename` 是有效的图像文件。如果提供的是非图像，可能会错误的识别为图像且函数会成功返回，但数组可能包含无意义的值。

不要使用 getimagesize() 识别指定的文件是否是有效的图像。请使用专业解决方案，比如 Fileinfo 扩展。

> 注意: 注意 JPC 和 JP2 是具有不同位深度的组件。此外，JP2 文件可能包含有`多个 JPEG 2000 代码流`，此情况下，getimagesize() 返回此文件顶层中碰到的第一个代码流的值。

> 注意: 从具有最高比特率的 icon 中检索有关 icon 的信息。

> 注意: GIF 图像由一个或多个帧组成，其中每个帧可能只占据图像的一部分。getimagesize() 报告的图像大小是整体大小（从逻辑屏幕描述符中读取）。

### 参数

`filename`

  此参数指定希望检索其信息的文件。可以指向本地文件或（配置允许）使用某个支持的流的远程文件。

`image_info`

  此可选参数允许从图像文件中提取一些扩展信息。目前会将不同的 JPG APP 标记作为关联数组返回。一些程序使用这些 APP 标记在图像中嵌入文本信息。一个非常常见的用途是将 » IPTC 信息嵌入到 APP13 标记中。可以使用 iptcparse() 函数将二进制的 APP13 标记解析为可读的内容。

  > 注意:

  > `image_info` 仅支持 JFIF 文件。

### 返回值

返回信息最多包含 7 个元素。并非所有图像类型都包含 `channels` 和 `bits` 元素。

索引 0 和 1 分别包含图像的宽度和高度。

> 注意:

> 一些格式可能没有图像或者包含多个图像。在这种情况下，getimagesize() 可能无法正确确定图像大小。getimagesize() 此时会返回的宽高为 0。

> 注意: getimagesize() 是独立于任何图像元数据的。例如，如果 Exif `Orientation` 标志设置为将图像旋转 90 或 270 度的值，索引 0 和 1 被交换，即包含高度和宽度。

索引 2 是表示图像类型的某个 `IMAGETYPE_*` 常量。

索引 3 是文本字符串，包含可以直接用于 IMG 标签的正确 `height="yyy" width="xxx"` 字符串。

`mime` 是图像对应的 MIME 类型。此信息可用于传递具有正确 HTTP `Content-type` 报头的图像：

示例 #1 getimagesize() 和 MIME 类型

    <?php
    $size = getimagesize($filename);
    $fp = fopen($filename, "rb");
    if ($size && $fp) {
        header("Content-type: {$size['mime']}");
        fpassthru($fp);
        exit;
    } else {
        // error
    }
    ?>

`channels` 对 RGB 图片为 3，对 CMYK 图像为 4。

`bits` 是每种颜色的位数。

对应一些图像类型，`channels` 和 `bits` 的存在可能会让人困惑。例如，GIF 每个像素始终使用 3 个通道，但对于带有全局彩色表的动画 GIF，却无法计算每个像素的位数。

失败时返回 `false`。

### 错误／异常

如果无法访问 `filename` 图像，getimagesize() 将生成 `E_WARNING` 级别的错误。读取错误时，getimagesize() 将生成 `E_NOTICE` 级别的错误。

从 PHP 8.0.0 开始，如果 `filename` 不存在或无法访问， 将抛出一个 ValueError。

### 更新日志

版本 | 说明
--- | ---
8.2.0 | 现在将正确返回 AVIF 图像的实际尺寸、bits 和 channels；以前，尺寸报告为 `0x0`，并且不会报告 bits 和 channels。
8.0.0 | 如果 `filename` 不存在或无法访问，将抛出一个 ValueError；之前会生成一个 `E_WARNING` 级别的错误，并且函数返回 `false`。
7.1.0 | 新增 WebP 支持。

### 示例

示例 #2 getimagesize() 示例

    <?php
    list($width, $height, $type, $attr) = getimagesize("img/flag.jpg");
    echo "<img src=\"img/flag.jpg\" $attr alt=\"getimagesize() example\" />";
    ?>

示例 #3 getimagesize (URL)

    <?php
    $size = getimagesize("http://www.example.com/gifs/logo.gif");

    // if the file name has space in it, encode it properly
    $size = getimagesize("http://www.example.com/gifs/lo%20go.gif");

    ?>

示例 #4 getimagesize() 返回 IPTC

    <?php
    $size = getimagesize("testimg.jpg", $info);
    if (isset($info["APP13"])) {
        $iptc = iptcparse($info["APP13"]);
        var_dump($iptc);
    }
    ?>

### 注释

> 注意: 此函数不需要 GD 图象库。

### 参见

- image_type_to_mime_type() - 取得 getimagesize、exif_read_data、exif_thumbnail、exif_imagetype 所返回的图像类型的 MIME 类型
- exif_imagetype() - 判断一个图像的类型
- exif_read_data() - 从一个图片文件中读取 EXIF 头信息
- exif_thumbnail() - 检索图像的嵌入式缩略图
- imagesx() - 取得图像宽度
- imagesy() - 取得图像高度

# getimagesizefromstring

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

getimagesizefromstring — 从字符串中获取图像尺寸信息

### 说明

function getimagesizefromstring(string `$string`, array `&$image_info` = `null`): array|false

同 getimagesize() 函数，区别是 getimagesizefromstring() 的第一个参数是接受字符串而不是文件名。

关于本函数如何工作的更多信息请参见 getimagesize() 函数。

### 参数

`string`

  图像数据的字符串表示。

`image_info`

  参见 getimagesize()。

### 返回值

参见 getimagesize()。

### 示例

示例 #1 getimagesizefromstring() 示例

    <?php
    $img = '/path/to/test.png';

    // 以文件方式打开
    $size_info1 = getimagesize($img);

    // 以字符串格式打开
    $data       = file_get_contents($img);
    $size_info2 = getimagesizefromstring($data);
    ?>

### 参见

- getimagesize() - 取得图像大小

# image_type_to_extension

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

image_type_to_extension — 取得图像类型的文件后缀

### 说明

function image_type_to_extension(int `$image_type`, bool `$include_dot` = `true`): string|false

根据给定的常量 `IMAGETYPE_*` 返回后缀名。

### 参数

`image_type`

  `IMAGETYPE_*` 系列常量之一。

`include_dot`

  是否在后缀名前加一个点。默认是 `true`。

### 返回值

根据指定的图像类型返回对应的后缀名， 或者在失败时返回 `false`。

### 示例

示例 #1 image_type_to_extension() 示例

    <?php
    // 创建图像实例
    $im = imagecreatetruecolor(100, 100);

    // 保存图像
    imagepng($im, './test' . image_type_to_extension(IMAGETYPE_PNG));
    ?>

### 注释

> 注意: 此函数不需要 GD 图象库。

# image_type_to_mime_type

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

image_type_to_mime_type — 取得 getimagesize、exif_read_data、exif_thumbnail、exif_imagetype 所返回的图像类型的 MIME 类型

### 说明

function image_type_to_mime_type(int `$image_type`): string

image_type_to_mime_type() 函数将确定 IMAGETYPE 常量的 MIME 类型。

### 参数

`image_type`

  `IMAGETYPE_*` 常量之一。

### 返回值

返回值如下：

返回值常量
`image_type` | 返回值
--- | ---
`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`（小端字节顺序） | `image/tiff`
`IMAGETYPE_TIFF_MM`（大端字节顺序） | `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`

### 示例

示例 #1 image_type_to_mime_type() 示例

    <?php
    header("Content-type: " . image_type_to_mime_type(IMAGETYPE_PNG));
    ?>

### 注释

> 注意: 此函数不需要 GD 图象库。

### 参见

- getimagesize() - 取得图像大小
- exif_imagetype() - 判断一个图像的类型
- exif_read_data() - 从一个图片文件中读取 EXIF 头信息
- exif_thumbnail() - 检索图像的嵌入式缩略图

# image2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

image2wbmp — 输出图象到浏览器或文件。

警告

本函数已自 PHP 7.3.0 起弃用，自 PHP 8.0.0 起移除。强烈建议不要依赖本函数。

### 说明

function image2wbmp(resource `$image`, string `$filename` = ?, int `$foreground` = ?): bool

image2wbmp() 输出或保存为指定 `image` 的 WBMP 版本。

### 参数

`image`

  图像资源，由某个图像创建函数返回，比如 imagecreatetruecolor()。

`filename`

  保存文件的路径。如果没有指定，将直接输出原始图片流。

`foreground`

  使用此参数从 imagecolorallocate() 获得的标识符来设置前景色。默认前景色为黑色。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

警告

如果 libgd 输出图像失败，函数会返回 `true`。

### 示例

示例 #1 image2wbmp() 示例

    <?php
    $file = 'php.png';
    $image = imagecreatefrompng($file);

    header('Content-Type: ' . image_type_to_mime_type(IMAGETYPE_WBMP));
    image2wbmp($image); // 直接输出流
    ?>

### 参见

- imagewbmp() - 输出图象到浏览器或文件。

# imageaffine

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffine — 返回经过仿射变换后的图像，剪切区域可选

### 说明

function imageaffine(GdImage `$image`, array `$affine`, ?array `$clip` = `null`): GdImage|false

警告

本函数还未编写文档，仅有参数列表。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`affine`

  数组，其中键为 0 至 5 的数字。

`clip`

  数组，其中键为 "x"，"y"，"width" 和 "height"；或者 `null`。

### 返回值

成功则返回仿射变换后的图像对象， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `clip` 现在允许为 null。
8.0.0 | 成功时此函数现在返回 GDImage 实例；之前返回 resource。

# imageaffinematrixconcat

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffinematrixconcat — Concatenate two affine transformation matrices

### 说明

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.

### 参数

`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).

### 返回值

An affine transformation matrix (an array with keys `0` to `5` and float values) 或者在失败时返回 `false`.

### 示例

示例 #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);
    ?>

以上示例会输出：

    Array
    (
        [0] => 4
        [1] => 0
        [2] => 0
        [3] => 5
        [4] => 8
        [5] => 15
    )

### 参见

- imageaffine() - 返回经过仿射变换后的图像，剪切区域可选
- imageaffinematrixget() - Get an affine transformation matrix

# imageaffinematrixget

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffinematrixget — Get an affine transformation matrix

### 说明

function imageaffinematrixget(int `$type`, array|float `$options`): array|false

Returns an affine transformation matrix.

### 参数

`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.

### 返回值

An affine transformation matrix (an array with keys `0` to `5` and float values) 或者在失败时返回 `false`.

### 示例

示例 #1 imageaffinematrixget() example

    <?php
    $matrix = imageaffinematrixget(IMG_AFFINE_TRANSLATE, array('x' => 2, 'y' => 3));
    print_r($matrix);
    ?>

以上示例会输出：

    Array
    (
        [0] => 1
        [1] => 0
        [2] => 0
        [3] => 1
        [4] => 2
        [5] => 3
    )

### 参见

- imageaffine() - 返回经过仿射变换后的图像，剪切区域可选
- imageaffinematrixconcat() - Concatenate two affine transformation matrices

# imagealphablending

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagealphablending — 设定图像的混色模式

### 说明

function imagealphablending(GdImage `$image`, bool `$enable`): true

imagealphablending() 允许在真彩色图像上使用两种不同的绘画模式。在混色（blending）模式下，alpha 通道色彩成分提供给所有的绘画函数，例如 imagesetpixel() 决定底层的颜色应在何种程度上被允许照射透过。作为结果，GD 自动将该点现有的颜色和画笔颜色混合，并将结果储存在图像中。结果的像素是不透明的。在非混色模式下，画笔颜色连同其 alpha 通道信息一起被拷贝，替换掉目标像素。混色模式在画调色板图像时不可用。如果 `blendmode` 为 `true`，则启用混色模式，否则关闭。成功时返回 `true`， 或者在失败时返回 `false`。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`enable`

  是否启用混合模式。在真彩色图像上，默认值为 `true`，否则默认值为 `false`

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 imagealphablending() 用法示例

    <?php
    // 创建图像
    $im = imagecreatetruecolor(100, 100);

    // 设置 alphablending 为开启
    imagealphablending($im, true);

    // 画正方形
    imagefilledrectangle($im, 30, 30, 70, 70, imagecolorallocate($im, 255, 0, 0));

    // 输出
    header('Content-Type: image/png');

    imagepng($im);
    ?>

# imageantialias

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imageantialias — 是否使用抗锯齿（antialias）功能

### 说明

function imageantialias(GdImage `$image`, bool `$enable`): true

对线段和多边形启用快速画图抗锯齿方法。不支持 alpha 部分。使用直接混色操作。仅用于真彩色图像。

不支持线宽和风格。

使用抗锯齿和透明背景色可能出现未预期的结果。混色方法把背景色当成任何其它颜色使用。缺乏 alpha 部分的支持导致不允许基于 alpha 抗锯齿方法。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`enable`

  是否启用抗锯齿。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。
7.2.0 | imageantialias() 现在普遍可用。以前只有编译 PHP 时使用捆绑版本的 GD 库才可用。

### 示例

示例 #1 比较两条线，一条开启了抗锯齿

    <?php
    // 设置抗锯齿图像和普通图像
    $aa = imagecreatetruecolor(400, 100);
    $normal = imagecreatetruecolor(200, 100);

    // 为图片启用抗锯齿功能
    imageantialias($aa, true);

    // 分配颜色
    $red = imagecolorallocate($normal, 255, 0, 0);
    $red_aa = imagecolorallocate($aa, 255, 0, 0);

    // 绘制两条线，其中一条启用 AA
    imageline($normal, 0, 0, 200, 100, $red);
    imageline($aa, 0, 0, 200, 100, $red_aa);

    // 将两幅图像并排合并输出（AA：左，Normal：右）
    imagecopymerge($aa, $normal, 200, 0, 0, 0, 200, 100, 100);

    // 输出图像
    header('Content-type: image/png');

    imagepng($aa);
    ?>

以上示例的输出类似于：

### 参见

- imagecreatetruecolor() - 新建真彩色图像

# imagearc

(PHP 4, PHP 5, PHP 7, PHP 8)

imagearc — 画弧线

### 说明

function imagearc(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$start_angle`,
int `$end_angle`,
int `$color`
): true

imagearc() 绘制以指定坐标为中心的弧线。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`center_x`

  中心的 x 坐标。

`center_y`

  中心的 y 坐标。

`width`

  弧宽。

`height`

  弧高。

`start_angle`

  弧线起始角度，以度为单位。

`end_angle`

  弧线结束角度，以度为单位。0° 位于三点钟位置，顺时针绘制弧线。

`color`

  颜色标识符使用 imagecolorallocate() 创建。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 使用 imagearc() 画圆

    <?php

    // 创建 200*200 图像
    $img = imagecreatetruecolor(200, 200);

    // 分配一些颜色
    $white = imagecolorallocate($img, 255, 255, 255);
    $red   = imagecolorallocate($img, 255,   0,   0);
    $green = imagecolorallocate($img,   0, 255,   0);
    $blue  = imagecolorallocate($img,   0,   0, 255);

    // 画头
    imagearc($img, 100, 100, 200, 200,  0, 360, $white);
    // 嘴
    imagearc($img, 100, 100, 150, 150, 25, 155, $red);
    // 先左眼，然后右眼
    imagearc($img,  60,  75,  50,  50,  0, 360, $green);
    imagearc($img, 140,  75,  50,  50,  0, 360, $blue);

    // 在浏览器中输出图像
    header("Content-type: image/png");
    imagepng($img);

    ?>

以上示例的输出类似于：

### 参见

- imagefilledarc() - 绘制部分弧形并填充
- imageellipse() - 画椭圆
- imagefilledellipse() - 绘制椭圆并填充

# imageavif

(PHP 8 >= 8.1.0)

imageavif — 输出图象到浏览器或文件。

### 说明

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`.

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`file`

  文件保存的路径或者已打开的流资源（此方法返回后自动关闭该流资源），如果未设置或为 `null`，将会直接输出原始图象流。

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

警告

如果 libgd 输出图像失败，函数会返回 `true`。

### 错误／异常

Throws a ValueError if `quality` or `speed` is invalid.

### 更新日志

版本 | 说明
--- | ---
8.4.0 | Now throws a ValueError if `quality` or `speed` is invalid.

### 参见

- imagepng() - 将 PNG 图像输出到浏览器或文件
- imagewbmp() - 输出图象到浏览器或文件。
- imagejpeg() - 输出图象到浏览器或文件。
- imagetypes() - 返回 PHP 内置支持的图像类型

# imagebmp

(PHP 7 >= 7.2.0, PHP 8)

imagebmp — Output a BMP image to browser or file

### 说明

function imagebmp(GdImage `$image`, resource|string|null `$file` = `null`, bool `$compressed` = `true`): bool

Outputs or saves a BMP version of the given `image`.

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`file`

  文件保存的路径或者已打开的流资源（此方法返回后自动关闭该流资源），如果未设置或为 `null`，将会直接输出原始图象流。

  > 注意:

  > `null` is invalid if the `compressed` arguments is not used.

`compressed`

  Whether the BMP should be compressed with run-length encoding (RLE), or not.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

警告

如果 libgd 输出图像失败，函数会返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。
8.0.0 | The type of `compressed` is bool now; formerly it was int.

### 示例

示例 #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 — 水平地绘制一个字符

### 说明

function imagechar(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$char`,
int `$color`
): true

imagechar() 将 `char` 的首个字符绘制在 `image` 标识的图像中，其左上角位于 `x`，`y`（图像左上角为 0, 0），颜色为 `color`。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`font`
  取值对于内建的 latin2 编码字体可以是：1、2、3、4、5(更高的数字对应更大的字体)， 或是通过 imageloadfont() 返回的 GdFont 实例。
`x`

  起点的 x 坐标。

`y`

  起点的 y 坐标。

`char`

  要绘制的字符。

`color`

  颜色标识符使用 imagecolorallocate() 创建。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | `font` 参数现在接受 GdFont 实例和 int，之前仅接受 int。
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 imagechar() 示例

    <?php

    $im = imagecreate(100, 100);

    $string = 'PHP';

    $bg = imagecolorallocate($im, 255, 255, 255);
    $black = imagecolorallocate($im, 0, 0, 0);

    // 在左上角打印一个黑色“P”
    imagechar($im, 1, 0, 0, $string, $black);

    header('Content-type: image/png');
    imagepng($im);

    ?>

以上示例的输出类似于：

### 参见

- imagecharup() - 垂直地绘制一个字符
- imageloadfont() - 载入新字体

# imagecharup

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecharup — 垂直地绘制一个字符

### 说明

function imagecharup(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$char`,
int `$color`
): true

在指定 `image` 的特定坐标处竖直绘制字符 `char`。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`font`
  取值对于内建的 latin2 编码字体可以是：1、2、3、4、5(更高的数字对应更大的字体)， 或是通过 imageloadfont() 返回的 GdFont 实例。
`x`

  起点的 x 坐标。

`y`

  起点的 y 坐标。

`char`

  要绘制的字符。

`color`

  颜色标识符使用 imagecolorallocate() 创建。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | `font` 参数现在接受 GdFont 实例和 int，之前仅接受 int。
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 imagecharup() 示例

    <?php

    $im = imagecreate(100, 100);

    $string = 'Note that the first letter is a N';

    $bg = imagecolorallocate($im, 255, 255, 255);
    $black = imagecolorallocate($im, 0, 0, 0);

    // 在白色背景上打印黑色“Z”
    imagecharup($im, 3, 10, 10, $string, $black);

    header('Content-type: image/png');
    imagepng($im);

    ?>

以上示例的输出类似于：

### 参见

- imagechar() - 水平地绘制一个字符
- imageloadfont() - 载入新字体

# imagecolorallocate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorallocate — 为图像分配颜色

### 说明

function imagecolorallocate(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int|false

返回颜色标识符，表示由指定 RGB 成分组成的颜色。

必须调用 imagecolorallocate() 创建要在 `image` 表示的图像中使用的每种颜色。

> 注意:

> 第一次调用 imagecolorallocate() 会对基于调色板的图像填充背景色——使用 imagecreate() 建立的图像。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`red`

  红色成分的值。

`green`

  绿色成分的值。

`blue`

  蓝色成分的值。

这些参数是 0 到 255 之间的整数或者 0x00 到 0xFF 之间的十六进制数字。

### 返回值

颜色标识符，如果分配失败，则为 `false`。

警告

此函数可能返回布尔值 `false`，但也可能返回等同于 `false` 的非布尔值。请阅读 布尔类型章节以获取更多信息。应使用 === 运算符来测试此函数的返回值。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 imagecolorallocate() 示例

    <?php

    $im = imagecreate(100, 100);

    // 设置背景为红色
    $background = imagecolorallocate($im, 255, 0, 0);

    // 设置一些颜色
    $white = imagecolorallocate($im, 255, 255, 255);
    $black = imagecolorallocate($im, 0, 0, 0);

    // 十六进制方式
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
    $black = imagecolorallocate($im, 0x00, 0x00, 0x00);

    ?>

### 参见

- imagecolorallocatealpha() - 为图像分配颜色
- imagecolordeallocate() - 取消图像颜色的分配

# imagecolorallocatealpha

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imagecolorallocatealpha — 为图像分配颜色

### 说明

function imagecolorallocatealpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int|false

imagecolorallocatealpha() 的行为和 imagecolorallocate() 相同，但多了一个额外的透明度参数 `alpha`。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`red`

  红色成分的值。

`green`

  绿色成分的值。

`blue`

  蓝色成分的值。

`alpha`

  介于 `0` 和 `127` 之间的值。`0` 表示完全不透明，而 `127` 表示完全透明。

`red`、`green` 和 `blue` 参数是 0 到 255 之间的整数或 0x00 到 0xFF 之间的十六进制数。

### 返回值

颜色标识符，如果分配失败，则为 `false`。

警告

此函数可能返回布尔值 `false`，但也可能返回等同于 `false` 的非布尔值。请阅读 布尔类型章节以获取更多信息。应使用 === 运算符来测试此函数的返回值。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 使用 imagecolorallocatealpha() 的示例

    <?php
    $size = 300;
    $image=imagecreatetruecolor($size, $size);

    // 白色背景加黑色边框
    $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;

    // 用 alpha 值分配一些颜色
    $yellow = imagecolorallocatealpha($image, 255, 255, 0, 75);
    $red    = imagecolorallocatealpha($image, 255, 0, 0, 75);
    $blue   = imagecolorallocatealpha($image, 0, 0, 255, 75);

    // 绘制 3 个重叠的圆
    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);

    // 不要忘记输出正确的 header！
    header('Content-Type: image/png');

    // 最后，输出结果
    imagepng($image);
    ?>

以上示例的输出类似于：

示例 #2 转换典型的 alpha 值以供 imagecolorallocatealpha() 使用

通常，alpha 值为 `0` 表示完全透明的像素，alpha 通道有 8 位。要转换此类 alpha 值以与 imagecolorallocatealpha() 兼容，只需进行一些简单的算术运算即可：

    <?php
    $alpha8 = 0; // 完全透明
    var_dump(127 - ($alpha8 >> 1));
    $alpha8 = 255; // 完全不透明
    var_dump(127 - ($alpha8 >> 1));
    ?>

以上示例会输出：

    int(127)
    int(0)

### 参见

- imagecolorallocate() - 为图像分配颜色
- imagecolordeallocate() - 取消图像颜色的分配

# imagecolorat

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorat — 取得某像素的颜色索引值

### 说明

function imagecolorat(GdImage `$image`, int `$x`, int `$y`): int|false

返回 `image` 所指定的图像中指定位置像素的颜色索引值。

如果图像是真彩色图像，此函数以整数返回该点的 RGB 值。用位移加掩码来取得红，绿，蓝各自的值：

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`x`

  点的 x 坐标。

`y`

  点的 y 坐标。

### 返回值

返回颜色的索引 或者在失败时返回 `false`。

警告

此函数可能返回布尔值 `false`，但也可能返回等同于 `false` 的非布尔值。请阅读 布尔类型章节以获取更多信息。应使用 === 运算符来测试此函数的返回值。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 访问不同的 RGB 值

    <?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);
    ?>

以上示例的输出类似于：

    int(119)
    int(123)
    int(180)

示例 #2 使用 imagecolorsforindex() 获取可读的 RGB 值

    <?php
    $im = imagecreatefrompng("php.png");
    $rgb = imagecolorat($im, 10, 15);

    $colors = imagecolorsforindex($im, $rgb);

    var_dump($colors);
    ?>

以上示例的输出类似于：

    array(4) {
      ["red"]=>
      int(119)
      ["green"]=>
      int(123)
      ["blue"]=>
      int(180)
      ["alpha"]=>
      int(127)
    }

### 参见

- imagecolorset() - 给指定调色板索引设定颜色
- imagecolorsforindex() - 获取索引的颜色
- imagesetpixel() - 设置单个像素

# imagecolorclosest

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorclosest — 取得与指定的颜色最接近的颜色索引值

### 说明

function imagecolorclosest(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

返回图像调色板中与指定的 RGB 值最“接近”的颜色索引。

计算所需颜色与调色板中每种颜色之间的“距离”，就好像 RGB 值表示三维空间中的点一样。

如果图象由文件创建，只有该图象使用到的颜色会被解析。仅存在于调色板中的颜色不会被解析。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`red`

  红色成分的值。

`green`

  绿色成分的值。

`blue`

  蓝色成分的值。

颜色参数是 0 到 255 之间的整数或 0x00 和 0xFF 之间的十六进制数。

### 返回值

返回图像调色板中最接近指定颜色的索引

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 在图像中搜索一组颜色

    <?php
    // 从图像开始并将其转换为基于调色板的图像
    $im = imagecreatefrompng('figures/imagecolorclosest.png');
    imagetruecolortopalette($im, false, 255);

    // 搜索颜色（RGB）
    $colors = array(
        array(254, 145, 154),
        array(153, 145, 188),
        array(153, 90, 145),
        array(255, 137, 92)
    );

    // 循环执行每个搜索并找到调色板中最接近的颜色。
    // 返回搜索编号、搜索 RGB 和转换后的 RGB 匹配项
    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: Search ($rgb[0], $rgb[1], $rgb[2]); Closest match: $result.\n";
    }
    ?>

以上示例的输出类似于：

    #0: Search (254, 145, 154); Closest match: (252, 150, 148).
    #1: Search (153, 145, 188); Closest match: (148, 150, 196).
    #2: Search (153, 90, 145); Closest match: (148, 90, 156).
    #3: Search (255, 137, 92); Closest match: (252, 150, 92).

### 参见

- imagecolorexact() - 取得指定颜色的索引值
- imagecolorclosestalpha() - 获取最接近指定颜色 + alpha 的颜色索引
- imagecolorclosesthwb() - 取得与给定颜色最接近的色度的黑白色的索引

# imagecolorclosestalpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorclosestalpha — 获取最接近指定颜色 + alpha 的颜色索引

### 说明

function imagecolorclosestalpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int

返回图像调色板中“最接近”指定 RGB 值以及 `alpha` 级别的颜色索引。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`red`

  红色成分的值。

`green`

  绿色成分的值。

`blue`

  蓝色成分的值。

`alpha`

  介于 `0` 和 `127` 之间的值。`0` 表示完全不透明，而 `127` 表示完全透明。

colors 参数是 0 到 255 之间的整数或 0x00 到 0xFF 之间的十六进制数。

### 返回值

返回调色板中最接近的颜色的索引。

### 示例

示例 #1 在图像中搜索一组颜色

    <?php
    // 从图像开始并将其转换为基于调色板的图像
    $im = imagecreatefrompng('figures/imagecolorclosest.png');
    imagetruecolortopalette($im, false, 255);

    // 搜索颜色（RGB）
    $colors = array(
        array(254, 145, 154, 50),
        array(153, 145, 188, 127),
        array(153, 90, 145, 0),
        array(255, 137, 92, 84)
    );

    // 循环执行每个搜索并找到调色板中最接近的颜色。
    // 返回搜索编号、搜索 RGB 和转换后的 RGB 匹配项
    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";
    }
    ?>

以上示例的输出类似于：

    #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).

### 参见

- imagecolorexactalpha() - 取得指定的颜色加透明度的索引值
- imagecolorclosest() - 取得与指定的颜色最接近的颜色索引值
- imagecolorclosesthwb() - 取得与给定颜色最接近的色度的黑白色的索引

# imagecolorclosesthwb

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecolorclosesthwb — 取得与给定颜色最接近的色度的黑白色的索引

### 说明

function imagecolorclosesthwb(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

取得与给定颜色最接近的色度的黑白色的索引。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`red`

  红色成分的值。

`green`

  绿色成分的值。

`blue`

  蓝色成分的值。

### 返回值

返回一个整数，是给定颜色最接近的色度的黑白色的索引。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 使用 imagecolorclosesthwb() 示例

    <?php
    $im = imagecreatefromgif('php.gif');

    echo 'HWB: ' . imagecolorclosesthwb($im, 116, 115, 152);
    ?>

以上示例的输出类似于：

    HWB: 33

### 参见

- imagecolorclosest() - 取得与指定的颜色最接近的颜色索引值

# imagecolordeallocate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolordeallocate — 取消图像颜色的分配

### 说明

function imagecolordeallocate(GdImage `$image`, int `$color`): true

取消分配先前由 imagecolorallocate() 或 imagecolorallocatealpha() 分配的颜色。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`color`

  颜色标识符。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 使用 imagecolordeallocate()

    <?php
    $white = imagecolorallocate($im, 255, 255, 255);
    imagecolordeallocate($im, $white);
    ?>

### 参见

- imagecolorallocate() - 为图像分配颜色
- imagecolorallocatealpha() - 为图像分配颜色

# imagecolorexact

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorexact — 取得指定颜色的索引值

### 说明

function imagecolorexact(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

返回图像调色板中指定颜色的索引值。

如果图象由文件创建，只有该图象使用到的颜色会被解析。仅存在于调色板中的颜色不会被解析。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`red`

  红色成分的值。

`green`

  绿色成分的值。

`blue`

  蓝色成分的值。

### 返回值

返回调色板中指定颜色的索引值，如果该颜色不存在则返回 -1。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 从 GD logo 中获取颜色

    <?php
    // 设置图像
    $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);
    ?>

以上示例的输出类似于：

    Array
    (
        [0] => 16711680
        [1] => 0
        [2] => 16777215
        [3] => 6618932
    )

### 参见

- imagecolorclosest() - 取得与指定的颜色最接近的颜色索引值

# imagecolorexactalpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorexactalpha — 取得指定的颜色加透明度的索引值

### 说明

function imagecolorexactalpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int

返回图像调色板中指定颜色加透明度的索引值。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`red`

  红色成分的值。

`green`

  绿色成分的值。

`blue`

  蓝色成分的值。

`alpha`

  介于 `0` 和 `127` 之间的值。`0` 表示完全不透明，而 `127` 表示完全透明。

colors 参数是 0 到 255 之间的整数或 0x00 到 0xFF 之间的十六进制数。

### 返回值

返回图像调色板中指定颜色加透明度的索引值。 如果颜色不在图像的调色板中，返回 -1。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 从 GD logo 中获取颜色

    <?php

    // 设置图像
    $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);
    ?>

以上示例的输出类似于：

    Array
    (
        [0] => 16711680
        [1] => 2130706432
        [2] => 939524095
        [3] => 342163252
    )

### 参见

- imagecolorclosestalpha() - 获取最接近指定颜色 + alpha 的颜色索引

# imagecolormatch

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagecolormatch — 使一个图像中调色板版本的颜色与真彩色版本更能匹配

### 说明

function imagecolormatch(GdImage `$image1`, GdImage `$image2`): true

使一个图像中调色板版本的颜色与真彩色版本更能匹配。

### 参数

`image1`

  真彩色图像对象。

`image2`

  调色板图像对象，指向与 `image1` 相同大小的图像。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image1` 和 `image2` 现在需要 GdImage 实例，之前需要 resource。

### 示例

示例 #1 imagecolormatch() 示例

    <?php
    // 设置真彩色和调色板图像
    $im1 = imagecreatefrompng('./gdlogo.png');
    $im2 = imagecreate(imagesx($im1), imagesy($im1));

    // 给 $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);

    // 将这些颜色与真彩图像进行匹配
    imagecolormatch($im1, $im2);
    ?>

### 参见

- imagecreatetruecolor() - 新建真彩色图像

# imagecolorresolve

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorresolve — 取得指定颜色的索引值或有可能得到的最接近的替代值

### 说明

function imagecolorresolve(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

本函数可以保证对所请求的颜色返回颜色索引，要么是准确的颜色要么是最接近的颜色。

如果图象由文件创建，只有该图象使用到的颜色会被解析。仅存在于调色板中的颜色不会被解析。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`red`

  红色成分的值。

`green`

  绿色成分的值。

`blue`

  蓝色成分的值。

### 返回值

返回颜色索引值。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 使用 imagecoloresolve() 从图像中获取颜色

    <?php
    // 加载图像
    $im = imagecreatefromgif('phplogo.gif');

    // 从图像中获取最接近的颜色
    $colors = array();
    $colors[] = imagecolorresolve($im, 255, 255, 255);
    $colors[] = imagecolorresolve($im, 0, 0, 200);

    // 输出
    print_r($colors);
    ?>

以上示例的输出类似于：

    Array
    (
        [0] => 89
        [1] => 85
    )

### 参见

- imagecolorclosest() - 取得与指定的颜色最接近的颜色索引值

# imagecolorresolvealpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorresolvealpha — 取得指定颜色 + alpha 或其最接近的替代值

### 说明

function imagecolorresolvealpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int

本函数保证返回所请求的颜色的颜色索引，要么是确切的颜色要么是最接近的颜色。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`red`

  红色成分的值。

`green`

  绿色成分的值。

`blue`

  蓝色成分的值。

`alpha`

  介于 `0` 和 `127` 之间的值。`0` 表示完全不透明，而 `127` 表示完全透明。

colors 参数是 0 到 255 之间的整数或 0x00 到 0xFF 之间的十六进制数。

### 返回值

返回颜色索引。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 使用 imagecoloresolvealpha() 从图像中获取颜色

    <?php
    // 加载图像
    $im = imagecreatefromgif('phplogo.gif');

    // 从图像中获取最接近的颜色
    $colors = array();
    $colors[] = imagecolorresolvealpha($im, 255, 255, 255, 0);
    $colors[] = imagecolorresolvealpha($im, 0, 0, 200, 127);

    // 输出
    print_r($colors);
    ?>

以上示例的输出类似于：

    Array
    (
        [0] => 89
        [1] => 85
    )

### 参见

- imagecolorclosestalpha() - 获取最接近指定颜色 + alpha 的颜色索引

# imagecolorset

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorset — 给指定调色板索引设定颜色

### 说明

function imagecolorset(
GdImage `$image`,
int `$color`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha` = 0
): ?false

本函数将调色板中指定的索引设定为指定的颜色。对于在调色板图像中创建类似区域填充（flood-fill）的效果很有用，免去了真的去填充的开销。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`color`

  调色板中的索引值。

`red`

  红色成分的值。

`green`

  绿色成分的值。

`blue`

  蓝色成分的值。

`alpha`

  alpha 的值。

### 返回值

函数成功时返回 `null`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 imagecolorset() 示例

    <?php
    // 创建 300x100 图像
    $im = imagecreate(300, 100);

    // 设置背景为红色
    imagecolorallocate($im, 255, 0, 0);

    // 获取背景颜色索引
    $bg = imagecolorat($im, 0, 0);

    // 设置背景为蓝色
    imagecolorset($im, $bg, 0, 0, 255);

    // 输出图像到浏览器
    header('Content-Type: image/png');

    imagepng($im);
    ?>

### 参见

- imagecolorat() - 取得某像素的颜色索引值

# imagecolorsforindex

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorsforindex — 获取索引的颜色

### 说明

function imagecolorsforindex(GdImage `$image`, int `$color`): array

获取指定索引的颜色。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`color`

  颜色索引。

### 返回值

返回具有 red、green、blue 和 alpha 的键名的关联数组，包含了指定颜色索引的适当值。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。
8.0.0 | 如果 `color` 超出范围，imagecolorsforindex() 现在抛出 ValueError 异常；之前返回 `false`。

### 示例

示例 #1 imagecolorsforindex() 示例

    <?php

    // 打开图像
    $im = imagecreatefrompng('nexen.png');

    // 获取颜色
    $start_x = 40;
    $start_y = 50;
    $color_index = imagecolorat($im, $start_x, $start_y);

    // 使其可读
    $color_tran = imagecolorsforindex($im, $color_index);

    // 显示该颜色的值
    print_r($color_tran);

    ?>

以上示例的输出类似于：

    Array
    (
       [red] => 226
       [green] => 222
       [blue] => 252
       [alpha] => 0
    )

### 参见

- imagecolorat() - 取得某像素的颜色索引值
- imagecolorexact() - 取得指定颜色的索引值

# imagecolorstotal

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorstotal — 取得图像调色板中的颜色数量

### 说明

function imagecolorstotal(GdImage `$image`): int

返回图像调色板中的颜色数量。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。

### 返回值

返回指定图像调色板中的颜色数量，真彩色图像为 0。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 使用 imagecolorstotal() 获取图像中的颜色总数

    <?php
    // 创建图像实例
    $im = imagecreatefromgif('php.gif');

    echo 'Total colors in image: ' . imagecolorstotal($im);
    ?>

以上示例的输出类似于：

    Total colors in image: 128

### 参见

- imagecolorat() - 取得某像素的颜色索引值
- imagecolorsforindex() - 获取索引的颜色
- imageistruecolor() - 检查图像是否为真彩色图像

# imagecolortransparent

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolortransparent — 将颜色定义为透明

### 说明

function imagecolortransparent(GdImage `$image`, ?int `$color` = `null`): int

获取或设置指定 `image` 中的透明色。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`color`

  颜色标识符使用 imagecolorallocate() 创建。

### 返回值

返回新（或当前，如果未指定）透明色的标识符。如果 `color` 为 `null`，并且图像没有透明色，则返回的标识符为 `-1`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。
8.0.0 | `color` 现在允许为 null。

### 示例

示例 #1 imagecolortransparent() 示例

    <?php
    // 创建 55x30 图像
    $im = imagecreatetruecolor(55, 30);
    $red = imagecolorallocate($im, 255, 0, 0);
    $black = imagecolorallocate($im, 0, 0, 0);

    // 使背景透明
    imagecolortransparent($im, $black);

    // 画红色矩形
    imagefilledrectangle($im, 4, 4, 50, 25, $red);

    // 保存图像
    imagepng($im, './imagecolortransparent.png');
    ?>

以上示例的输出类似于：

### 注释

> 注意:

> 透明度仅能使用 imagecopymerge() 和真彩色图像复制，而不使用 imagecopy() 或调色板图像。

> 注意:

> 透明色是图像的属性，透明度不是颜色的属性。一旦设定某个颜色为透明色，图像中之前绘制为该颜色的任何区域都成为透明的。

# imageconvolution

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

imageconvolution — 用系数 div 和 offset 申请一个 3x3 的卷积矩阵

### 说明

function imageconvolution(
GdImage `$image`,
array `$matrix`,
float `$divisor`,
float `$offset`
): bool

使用指定的系数和 offset 在图像上应用卷积矩阵。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`matrix`

  3x3 矩阵：三个浮点数组成的数组，再由这样的三个数组组成的数组。

`divisor`

  The divisor of the result of the convolution, used for normalization.

`offset`

  颜色偏移。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #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);
    ?>

以上示例会输出：

示例 #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);
    ?>

以上示例会输出：

### 参见

- imagefilter() - 对图像使用过滤器

# imagecopy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecopy — 拷贝图像的一部分

### 说明

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

从 x、y 坐标 `src_x`、`src_y` 开始，将 `src_image` 的一部分复制到 `dst_image` 上，宽度为 `src_width`，高度为 `src_height`。定义的部分将被复制到 x,y 坐标 `dst_x` 和 `dst_y` 上。

### 参数

`dst_image`

  目标图象资源。

`src_image`

  源图象资源。

`dst_x`

  目标点的 x 坐标。

`dst_y`

  目标点的 y 坐标。

`src_x`

  源点的 x 坐标。

`src_y`

  源点的 y 坐标。

`src_width`

  源图象的宽度。

`src_height`

  源图象的高度。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `dst_image` 和 `src_image` 现在需要 GdImage 实例；之前需要 resource。

### 示例

示例 #1 裁剪 PHP.net logo

    <?php
    // 创建图像实例
    $src = imagecreatefromgif('php.gif');
    $dest = imagecreatetruecolor(80, 40);

    // 复制
    imagecopy($dest, $src, 0, 0, 20, 13, 80, 40);

    // 输出
    header('Content-Type: image/gif');
    imagegif($dest);
    ?>

以上示例的输出类似于：

### 参见

- imagecrop() - Crop an image to the given rectangle

# imagecopymerge

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecopymerge — 拷贝并合并图像的一部分

### 说明

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

从 x、y 坐标 `src_x`、`src_y` 开始，将 `src_image` 的一部分复制到 `dst_image` 上，宽度为 `src_width`，高度为 `src_height`。定义的部分将被复制到 x、y 坐标 `dst_x` 和 `dst_y` 上。

### 参数

`dst_image`

  目标图象资源。

`src_image`

  源图象资源。

`dst_x`

  目标点的 x 坐标。

`dst_y`

  目标点的 y 坐标。

`src_x`

  源点的 x 坐标。

`src_y`

  源点的 y 坐标。

`src_width`

  源图象的宽度。

`src_height`

  源图象的高度。

`pct`

  两个图像将根据 `pct` 合并，范围是 0 到 100。当 `pct` = 0，不采取任何操作，当 100 时，此函数的行为与调色板图像的 imagecopy() 相同，除了忽略 alpha alpha 组件（components），其实现了真彩色图像的 alpha 透明度。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `dst_image` 和 `src_image` 现在需要 GdImage 实例；之前需要 resource。

### 示例

示例 #1 使用 75% 透明度合并 PHP.net logo 的两个副本

    <?php
    // 创建图像实例
    $dest = imagecreatefromgif('php.gif');
    $src = imagecreatefromgif('php.gif');

    // 复制并合并
    imagecopymerge($dest, $src, 10, 10, 0, 0, 100, 47, 75);

    // 输出
    header('Content-Type: image/gif');
    imagegif($dest);
    ?>

# imagecopymergegray

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecopymergegray — 用灰度复制并合并图像的一部分

### 说明

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() 将 `src_image` 的一部分复制到 `dst_image` 上，起始于 x、y 坐标 `src_x`、`src_y`，宽度为 `src_width`，高度为 `src_height`。定义的部分将被复制到 x、y 坐标 `dst_x` 和 `dst_y` 上。

本函数和 imagecopymerge() 相同，只是在合并时通过在复制操作前将目标像素转换为灰度级来保留了原色度。

### 参数

`dst_image`

  目标图象资源。

`src_image`

  源图象资源。

`dst_x`

  目标点的 x 坐标。

`dst_y`

  目标点的 y 坐标。

`src_x`

  源点的 x 坐标。

`src_y`

  源点的 y 坐标。

`src_width`

  源图象的宽度。

`src_height`

  源图象的高度。

`pct`

  `src_image` 将根据 `pct` 改变灰度，其中 0 为全灰度，100 不变。当 `pct` = 100 时，此函数的行为与调色板图像的 imagecopy() 相同，除了忽略 alpha 组件（components），其实现了真彩色图像的 alpha 透明度。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `dst_image` 和 `src_image` 现在需要 GdImage 实例，之前需要 resource。

### 示例

示例 #1 imagecopymergegray() 用法

    <?php
    // 创建图像实例
    $dest = imagecreatefromgif('php.gif');
    $src = imagecreatefromgif('php.gif');

    // 复制并合并 - 灰色 = 20%
    imagecopymergegray($dest, $src, 10, 10, 0, 0, 100, 47, 20);

    // 输出
    header('Content-Type: image/gif');
    imagegif($dest);
    ?>

# imagecopyresampled

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecopyresampled — 重采样拷贝部分图像并调整大小

### 说明

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() 将一幅图像中的一块正方形区域拷贝到另一个图像中，平滑地插入像素值，因此，尤其是，减小了图像的大小而仍然保持了极大的清晰度。

换句话说，imagecopyresampled() 会从 `src_image` 中取出一个宽度为 `src_width` 高度为 `src_height` 的矩形区域，在位置（`src_x`、`src_y`）并将其放置在 `dst_image` 中宽度为 `dst_width` 高度为 `dst_height` 的矩形区域中，位置为（`dst_x`、`dst_y`）。

如果源和目标的宽度和高度不同，则会进行相应的图像收缩和拉伸。坐标指的是左上角。本函数可用来在同一幅图内部拷贝（如果 `dst_image` 和 `src_image` 相同的话）区域，但如果区域交迭的话则结果不可预知。

### 参数

`dst_image`

  目标图象资源。

`src_image`

  源图象资源。

`dst_x`

  目标 X 坐标点。

`dst_y`

  目标 Y 坐标点。

`src_x`

  源的 X 坐标点。

`src_y`

  源的 Y 坐标点。

`dst_width`

  目标宽度。

`dst_height`

  目标高度。

`src_width`

  源图象的宽度。

`src_height`

  源图象的高度。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `dst_image` 和 `src_image` 现在需要 GdImage 实例，之前需要 resource。

### 示例

示例 #1 简单的示例

这个例子会将图像调整为原有尺寸的一半。

    <?php
    // 这个文件
    $filename = 'test.jpg';
    $percent = 0.5;

    // 内容类型
    header('Content-Type: image/jpeg');

    // 获取新的尺寸
    list($width, $height) = getimagesize($filename);
    $new_width = $width * $percent;
    $new_height = $height * $percent;

    // 重新取样
    $image_p = imagecreatetruecolor($new_width, $new_height);
    $image = imagecreatefromjpeg($filename);
    imagecopyresampled($image_p, $image, 0, 0, 0, 0, $new_width, $new_height, $width, $height);

    // 输出
    imagejpeg($image_p, null, 100);
    ?>

以上示例的输出类似于：

示例 #2 按比例对图像重新采样

这个例子会以最大宽度高度为 200 像素显示一个图像。

    <?php
    // 源文件
    $filename = 'test.jpg';

    // 设置最大宽高
    $width = 200;
    $height = 200;

    // Content type
    header('Content-Type: image/jpeg');

    // 获取新尺寸
    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;
    }

    // 重新取样
    $image_p = imagecreatetruecolor($width, $height);
    $image = imagecreatefromjpeg($filename);
    imagecopyresampled($image_p, $image, 0, 0, 0, 0, $width, $height, $width_orig, $height_orig);

    // 输出
    imagejpeg($image_p, null, 100);
    ?>

以上示例的输出类似于：

### 注释

> 注意:

> 因为调色板图像限制（255+1 种颜色）有个问题。重采样或过滤图像通常需要多于 255 种颜色，计算新的被重采样的像素及其颜色时采用了一种近似值。对调色板图像尝试分配一个新颜色时，如果失败我们选择了计算结果最接近（理论上）的颜色。这并不总是视觉上最接近的颜色。这可能会产生怪异的结果，例如空白（或者视觉上是空白）的图像。要跳过这个问题，请使用真彩色图像作为目标图像，例如用 imagecreatetruecolor() 创建的。

### 参见

- imagecopyresized() - 拷贝部分图像并调整大小
- 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 — 拷贝部分图像并调整大小

### 说明

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() 将一幅图像中的一块矩形区域拷贝到另一个图像中。`dst_image` 和 `src_image` 分别是目标图像和源图像的标识符。

换句话说，imagecopyresized() 会从 `src_image` 中取出一个宽度为 `src_width` 高度为 `src_height` 的矩形区域，在位置（`src_x`、`src_y`）并将其放置在 `dst_image` 中宽度为 `dst_width` 高度为 `dst_height` 的矩形区域中，位置为（`dst_x`、`dst_y`）。

如果源和目标的宽度和高度不同，则会进行相应的图像收缩和拉伸。坐标指的是左上角。本函数可用来在同一幅图内部拷贝（如果 `dst_image` 和 `src_image` 相同的话）区域，但如果区域交迭的话则结果不可预知。

### 参数

`dst_image`

  目标图象资源。

`src_image`

  源图象资源。

`dst_x`

  目标点的 x 坐标。

`dst_y`

  目标点的 y 坐标。

`src_x`

  源点的 x 坐标。

`src_y`

  源点的 y 坐标。

`dst_width`

  目标宽度。

`dst_height`

  目标高度。

`src_width`

  源图象的宽度。

`src_height`

  源图象的高度。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `dst_image` 和 `src_image` 现在需要 GdImage 实例，之前需要 resource。

### 示例

示例 #1 缩放图像

此示例将以一半大小显示图像。

    <?php
    // File and new size
    $filename = 'test.jpg';
    $percent = 0.5;

    // Content type
    header('Content-Type: image/jpeg');

    // Get new sizes
    list($width, $height) = getimagesize($filename);
    $newwidth = $width * $percent;
    $newheight = $height * $percent;

    // Load
    $thumb = imagecreatetruecolor($newwidth, $newheight);
    $source = imagecreatefromjpeg($filename);

    // Resize
    imagecopyresized($thumb, $source, 0, 0, 0, 0, $newwidth, $newheight, $width, $height);

    // Output
    imagejpeg($thumb);
    ?>

以上示例的输出类似于：

图像将以一半大小输出，但使用 imagecopyresampled() 可以获得更好的质量。

### 注释

> 注意:

> 因为调色板图像限制（255+1 种颜色）有个问题。重采样或过滤图像通常需要多于 255 种颜色，计算新的被重采样的像素及其颜色时采用了一种近似值。对调色板图像尝试分配一个新颜色时，如果失败我们选择了计算结果最接近（理论上）的颜色。这并不总是视觉上最接近的颜色。这可能会产生怪异的结果，例如空白（或者视觉上是空白）的图像。要跳过这个问题，请使用真彩色图像作为目标图像，例如用 imagecreatetruecolor() 创建的。

### 参见

- imagecopyresized()
- 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 — 创建新的基于调色板的图像

### 说明

function imagecreate(int `$width`, int `$height`): GdImage|false

imagecreate() 返回代表指定大小的空白图像的图像标识符。

通常，建议使用 imagecreatetruecolor() 而不是 imagecreate()，以便在尽可能的最高质量图像上进行图像处理。如果要输出调色板图像，则应在使用 imagepng() 或 imagegif() 保存图像之前立即调用 imagetruecolortopalette()。

### 参数

`width`

  图像宽度。

`height`

  图像高度。

### 返回值

成功后返回图象对象,失败后返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 成功时，此函数现在返回 GDImage 实例，之前返回 resource。

### 示例

示例 #1 创建新的 GD 图像流并输出图像。

    <?php
    header("Content-Type: image/png");
    $im = @imagecreate(110, 20)
        or die("Cannot Initialize new GD image stream");
    $background_color = imagecolorallocate($im, 0, 0, 0);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);
    imagepng($im);
    ?>

以上示例的输出类似于：

### 参见

- imagecreatetruecolor() - 新建真彩色图像

# imagecreatefromavif

(PHP 8 >= 8.1.0)

imagecreatefromavif — 由文件或 URL 创建一个新图象。

### 说明

function imagecreatefromavif(string `$filename`): GdImage|false

imagecreatefromavif() returns an image object representing the image obtained from the given filename.

### 参数

`filename`

  Path to the AVIF raster image.

### 返回值

成功后返回图象对象,失败后返回 `false`。

# imagecreatefrombmp

(PHP 7 >= 7.2.0, PHP 8)

imagecreatefrombmp — 由文件或 URL 创建一个新图象。

### 说明

function imagecreatefrombmp(string `$filename`): GdImage|false

imagecreatefrombmp() returns an image identifier representing the image obtained from the given filename.

小技巧

如已启用fopen 包装器，在此函数中， URL 可作为文件名。关于如何指定文件名详见 fopen()。各种 wapper 的不同功能请参见 支持的协议和封装协议，注意其用法及其可提供的预定义变量。

### 参数

`filename`

  Path to the BMP image.

### 返回值

成功后返回图象对象,失败后返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.

### 示例

示例 #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 — 从 GD 文件或 URL 新建一图像

### 说明

function imagecreatefromgd(string `$filename`): GdImage|false

从 GD 文件或 URL 新建图像。

小技巧

如已启用fopen 包装器，在此函数中， URL 可作为文件名。关于如何指定文件名详见 fopen()。各种 wapper 的不同功能请参见 支持的协议和封装协议，注意其用法及其可提供的预定义变量。

### 参数

`filename`

  GD 文件的路径。

### 返回值

成功后返回图象对象,失败后返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 成功时，此函数现在返回 GDImage 实例，之前返回 resource。

### 示例

示例 #1 imagecreatefromgd() 示例

    <?php
    // 加载 gd 图像
    $im = @imagecreatefromgd('./test.gd');

    // 测试图像是否加载
    if(!$im)
    {
         die('Unable to load gd image!');
    }

    // 这里进行图像操作

    // 保存图像
    imagegd($im, './test_updated.gd');
    ?>

### 注释

警告

The GD and GD2 image formats are proprietary image formats of libgd. They have to be regarded obsolete, and should only be used for development and testing purposes.

# imagecreatefromgd2

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd2 — 从 GD2 文件或 URL 新建一图像

### 说明

function imagecreatefromgd2(string `$filename`): GdImage|false

从 GD2 文件或 URL 新建一图像。

小技巧

如已启用fopen 包装器，在此函数中， URL 可作为文件名。关于如何指定文件名详见 fopen()。各种 wapper 的不同功能请参见 支持的协议和封装协议，注意其用法及其可提供的预定义变量。

### 参数

`filename`

  GD2 图像的路径。

### 返回值

成功后返回图象对象,失败后返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 成功时，此函数现在返回 GDImage 实例，之前返回 resource。

### 示例

示例 #1 imagecreatefromgd2() 示例

    <?php
    // 加载 gd2 图像
    $im = imagecreatefromgd2('./test.gd2');

    // 在图像上应用效果。
    // 在这个例子中，反转图像颜色
    if(function_exists('imagefilter'))
    {
        imagefilter($im, IMG_FILTER_NEGATE);
    }

    // 保存图像
    imagegd2($im, './test_updated.gd2');
    ?>

### 注释

警告

The GD and GD2 image formats are proprietary image formats of libgd. They have to be regarded obsolete, and should only be used for development and testing purposes.

# imagecreatefromgd2part

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd2part — 从指定的 GD2 文件或 URL 的部分创建新图像

### 说明

function imagecreatefromgd2part(
string `$filename`,
int `$x`,
int `$y`,
int `$width`,
int `$height`
): GdImage|false

从指定的 GD2 文件或 URL 的部分创建新图像。

小技巧

如已启用fopen 包装器，在此函数中， URL 可作为文件名。关于如何指定文件名详见 fopen()。各种 wapper 的不同功能请参见 支持的协议和封装协议，注意其用法及其可提供的预定义变量。

### 参数

`filename`

  GD2 图像路径。

`x`

  源点的 x 坐标。

`y`

  源点的 y 坐标。

`width`

  源图象的宽度。

`height`

  源图象的高度。

### 返回值

成功后返回图象对象,失败后返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 成功时，此函数现在返回 GDImage 实例，之前返回 resource。

### 示例

示例 #1 imagecreatefromgd2part() 示例

    <?php
    // 对于这个例子，需要先获取图像的尺寸
    $image = getimagesize('./test.gd2');

    // 现在获得了图像大小，创建图像实例
    $im = imagecreatefromgd2part('./test.gd2', 4, 4, ($image[0] / 2) - 6, ($image[1] / 2) - 6);

    // 执行图像操作，在本例中对图像进行浮雕
    if(function_exists('imagefilter'))
    {
        imagefilter($im, IMG_FILTER_EMBOSS);
    }

    // 保存优化后的图像
    imagegd2($im, './test_emboss.gd2');
    ?>

### 注释

警告

The GD and GD2 image formats are proprietary image formats of libgd. They have to be regarded obsolete, and should only be used for development and testing purposes.

# imagecreatefromgif

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefromgif — 由文件或 URL 创建一个新图象。

### 说明

function imagecreatefromgif(string `$filename`): GdImage|false

imagecreatefromgif() 返回图像标识符，代表从指定文件名获得的图像。

警告

当读取 GIF 文件到内存中时，图像对象仅返回第一帧。图像的大小不一定是 getimagesize() 报告的大小。

小技巧

如已启用fopen 包装器，在此函数中， URL 可作为文件名。关于如何指定文件名详见 fopen()。各种 wapper 的不同功能请参见 支持的协议和封装协议，注意其用法及其可提供的预定义变量。

### 参数

`filename`

  GIF 图像的路径。

### 返回值

成功后返回图象对象,失败后返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 成功时，此函数现在返回 GDImage 实例；之前返回 resource。

### 示例

示例 #1 在加载 GIF 期间处理错误的示例

    <?php
    function LoadGif($imgname)
    {
        /* 尝试打开 */
        $im = @imagecreatefromgif($imgname);

        /* 查看是否失败 */
        if(!$im)
        {
            /* 创建空白图像 */
            $im = imagecreatetruecolor (150, 30);
            $bgc = imagecolorallocate ($im, 255, 255, 255);
            $tc = imagecolorallocate ($im, 0, 0, 0);

            imagefilledrectangle ($im, 0, 0, 150, 30, $bgc);

            /* 输出错误消息 */
            imagestring ($im, 1, 5, 5, 'Error loading ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/gif');

    $img = LoadGif('bogus.image');

    imagegif($img);
    ?>

以上示例的输出类似于：

# imagecreatefromjpeg

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefromjpeg — 由文件或 URL 创建一个新图象。

### 说明

function imagecreatefromjpeg(string `$filename`): GdImage|false

imagecreatefromjpeg() 返回图像标识符，代表从指定文件名获得的图像。

小技巧

如已启用fopen 包装器，在此函数中， URL 可作为文件名。关于如何指定文件名详见 fopen()。各种 wapper 的不同功能请参见 支持的协议和封装协议，注意其用法及其可提供的预定义变量。

### 参数

`filename`

  JPEG 图像的路径。

### 返回值

成功后返回图象对象,失败后返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 成功时，此函数现在返回 GDImage 实例；之前返回 resource。

### 示例

示例 #1 在加载 JPEG 期间处理错误的示例

    <?php
    function LoadJpeg($imgname)
    {
        /* 尝试打开 */
        $im = @imagecreatefromjpeg($imgname);

        /* 查看是否失败 */
        if(!$im)
        {
            /* 创建空白图像 */
            $im  = imagecreatetruecolor(150, 30);
            $bgc = imagecolorallocate($im, 255, 255, 255);
            $tc  = imagecolorallocate($im, 0, 0, 0);

            imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

            /* 输出错误消息 */
            imagestring($im, 1, 5, 5, 'Error loading ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/jpeg');

    $img = LoadJpeg('bogus.image');

    imagejpeg($img);
    ?>

以上示例的输出类似于：

# imagecreatefrompng

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefrompng — 由文件或 URL 创建一个新图象。

### 说明

function imagecreatefrompng(string `$filename`): GdImage|false

imagecreatefrompng() 返回图像标识符，代表从指定文件名获得的图像。

小技巧

如已启用fopen 包装器，在此函数中， URL 可作为文件名。关于如何指定文件名详见 fopen()。各种 wapper 的不同功能请参见 支持的协议和封装协议，注意其用法及其可提供的预定义变量。

### 参数

`filename`

  PNG 图像的路径。

### 返回值

成功后返回图象对象,失败后返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 成功时，此函数现在返回 GDImage 实例；之前返回 resource。

### 示例

示例 #1 在加载 PNG 期间处理错误的示例

    <?php
    function LoadPNG($imgname)
    {
        /* 尝试打开 */
        $im = @imagecreatefrompng($imgname);

        /* 查看是否失败 */
        if(!$im)
        {
            /* 创建空白图像 */
            $im  = imagecreatetruecolor(150, 30);
            $bgc = imagecolorallocate($im, 255, 255, 255);
            $tc  = imagecolorallocate($im, 0, 0, 0);

            imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

            /* 输出错误消息 */
            imagestring($im, 1, 5, 5, 'Error loading ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/png');

    $img = LoadPNG('bogus.image');

    imagepng($img);
    ?>

以上示例的输出类似于：

# imagecreatefromstring

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

imagecreatefromstring — 从字符串的图像流中新建图像

### 说明

function imagecreatefromstring(string `$data`): GdImage|false

imagecreatefromstring() 返回图像标识符，代表从指定 `data` 获得的图像。图像格式将自动检测，只要编译的 PHP 支持：JPEG、PNG、GIF、BMP、WBMP、GD2、 WEBP 和 AVIF。

### 参数

`data`

  包含图像数据的字符串。

### 返回值

成功时返回图像对象。如果图像类型不支持、数据格式不可识别或者图像已损坏且无法加载，则返回 `false`。

### 错误／异常

如果数据格式不可识别，则 imagecreatefromstring() 引发 E_WARNING 级别错误。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 成功时，此函数现在返回 GDImage 实例；之前返回 resource。
7.3.0 | 现在支持 WEBP（如果使用的是 libgd）。

### 示例

示例 #1 imagecreatefromstring() 示例

    <?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.';
    }
    ?>

以上示例的输出类似于：

### 参见

- imagecreatefromjpeg() - 由文件或 URL 创建一个新图象。
- imagecreatefrompng() - 由文件或 URL 创建一个新图象。
- imagecreatefromgif() - 由文件或 URL 创建一个新图象。
- imagecreatetruecolor() - 新建真彩色图像

# imagecreatefromtga

(PHP 7 >= 7.4.0, PHP 8)

imagecreatefromtga — 由文件或 URL 创建一个新图象。

### 说明

function imagecreatefromtga(string `$filename`): GdImage|false

imagecreatefromtga() returns an image object representing the image obtained from the given filename.

### 参数

`filename`

  Path to the Truevision TGA image.

### 返回值

成功后返回图象对象,失败后返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.

# imagecreatefromwbmp

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromwbmp — 由文件或 URL 创建一个新图象。

### 说明

function imagecreatefromwbmp(string `$filename`): GdImage|false

imagecreatefromwbmp() 返回图像标识符，代表从指定文件名获得的图像。

> 注意: WBMP 图像是无线位图（Wireless Bitmaps），不是 Windows 位图（Windows Bitmaps）。后者可以用 imagecreatefrombmp() 加载。

小技巧

如已启用fopen 包装器，在此函数中， URL 可作为文件名。关于如何指定文件名详见 fopen()。各种 wapper 的不同功能请参见 支持的协议和封装协议，注意其用法及其可提供的预定义变量。

### 参数

`filename`

  WBMP 图像的路径。

### 返回值

成功后返回图象对象,失败后返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 成功时，此函数现在返回 GDImage 实例；之前返回 resource。

### 示例

示例 #1 在加载 WBMP 期间处理错误的示例

    <?php
    function LoadWBMP($imgname)
    {
        /* 尝试打开 */
        $im = @imagecreatefromwbmp($imgname);

        /* 查看是否失败 */
        if(!$im)
        {
            /* 创建空白图像 */
            $im  = imagecreatetruecolor(150, 30);
            $bgc = imagecolorallocate($im, 255, 255, 255);
            $tc  = imagecolorallocate($im, 0, 0, 0);

            imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

            /* 输出错误消息 */
            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 — 由文件或 URL 创建一个新图象。

### 说明

function imagecreatefromwebp(string `$filename`): GdImage|false

imagecreatefromwebp() 返回图像标识符，代表从指定文件名获得的图像。请注意，无法读取动画 WebP 文件。

小技巧

如已启用fopen 包装器，在此函数中， URL 可作为文件名。关于如何指定文件名详见 fopen()。各种 wapper 的不同功能请参见 支持的协议和封装协议，注意其用法及其可提供的预定义变量。

### 参数

`filename`

  WebP 图像路径。

### 返回值

成功后返回图象对象,失败后返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 成功时，此函数现在返回 GDImage 实例；之前返回 resource。

### 示例

示例 #1 使用 imagecreatefromwebp() 转换 WebP 图像为 jpeg 图像

    <?php
    // 加载 WebP 文件
    $im = imagecreatefromwebp('./example.webp');

    // 以 100% 的质量转换成 jpeg 格式
    imagejpeg($im, './example.jpeg', 100);
    ?>

# imagecreatefromxbm

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromxbm — 由文件或 URL 创建一个新图象。

### 说明

function imagecreatefromxbm(string `$filename`): GdImage|false

imagecreatefromxbm() 返回图像标识符，代表从指定文件名获得的图像。

小技巧

如已启用fopen 包装器，在此函数中， URL 可作为文件名。关于如何指定文件名详见 fopen()。各种 wapper 的不同功能请参见 支持的协议和封装协议，注意其用法及其可提供的预定义变量。

### 参数

`filename`

  XBM 图像路径。

### 返回值

成功后返回图象对象,失败后返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 成功时，此函数现在返回 GDImage 实例；之前返回 resource。

### 示例

示例 #1 使用 imagecreatefromxbm() 转换 XBM 图像为 png 图像

    <?php
    // 加载 xbm 文件
    $xbm = imagecreatefromxbm('./example.xbm');

    // 转化为 png 文件
    imagepng($xbm, './example.png');
    ?>

# imagecreatefromxpm

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromxpm — 由文件或 URL 创建一个新图象。

### 说明

function imagecreatefromxpm(string `$filename`): GdImage|false

imagecreatefromxpm() 返回图像标识符，代表从指定文件名获得的图像。

小技巧

如已启用fopen 包装器，在此函数中， URL 可作为文件名。关于如何指定文件名详见 fopen()。各种 wapper 的不同功能请参见 支持的协议和封装协议，注意其用法及其可提供的预定义变量。

### 参数

`filename`

  XPM 图像的路径。

### 返回值

成功后返回图象对象,失败后返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 成功时，此函数现在返回 GDImage 实例；之前返回 resource。

### 示例

示例 #1 使用 imagecreatefromxpm() 创建图像实例

    <?php
    // 检测 XPM 支持
    if(!(imagetypes() & IMG_XPM))
    {
        die('Support for xpm was not found!');
    }

    // 创建图像实例
    $xpm = imagecreatefromxpm('./example.xpm');

    // Do image operations here

    // PHP 不支持写入 xpm 图像，
    // 因此在这种情况下将图像保存为具有
    // 100% 质量的 jpeg 文件
    imagejpeg($xpm, './example.jpg', 100);
    ?>

# imagecreatetruecolor

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecreatetruecolor — 新建真彩色图像

### 说明

function imagecreatetruecolor(int `$width`, int `$height`): GdImage|false

imagecreatetruecolor() 返回图像对象，表示指定大小的黑色图像。

### 参数

`width`

  图像宽度。

`height`

  图像高度。

### 返回值

成功后返回图象对象,失败后返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 成功时，此函数现在返回 GDImage 实例；之前返回 resource。

### 示例

示例 #1 新建 GD 图像流并输出图像。

    <?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);
    ?>

以上示例的输出类似于：

### 参见

- imagecreate() - 创建新的基于调色板的图像

# imagecrop

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagecrop — Crop an image to the given rectangle

### 说明

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.

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`rectangle`

  The cropping rectangle as array with keys `x`, `y`, `width` and `height`.

### 返回值

Return cropped image object on success 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.

### 示例

示例 #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');
    }
    ?>

### 参见

- 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

### 说明

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`.

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`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.

  > 注意: 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.

### 返回值

Returns a cropped image object on success 或者在失败时返回 `false`. `false` is also returned if the whole image was cropped.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。
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.

### 示例

示例 #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
    }
    ?>

### 参见

- imagecrop() - Crop an image to the given rectangle

# imagedashedline

(PHP 4, PHP 5, PHP 7, PHP 8)

imagedashedline — 绘制虚线

### 说明

function imagedashedline(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

弃用此函数。使用 imagesetstyle() 和 imageline() 组合替代。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`x1`

  左上 x 坐标。

`y1`

  左上 y 坐标。0，0 为图像的左上角。

`x2`

  右下 x 坐标。

`y2`

  右下 y 坐标。

`color`

  填充颜色。颜色标识符使用 imagecolorallocate() 创建。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 imagedashedline() 示例

    <?php
    // 创建 100x100 图像
    $im = imagecreatetruecolor(100, 100);
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);

    // 绘制垂直虚线
    imagedashedline($im, 50, 25, 50, 75, $white);

    // 保存图像
    imagepng($im, './dashedline.png');
    ?>

以上示例的输出类似于：

示例 #2 替代 imagedashedline()

    <?php
    // 创建 100x100 图像
    $im = imagecreatetruecolor(100, 100);
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);

    // 定义样式：前 4 个像素为白色，
    // 后 4 个像素为透明。这将创建虚线效果
    $style = Array(
                    $white,
                    $white,
                    $white,
                    $white,
                    IMG_COLOR_TRANSPARENT,
                    IMG_COLOR_TRANSPARENT,
                    IMG_COLOR_TRANSPARENT,
                    IMG_COLOR_TRANSPARENT
                    );

    imagesetstyle($im, $style);

    // 绘制虚线
    imageline($im, 50, 25, 50, 75, IMG_COLOR_STYLED);

    // 保存图像
    imagepng($im, './imageline.png');
    ?>

### 参见

- imagesetstyle() - 设定线条的样式
- imageline() - 绘制直线

# imagedestroy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagedestroy — 销毁图像

警告

此函数自 PHP 8.5.0 起弃用。强烈建议不要应用此函数。

### 说明

#[\Deprecated]
function imagedestroy(GdImage `$image`): true

> 注意: 此函数无效。在 PHP 8.0.0 之前，用于关闭资源。

在 PHP 8.0.0 之前，imagedestroy() 会释放与 `image` 资源相关的所有内存。自 8.0.0 起，GD 扩展使用对象而不是资源，并且无法明确关闭对象。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.5.0 | 此函数已被弃用。
8.0.0 | 此函数现在是 NOP（空操作）。
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 PHP 8.0.0 前使用 imagedestroy()

    <?php
    // 创建 100 x 100 图像
    $im = imagecreatetruecolor(100, 100);

    // 修改或保存图像

    // 从内存中释放图像
    imagedestroy($im);
    ?>

# imageellipse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imageellipse — 画椭圆

### 说明

function imageellipse(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$color`
): true

绘制以指定坐标为中心的椭圆。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`center_x`

  中间的 x 坐标。

`center_y`

  中间的 y 坐标。

`width`

  椭圆的宽度。

`height`

  椭圆的高度。

`color`

  椭圆的颜色。颜色标识符使用 imagecolorallocate() 创建。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 imageellipse() 示例

    <?php

    // 新建一个空白图像
    $image = imagecreatetruecolor(400, 300);

    // 填充背景色
    $bg = imagecolorallocate($image, 0, 0, 0);

    // 选择椭圆的颜色
    $col_ellipse = imagecolorallocate($image, 255, 255, 255);

    // 画一个椭圆
    imageellipse($image, 200, 150, 300, 200, $col_ellipse);

    // 输出图像
    header("Content-type: image/png");
    imagepng($image);

    ?>

以上示例的输出类似于：

### 注释

> 注意:

> imageellipse() 忽略 imagesetthickness()。

### 参见

- imagefilledellipse() - 绘制椭圆并填充
- imagearc() - 画弧线

# imagefill

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefill — 漫水填充

### 说明

function imagefill(
GdImage `$image`,
int `$x`,
int `$y`,
int `$color`
): true

使用 `image` 中的指定 `color` 从指定坐标（左上角为 0，0）开始执行漫水填充。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`x`

  起点的 x 坐标。

`y`

  起点的 y 坐标。

`color`

  填充颜色。颜色标识符使用 imagecolorallocate() 创建。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 imagefill() 示例

    <?php

    $im = imagecreatetruecolor(100, 100);

    // 设置背景为红色
    $red = imagecolorallocate($im, 255, 0, 0);
    imagefill($im, 0, 0, $red);

    header('Content-type: image/png');
    imagepng($im);
    ?>

以上示例的输出类似于：

### 参见

- imagecolorallocate() - 为图像分配颜色

# imagefilledarc

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagefilledarc — 绘制部分弧形并填充

### 说明

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

在指定 `image` 中以指定坐标为中心绘制部分弧形。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`center_x`

  中间的 x 坐标。

`center_y`

  中间的 y 坐标。

`width`

  弧形宽度。

`height`

  弧形高度。

`start_angle`

  弧形起始角，以度为单位。

`end_angle`

  弧形结束角度，以度为单位。0° 位于三点钟位置，顺时针绘制弧形。

`color`

  颜色标识符使用 imagecolorallocate() 创建。

`style`

  值可以是下列值的按位或（OR）：

  1. `IMG_ARC_PIE`
  2. `IMG_ARC_CHORD`
  3. `IMG_ARC_NOFILL`
  4. `IMG_ARC_EDGED`
  `IMG_ARC_PIE` 和 `IMG_ARC_CHORD` 是互斥的；`IMG_ARC_CHORD` 只是用直线连接了起始和结束点，`IMG_ARC_PIE` 则产生圆形边界。`IMG_ARC_NOFILL` 指明弧或弦只有轮廓，不填充。`IMG_ARC_EDGED` 指明用直线将起始和结束点与中心点相连，和 `IMG_ARC_NOFILL` 一起使用是画饼状图轮廓的好方法（而不用填充）。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 创建 3D 外观的饼图

    <?php

    // 创建图像
    $image = imagecreatetruecolor(100, 100);

    // 分配一些颜色
    $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);

    // 创建 3D 效果
    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);

    // 输出图像
    header('Content-type: image/png');
    imagepng($image);
    ?>

以上示例的输出类似于：

# imagefilledellipse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagefilledellipse — 绘制椭圆并填充

### 说明

function imagefilledellipse(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$color`
): true

在指定 `image` 上以指定坐标为中心绘制椭圆。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`center_x`

  中央的 x 坐标。

`center_y`

  中央的 y 坐标。

`width`

  椭圆的宽度。

`height`

  椭圆的高度。

`color`

  填充颜色。颜色标识符使用 imagecolorallocate() 创建。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 imagefilledellipse() 示例

    <?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);

    ?>

以上示例的输出类似于：

### 注释

> 注意:

> imagefilledellipse() 忽略 imagesetthickness()。

### 参见

- imageellipse() - 画椭圆
- imagefilledarc() - 绘制部分弧形并填充

# imagefilledpolygon

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilledpolygon — 绘制多边形并填充

### 说明

自 PHP 8.0.0 起的签名（不支持命名参数）

function imagefilledpolygon(GdImage `$image`, array `$points`, int `$color`): bool

替代签名（从 PHP 8.1.0 起弃用）

function imagefilledpolygon(
GdImage `$image`,
array `$points`,
int `$num_points`,
int `$color`
): bool

imagefilledpolygon() 在指定 `image` 中创建多边形并填充。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`points`

  包含连续多边形顶点的 `x` 和 `y` 坐标的数组。

`num_points`

  点（顶点）的总数，必须最少为 3。

  如果根据第二个签名省略此参数，则 `points` 必须具有偶数个元素，并且假定 `num_points` 为 `count($points)/2`。
`color`

  颜色标识符使用 imagecolorallocate() 创建。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 弃用参数 `num_points`。
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 imagefilledpolygon() 示例

    <?php
    // 为多边形设置点数组
    $values = array(
                40,  50,  // Point 1 (x, y)
                20,  240, // Point 2 (x, y)
                60,  60,  // Point 3 (x, y)
                240, 20,  // Point 4 (x, y)
                50,  40,  // Point 5 (x, y)
                10,  10   // Point 6 (x, y)
                );

    // 创建图像
    $image = imagecreatetruecolor(250, 250);

    // 分配颜色
    $bg   = imagecolorallocate($image, 0, 0, 0);
    $blue = imagecolorallocate($image, 0, 0, 255);

    // 填充背景
    imagefilledrectangle($image, 0, 0, 249, 249, $bg);

    // 绘制多边形
    imagefilledpolygon($image, $values, $blue);

    // 输出图像
    header('Content-type: image/png');
    imagepng($image);
    ?>

以上示例的输出类似于：

### 参见

- imagepolygon() - 绘制多边形

# imagefilledrectangle

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilledrectangle — 绘制矩形并填充

### 说明

function imagefilledrectangle(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

在指定 `image` 中创建一个从点 1 开始到点 2 结束的的矩形并填充 `color`。0, 0 是图像的左上角。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`x1`

  点 1 的 x 坐标。

`y1`

  点 1 的 y 坐标。

`x2`

  点 2 的 x 坐标。

`y2`

  点 2 的 y 坐标。

`color`

  填充颜色。颜色标识符使用 imagecolorallocate() 创建。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 imagefilledrectangle() 用法

    <?php
    // 创建 55x30 图像
    $im = imagecreatetruecolor(55, 30);
    $white = imagecolorallocate($im, 255, 255, 255);

    // 画白色矩形
    imagefilledrectangle($im, 4, 4, 50, 25, $white);

    // 保存图像
    imagepng($im, './imagefilledrectangle.png');
    ?>

以上示例的输出类似于：

# imagefilltoborder

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilltoborder — 漫水填充特定颜色

### 说明

function imagefilltoborder(
GdImage `$image`,
int `$x`,
int `$y`,
int `$border_color`,
int `$color`
): true

imagefilltoborder() 执行漫水填充，其边框颜色由 `border_color` 定义。填充的起点是 `x`, `y`（左上角是0, 0），区域用颜色 `color` 填充。【注：边界内的所有颜色都会被填充。如果指定的边界色和该点颜色相同，则没有填充。如果图像中没有该边界色，则整幅图像都会被填充。】

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`x`

  起点的 x 坐标。

`y`

  起点的 y 坐标。

`border_color`

  边框颜色。颜色标识符使用 imagecolorallocate() 创建。

`color`

  填充颜色。颜色标识符使用 imagecolorallocate() 创建。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 用颜色填充椭圆

    <?php
    // 创建图像句柄，并将背景设置为白色
    $im = imagecreatetruecolor(100, 100);
    imagefilledrectangle($im, 0, 0, 100, 100, imagecolorallocate($im, 255, 255, 255));

    // 绘制椭圆，并用黑色边框填充
    imageellipse($im, 50, 50, 50, 50, imagecolorallocate($im, 0, 0, 0));

    // 设置边框和填充颜色
    $border = imagecolorallocate($im, 0, 0, 0);
    $fill = imagecolorallocate($im, 255, 0, 0);

    // 填充选区
    imagefilltoborder($im, 50, 50, $border, $fill);

    // 输出
    header('Content-type: image/png');
    imagepng($im);
    ?>

以上示例的输出类似于：

### 注释

算法不会明确记住已经设置哪些像素，而是从像素的颜色判断，所以无法区分新设置的元素和已经存在的元素。这意味着选择任何图像中已经使用的填充颜色都可能会产生不期望的结果。

# imagefilter

(PHP 5, PHP 7, PHP 8)

imagefilter — 对图像使用过滤器

### 说明

function imagefilter(GdImage `$image`, int `$filter`, array|int|float|bool `...$args`): bool

imagefilter() 在 `image` 上应用指定的过滤器 `filter`。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`filter`

  `filter` 可以是下列中的一个：

  - `IMG_FILTER_NEGATE`：将图像中所有颜色反转。
  - `IMG_FILTER_GRAYSCALE`：将图像转换为灰度，通过使用与 REC.601 亮度 (Y') 计算相同的系数来更改红色、绿色和蓝色分量的加权和。保留 alpha 分量。对于调色板图像，由于调色板限制，结果可能有所不同。
  - `IMG_FILTER_BRIGHTNESS`：更改图像的亮度。使用 `args` 设置亮度级别。亮度的范围是 -255 到 255。
  - `IMG_FILTER_CONTRAST`：更改图像的对比度。使用 `args` 设置对比度级别。
  - `IMG_FILTER_COLORIZE`：与 `IMG_FILTER_GRAYSCALE` 类似，区别是可以指定颜色。使用 `args`、`arg2` 和 `arg3` 以 `red`、`green`、`blue` 的形式和 `arg4` 用于 `alpha` 通道。每种颜色的范围是 0 到 255。
  - `IMG_FILTER_EDGEDETECT`：用边缘检测来突出图像的边缘。
  - `IMG_FILTER_EMBOSS`：使图像浮雕化。
  - `IMG_FILTER_GAUSSIAN_BLUR`：用高斯算法模糊图像。
  - `IMG_FILTER_SELECTIVE_BLUR`：模糊图像。
  - `IMG_FILTER_MEAN_REMOVAL`：用平均移除法来达到“轮廓”效果。
  - `IMG_FILTER_SMOOTH`：使图像更平滑。用 `args` 设定平滑级别。
  - `IMG_FILTER_PIXELATE`：对图像应用像素化效果，使用 `args` 设置块大小和 `arg2` 设置像素化效果模式。
  - `IMG_FILTER_SCATTER`：将散射效果应用于图像，使用 `args` 和 `arg2` 定义效果强度，另外使用 `arg3` 仅应用选定像素颜色。
`args`

  - `IMG_FILTER_BRIGHTNESS`：亮度级别。
  - `IMG_FILTER_CONTRAST`：对比度级别。
  - `IMG_FILTER_COLORIZE`: 红色成分的值。
  - `IMG_FILTER_SMOOTH`：平滑级别。
  - `IMG_FILTER_PIXELATE`：块大小（像素）。
  - `IMG_FILTER_SCATTER`：效果减法级别。 不能高于或等于 `arg2` 设置的加法级别。
`arg2`

  - `IMG_FILTER_COLORIZE`: 绿色成分的值。
  - `IMG_FILTER_PIXELATE`：是否使用高级像素化效果（默认为 `false`）。
  - `IMG_FILTER_SCATTER`：效果添加级别。
`arg3`

  - `IMG_FILTER_COLORIZE`: 蓝色成分的值。
  - `IMG_FILTER_SCATTER`：可选的数组索引颜色值，应用效果。
`arg4`

  - `IMG_FILTER_COLORIZE`：Alpha 通道，A 值在 0 到 127 之间。 0 表示完全不透明，而 127 表示完全透明。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

抛出 ValueError 异常，如果 `sub` 或 `plus` 会导致 `IMG_FILTER_SCATTER` `filter` 的溢出/下溢。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 现在抛出 ValueError 异常，如果 `sub` 或 `plus` 会导致 `IMG_FILTER_SCATTER` `filter` 的溢出/下溢。
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。
7.4.0 | 新增散射支持（`IMG_FILTER_SCATTER`）。

### 示例

示例 #1 imagefilter() 灰度示例

    <?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.';
    }
    ?>

示例 #2 imagefilter() 亮度示例

    <?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.';
    }
    ?>

示例 #3 imagefilter() 着色示例

    <?php
    $im = imagecreatefrompng('philip.png');

    /* R、G、B, 所以 0, 255, 0 是绿色 */
    if($im && imagefilter($im, IMG_FILTER_COLORIZE, 0, 255, 0))
    {
        echo 'Image successfully shaded green.';

        imagepng($im, 'philip.png');
    }
    else
    {
        echo 'Green shading failed.';
    }
    ?>

示例 #4 imagefilter() 反例

    <?php
    // 定义否定函数，以便可以移植到没有
    // imagefilter() 的 php 版本
    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.';
    }
    ?>

示例 #5 imagefilter() 像素化示例

    <?php
    // 加载 PHP log，需要创建两个实例
    // 来显示差异
    $logo1 = imagecreatefrompng('./php.png');
    $logo2 = imagecreatefrompng('./php.png');

    // 创建想要显示差异的图像实例
    $output = imagecreatetruecolor(imagesx($logo1) * 2, imagesy($logo1));

    // 对每个实例应用像素化，块大小为 3
    imagefilter($logo1, IMG_FILTER_PIXELATE, 3);
    imagefilter($logo2, IMG_FILTER_PIXELATE, 3, true);

    // 合并差异到输出图像上
    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);

    // 输出差异
    header('Content-Type: image/png');
    imagepng($output);
    ?>

以上示例的输出类似于：

示例 #6 imagefilter() 散射示例

    <?php
    // 加载图像
    $logo = imagecreatefrompng('./php.png');

    // 对图像应用非常柔和的散射效果
    imagefilter($logo, IMG_FILTER_SCATTER, 3, 5);

    // 输出带有散射效果的图像
    header('Content-Type: image/png');
    imagepng($logo);
    ?>

以上示例的输出类似于：

### 注释

> 注意: `IMG_FILTER_SCATTER` 的结果始终随机。

### 参见

- imageconvolution() - 用系数 div 和 offset 申请一个 3x3 的卷积矩阵

# imageflip

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageflip — Flips an image using a given mode

### 说明

function imageflip(GdImage `$image`, int `$mode`): true

Flips the `image` image using the given `mode`.

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`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.

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #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);
    ?>

以上示例的输出类似于：

示例 #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);
    ?>

以上示例的输出类似于：

# imagefontheight

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefontheight — 获取字体高度

### 说明

function imagefontheight(GdFont|int `$font`): int

返回指定字体中字符的像素高度。

### 参数

`font`
  取值对于内建的 latin2 编码字体可以是：1、2、3、4、5(更高的数字对应更大的字体)， 或是通过 imageloadfont() 返回的 GdFont 实例。

### 返回值

返回字体的像素高度。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | `font` 参数现在接受 GdFont 实例和 int，之前仅接受 int。

### 示例

示例 #1 在内置字体上使用 imagefontheight()

    <?php
    echo 'Font height: ' . imagefontheight(4);
    ?>

以上示例的输出类似于：

    Font height: 16

示例 #2 将 imagefontheight() 与 imageloadfont() 一起使用

    <?php
    // Load a .gdf font
    $font = imageloadfont('anonymous.gdf');

    echo 'Font height: ' . imagefontheight($font);
    ?>

以上示例的输出类似于：

    Font height: 43

### 参见

- imagefontwidth() - 获取字体宽度
- imageloadfont() - 载入新字体

# imagefontwidth

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefontwidth — 获取字体宽度

### 说明

function imagefontwidth(GdFont|int `$font`): int

返回字体中字符的像素宽度。

### 参数

`font`
  取值对于内建的 latin2 编码字体可以是：1、2、3、4、5(更高的数字对应更大的字体)， 或是通过 imageloadfont() 返回的 GdFont 实例。

### 返回值

返回字体的像素宽度。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | `font` 参数现在接受 GdFont 实例和 int，之前仅接受 int。

### 示例

示例 #1 在内置字体上使用 imagefontwidth()

    <?php
    echo 'Font width: ' . imagefontwidth(4);
    ?>

以上示例的输出类似于：

    Font width: 8

示例 #2 将 imagefontwidth() 与 imageloadfont() 一起使用

    <?php
    // Load a .gdf font
    $font = imageloadfont('anonymous.gdf');

    echo 'Font width: ' . imagefontwidth($font);
    ?>

以上示例的输出类似于：

    Font width: 23

### 参见

- imagefontheight() - 获取字体高度
- imageloadfont() - 载入新字体

# imageftbbox

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imageftbbox — 通过 freetype2 使用字体给出文本的边界框

### 说明

function imageftbbox(
float `$size`,
float `$angle`,
string `$font_filename`,
string `$string`,
array `$options` = []
): array|false

此函数计算并返回 FreeType 文本的边界框（以像素为单位）。

> 注意:

> 在 PHP 8.0.0 之前，imageftbbox() 是 imagettfbbox() 的扩展变体，它还支持 `options`。自 PHP 8.0.0 起，imagettfbbox() 是 imageftbbox() 的别名。

### 参数

`size`

  字体的尺寸，单位：点（磅）。

`angle`

  测量的 `string` 的角度（以度为单位）。

`font_filename`

  TrueType 字体文件的名称（可以是 URL）。根据 PHP 使用的 GD 库的版本，可能会尝试搜索没有以“/”开头并会在末尾追加“.ttf”的文件名，并沿着库定义的字体路径搜索。

`string`

  要测量的字符串。

`options`

  `options` 可能的数组索引
  键 | 类型 | 含义
  --- | --- | ---
  `linespacing` | float | 定义绘制行距

### 返回值

imageftbbox() 返回包含 8 个元素的数组，代表构成文本边界框的四个点：

0 | 左下角，X 坐标
1 | 左下角，Y 坐标
2 | 右下角，X 坐标
3 | 右下角，Y 坐标
4 | 右上角，X 坐标
5 | 右上角， Y 坐标
6 | 左上角，X 坐标
7 | 左上角，Y 坐标

无论 `angle` 如何，这些点都是相对于 text，因此“左上角”意味着在左上角水平地看到文本。

失败时，返回 `false`。

### 示例

示例 #1 imageftbbox() 示例

    <?php
    // 创建 300x150 图像
    $im = imagecreatetruecolor(300, 150);
    $black = imagecolorallocate($im, 0, 0, 0);
    $white = imagecolorallocate($im, 255, 255, 255);

    // 将背景设置为白色
    imagefilledrectangle($im, 0, 0, 299, 299, $white);

    // 字体文件的路径
    $font = './arial.ttf';

    // 首先创建边界框
    $bbox = imageftbbox(10, 0, $font, 'The PHP Documentation Group');

    // 这是 X 和 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');

    // 输出到浏览器
    header('Content-Type: image/png');

    imagepng($im);
    ?>

### 注释

> 注意: 此函数仅在 PHP 编译时加入 freetype 支持时有效（--with-freetype-dir=DIR）。

### 参见

- imagefttext() - 使用 FreeType 2 字体将文本写入图像
- imagettfbbox() - 取得使用 TrueType 字体的文本的边界框

# imagefttext

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagefttext — 使用 FreeType 2 字体将文本写入图像

### 说明

function imagefttext(
GdImage `$image`,
float `$size`,
float `$angle`,
int `$x`,
int `$y`,
int `$color`,
string `$font_filename`,
string `$text`,
array `$options` = []
): array|false

> 注意:

> 在 PHP 8.0.0 之前，imagefttext() 是 imagettftext() 的扩展变体，它还支持 `options`。自 PHP 8.0.0 起，imagettftext() 是 imagefttext() 的别名。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`size`

  字体的尺寸，单位：点（磅）。

`angle`

  以度为单位的角度，0 度表示从左到右阅读文本。较高的值表示逆时针旋转。例如，值为 90 将导致从下到上阅读文本。

`x`

  `x` 和 `y` 给出的坐标将定义第一个字符的基点（大致是字符的左下角）。 这与 imagestring() 不同，其中 `x` 和 `y` 定义第一个字符的左上角。例如，“左上角”是 0, 0。

`y`

  y 坐标。设置字体基线的位置，而不是字符的最底部。

`color`

  文本所需颜色的索引，请参阅 imagecolorexact()。

`font_filename`

  希望使用的 TrueType 字体的路径。

  根据 PHP 使用的 GD 库版本，当 `font_filename` 不以 `/` 开头时，将追加 `.ttf` 到文件名末尾，库将尝试沿着库定义的字体路径搜索该文件名。

  在许多情况下，字体与使用的脚本位于同一目录中，以下技巧将缓解任何包含问题。

      <?php
      // 设置 GD 的环境变量
      putenv('GDFONTPATH=' . realpath('.'));

      // 要使用的字体名称（注意没有 .ttf 扩展名）
      $font = 'SomeFont';
      ?>

`text`

  要插入到图像中的文本。

`options`

  `options` 可能的数组索引
  键 | 类型 | 含义
  --- | --- | ---
  `linespacing` | float | 定义绘制行距

### 返回值

这个函数返回数组，定义了盒子的四个点，从左下角开始逆时针移动：

0 | 左下 x 坐标
1 | 左下 y 坐标
2 | 右下 x 坐标
3 | 右下 x 坐标
4 | 右上 x 坐标
5 | 右上 x 坐标
6 | 左上 x 坐标
7 | 左上 y 坐标

失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 imagefttext() 示例

    <?php
    // 创建 300x100 图像
    $im = imagecreatetruecolor(300, 100);
    $red = imagecolorallocate($im, 0xFF, 0x00, 0x00);
    $black = imagecolorallocate($im, 0x00, 0x00, 0x00);

    // 将背景设为红色
    imagefilledrectangle($im, 0, 0, 299, 99, $red);

    // ttf 字体文件的路径
    $font_file = './arial.ttf';

    // 使用字体大小 13 绘制文本“PHP Manual”
    imagefttext($im, 13, 0, 105, 55, $black, $font_file, 'PHP Manual');

    // 输出图像到浏览器
    header('Content-Type: image/png');

    imagepng($im);
    ?>

### 注释

> 注意: 此函数仅在 PHP 编译时加入 freetype 支持时有效（--with-freetype-dir=DIR）。

### 参见

- imageftbbox() - 通过 freetype2 使用字体给出文本的边界框
- imagettftext() - 用 TrueType 字体向图像写入文本

# imagegammacorrect

(PHP 4, PHP 5, PHP 7, PHP 8)

imagegammacorrect — 对 GD 图像应用伽玛校正

### 说明

function imagegammacorrect(GdImage `$image`, float `$input_gamma`, float `$output_gamma`): true

在指定输入/输出伽玛的情况下，对给指定的 gd `image` 应用伽玛校正。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`input_gamma`

  输入伽玛。

`output_gamma`

  输出伽玛。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 imagegammacorrect() 用法

    <?php
    // 创建图像实例
    $im = imagecreatefromgif('php.gif');

    // 校正伽马，输出 = 1.537
    imagegammacorrect($im, 1.0, 1.537);

    // 保存
    imagegif($im, './php_gamma_corrected.gif');
    ?>

# imagegd

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagegd — 将 GD 图像输出到浏览器或文件

### 说明

function imagegd(GdImage `$image`, ?string `$file` = `null`): bool

输出或保存 `image` 参数指定的 GD 图像。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`file`

  文件保存的路径或者已打开的流资源（此方法返回后自动关闭该流资源），如果未设置或为 `null`，将会直接输出原始图象流。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

警告

如果 libgd 输出图像失败，函数会返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.3 | `file` 现在可以为 null。
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。
7.2.0 | imagegd() 现在允许输出真彩色图像。以前，已隐式转换为调色板。

### 示例

示例 #1 输出 GD 图像

    <?php
    // 创建空白图像并添加一些文本
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);

    // 输出图像
    imagegd($im);
    ?>

示例 #2 保存 GD 图像

    <?php
    // 创建空白图像并添加一些文本
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);

    // 保存 gd 图像
    // GD 图像的文件格式为 .gd，参阅 http://www.libgd.org/GdFileFormats
    imagegd($im, 'simple.gd');
    ?>

### 注释

> 注意:

> GD 格式通常用于允许快速加载部分图像。请注意，GD 格式仅可用于与 GD 兼容的应用程序。

警告

The GD and GD2 image formats are proprietary image formats of libgd. They have to be regarded obsolete, and should only be used for development and testing purposes.

### 参见

- imagegd2() - 将 GD2 图像输出到浏览器或文件

# imagegd2

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagegd2 — 将 GD2 图像输出到浏览器或文件

### 说明

function imagegd2(
GdImage `$image`,
?string `$file` = `null`,
int `$chunk_size` = 128,
int `$mode` = `IMG_GD2_RAW`
): bool

输出或保存 `image` 参数指定的 GD2 图像。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`file`

  文件保存的路径或者已打开的流资源（此方法返回后自动关闭该流资源），如果未设置或为 `null`，将会直接输出原始图象流。

`chunk_size`

  块大小。

`mode`

  可以是 `IMG_GD2_RAW` 或 `IMG_GD2_COMPRESSED`。默认为 `IMG_GD2_RAW`。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

警告

如果 libgd 输出图像失败，函数会返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.3 | `file` 现在可以为 null。
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 输出 GD2 图像

    <?php
    // 创建空白图像并添加一些文本
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);

    // 输出图像
    imagegd2($im);
    ?>

示例 #2 保存 GD2 图像

    <?php
    // 创建空白图像并添加一些文本
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);

    // 保存 gd2 图像
    // GD2 图像的文件格式为 .gd2，参阅 http://www.libgd.org/GdFileFormats
    imagegd2($im, 'simple.gd2');
    ?>

### 注释

> 注意:

> GD2 格式通常用于允许快速加载部分图像。请注意，GD2 格式仅可用于与 GD2 兼容的应用程序。

警告

The GD and GD2 image formats are proprietary image formats of libgd. They have to be regarded obsolete, and should only be used for development and testing purposes.

### 参见

- imagegd() - 将 GD 图像输出到浏览器或文件

# imagegetclip

(PHP 7 >= 7.2.0, PHP 8)

imagegetclip — Get the clipping rectangle

### 说明

function imagegetclip(GdImage `$image`): array

imagegetclip() retrieves the current clipping rectangle, i.e. the area beyond which no pixels will be drawn.

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。

### 返回值

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

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 imagegetclip() example

Setting and retrieving the clipping rectangle.

    <?php
    $im = imagecreate(100, 100);
    imagesetclip($im, 10,10, 89,89);
    print_r(imagegetclip($im));

以上示例会输出：

    Array
    (
        [0] => 10
        [1] => 10
        [2] => 89
        [3] => 89
    )

### 参见

- imagesetclip() - Set the clipping rectangle

# imagegetinterpolation

(PHP 8)

imagegetinterpolation — Get the interpolation method

### 说明

function imagegetinterpolation(GdImage `$image`): int

Gets the currently set interpolation method of the `image`.

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。

### 返回值

Returns the interpolation method.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 参见

- imagesetinterpolation() - Set the interpolation method

# imagegif

(PHP 4, PHP 5, PHP 7, PHP 8)

imagegif — 输出图象到浏览器或文件。

### 说明

function imagegif(GdImage `$image`, resource|string|null `$file` = `null`): bool

imagegif() 从图像 `image` 在 `file` 中创建 GIF 图像。`image` 参数是 imagecreate() 或 `imagecreatefrom*` 函数的返回值。

图像格式为 GIF87a。如果用了 imagecolortransparent() 使图像为透明，则其格式为 GIF89a。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`file`

  文件保存的路径或者已打开的流资源（此方法返回后自动关闭该流资源），如果未设置或为 `null`，将会直接输出原始图象流。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

警告

如果 libgd 输出图像失败，函数会返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 使用 imagegif() 输出图像

    <?php
    // 创建新的图像实例
    $im = imagecreatetruecolor(100, 100);

    // 设置背景为白色
    imagefilledrectangle($im, 0, 0, 99, 99, 0xFFFFFF);

    //在图像上绘制文本字符串
    imagestring($im, 3, 40, 20, 'GD Library', 0xFFBA00);

    // 输出图像到浏览器
    header('Content-Type: image/gif');

    imagegif($im);
    ?>

示例 #2 使用 imagegif() 将 PNG 图像转换成 GIF

    <?php

    // 载入 PNG
    $png = imagecreatefrompng('./php.png');

    // 以 GIF 保存图像
    imagegif($png, './php.gif');

    // 完工
    echo 'Converted PNG image to GIF with success!';
    ?>

### 注释

> 注意:

> 以下代码段通过自动检测 GD 支持的图像类型来写出移植性更好的 PHP 程序。用更灵活的代码替代了原来的 `header("Content-type: image/gif"); imagegif($im);`：

>     <?php
>     // 创建新的图像实例
>     $im = imagecreatetruecolor(100, 100);

>     // 在这里对图像进行一些操作

>     // 处理输出
>     if(function_exists('imagegif'))
>     {
>         // 针对 GIF
>         header('Content-Type: image/gif');

>         imagegif($im);
>     }
>     elseif(function_exists('imagejpeg'))
>     {
>         // 针对 JPEG
>         header('Content-Type: image/jpeg');

>         imagejpeg($im, NULL, 100);
>     }
>     elseif(function_exists('imagepng'))
>     {
>         // 针对 PNG
>         header('Content-Type: image/png');

>         imagepng($im);
>     }
>     elseif(function_exists('imagewbmp'))
>     {
>         // 针对 WBMP
>         header('Content-Type: image/vnd.wap.wbmp');

>         imagewbmp($im);
>     }
>     else
>     {
>         die('No image support in this PHP server');
>     }
>     ?>

> 注意:

> 可以用 imagetypes() 函数检查是否支持某种图像格式：

>     <?php
>     if(imagetypes() & IMG_GIF)
>     {
>         header('Content-Type: image/gif');
>         imagegif($im);
>     }
>     elseif(imagetypes() & IMG_JPG)
>     {
>         /* ... etc. */
>     }
>     ?>

### 参见

- imagepng() - 将 PNG 图像输出到浏览器或文件
- imagewbmp() - 输出图象到浏览器或文件。
- imagejpeg() - 输出图象到浏览器或文件。
- imagetypes() - 返回 PHP 内置支持的图像类型

# imagegrabscreen

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

imagegrabscreen — Captures the whole screen

### 说明

function imagegrabscreen(): GdImage|false

Grabs a screenshot of the whole screen.

> 注意:

> This function is only available on Windows.

### 参数

此函数没有参数。

### 返回值

Returns an image object on success, `false` on failure.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.

### 示例

示例 #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");
    ?>

### 参见

- imagegrabwindow() - Captures a window

# imagegrabwindow

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

imagegrabwindow — Captures a window

### 说明

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)

> 注意:

> This function is only available on Windows.

### 参数

`handle`

  The HWND window ID.

`client_area`

  Include the client area of the application window.

### 返回值

Returns an image object on success, `false` on failure.

### 错误／异常

E_NOTICE is issued if `handle` is invalid window handle. E_WARNING is issued if the Windows API is too old.

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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");
    ?>

### 参见

- imagegrabscreen() - Captures the whole screen

# imageinterlace

(PHP 4, PHP 5, PHP 7, PHP 8)

imageinterlace — 启用或禁用隔行扫描

### 说明

function imageinterlace(GdImage `$image`, ?bool `$enable` = `null`): bool

imageinterlace() 打开或关闭隔行扫描位（bit）。

如果设置了隔行扫描位（interlace bit）并且图像被用作 JPEG，将会创建为渐进式 JPEG 图像。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`enable`

  如果为 `true`，则图像开启隔行扫描，如果为 `false`，否则将关闭隔行扫描。传递 `null` 不会让隔行扫描行为发生改变。

### 返回值

如果为图像设置了隔行扫描位，则返回 `true`，否则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.5 | imageinterlace() 现在返回 bool；之前返回 int（非零为隔行扫描图像，否则为 0）
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。
8.0.0 | `enable` 现在接受 bool；之前接受 int。

### 示例

示例 #1 使用 imageinterlace() 打开隔行扫描

    <?php
    // 创建图像实例
    $im = imagecreatefromgif('php.gif');

    // 打开隔行扫描
    imageinterlace($im, true);

    // 保存隔行扫描图像
    imagegif($im, './php_interlaced.gif');
    ?>

# imageistruecolor

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imageistruecolor — 检查图像是否为真彩色图像

### 说明

function imageistruecolor(GdImage `$image`): bool

imageistruecolor() 检查 `image` 图像是否为真彩色图像。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。

### 返回值

如果 `image` 是真彩色返回 `true`，否则返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 使用 imageistruecolor() 简单检测真彩色实例

    <?php
    // $im 是图像实例

    // 检查图像是否为真彩色图像
    if(!imageistruecolor($im))
    {
        // 创建新的真彩色图像实例
        $tc = imagecreatetruecolor(imagesx($im), imagesy($im));

        // 复制像素
        imagecopy($tc, $im, 0, 0, 0, 0, imagesx($im), imagesy($im));

        $im = $tc;
        $tc = NULL;

        // 或者使用 imagepalettetotruecolor()
    }

    // 继续使用图像实例
    ?>

### 参见

- imagecreatetruecolor() - 新建真彩色图像
- imagepalettetotruecolor() - Converts a palette based image to true color

# imagejpeg

(PHP 4, PHP 5, PHP 7, PHP 8)

imagejpeg — 输出图象到浏览器或文件。

### 说明

function imagejpeg(GdImage `$image`, resource|string|null `$file` = `null`, int `$quality` = -1): bool

imagejpeg() 从指定 `image` 图像创建 JPEG 文件。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`file`

  文件保存的路径或者已打开的流资源（此方法返回后自动关闭该流资源），如果未设置或为 `null`，将会直接输出原始图象流。

`quality`

  `quality` 为可选项，范围从 0（最差质量，文件最小）到 100（最佳质量，文件最大）。默认值（`-1`）使用 IJG 默认的质量值（大约 75）。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

警告

如果 libgd 输出图像失败，函数会返回 `true`。

### 错误／异常

如果 `quality` 无效，抛出 ValueError。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 现在如果 `quality` 无效，抛出 ValueError。
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 输出 JPEG 图像到浏览器

    <?php
    // 创键空白图像并添加一些文本
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // 设置内容类型标头 —— 这个例子里是 image/jpeg
    header('Content-Type: image/jpeg');

    // 输出图像
    imagejpeg($im);
    ?>

以上示例的输出类似于：

示例 #2 保存 JPEG 图像到文件

    <?php
    // 创键空白图像并添加一些文本
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // 保存图像为“simpletext.jpg”
    imagejpeg($im, 'simpletext.jpg');
    ?>

示例 #3 以 75% 的图像质量输出图像到浏览器

    <?php
    // 创键空白图像并添加一些文本
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // 设置内容类型标头 —— 这个例子里是 image/jpeg
    header('Content-Type: image/jpeg');

    // 使用 NULL 跳过 file 参数，并设置图像质量为 75%
    imagejpeg($im, NULL, 75);
    ?>

### 注释

> 注意:

> 如果想输出渐进式 JPEG，需要使用 imageinterlace() 设置隔行扫描。

### 参见

- imagepng() - 将 PNG 图像输出到浏览器或文件
- imagegif() - 输出图象到浏览器或文件。
- imagewbmp() - 输出图象到浏览器或文件。
- imageinterlace() - 启用或禁用隔行扫描
- imagetypes() - 返回 PHP 内置支持的图像类型

# imagelayereffect

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagelayereffect — 设定 alpha 混合标志以使用分层效果

### 说明

function imagelayereffect(GdImage `$image`, int `$effect`): true

设定 alpha 混色标志以使用分层效果。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`effect`

  下列常量之一：

  `IMG_EFFECT_REPLACE`
    使用像素替换（等同于将 `true` 传递给 imagealphablending()）
  `IMG_EFFECT_ALPHABLEND`
    使用普通像素混合（等同于将 `false` 传递给 imagealphablending()）
  `IMG_EFFECT_NORMAL`
    与 `IMG_EFFECT_ALPHABLEND` 相同。
  `IMG_EFFECT_OVERLAY`
    叠加（overlay）的效果是黑色背景像素将保持黑色，白色背景像素将保持白色，但灰色背景像素将采用前景像素的颜色。
  `IMG_EFFECT_MULTIPLY`
    Overlays with a multiply effect.

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。
7.2.0 | 新增 `IMG_EFFECT_MULTIPLY`（要求系统 libgd >= 2.1.1 或捆绑 libgd）。

### 示例

示例 #1 imagelayereffect() 示例

    <?php
    // 设置图像
    $im = imagecreatetruecolor(100, 100);

    // 设置背景
    imagefilledrectangle($im, 0, 0, 100, 100, imagecolorallocate($im, 220, 220, 220));

    // Apply the overlay alpha blending flag
    imagelayereffect($im, IMG_EFFECT_OVERLAY);

    // 绘制两个灰色椭圆
    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));

    // 输出
    header('Content-type: image/png');

    imagepng($im);
    ?>

以上示例的输出类似于：

# imageline

(PHP 4, PHP 5, PHP 7, PHP 8)

imageline — 绘制直线

### 说明

function imageline(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

在指定的两个点之间画一条直线。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`x1`

  第一个点的 x 坐标。

`y1`

  第一个点的 y 坐标。

`x2`

  第二个点的 x 坐标。

`y2`

  第二个点的 y 坐标。

`color`

  直线颜色。颜色标识符使用 imagecolorallocate() 创建。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 绘制粗线

    <?php

    function imagelinethick($image, $x1, $y1, $x2, $y2, $color, $thick = 1)
    {
        /* 这样只适用于正交线
        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);
    }

    ?>

### 参见

- imagecreatetruecolor() - 新建真彩色图像
- imagecolorallocate() - 为图像分配颜色

# imageloadfont

(PHP 4, PHP 5, PHP 7, PHP 8)

imageloadfont — 载入新字体

### 说明

function imageloadfont(string `$filename`): GdFont|false

imageloadfont() 加载用户定义的点阵字体并返回其标识符。

### 参数

`filename`

  字体文件格式目前是二进制且依赖于体系结构。这意味着应该用跟运行 PHP 相同类型 CPU 的机器生成字体。

  字体文件格式
  字节位置 | C 数据类型 | 说明
  --- | --- | ---
  byte 0-3 | int | 字体中的字符数
  byte 4-7 | int | 字体中第一个字符的值（通常 32 代表空格）
  byte 8-11 | int | 每个字符宽度的像素值
  byte 12-15 | int | 每个字符高度的像素值
  byte 16- | char | 字符数据的数组，每字符中每像素 1 字节，一共（nchars*width*height）字节。

### 返回值

返回 GdFont 实例， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在返回 GdFont 实例；之前返回 int。

### 示例

示例 #1 imageloadfont() 用法示例

    <?php
    // 创建新的图像实例
    $im = imagecreatetruecolor(50, 20);
    $black = imagecolorallocate($im, 0, 0, 0);
    $white = imagecolorallocate($im, 255, 255, 255);

    // 将背景设为白色
    imagefilledrectangle($im, 0, 0, 49, 19, $white);

    // 加载 gd 字体并输入“Hello”
    $font = imageloadfont('./04b.gdf');
    imagestring($im, $font, 0, 0, 'Hello', $black);

    // 输出到浏览器
    header('Content-type: image/png');

    imagepng($im);
    ?>

### 参见

- imagefontwidth() - 获取字体宽度
- imagefontheight() - 获取字体高度
- imagestring() - 水平绘制字符串

# imageopenpolygon

(PHP 7 >= 7.2.0, PHP 8)

imageopenpolygon — Draws an open polygon

### 说明

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.

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`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`

  颜色标识符使用 imagecolorallocate() 创建。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | The parameter `num_points` has been deprecated.
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #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);
    ?>

以上示例的输出类似于：

### 参见

- imagepolygon() - 绘制多边形

# imagepalettecopy

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagepalettecopy — 将调色板从一个图像复制到另一个

### 说明

function imagepalettecopy(GdImage `$dst`, GdImage `$src`): void

imagepalettecopy() 把调色板从 `src` 图像复制到 `dst` 图像。

### 参数

`dst`

  目标图像对象。

`src`

  源图像对象。

### 返回值

没有返回值。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `dst` 和 `src` 现在接受 GdImage 实例；之前接受 resource。

### 示例

示例 #1 imagepalettecopy() 示例

    <?php
    // 创建两个调色板图像
    $palette1 = imagecreate(100, 100);
    $palette2 = imagecreate(100, 100);

    // 在第一个调色板图像中
    // 将背景分配为绿色
    $green = imagecolorallocate($palette1, 0, 255, 0);

    // 将调色板从图像 1 复制到图像 2
    imagepalettecopy($palette2, $palette1);

    // 由于调色板现已复制，可以使用
    // 分配给图像 1 的绿色，而无需
    // 两次使用 imagecolorallocate()
    imagefilledrectangle($palette2, 0, 0, 99, 99, $green);

    // 输出图像到浏览器
    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

### 说明

function imagepalettetotruecolor(GdImage `$image`): bool

Converts a palette based image, created by functions like imagecreate() to a true color image, like imagecreatetruecolor().

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。

### 返回值

Returns `true` if the conversion was complete, or if the source image already is a true color image, otherwise `false` is returned.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #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();
    ?>

以上示例会输出：

    typeof($im) = palette
    typeof($im) = true color

### 参见

- imagecreatetruecolor() - 新建真彩色图像
- imageistruecolor() - 检查图像是否为真彩色图像

# imagepng

(PHP 4, PHP 5, PHP 7, PHP 8)

imagepng — 将 PNG 图像输出到浏览器或文件

### 说明

function imagepng(
GdImage `$image`,
resource|string|null `$file` = `null`,
int `$quality` = -1,
int `$filters` = -1
): bool

从指定 `image` 输出或保存 PNG 图像。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`file`

  文件保存的路径或者已打开的流资源（此方法返回后自动关闭该流资源），如果未设置或为 `null`，将会直接输出原始图象流。

  > 注意:

  > 如果未使用 `quality` 和 `filters` 参数，则 `null` 无效。

`quality`

  压缩级别：从 0（不压缩）到 9。 默认值（`-1`）使用 zlib 压缩默认值。 有关详细信息，请参阅 » zlib 手册。

`filters`

  允许减小 PNG 文件的大小。它是位掩码字段，可以设置为任意 `PNG_FILTER_*` 常量的组合。`PNG_NO_FILTER` 或 `PNG_ALL_FILTERS` 也可分别用于禁用或激活所有过滤器。 默认值（`-1`）禁用过滤。

  警告

  系统 libgd 忽略 `filters` 参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

警告

如果 libgd 输出图像失败，函数会返回 `true`。

### 错误／异常

如果 `quality` 无效，抛出 ValueError。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 现在如果 `quality` 无效，抛出 ValueError。
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

    <?php
    $im = imagecreatefrompng("test.png");

    header('Content-Type: image/png');

    imagepng($im);
    ?>

### 参见

- imagegif() - 输出图象到浏览器或文件。
- imagewbmp() - 输出图象到浏览器或文件。
- imagejpeg() - 输出图象到浏览器或文件。
- imagetypes() - 返回 PHP 内置支持的图像类型
- imagesavealpha() - 保存图像时是否保留完整的 alpha 通道信息

# imagepolygon

(PHP 4, PHP 5, PHP 7, PHP 8)

imagepolygon — 绘制多边形

### 说明

自 PHP 8.0.0 起的签名（不支持命名参数）

function imagepolygon(GdImage `$image`, array `$points`, int `$color`): bool

替代签名（从 PHP 8.1.0 开始弃用）

function imagepolygon(
GdImage `$image`,
array `$points`,
int `$num_points`,
int `$color`
): bool

imagepolygon() 在指定 `image` 中创建多边形。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`points`

  包含多边形顶点的数组，例如：

  points[0] | = x0
  points[1] | = y0
  points[2] | = x1
  points[3] | = y1

`num_points`

  点（顶点）的总数，必须最少为 3。

  如果根据第二个签名省略此参数，则 `points` 必须具有偶数个元素，并且假定 `num_points` 为 `count($points)/2`。
`color`

  颜色标识符使用 imagecolorallocate() 创建。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 弃用参数 `num_points`。
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 imagepolygon() 示例

    <?php
    // 创建空白图像
    $image = imagecreatetruecolor(400, 300);

    // 为多边形分配颜色
    $col_poly = imagecolorallocate($image, 255, 255, 255);

    // 绘制多边形
    imagepolygon($image, array(
            0,   0,
            100, 200,
            300, 200
        ),
        $col_poly);

    // 输出图像到浏览器
    header('Content-type: image/png');

    imagepng($image);
    ?>

以上示例的输出类似于：

### 参见

- imagefilledpolygon() - 绘制多边形并填充
- imageopenpolygon() - Draws an open polygon
- imagecreate() - 创建新的基于调色板的图像
- imagecreatetruecolor() - 新建真彩色图像

# imagerectangle

(PHP 4, PHP 5, PHP 7, PHP 8)

imagerectangle — 绘制矩形

### 说明

function imagerectangle(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

imagerectangle() 创建从指定坐标开始的矩形。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`x1`

  左上角 x 坐标。

`y1`

  左上角 y 坐标。 0, 0 是图像左上角。

`x2`

  右下角 x 坐标。

`y2`

  右下角 y 坐标。

`color`

  颜色标识符使用 imagecolorallocate() 创建。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 imagerectangle() 的简单示例

    <?php
    // 创建 200 x 200 图像
    $canvas = imagecreatetruecolor(200, 200);

    // 分配颜色
    $pink = imagecolorallocate($canvas, 255, 105, 180);
    $white = imagecolorallocate($canvas, 255, 255, 255);
    $green = imagecolorallocate($canvas, 132, 135, 28);

    // 绘制三个矩形，每个矩形都有自己的颜色
    imagerectangle($canvas, 50, 50, 150, 150, $pink);
    imagerectangle($canvas, 45, 60, 120, 100, $white);
    imagerectangle($canvas, 100, 120, 75, 160, $green);

    // 输出
    header('Content-Type: image/jpeg');
    imagejpeg($canvas);
    ?>

以上示例的输出类似于：

# imageresolution

(PHP 7 >= 7.2.0, PHP 8)

imageresolution — Get or set the resolution of the image

### 说明

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.

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`resolution_x`

  The horizontal resolution in DPI.

`resolution_y`

  The vertical resolution in DPI.

### 返回值

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`.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `resolution_x` and `resolution_y` are now nullable.

### 示例

示例 #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));
    ?>

以上示例会输出：

    Array
    (
        [0] => 200
        [1] => 200
    )
    Array
    (
        [0] => 300
        [1] => 72
    )

# imagerotate

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagerotate — 用给定角度旋转图像

### 说明

function imagerotate(GdImage `$image`, float `$angle`, int `$background_color`): GdImage|false

将 `image` 图像按指定 `angle` 角度旋转。

旋转的中心是图像的中心，旋转后的图像可能与原始图像具有不同的尺寸。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`angle`

  旋转角度，以度为单位。旋转角度是为逆时针旋转图像的度数。

`background_color`

  指定旋转后未覆盖区域的颜色

### 返回值

返回旋转图像后的图像对象， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.3.0 | 未使用的 `ignore_transparent` 已完全删除。
8.0.0 | 成功时此函数现在返回 GDImage 实例；之前返回 resource。
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。
8.0.0 | 未使用的 `ignore_transparent` 现在接受 bool；之前接受 int。

### 示例

示例 #1 图像旋转 180 度

示例把图像旋转 180 度——上下颠倒。

    <?php
    // 文件和旋转角度
    $filename = 'test.jpg';
    $degrees = 180;

    // 内容类型
    header('Content-type: image/jpeg');

    // 加载
    $source = imagecreatefromjpeg($filename);

    // 旋转
    $rotate = imagerotate($source, $degrees, 0);

    // 输出
    imagejpeg($rotate);
    ?>

以上示例的输出类似于：

### 注释

> 注意: 此函数受到 imagesetinterpolation() 中设定的插值方法影响。

### 参见

- imagesetinterpolation() - Set the interpolation method

# imagesavealpha

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imagesavealpha — 保存图像时是否保留完整的 alpha 通道信息

### 说明

function imagesavealpha(GdImage `$image`, bool `$enable`): true

imagesavealpha() 设置标记，确定在保存图像时是否保存完整的 alpha 通道信息（与单一透明色相反）。 这仅支持支持完整 alpha 通道信息的图像格式，即 `PNG`、`WebP` 和 `AVIF`。

> 注意: imagesavealpha() 仅对 `PNG` 图像有意义，因为 `WebP` 和 `AVIF` 始终会保存完整的 alpha 通道。不建议依赖此行为，因为将来可能会发生变化。因此，对于 `WebP` 和 `AVIF` 图像，也应明确调用 imagesavealpha()。

必须禁用 alpha 混合（`imagealphablending($im, false)`），以首先保留 alpha 通道。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`enable`

  是否保存透明（alpha）通道。默认 `false`。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 基础 imagesavealpha() 用法

    <?php
    // 载入带 alpha 通道的 png 图像
    $png = imagecreatefrompng('./alphachannel_example.png');

    // 关闭 alpha 混合
    imagealphablending($png, false);

    // 执行所需操作

    // 并设置 alpha flag
    imagesavealpha($png, true);

    // 输出图像到浏览器
    header('Content-Type: image/png');

    imagepng($png);
    ?>

### 参见

- imagealphablending() - 设定图像的混色模式

# imagescale

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagescale — Scale an image using the given new width and height

### 说明

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.

> 注意:

> Unlike many of other image functions, imagescale() does not modify the passed `image`; instead, a new image is returned.

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`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).

  > 注意: `IMG_WEIGHTED4` is not yet supported.

### 返回值

Return the scaled image object on success 或者在失败时返回 `false`.

### 错误／异常

Throws a ValueError if `width` or `height` would cause over-/underflow.

Throws a ValueError if `mode` is invalid.

### 更新日志

版本 | 说明
--- | ---
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` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 参见

- imagecopyresized() - 拷贝部分图像并调整大小
- imagecopyresampled() - 重采样拷贝部分图像并调整大小

# imagesetbrush

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetbrush — 为线条设置笔刷图像

### 说明

function imagesetbrush(GdImage `$image`, GdImage `$brush`): true

当用特殊的颜色 `IMG_COLOR_BRUSHED` 或 `IMG_COLOR_STYLEDBRUSHED` 绘制时，imagesetbrush() 通过所有的线条函数设置要使用的笔刷图像。【注：使用笔刷图像，所画的线是由 `brush` 所代表的图像构成的。请参考并尝试运行 imagesetstyle() 中的例子以帮助理解。】

警告

笔刷完成后不需要采取什么特殊动作，但如果要销毁笔刷图像（或让 PHP 销毁），不能使用 `IMG_COLOR_BRUSHED` 或 `IMG_COLOR_STYLEDBRUSHED` 颜色，除非设置了新的笔刷图像。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`brush`

  图像对象。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 和 `brush` 现在需要 GdImage 实例，之前需要 resource。

### 示例

示例 #1 imagesetbrush() 示例

    <?php
    // 加载迷你 php logo
    $php = imagecreatefrompng('./php.png');

    // 创建主图像 100x100
    $im = imagecreatetruecolor(100, 100);

    // 用白色填充背景
    $white = imagecolorallocate($im, 255, 255, 255);
    imagefilledrectangle($im, 0, 0, 299, 99, $white);

    // 设置画笔
    imagesetbrush($im, $php);

    // 画几支画笔，每支都相互重叠
    imageline($im, 50, 50, 50, 60, IMG_COLOR_BRUSHED);

    // 输出图像到浏览器
    header('Content-type: image/png');

    imagepng($im);
    ?>

以上示例的输出类似于：

# imagesetclip

(PHP 7 >= 7.2.0, PHP 8)

imagesetclip — Set the clipping rectangle

### 说明

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.

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`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.

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 参见

- imagegetclip() - Get the clipping rectangle

# imagesetinterpolation

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagesetinterpolation — Set the interpolation method

### 说明

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.

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #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 ...
    ?>

### 注释

Changing the interpolation method affects the following functions when rendering:

- imageaffine()
- imagerotate()

### 参见

- imagegetinterpolation() - Get the interpolation method

# imagesetpixel

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesetpixel — 设置单个像素

### 说明

function imagesetpixel(
GdImage `$image`,
int `$x`,
int `$y`,
int `$color`
): true

imagesetpixel() 在指定坐标处绘制像素。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`x`

  x 坐标。

`y`

  y 坐标。

`color`

  颜色标识符使用 imagecolorallocate() 创建。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 imagesetpixel() 示例

A random drawing that ends with a regular picture.

    <?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);

    ?>

以上示例的输出类似于：

### 参见

- imagecreatetruecolor() - 新建真彩色图像
- imagecolorallocate() - 为图像分配颜色
- imagecolorat() - 取得某像素的颜色索引值

# imagesetstyle

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetstyle — 设定线条的样式

### 说明

function imagesetstyle(GdImage `$image`, array `$style`): bool

imagesetstyle() 设定所有线条函数（例如 imageline() 和 imagepolygon()）在使用特殊颜色 `IMG_COLOR_STYLED` 或者颜色为 `IMG_COLOR_STYLEDBRUSHED` 绘制图像线条的样式。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`style`

  像素颜色组成的数组。可以通过常量 `IMG_COLOR_TRANSPARENT` 来添加透明像素。注意 `style` 不能是空 array。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

下面的示例脚本在画布上从左上角到右下角画一行虚线：

示例 #1 imagesetstyle() 例子

    <?php
    header("Content-type: image/jpeg");
    $im  = imagecreatetruecolor(100, 100);
    $w   = imagecolorallocate($im, 255, 255, 255);
    $red = imagecolorallocate($im, 255, 0, 0);

    /* 画一条虚线，5 个红色像素，5 个白色像素 */
    $style = array($red, $red, $red, $red, $red, $w, $w, $w, $w, $w);
    imagesetstyle($im, $style);
    imageline($im, 0, 0, 100, 100, IMG_COLOR_STYLED);

    /* 用 imagesetbrush() 和 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);
    ?>

以上示例的输出类似于：

### 参见

- imagesetbrush() - 为线条设置笔刷图像
- imageline() - 绘制直线

# imagesetthickness

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetthickness — 设定画线的粗细

### 说明

function imagesetthickness(GdImage `$image`, int `$thickness`): true

imagesetthickness() 将绘制矩形、多边形、圆弧等绘制的线条粗细设置为 `thickness` 像素。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`thickness`

  粗细，以像素为单位。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 imagesetthickness() 示例

    <?php
    // 创建 200x100 图像
    $im = imagecreatetruecolor(200, 100);
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
    $black = imagecolorallocate($im, 0x00, 0x00, 0x00);

    // 设置背景为白色
    imagefilledrectangle($im, 0, 0, 299, 99, $white);

    // 将线条粗细设置为 5
    imagesetthickness($im, 5);

    // 绘制矩形
    imagerectangle($im, 14, 14, 185, 85, $black);

    // 输出图像到浏览器
    header('Content-Type: image/png');

    imagepng($im);
    ?>

以上示例的输出类似于：

# imagesettile

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesettile — 设置要填充的平铺图像

### 说明

function imagesettile(GdImage `$image`, GdImage `$tile`): true

当使用特殊颜色 `IMG_COLOR_TILED`时，imagesettile() 设置所有区域填充函数（比如 imagefill() 和 imagefilledpolygon()）要使用的平铺图像。

平铺是指使用重复模式填充区域的图像。任何 GD 图像都可以用于平铺，并且通过使用 imagecolortransparent() 来设定平铺图像的透明颜色索引，可以创建允许底层区域的某些部分透过的平铺。

警告

平铺完成后不需要采取什么特殊动作，但如果要销毁平铺图像（或让 PHP 销毁），不能使用 `IMG_COLOR_TILED` 颜色，除非设置了新的平铺图像。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`tile`

  用作平铺的图像对象。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 和 `tile` 现在需要 GdImage 实例；之前需要 resource。

### 示例

示例 #1 imagesettile() 示例

    <?php
    // 加载外部图像
    $zend = imagecreatefromgif('./zend.gif');

    // 创建 200x200 图像
    $im = imagecreatetruecolor(200, 200);

    // 设置平铺
    imagesettile($im, $zend);

    // 重复图像
    imagefilledrectangle($im, 0, 0, 199, 199, IMG_COLOR_TILED);

    // 输出图像到浏览器
    header('Content-Type: image/png');

    imagepng($im);
    ?>

以上示例的输出类似于：

# imagestring

(PHP 4, PHP 5, PHP 7, PHP 8)

imagestring — 水平绘制字符串

### 说明

function imagestring(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$string`,
int `$color`
): true

在指定坐标处水平绘制 `string`。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`font`
  取值对于内建的 latin2 编码字体可以是：1、2、3、4、5(更高的数字对应更大的字体)， 或是通过 imageloadfont() 返回的 GdFont 实例。
`x`

  左上角的 x 坐标。

`y`

  左上角的 y 坐标。

`string`

  要写入的字符串。

`color`

  颜色标识符使用 imagecolorallocate() 创建。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | `font` 参数现在接受 GdFont 实例和 int，之前仅接受 int。
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 imagestring() 示例

    <?php
    // 创建 100*30 图像
    $im = imagecreate(100, 30);

    // 白色背景和蓝色文字
    $bg = imagecolorallocate($im, 255, 255, 255);
    $textcolor = imagecolorallocate($im, 0, 0, 255);

    // 写入字符串到左上角
    imagestring($im, 5, 0, 0, 'Hello world!', $textcolor);

    // 输出图像
    header('Content-type: image/png');

    imagepng($im);
    ?>

以上示例的输出类似于：

### 参见

- imagestringup() - 垂直绘制字符串
- imageloadfont() - 载入新字体
- imagettftext() - 用 TrueType 字体向图像写入文本

# imagestringup

(PHP 4, PHP 5, PHP 7, PHP 8)

imagestringup — 垂直绘制字符串

### 说明

function imagestringup(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$string`,
int `$color`
): true

在指定坐标处垂直绘制 `string`。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`font`
  取值对于内建的 latin2 编码字体可以是：1、2、3、4、5(更高的数字对应更大的字体)， 或是通过 imageloadfont() 返回的 GdFont 实例。
`x`

  左下角的 x 坐标。

`y`

  左下角的 y 坐标。

`string`

  要写入的字符串。

`color`

  颜色标识符使用 imagecolorallocate() 创建。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | `font` 参数现在接受 GdFont 实例和 int，之前仅接受 int。
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 imagestringup() 示例

    <?php
    // 创建 100*100 图像
    $im = imagecreatetruecolor(100, 100);

    // 写入文本
    $textcolor = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
    imagestringup($im, 3, 40, 80, 'gd library', $textcolor);

    // 保存图像
    imagepng($im, './stringup.png');
    ?>

以上示例的输出类似于：

### 参见

- imagestring() - 水平绘制字符串
- imageloadfont() - 载入新字体

# imagesx

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesx — 取得图像宽度

### 说明

function imagesx(GdImage `$image`): int

返回指定 `image` 对象的宽度。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。

### 返回值

返回 `image` 的宽度。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 使用 imagesx()

    <?php

    // create a 300*200 image
    $img = imagecreatetruecolor(300, 200);

    echo imagesx($img); // 300

    ?>

### 参见

- imagecreatetruecolor() - 新建真彩色图像
- getimagesize() - 取得图像大小
- imagesy() - 取得图像高度

# imagesy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesy — 取得图像高度

### 说明

function imagesy(GdImage `$image`): int

返回指定 `image` 对象的高度。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。

### 返回值

返回 `image` 的高度。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 使用 imagesy()

    <?php

    // create a 300*200 image
    $img = imagecreatetruecolor(300, 200);

    echo imagesy($img); // 200

    ?>

### 参见

- imagecreatetruecolor() - 新建真彩色图像
- getimagesize() - 取得图像大小
- imagesx() - 取得图像宽度

# imagetruecolortopalette

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagetruecolortopalette — 将真彩色图像转换为调色板图像

### 说明

function imagetruecolortopalette(GdImage `$image`, bool `$dither`, int `$num_colors`): bool

imagetruecolortopalette()将一幅真彩色图像转换为调色板图像。本函数的代码原本是从独立的 JPEG 小组库代码中提取出来的，非常出色。此代码被修改以在结果调色板中保留尽可能多的 alpha 通道信息以及尽可能多的颜色。但并没有达到期望的效果。通常最好生成真彩色图像输出，这样可以保证得到最高的输出质量。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`dither`

  指明图像是否被抖动（dithered），如果为 `true` 则图像将被抖动使图像中的斑点更多但是颜色更接近。

`num_colors`

  设定调色板中被保留的颜色的最大数目。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 将真彩色图像转换为基于调色板的图像

    <?php
    // 创建新的真彩色图像
    $im = imagecreatetruecolor(100, 100);

    // 转换为基于调色板的无抖动和 255 种颜色
    imagetruecolortopalette($im, false, 255);

    // 保存图像
    imagepng($im, './paletteimage.png');
    ?>

# imagettfbbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imagettfbbox — 取得使用 TrueType 字体的文本的边界框

### 说明

function imagettfbbox(
float `$size`,
float `$angle`,
string `$font_filename`,
string `$string`,
array `$options` = []
): array|false

本函数计算并返回 TrueType 文本的边界框的像素大小。

> 注意:

> 在 PHP 8.0.0 之前，imageftbbox() 是 imagettfbbox() 的扩展变体，额外支持 `extrainfo`。自 PHP 8.0.0 起，imagettfbbox() 是 imageftbbox() 的别名。

### 参数

`size`

  字体的尺寸，单位：点（磅）。

`angle`

  测量字符串的角度（以度为单位）。

`fontfile`
  想要使用的 TrueType 字体的路径。 根据 PHP 所使用的 GD 库版本，当 `fontfile` 没有以 `/` 开头时则 `.ttf` 将追加到文件名之后，并且会在库定义字体路径中尝试搜索该文件名。 当使用的 GD 库版本低于 2.0.18 时，`space` 字符而不是分号将被用来作为不同字体文件的“路径分隔符”。不小心使用了此特性将会导致一条警告信息：`Warning: Could not find/open font`。对受影响的版本来说唯一解决方案就是将字体移动到不包含空格的路径。

  很多情况下字体与使用字体的脚本在同一个目录中，下面的小技巧可以缓解 include 的问题。

      <?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';
      ?>

  > 注意: 注意 open_basedir 不 适用于 `fontfile`。

`string`

  要测量的字符串。

`options`

  与 imagettftext() 相同。

### 返回值

imagettfbbox() 成功时返回包含 8 个元素的数组，代表构成文本边界框的四个点。失败时返回 `false`。

键 | 内容
--- | ---
0 | 左下角,X 位置
1 | 左下角，Y 位置
2 | 右下角，X 位置
3 | 右下角，Y 位置
4 | 右上角，X 位置
5 | 右上角，Y 位置
6 | 左上角，X 位置
7 | 左上角，Y 位置

这些点相对于 text，与 `angle` 无关，因此“左上角”意味着可以在左上角看到横排文本。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 新增 `options`。

### 示例

示例 #1 imagettfbbox() 示例

    <?php
    // 创建 300x150 图像
    $im = imagecreatetruecolor(300, 150);
    $black = imagecolorallocate($im, 0, 0, 0);
    $white = imagecolorallocate($im, 255, 255, 255);

    // 设置白色背景色
    imagefilledrectangle($im, 0, 0, 299, 299, $white);

    // 字体文件的路径
    $font = './arial.ttf';

    // 首先为第一个文本创建边界框
    $bbox = imagettfbbox(10, 45, $font, 'Powered by PHP ' . phpversion());

    // 这是 X 坐标和 Y 坐标
    $x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) - 25;
    $y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

    // 写入
    imagettftext($im, 10, 45, $x, $y, $black, $font, 'Powered by PHP ' . phpversion());

    // 为第二个文本创建边界框
    $bbox = imagettfbbox(10, 45, $font, 'and Zend Engine ' . zend_version());

    // 设置坐标，使其位于第一个字的旁边
    $x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) + 10;
    $y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

    // 写入
    imagettftext($im, 10, 45, $x, $y, $black, $font, 'and Zend Engine ' . zend_version());

    // 输出到浏览器
    header('Content-Type: image/png');

    imagepng($im);
    ?>

### 注释

> 注意: 此函数仅在 PHP 编译时加入 freetype 支持时有效（--with-freetype-dir=DIR）。

### 参见

- imagettftext() - 用 TrueType 字体向图像写入文本
- imageftbbox() - 通过 freetype2 使用字体给出文本的边界框

# imagettftext

(PHP 4, PHP 5, PHP 7, PHP 8)

imagettftext — 用 TrueType 字体向图像写入文本

### 说明

function imagettftext(
GdImage `$image`,
float `$size`,
float `$angle`,
int `$x`,
int `$y`,
int `$color`,
string `$font_filename`,
string `$text`,
array `$options` = []
): array|false

使用 TrueType 字体将指定的 `text` 写入图像。

> 注意:

> PHP 8.0.0 之前，imagefttext() 是 imagettftext() 的扩展变体，额外支持 `extrainfo`。自 PHP 8.0.0 起，imagettftext() 是 imagefttext() 的别名。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`size`

  字体的尺寸，单位：点（磅）。

`angle`

  角度制表示的角度，0 度为从左向右读的文本。较高数值表示逆时针旋转。例如 90 度表示从下向上读的文本。

`x`

  由 `x`，`y` 所表示的坐标定义了第一个字符的基本点（大概是字符的左下角）。这和 imagestring() 不同，其中 `x`，`y` 定义了第一个字符的左上角。例如“top left”为 0, 0。

`y`

  Y 坐标。它设定了字体基线的位置，不是字符的最底端。

`color`

  颜色索引。使用负的颜色索引值具有关闭防锯齿的效果。见 imagecolorallocate()。

`fontfile`
  想要使用的 TrueType 字体的路径。 根据 PHP 所使用的 GD 库版本，当 `fontfile` 没有以 `/` 开头时则 `.ttf` 将追加到文件名之后，并且会在库定义字体路径中尝试搜索该文件名。 当使用的 GD 库版本低于 2.0.18 时，`space` 字符而不是分号将被用来作为不同字体文件的“路径分隔符”。不小心使用了此特性将会导致一条警告信息：`Warning: Could not find/open font`。对受影响的版本来说唯一解决方案就是将字体移动到不包含空格的路径。

  很多情况下字体与使用字体的脚本在同一个目录中，下面的小技巧可以缓解 include 的问题。

      <?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';
      ?>

  > 注意: 注意 open_basedir 不 适用于 `fontfile`。

`text`

  UTF-8 编码的文本字符串。

  可以包含十进制数字化字符表示（形式为：`&#8364;`）来访问字体中超过位置 127 的字符，支持十六进制格式（如 `&#xA9;`）。UTF-8 编码的字符串可以直接传递。

  不支持命名实体，比如 `&copy;`。可以考虑使用 html_entity_decode() 将这些命名实体解码为 UTF-8 字符。

  如果字符串中使用了字体不支持的字符，则将用空心矩形替换该字符。

`options`

  包含 key 为 `linespacing` 且其值为 float 的数组。

### 返回值

返回含有 8 个元素的数组，代表构成文本外框的四个点，顺序为左下、右下、右上、左上。无论角度如何，这些点是相对于文本的，因此“左上角”指的是以水平方向看文字时的左上角。错误时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 新增 `options`。

### 示例

示例 #1 imagettftext() 示例

此示例脚本将生成白色 400x30 像素的 PNG 图像，其中有黑色（带灰色阴影）Arial 字体写的“Testing...”。

    <?php

    // 设置 content-type
    header('Content-Type: image/png');

    // 创建图像
    $im = imagecreatetruecolor(400, 30);

    // 创建一些颜色
    $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);

    // 要绘制的文本
    $text = 'Testing...';

    // 用自己的字体路径替换路径
    $font = 'arial.ttf';

    // 给文本添加一些阴影
    imagettftext($im, 20, 0, 11, 21, $grey, $font, $text);

    // 添加文本
    imagettftext($im, 20, 0, 10, 20, $black, $font, $text);

    // 与 imagejpeg() 相比，使用 imagepng() 可产生更清晰的文本
    imagepng($im);

    ?>

以上示例的输出类似于：

### 注释

> 注意: 此函数仅在 PHP 编译时加入 freetype 支持时有效（--with-freetype-dir=DIR）。

### 参见

- imagettfbbox() - 取得使用 TrueType 字体的文本的边界框
- imagefttext() - 使用 FreeType 2 字体将文本写入图像
- imagestring() - 水平绘制字符串

# imagetypes

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

imagetypes — 返回 PHP 内置支持的图像类型

### 说明

function imagetypes(): int

返回当前安装的 PHP 支持的图片类型。

### 参数

此函数没有参数。

### 返回值

返回链接到 PHP 的 GD 版本支持的图片类型相对应的位字段。返回以下位：`IMG_AVIF` | `IMG_BMP` | `IMG_GIF` | `IMG_JPG` | `IMG_PNG` | `IMG_WBMP` | `IMG_XPM` | `IMG_WEBP`.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 新增 `IMG_AVIF`。
7.2.0 | 新增 `IMG_BMP`。
7.0.10 | 新增 `IMG_WEBP`。

### 示例

示例 #1 检测 PNG 支持

    <?php
    if (imagetypes() & IMG_PNG) {
        echo "PNG Support is enabled";
    }
    ?>

### 参见

- gd_info() - 取得当前安装的 GD 库的信息

# imagewbmp

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagewbmp — 输出图象到浏览器或文件。

### 说明

function imagewbmp(GdImage `$image`, resource|string|null `$file` = `null`, ?int `$foreground_color` = `null`): bool

imagewbmp() 输出或保存为指定 `image` 的 WBMP 版本。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`file`

  文件保存的路径或者已打开的流资源（此方法返回后自动关闭该流资源），如果未设置或为 `null`，将会直接输出原始图象流。

`foreground_color`

  使用此参数从 imagecolorallocate() 获得的标识符来设置前景色。默认前景色为黑色。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

警告

如果 libgd 输出图像失败，函数会返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。
8.0.0 | `foreground_color` 现在允许为 null。

### 示例

示例 #1 输出 WBMP 图像

    <?php
    // 创建空白图像并添加文本
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // 设置内容类型标头——在本例中是 image/vnd.wap.wbmp
    // 提示，请参阅 image_type_to_mime_type() 了解内容类型
    header('Content-Type: image/vnd.wap.wbmp');

    // 输出图像
    imagewbmp($im);
    ?>

示例 #2 保存 WBMP 图像

    <?php
    // 创建空白图像并添加文本
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // 保存图像
    imagewbmp($im, 'simpletext.wbmp');
    ?>

示例 #3 使用不同的前景色输出图像

    <?php
    // 创建空白图像并添加文本
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // 设置内容类型标头——在本例中是 image/vnd.wap.wbmp
    // 提示，请参阅 image_type_to_mime_type() 了解内容类型
    header('Content-Type: image/vnd.wap.wbmp');

    // 设置替换的前景色
    $foreground_color = imagecolorallocate($im, 255, 0, 0);

    imagewbmp($im, NULL, $foreground_color);
    ?>

### 参见

- image2wbmp() - 输出图象到浏览器或文件。
- imagepng() - 将 PNG 图像输出到浏览器或文件
- imagegif() - 输出图象到浏览器或文件。
- imagejpeg() - 输出图象到浏览器或文件。
- imagetypes() - 返回 PHP 内置支持的图像类型

# imagewebp

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

imagewebp — 将 WebP 格式的图像输出到浏览器或文件

### 说明

function imagewebp(GdImage `$image`, resource|string|null `$file` = `null`, int `$quality` = -1): bool

输出或保存为指定 `image` 的 WebP 版本。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`file`

  文件保存的路径或者已打开的流资源（此方法返回后自动关闭该流资源），如果未设置或为 `null`，将会直接输出原始图象流。

`quality`

  `quality` 范围从 0（最低质量，最小文件体积）到 100（最好质量, 最大文件体积）。 如果设置为 `-1`，则使用默认值 `80`。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

警告

如果 libgd 输出图像失败，函数会返回 `true`。

### 错误／异常

如果 `quality` 无效，抛出 ValueError。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 现在如果 `quality` 无效，抛出 ValueError。
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。

### 示例

示例 #1 保存为 WebP 图像文件

    <?php
    // 创建一个空图像并在其上加入一些文字
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);

    imagestring($im, 1, 5, 5,  'WebP with PHP', $text_color);

    // 保存图像
    imagewebp($im, 'php.webp');
    ?>

# imagexbm

(PHP 5, PHP 7, PHP 8)

imagexbm — 输出 XBM 图像到浏览器或文件

### 说明

function imagexbm(GdImage `$image`, ?string `$filename`, ?int `$foreground_color` = `null`): bool

输出或保存 `image` 的 XBM 版本。

> 注意: imagexbm() 不应用任何填充，因此图片宽度必须是 8 的倍数。从 PHP 7.0.9 起此限制不再适用。

### 参数

`image`
  由图象创建函数(例如imagecreatetruecolor())返回的 GdImage 对象。
`filename`

  string 格式，给出保存到文件的路径。如果为 `null`，将直接输出原始图像流。

  `filename`（不带 .xbm 扩展名）也用于 XBM 的 C 标识符，其中当前区域设置的非字母数字字符将由下划线替换。如果 `filename` 设置为 `null`，则 `image` 用于构建 C 标识符。

`foreground_color`

  通过设置从 imagecolorallocate() 获得的标识符来使用此参数设置前景色。默认前景色是黑色。所有的其它颜色都视为背景。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

警告

如果 libgd 输出图像失败，函数会返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `image` 现在需要 GdImage 实例；之前需要有效的 `gd` resource。
8.0.0 | `foreground_color` 现在允许为 null。
8.0.0 | 第四个参数未使用，已移除。

### 示例

示例 #1 保存 XBM 文件

    <?php
    // 创建空白图像并添加文字
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // 保存图像
    imagexbm($im, 'simpletext.xbm');
    ?>

示例 #2 以不同前景色保存一个 XBM 文件

    <?php
    // 创建空白图像并添加文字
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // 设置替换的前景色
    $foreground_color = imagecolorallocate($im, 255, 0, 0);

    // 保存图像
    imagexbm($im, NULL, $foreground_color);
    ?>

# iptcembed

(PHP 4, PHP 5, PHP 7, PHP 8)

iptcembed — 嵌入二进制 IPTC 数据到 JPEG 图像中

### 说明

function iptcembed(string `$iptc_data`, string `$filename`, int `$spool` = 0): string|bool

嵌入二进制 IPTC 数据到 JPEG 图像中。

### 参数

`iptc_data`

  写入的数据。

`filename`

  JPEG 图片的路径。

`spool`

  Spool flag。如果 spool flag 小于 2，然后 JPEG 将使用字符串返回。否则 JPEG 将打印到 STDOUT。

### 返回值

如果 `spool` 小于 2，将返回 JPEG， 或者在失败时返回 `false`。否则成功时返回 `true` 或者在失败时返回 `false`。

### 示例

示例 #1 嵌入 IPTC 数据到 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);
    ?>

### 注释

> 注意: 此函数不需要 GD 图象库。

# iptcparse

(PHP 4, PHP 5, PHP 7, PHP 8)

iptcparse — 将二进制 IPTC 块解析为单个标签

### 说明

function iptcparse(string `$iptc_block`): array|false

将 » IPTC 块解析为单个标签。

### 参数

`iptc_block`

  二进制的 IPTC 块。

### 返回值

返回一个数组，用 tagmarker 作为索引，以 value 为值。如果出错或未发现 IPTC 数据则返回 `false`。

### 示例

示例 #1 iptcparse() 与 getimagesize() 一起使用

    <?php
    $size = getimagesize('./test.jpg', $info);
    if(isset($info['APP13']))
    {
        $iptc = iptcparse($info['APP13']);
        var_dump($iptc);
    }
    ?>

### 注释

> 注意: 此函数不需要 GD 图象库。

# jpeg2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

jpeg2wbmp — 将 JPEG 图像文件转换为 WBMP 图像文件

警告

本函数已自 PHP 7.2.0 起被废弃，并自 PHP 8.0.0 起被移除。 强烈建议不要依赖本函数。

### 说明

function jpeg2wbmp(
string `$jpegname`,
string `$wbmpname`,
int `$dest_height`,
int `$dest_width`,
int `$threshold`
): bool

将 JPEG 图像文件转换为 WBMP 图像文件。

### 参数

`jpegname`

  JPEG 文件的路径。

`wbmpname`

  目标 WBMP 文件的路径。

`dest_height`

  目标图像高度。

`dest_width`

  目标图像宽度。

`threshold`

  阈值，在 0 和 8 之间（含）。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

警告

如果 libgd 输出图像失败，函数会返回 `true`。

### 示例

示例 #1 jpeg2wbmp() 示例

    <?php
    // 目标 jpeg 的路径
    $path = './test.jpg';

    // 获取图像尺寸
    $image = getimagesize($path);

    // 转换图像
    jpeg2wbmp($path, './test.wbmp', $image[1], $image[0], 5);
    ?>

### 参见

- png2wbmp() - 将 PNG 图像文件转换为 WBMP 图像文件

# png2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

png2wbmp — 将 PNG 图像文件转换为 WBMP 图像文件

警告

本函数已自 PHP 7.2.0 起被废弃，并自 PHP 8.0.0 起被移除。 强烈建议不要依赖本函数。

### 说明

function png2wbmp(
string `$pngname`,
string `$wbmpname`,
int `$dest_height`,
int `$dest_width`,
int `$threshold`
): bool

转换 PNG 文件到 WBMP 文件。

### 参数

`pngname`

  PNG 文件的路径。

`wbmpname`

  目标 WBMP 文件的路径。

`dest_height`

  目标图像的高度。

`dest_width`

  目标图像的宽度。

`threshold`

  阈值，在 0 到 8 之间（含）。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

警告

如果 libgd 输出图像失败，函数会返回 `true`。

### 示例

示例 #1 png2wbmp() 示例

    <?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);
    ?>

### 参见

- jpeg2wbmp() - 将 JPEG 图像文件转换为 WBMP 图像文件

## 目录

- gd_info — 取得当前安装的 GD 库的信息
- getimagesize — 取得图像大小
- getimagesizefromstring — 从字符串中获取图像尺寸信息
- image_type_to_extension — 取得图像类型的文件后缀
- image_type_to_mime_type — 取得 getimagesize、exif_read_data、exif_thumbnail、exif_imagetype 所返回的图像类型的 MIME 类型
- image2wbmp — 输出图象到浏览器或文件。
- imageaffine — 返回经过仿射变换后的图像，剪切区域可选
- imageaffinematrixconcat — Concatenate two affine transformation matrices
- imageaffinematrixget — Get an affine transformation matrix
- imagealphablending — 设定图像的混色模式
- imageantialias — 是否使用抗锯齿（antialias）功能
- imagearc — 画弧线
- imageavif — 输出图象到浏览器或文件。
- imagebmp — Output a BMP image to browser or file
- imagechar — 水平地绘制一个字符
- imagecharup — 垂直地绘制一个字符
- imagecolorallocate — 为图像分配颜色
- imagecolorallocatealpha — 为图像分配颜色
- imagecolorat — 取得某像素的颜色索引值
- imagecolorclosest — 取得与指定的颜色最接近的颜色索引值
- imagecolorclosestalpha — 获取最接近指定颜色 + alpha 的颜色索引
- imagecolorclosesthwb — 取得与给定颜色最接近的色度的黑白色的索引
- imagecolordeallocate — 取消图像颜色的分配
- imagecolorexact — 取得指定颜色的索引值
- imagecolorexactalpha — 取得指定的颜色加透明度的索引值
- imagecolormatch — 使一个图像中调色板版本的颜色与真彩色版本更能匹配
- imagecolorresolve — 取得指定颜色的索引值或有可能得到的最接近的替代值
- imagecolorresolvealpha — 取得指定颜色 + alpha 或其最接近的替代值
- imagecolorset — 给指定调色板索引设定颜色
- imagecolorsforindex — 获取索引的颜色
- imagecolorstotal — 取得图像调色板中的颜色数量
- imagecolortransparent — 将颜色定义为透明
- imageconvolution — 用系数 div 和 offset 申请一个 3x3 的卷积矩阵
- imagecopy — 拷贝图像的一部分
- imagecopymerge — 拷贝并合并图像的一部分
- imagecopymergegray — 用灰度复制并合并图像的一部分
- imagecopyresampled — 重采样拷贝部分图像并调整大小
- imagecopyresized — 拷贝部分图像并调整大小
- imagecreate — 创建新的基于调色板的图像
- imagecreatefromavif — 由文件或 URL 创建一个新图象。
- imagecreatefrombmp — 由文件或 URL 创建一个新图象。
- imagecreatefromgd — 从 GD 文件或 URL 新建一图像
- imagecreatefromgd2 — 从 GD2 文件或 URL 新建一图像
- imagecreatefromgd2part — 从指定的 GD2 文件或 URL 的部分创建新图像
- imagecreatefromgif — 由文件或 URL 创建一个新图象。
- imagecreatefromjpeg — 由文件或 URL 创建一个新图象。
- imagecreatefrompng — 由文件或 URL 创建一个新图象。
- imagecreatefromstring — 从字符串的图像流中新建图像
- imagecreatefromtga — 由文件或 URL 创建一个新图象。
- imagecreatefromwbmp — 由文件或 URL 创建一个新图象。
- imagecreatefromwebp — 由文件或 URL 创建一个新图象。
- imagecreatefromxbm — 由文件或 URL 创建一个新图象。
- imagecreatefromxpm — 由文件或 URL 创建一个新图象。
- imagecreatetruecolor — 新建真彩色图像
- imagecrop — Crop an image to the given rectangle
- imagecropauto — Crop an image automatically using one of the available modes
- imagedashedline — 绘制虚线
- imagedestroy — 销毁图像
- imageellipse — 画椭圆
- imagefill — 漫水填充
- imagefilledarc — 绘制部分弧形并填充
- imagefilledellipse — 绘制椭圆并填充
- imagefilledpolygon — 绘制多边形并填充
- imagefilledrectangle — 绘制矩形并填充
- imagefilltoborder — 漫水填充特定颜色
- imagefilter — 对图像使用过滤器
- imageflip — Flips an image using a given mode
- imagefontheight — 获取字体高度
- imagefontwidth — 获取字体宽度
- imageftbbox — 通过 freetype2 使用字体给出文本的边界框
- imagefttext — 使用 FreeType 2 字体将文本写入图像
- imagegammacorrect — 对 GD 图像应用伽玛校正
- imagegd — 将 GD 图像输出到浏览器或文件
- imagegd2 — 将 GD2 图像输出到浏览器或文件
- imagegetclip — Get the clipping rectangle
- imagegetinterpolation — Get the interpolation method
- imagegif — 输出图象到浏览器或文件。
- imagegrabscreen — Captures the whole screen
- imagegrabwindow — Captures a window
- imageinterlace — 启用或禁用隔行扫描
- imageistruecolor — 检查图像是否为真彩色图像
- imagejpeg — 输出图象到浏览器或文件。
- imagelayereffect — 设定 alpha 混合标志以使用分层效果
- imageline — 绘制直线
- imageloadfont — 载入新字体
- imageopenpolygon — Draws an open polygon
- imagepalettecopy — 将调色板从一个图像复制到另一个
- imagepalettetotruecolor — Converts a palette based image to true color
- imagepng — 将 PNG 图像输出到浏览器或文件
- imagepolygon — 绘制多边形
- imagerectangle — 绘制矩形
- imageresolution — Get or set the resolution of the image
- imagerotate — 用给定角度旋转图像
- imagesavealpha — 保存图像时是否保留完整的 alpha 通道信息
- imagescale — Scale an image using the given new width and height
- imagesetbrush — 为线条设置笔刷图像
- imagesetclip — Set the clipping rectangle
- imagesetinterpolation — Set the interpolation method
- imagesetpixel — 设置单个像素
- imagesetstyle — 设定线条的样式
- imagesetthickness — 设定画线的粗细
- imagesettile — 设置要填充的平铺图像
- imagestring — 水平绘制字符串
- imagestringup — 垂直绘制字符串
- imagesx — 取得图像宽度
- imagesy — 取得图像高度
- imagetruecolortopalette — 将真彩色图像转换为调色板图像
- imagettfbbox — 取得使用 TrueType 字体的文本的边界框
- imagettftext — 用 TrueType 字体向图像写入文本
- imagetypes — 返回 PHP 内置支持的图像类型
- imagewbmp — 输出图象到浏览器或文件。
- imagewebp — 将 WebP 格式的图像输出到浏览器或文件
- imagexbm — 输出 XBM 图像到浏览器或文件
- iptcembed — 嵌入二进制 IPTC 数据到 JPEG 图像中
- iptcparse — 将二进制 IPTC 块解析为单个标签
- jpeg2wbmp — 将 JPEG 图像文件转换为 WBMP 图像文件
- png2wbmp — 将 PNG 图像文件转换为 WBMP 图像文件

# GdImage 类

(PHP 8)

## 简介

完全不透明的类，从 PHP 8.0.0 起开始替换 `gd` 资源。

## 类摘要

final class GdImage {
}

# The GdFont class

(PHP 8 >= 8.1.0)

## 简介

A fully opaque class which replaces `gd font` resources as of PHP 8.1.0.

## 类摘要

final class GdFont {
}

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
  - 资源类型
- 预定义常量
- 示例
  - 使用 PHP 创建 PNG 图像
  - 使用 Alpha 通道为图像加水印
  - 使用 imagecopymerge 函数创建半透明水印
- GD 和图像处理 函数
  - gd_info — 取得当前安装的 GD 库的信息
  - getimagesize — 取得图像大小
  - getimagesizefromstring — 从字符串中获取图像尺寸信息
  - image_type_to_extension — 取得图像类型的文件后缀
  - image_type_to_mime_type — 取得 getimagesize、exif_read_data、exif_thumbnail、exif_imagetype 所返回的图像类型的 MIME 类型
  - image2wbmp — 输出图象到浏览器或文件。
  - imageaffine — 返回经过仿射变换后的图像，剪切区域可选
  - imageaffinematrixconcat — Concatenate two affine transformation matrices
  - imageaffinematrixget — Get an affine transformation matrix
  - imagealphablending — 设定图像的混色模式
  - imageantialias — 是否使用抗锯齿（antialias）功能
  - imagearc — 画弧线
  - imageavif — 输出图象到浏览器或文件。
  - imagebmp — Output a BMP image to browser or file
  - imagechar — 水平地绘制一个字符
  - imagecharup — 垂直地绘制一个字符
  - imagecolorallocate — 为图像分配颜色
  - imagecolorallocatealpha — 为图像分配颜色
  - imagecolorat — 取得某像素的颜色索引值
  - imagecolorclosest — 取得与指定的颜色最接近的颜色索引值
  - imagecolorclosestalpha — 获取最接近指定颜色 + alpha 的颜色索引
  - imagecolorclosesthwb — 取得与给定颜色最接近的色度的黑白色的索引
  - imagecolordeallocate — 取消图像颜色的分配
  - imagecolorexact — 取得指定颜色的索引值
  - imagecolorexactalpha — 取得指定的颜色加透明度的索引值
  - imagecolormatch — 使一个图像中调色板版本的颜色与真彩色版本更能匹配
  - imagecolorresolve — 取得指定颜色的索引值或有可能得到的最接近的替代值
  - imagecolorresolvealpha — 取得指定颜色 + alpha 或其最接近的替代值
  - imagecolorset — 给指定调色板索引设定颜色
  - imagecolorsforindex — 获取索引的颜色
  - imagecolorstotal — 取得图像调色板中的颜色数量
  - imagecolortransparent — 将颜色定义为透明
  - imageconvolution — 用系数 div 和 offset 申请一个 3x3 的卷积矩阵
  - imagecopy — 拷贝图像的一部分
  - imagecopymerge — 拷贝并合并图像的一部分
  - imagecopymergegray — 用灰度复制并合并图像的一部分
  - imagecopyresampled — 重采样拷贝部分图像并调整大小
  - imagecopyresized — 拷贝部分图像并调整大小
  - imagecreate — 创建新的基于调色板的图像
  - imagecreatefromavif — 由文件或 URL 创建一个新图象。
  - imagecreatefrombmp — 由文件或 URL 创建一个新图象。
  - imagecreatefromgd — 从 GD 文件或 URL 新建一图像
  - imagecreatefromgd2 — 从 GD2 文件或 URL 新建一图像
  - imagecreatefromgd2part — 从指定的 GD2 文件或 URL 的部分创建新图像
  - imagecreatefromgif — 由文件或 URL 创建一个新图象。
  - imagecreatefromjpeg — 由文件或 URL 创建一个新图象。
  - imagecreatefrompng — 由文件或 URL 创建一个新图象。
  - imagecreatefromstring — 从字符串的图像流中新建图像
  - imagecreatefromtga — 由文件或 URL 创建一个新图象。
  - imagecreatefromwbmp — 由文件或 URL 创建一个新图象。
  - imagecreatefromwebp — 由文件或 URL 创建一个新图象。
  - imagecreatefromxbm — 由文件或 URL 创建一个新图象。
  - imagecreatefromxpm — 由文件或 URL 创建一个新图象。
  - imagecreatetruecolor — 新建真彩色图像
  - imagecrop — Crop an image to the given rectangle
  - imagecropauto — Crop an image automatically using one of the available modes
  - imagedashedline — 绘制虚线
  - imagedestroy — 销毁图像
  - imageellipse — 画椭圆
  - imagefill — 漫水填充
  - imagefilledarc — 绘制部分弧形并填充
  - imagefilledellipse — 绘制椭圆并填充
  - imagefilledpolygon — 绘制多边形并填充
  - imagefilledrectangle — 绘制矩形并填充
  - imagefilltoborder — 漫水填充特定颜色
  - imagefilter — 对图像使用过滤器
  - imageflip — Flips an image using a given mode
  - imagefontheight — 获取字体高度
  - imagefontwidth — 获取字体宽度
  - imageftbbox — 通过 freetype2 使用字体给出文本的边界框
  - imagefttext — 使用 FreeType 2 字体将文本写入图像
  - imagegammacorrect — 对 GD 图像应用伽玛校正
  - imagegd — 将 GD 图像输出到浏览器或文件
  - imagegd2 — 将 GD2 图像输出到浏览器或文件
  - imagegetclip — Get the clipping rectangle
  - imagegetinterpolation — Get the interpolation method
  - imagegif — 输出图象到浏览器或文件。
  - imagegrabscreen — Captures the whole screen
  - imagegrabwindow — Captures a window
  - imageinterlace — 启用或禁用隔行扫描
  - imageistruecolor — 检查图像是否为真彩色图像
  - imagejpeg — 输出图象到浏览器或文件。
  - imagelayereffect — 设定 alpha 混合标志以使用分层效果
  - imageline — 绘制直线
  - imageloadfont — 载入新字体
  - imageopenpolygon — Draws an open polygon
  - imagepalettecopy — 将调色板从一个图像复制到另一个
  - imagepalettetotruecolor — Converts a palette based image to true color
  - imagepng — 将 PNG 图像输出到浏览器或文件
  - imagepolygon — 绘制多边形
  - imagerectangle — 绘制矩形
  - imageresolution — Get or set the resolution of the image
  - imagerotate — 用给定角度旋转图像
  - imagesavealpha — 保存图像时是否保留完整的 alpha 通道信息
  - imagescale — Scale an image using the given new width and height
  - imagesetbrush — 为线条设置笔刷图像
  - imagesetclip — Set the clipping rectangle
  - imagesetinterpolation — Set the interpolation method
  - imagesetpixel — 设置单个像素
  - imagesetstyle — 设定线条的样式
  - imagesetthickness — 设定画线的粗细
  - imagesettile — 设置要填充的平铺图像
  - imagestring — 水平绘制字符串
  - imagestringup — 垂直绘制字符串
  - imagesx — 取得图像宽度
  - imagesy — 取得图像高度
  - imagetruecolortopalette — 将真彩色图像转换为调色板图像
  - imagettfbbox — 取得使用 TrueType 字体的文本的边界框
  - imagettftext — 用 TrueType 字体向图像写入文本
  - imagetypes — 返回 PHP 内置支持的图像类型
  - imagewbmp — 输出图象到浏览器或文件。
  - imagewebp — 将 WebP 格式的图像输出到浏览器或文件
  - imagexbm — 输出 XBM 图像到浏览器或文件
  - iptcembed — 嵌入二进制 IPTC 数据到 JPEG 图像中
  - iptcparse — 将二进制 IPTC 块解析为单个标签
  - jpeg2wbmp — 将 JPEG 图像文件转换为 WBMP 图像文件
  - png2wbmp — 将 PNG 图像文件转换为 WBMP 图像文件
- GdImage — GdImage 类
- GdFont — The GdFont class

# Gmagick

# 简介

警告

此扩展是实验性的。 此扩展的行为，包括其函数的名称和围绕此扩展的相关文档都可能会在未来的 PHP 版本中发生变化而不另行通知。使用本扩展应自行承担风险。

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).

# 安装/配置

## 目录

- 需求
- 安装

## 需求

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.

## 安装

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/gmagick.

> 注意: The official name of this extension is gmagick.

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

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)

# 示例

The following shows some common Gmagick image operations.

示例 #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)

## 简介

## 类摘要

class Gmagick {
/* 方法 */
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

### 说明

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.

### 参数

`source`
  The source Gmagick object

### 返回值

The Gmagick object with image added

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::addnoiseimage

(PECL gmagick >= Unknown)

Gmagick::addnoiseimage — Adds random noise to the image

### 说明

public function Gmagick::addnoiseimage(int `$noise_type`): Gmagick

Adds random noise to the image.

### 参数

`noise_type`
  The type of the noise. Refer to this list of noise constants.

### 返回值

The Gmagick object with noise added.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::annotateimage

(PECL gmagick >= Unknown)

Gmagick::annotateimage — Annotates an image with text

### 说明

public function Gmagick::annotateimage(
GmagickDraw `$GmagickDraw`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): Gmagick

Annotates an image with text.

### 参数

`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.

### 返回值

The Gmagick object with annotation made.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::blurimage

(PECL gmagick >= Unknown)

Gmagick::blurimage — Adds blur filter to image

### 说明

public function Gmagick::blurimage(float `$radius`, float `$sigma`, int `$channel` = ?): Gmagick

Adds blur filter to image.

### 参数

`radius`
  Blur radius
`sigma`
  Standard deviation

### 返回值

The blurred Gmagick object

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::borderimage

(PECL gmagick >= Unknown)

Gmagick::borderimage — Surrounds the image with a border

### 说明

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.

### 参数

`color`
  GmagickPixel object or a string containing the border color.
`width`
  Border width.
`height`
  Border height.

### 返回值

The Gmagick object with border defined.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::charcoalimage

(PECL gmagick >= Unknown)

Gmagick::charcoalimage — Simulates a charcoal drawing

### 说明

public function Gmagick::charcoalimage(float `$radius`, float `$sigma`): Gmagick

Simulates a charcoal drawing.

### 参数

`radius`
  The radius of the Gaussian, in pixels, not counting the center pixel.
`sigma`
  The standard deviation of the Gaussian, in pixels.

### 返回值

The Gmagick object with charcoal simulation.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::chopimage

(PECL gmagick >= Unknown)

Gmagick::chopimage — Removes a region of an image and trims

### 说明

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.

### 参数

`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.

### 返回值

The chopped Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::clear

(PECL gmagick >= Unknown)

Gmagick::clear — Clears all resources associated to Gmagick object

### 说明

public function Gmagick::clear(): Gmagick

Clears all resources associated to Gmagick object.

### 参数

此函数没有参数。

### 返回值

The cleared Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::commentimage

(PECL gmagick >= Unknown)

Gmagick::commentimage — Adds a comment to your image

### 说明

public function Gmagick::commentimage(string `$comment`): Gmagick

Adds a comment to your image.

### 参数

`comment`
  The comment to add.

### 返回值

The Gmagick object with comment added.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::compositeimage

(PECL gmagick >= Unknown)

Gmagick::compositeimage — Composite one image onto another

### 说明

public function Gmagick::compositeimage(
Gmagick `$source`,
int `$COMPOSE`,
int `$x`,
int `$y`
): Gmagick

Composite one image onto another at the specified offset.

### 参数

`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.

### 返回值

The Gmagick object with compositions.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::__construct

(PECL gmagick >= Unknown)

Gmagick::__construct — The Gmagick constructor

### 说明

public function Gmagick::__construct(string `$filename` = ?)

The Gmagick constructor.

### 参数

`filename`
  The path to an image to load or array of paths.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::cropimage

(PECL gmagick >= Unknown)

Gmagick::cropimage — Extracts a region of the image

### 说明

public function Gmagick::cropimage(
int `$width` ,
int `$height` ,
int `$x`,
int `$y`
): Gmagick

Extracts a region of the image.

### 参数

`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.

### 返回值

The cropped Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::cropthumbnailimage

(PECL gmagick >= Unknown)

Gmagick::cropthumbnailimage — Creates a crop thumbnail

### 说明

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.

### 参数

`width`
  The width of the thumbnail.
`height`
  The Height of the thumbnail.

### 返回值

The cropped Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::current

(PECL gmagick >= Unknown)

Gmagick::current — The current purpose

### 说明

public function Gmagick::current(): Gmagick

Returns reference to the current gmagick object with image pointer at the correct sequence.

### 参数

此函数没有参数。

### 返回值

Returns self on success.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::cyclecolormapimage

(PECL gmagick >= Unknown)

Gmagick::cyclecolormapimage — Displaces an image's colormap

### 说明

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.

### 参数

`displace`
  The amount to displace the colormap.

### 返回值

Returns self on success.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::deconstructimages

(PECL gmagick >= Unknown)

Gmagick::deconstructimages — Returns certain pixel differences between images

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns a new Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::despeckleimage

(PECL gmagick >= Unknown)

Gmagick::despeckleimage — The despeckleimage purpose

### 说明

public function Gmagick::despeckleimage(): Gmagick

Reduces the speckle noise in an image while preserving the edges of the original image.

### 参数

此函数没有参数。

### 返回值

The despeckled Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

### 示例

示例 #1 Gmagick::despeckleimage() example

    <?php
    /* ... */
    ?>

以上示例的输出类似于：

    ...

# Gmagick::destroy

(PECL gmagick >= Unknown)

Gmagick::destroy — The destroy purpose

### 说明

public function Gmagick::destroy(): bool

Destroys the Gmagick object and frees all resources associated with it

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::drawimage

(PECL gmagick >= Unknown)

Gmagick::drawimage — Renders the GmagickDraw object on the current image

### 说明

public function Gmagick::drawimage(GmagickDraw `$GmagickDraw`): Gmagick

Renders the GmagickDraw object on the current image.

### 参数

`GmagickDraw`
  The drawing operations to render on the image.

### 返回值

The drawn Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::edgeimage

(PECL gmagick >= Unknown)

Gmagick::edgeimage — Enhance edges within the image

### 说明

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.

### 参数

`radius`
  The radius of the operation.

### 返回值

The Gmagick object with edges enhanced.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::embossimage

(PECL gmagick >= Unknown)

Gmagick::embossimage — Returns a grayscale image with a three-dimensional effect

### 说明

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.

### 参数

`radius`
  The radius of the effect.
`sigma`
  The sigma of the effect.

### 返回值

The embossed Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::enhanceimage

(PECL gmagick >= Unknown)

Gmagick::enhanceimage — Improves the quality of a noisy image

### 说明

public function Gmagick::enhanceimage(): Gmagick

Applies a digital filter that improves the quality of a noisy image.

### 参数

此函数没有参数。

### 返回值

The enhanced Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::equalizeimage

(PECL gmagick >= Unknown)

Gmagick::equalizeimage — Equalizes the image histogram

### 说明

public function Gmagick::equalizeimage(): Gmagick

Equalizes the image histogram.

### 参数

此函数没有参数。

### 返回值

The equalized Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::flipimage

(PECL gmagick >= Unknown)

Gmagick::flipimage — Creates a vertical mirror image

### 说明

public function Gmagick::flipimage(): Gmagick

Creates a vertical mirror image by reflecting the pixels around the central x-axis.

### 参数

此函数没有参数。

### 返回值

The flipped Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

### 参见

- Gmagick::flopimage() - Creates a horizontal mirror image

# Gmagick::flopimage

(PECL gmagick >= Unknown)

Gmagick::flopimage — Creates a horizontal mirror image

### 说明

public function Gmagick::flopimage(): Gmagick

Creates a horizontal mirror image by reflecting the pixels around the central y-axis.

### 参数

此函数没有参数。

### 返回值

The flopped Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

### 参见

- Gmagick::flipimage() - Creates a vertical mirror image

# Gmagick::frameimage

(PECL gmagick >= Unknown)

Gmagick::frameimage — Adds a simulated three-dimensional border

### 说明

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.

### 参数

`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.

### 返回值

The framed Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::gammaimage

(PECL gmagick >= Unknown)

Gmagick::gammaimage — Gamma-corrects an image

### 说明

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.

### 参数

`gamma`
  The amount of gamma-correction.

### 返回值

The gamma corrected Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getcopyright

(PECL gmagick >= Unknown)

Gmagick::getcopyright — Returns the GraphicsMagick API copyright as a string

### 说明

public function Gmagick::getcopyright(): string

Returns the GraphicsMagick API copyright as a string.

### 参数

此函数没有参数。

### 返回值

Returns a string containing the copyright notice of GraphicsMagick and Magickwand C API.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getfilename

(PECL gmagick >= Unknown)

Gmagick::getfilename — The filename associated with an image sequence

### 说明

public function Gmagick::getfilename(): string

Returns the filename associated with an image sequence.

### 参数

此函数没有参数。

### 返回值

Returns a string on success.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimagebackgroundcolor

(PECL gmagick >= Unknown)

Gmagick::getimagebackgroundcolor — Returns the image background color

### 说明

public function Gmagick::getimagebackgroundcolor(): GmagickPixel

Returns the image background color.

### 参数

此函数没有参数。

### 返回值

Returns an GmagickPixel set to the background color of the image.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimageblueprimary

(PECL gmagick >= Unknown)

Gmagick::getimageblueprimary — Returns the chromaticy blue primary point

### 说明

public function Gmagick::getimageblueprimary(): array

Returns the chromaticity blue primary point for the image.

### 参数

`x`
  The chromaticity blue primary x-point.
`y`
  The chromaticity blue primary y-point.

### 返回值

Array consisting of "x" and "y" coordinates of point.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimagebordercolor

(PECL gmagick >= Unknown)

Gmagick::getimagebordercolor — Returns the image border color

### 说明

public function Gmagick::getimagebordercolor(): GmagickPixel

Returns the image border color.

### 参数

此函数没有参数。

### 返回值

GmagickPixel object representing the color of the border.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimagechanneldepth

(PECL gmagick >= Unknown)

Gmagick::getimagechanneldepth — Gets the depth for a particular image channel

### 说明

public function Gmagick::getimagechanneldepth(int `$channel_type`): int

Gets the depth for a particular image channel.

### 参数

此函数没有参数。

### 返回值

Depth of image channel

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimagecolors

(PECL gmagick >= Unknown)

Gmagick::getimagecolors — Returns the color of the specified colormap index

### 说明

public function Gmagick::getimagecolors(): int

Returns the color of the specified colormap index.

### 参数

此函数没有参数。

### 返回值

The number of colors in image.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimagecolorspace

(PECL gmagick >= Unknown)

Gmagick::getimagecolorspace — Gets the image colorspace

### 说明

public function Gmagick::getimagecolorspace(): int

Gets the image colorspace.

### 参数

此函数没有参数。

### 返回值

Colorspace

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimagecompose

(PECL gmagick >= Unknown)

Gmagick::getimagecompose — Returns the composite operator associated with the image

### 说明

public function Gmagick::getimagecompose(): int

Returns the composite operator associated with the image.

### 参数

此函数没有参数。

### 返回值

Returns the composite operator associated with the image.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimagedelay

(PECL gmagick >= Unknown)

Gmagick::getimagedelay — Gets the image delay

### 说明

public function Gmagick::getimagedelay(): int

Gets the image delay

### 参数

此函数没有参数。

### 返回值

Returns the composite operator associated with the image.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimagedepth

(PECL gmagick >= Unknown)

Gmagick::getimagedepth — Gets the depth of the image

### 说明

public function Gmagick::getimagedepth(): int

Gets the depth of the image.

### 参数

此函数没有参数。

### 返回值

Image depth

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimagedispose

(PECL gmagick >= Unknown)

Gmagick::getimagedispose — Gets the image disposal method

### 说明

public function Gmagick::getimagedispose(): int

Gets the image disposal method

### 参数

此函数没有参数。

### 返回值

Returns the dispose method on success.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimageextrema

(PECL gmagick >= Unknown)

Gmagick::getimageextrema — Gets the extrema for the image

### 说明

public function Gmagick::getimageextrema(): array

Returns an associative array with the keys "min" and "max". 错误时抛出 GmagickException。

### 参数

此函数没有参数。

### 返回值

Returns an associative array with the keys "min" and "max".

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimagefilename

(PECL gmagick >= Unknown)

Gmagick::getimagefilename — Returns the filename of a particular image in a sequence

### 说明

public function Gmagick::getimagefilename(): string

Returns the filename of a particular image in a sequence

### 参数

此函数没有参数。

### 返回值

Returns a string with the filename of the image

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimageformat

(PECL gmagick >= Unknown)

Gmagick::getimageformat — Returns the format of a particular image in a sequence

### 说明

public function Gmagick::getimageformat(): string

Returns the format of a particular image in a sequence.

### 参数

此函数没有参数。

### 返回值

Returns a string containing the image format on success.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimagegamma

(PECL gmagick >= Unknown)

Gmagick::getimagegamma — Gets the image gamma

### 说明

public function Gmagick::getimagegamma(): float

Gets the image gamma

### 参数

此函数没有参数。

### 返回值

Returns the image gamma on success

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimagegreenprimary

(PECL gmagick >= Unknown)

Gmagick::getimagegreenprimary — Returns the chromaticy green primary point

### 说明

public function Gmagick::getimagegreenprimary(): array

Returns the chromaticity green primary point. Returns an array with the keys "x" and "y".

### 参数

此函数没有参数。

### 返回值

Returns an array with the keys "x" and "y" on success.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimageheight

(PECL gmagick >= Unknown)

Gmagick::getimageheight — Returns the image height

### 说明

public function Gmagick::getimageheight(): int

Returns the image height

### 参数

此函数没有参数。

### 返回值

Returns the image height in pixels.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimagehistogram

(PECL gmagick >= Unknown)

Gmagick::getimagehistogram — Gets the image histogram

### 说明

public function Gmagick::getimagehistogram(): array

Returns the image histogram as an array of GmagickPixel objects. Throw an GmagickException on error.

### 参数

此函数没有参数。

### 返回值

Returns the image histogram as an array of GmagickPixel objects.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimageindex

(PECL gmagick >= Unknown)

Gmagick::getimageindex — Gets the index of the current active image

### 说明

public function Gmagick::getimageindex(): int

Returns the index of the current active image within the Gmagick object.

### 参数

此函数没有参数。

### 返回值

Index of current active image.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimageinterlacescheme

(PECL gmagick >= Unknown)

Gmagick::getimageinterlacescheme — Gets the image interlace scheme

### 说明

public function Gmagick::getimageinterlacescheme(): int

Gets the image interlace scheme.

### 参数

此函数没有参数。

### 返回值

Returns the interlace scheme as an integer on success

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimageiterations

(PECL gmagick >= Unknown)

Gmagick::getimageiterations — Gets the image iterations

### 说明

public function Gmagick::getimageiterations(): int

Gets the image iterations.

### 参数

此函数没有参数。

### 返回值

Returns the image iterations as an integer.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimagematte

(PECL gmagick >= Unknown)

Gmagick::getimagematte — Check if the image has a matte channel

### 说明

public function Gmagick::getimagematte(): int

Returns `true` if the image has a matte channel, otherwise `false`.

### 参数

此函数没有参数。

### 返回值

Returns `true` if the image has a matte channel, otherwise `false`.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimagemattecolor

(PECL gmagick >= Unknown)

Gmagick::getimagemattecolor — Returns the image matte color

### 说明

public function Gmagick::getimagemattecolor(): GmagickPixel

Returns GmagickPixel object on success. Throw an GmagickException on error.

### 参数

此函数没有参数。

### 返回值

Returns GmagickPixel object on success.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimageprofile

(PECL gmagick >= Unknown)

Gmagick::getimageprofile — Returns the named image profile

### 说明

public function Gmagick::getimageprofile(string `$name`): string

Returns the named image profile.

### 参数

此函数没有参数。

### 返回值

Returns a string containing the image profile.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimageredprimary

(PECL gmagick >= Unknown)

Gmagick::getimageredprimary — Returns the chromaticity red primary point

### 说明

public function Gmagick::getimageredprimary(): array

Returns the chromaticity red primary point as an array with the keys "x" and "y".

### 参数

此函数没有参数。

### 返回值

Returns the chromaticity red primary point as an array with the keys "x" and "y".

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimagerenderingintent

(PECL gmagick >= Unknown)

Gmagick::getimagerenderingintent — Gets the image rendering intent

### 说明

public function Gmagick::getimagerenderingintent(): int

Gets the image rendering intent

### 参数

此函数没有参数。

### 返回值

Extracts a region of the image and returns it as a new wand

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimageresolution

(PECL gmagick >= Unknown)

Gmagick::getimageresolution — Gets the image X and Y resolution

### 说明

public function Gmagick::getimageresolution(): array

Returns the resolution as an array.

### 参数

此函数没有参数。

### 返回值

Returns the resolution as an array.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimagescene

(PECL gmagick >= Unknown)

Gmagick::getimagescene — Gets the image scene

### 说明

public function Gmagick::getimagescene(): int

Gets the image scene.

### 参数

此函数没有参数。

### 返回值

Returns the image scene.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimagesignature

(PECL gmagick >= Unknown)

Gmagick::getimagesignature — Generates an SHA-256 message digest

### 说明

public function Gmagick::getimagesignature(): string

Generates an SHA-256 message digest for the image pixel stream.

### 参数

此函数没有参数。

### 返回值

Returns a string containing the SHA-256 hash of the file.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimagetype

(PECL gmagick >= Unknown)

Gmagick::getimagetype — Gets the potential image type

### 说明

public function Gmagick::getimagetype(): int

Gets the potential image type.

### 参数

此函数没有参数。

### 返回值

Returns the potential image type.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimageunits

(PECL gmagick >= Unknown)

Gmagick::getimageunits — Gets the image units of resolution

### 说明

public function Gmagick::getimageunits(): int

Gets the image units of resolution.

### 参数

此函数没有参数。

### 返回值

Returns the image units of resolution.

# Gmagick::getimagewhitepoint

(PECL gmagick >= Unknown)

Gmagick::getimagewhitepoint — Returns the chromaticity white point

### 说明

public function Gmagick::getimagewhitepoint(): array

Returns the chromaticity white point as an associative array with the keys "x" and "y".

### 参数

此函数没有参数。

### 返回值

Returns the chromaticity white point as an associative array with the keys "x" and "y".

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getimagewidth

(PECL gmagick >= Unknown)

Gmagick::getimagewidth — Returns the width of the image

### 说明

public function Gmagick::getimagewidth(): int

Returns the width of the image.

### 参数

此函数没有参数。

### 返回值

Returns the image width.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getpackagename

(PECL gmagick >= Unknown)

Gmagick::getpackagename — Returns the GraphicsMagick package name

### 说明

public function Gmagick::getpackagename(): string

Returns the GraphicsMagick package name.

### 参数

此函数没有参数。

### 返回值

Returns the GraphicsMagick package name as a string.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getquantumdepth

(PECL gmagick >= Unknown)

Gmagick::getquantumdepth — Returns the Gmagick quantum depth as a string

### 说明

public function Gmagick::getquantumdepth(): array

Returns the Gmagick quantum depth as a string.

### 参数

此函数没有参数。

### 返回值

Returns the Gmagick quantum depth as a string.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getreleasedate

(PECL gmagick >= Unknown)

Gmagick::getreleasedate — Returns the GraphicsMagick release date as a string

### 说明

public function Gmagick::getreleasedate(): string

Returns the GraphicsMagick release date as a string.

### 参数

此函数没有参数。

### 返回值

Returns the GraphicsMagick release date as a string.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getsamplingfactors

(PECL gmagick >= Unknown)

Gmagick::getsamplingfactors — Gets the horizontal and vertical sampling factor

### 说明

public function Gmagick::getsamplingfactors(): array

Gets the horizontal and vertical sampling factor.

### 参数

此函数没有参数。

### 返回值

Returns an associative array with the horizontal and vertical sampling factors of the image.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getsize

(PECL gmagick >= Unknown)

Gmagick::getsize — Returns the size associated with the Gmagick object

### 说明

public function Gmagick::getsize(): array

Returns the size associated with the Gmagick object as an array with the keys "columns" and "rows".

### 参数

此函数没有参数。

### 返回值

Returns the size associated with the Gmagick object as an array with the keys "columns" and "rows".

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::getversion

(PECL gmagick >= Unknown)

Gmagick::getversion — Returns the GraphicsMagick API version

### 说明

public function Gmagick::getversion(): array

Returns the GraphicsMagick API version as a string and as a number.

### 参数

此函数没有参数。

### 返回值

Returns the GraphicsMagick API version as a string and as a number.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::hasnextimage

(PECL gmagick >= Unknown)

Gmagick::hasnextimage — Checks if the object has more images

### 说明

public function Gmagick::hasnextimage(): mixed

Returns `true` if the object has more images when traversing the list in the forward direction.

### 参数

此函数没有参数。

### 返回值

Returns `true` if the object has more images when traversing the list in the forward direction, returns `false` if there are none.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::haspreviousimage

(PECL gmagick >= Unknown)

Gmagick::haspreviousimage — Checks if the object has a previous image

### 说明

public function Gmagick::haspreviousimage(): mixed

Returns `true` if the object has more images when traversing the list in the reverse direction.

### 参数

此函数没有参数。

### 返回值

Returns `true` if the object has more images when traversing the list in the reverse direction, returns `false` if there are none.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::implodeimage

(PECL gmagick >= Unknown)

Gmagick::implodeimage — Creates a new image as a copy

### 说明

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.

### 参数

`radius`
  The radius of the implode.

### 返回值

Returns imploded Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::labelimage

(PECL gmagick >= Unknown)

Gmagick::labelimage — Adds a label to an image

### 说明

public function Gmagick::labelimage(string `$label`): mixed

Adds a label to an image.

### 参数

`label`
  The label to add

### 返回值

Gmagick with label.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::levelimage

(PECL gmagick >= Unknown)

Gmagick::levelimage — Adjusts the levels of an image

### 说明

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.

### 参数

`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.

### 返回值

Gmagick object with image leveled.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::magnifyimage

(PECL gmagick >= Unknown)

Gmagick::magnifyimage — Scales an image proportionally 2x

### 说明

public function Gmagick::magnifyimage(): mixed

Conveniently scales an image proportionally to twice its original size.

### 参数

此函数没有参数。

### 返回值

Magnified Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::mapimage

(PECL gmagick >= Unknown)

Gmagick::mapimage — Replaces the colors of an image with the closest color from a reference image

### 说明

public function Gmagick::mapimage(gmagick `$gmagick`, bool `$dither`): Gmagick

Replaces the colors of an image with the closest color from a reference image.

### 参数

`gmagick`
  The reference image.
`dither`
  Set this integer value to something other than zero to dither the mapped image.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::medianfilterimage

(PECL gmagick >= Unknown)

Gmagick::medianfilterimage — Applies a digital filter

### 说明

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.

### 参数

`radius`
  The radius of the pixel neighborhood.

### 返回值

Gmagick object with median filter applied.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::minifyimage

(PECL gmagick >= Unknown)

Gmagick::minifyimage — Scales an image proportionally to half its size

### 说明

public function Gmagick::minifyimage(): Gmagick

A convenient method that scales an image proportionally to one-half its original size.

### 参数

此函数没有参数。

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::modulateimage

(PECL gmagick >= Unknown)

Gmagick::modulateimage — Control the brightness, saturation, and hue

### 说明

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.

### 参数

`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)

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::motionblurimage

(PECL gmagick >= Unknown)

Gmagick::motionblurimage — Simulates motion blur

### 说明

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.

### 参数

`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.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::newimage

(PECL gmagick >= Unknown)

Gmagick::newimage — Creates a new image

### 说明

public function Gmagick::newimage(
int `$width`,
int `$height`,
string `$background`,
string `$format` = ?
): Gmagick

Creates a new image with the specified background color.

### 参数

`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.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::nextimage

(PECL gmagick >= Unknown)

Gmagick::nextimage — Moves to the next image

### 说明

public function Gmagick::nextimage(): bool

Associates the next image in the image list with an Gmagick object.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::normalizeimage

(PECL gmagick >= Unknown)

Gmagick::normalizeimage — Enhances the contrast of a color image

### 说明

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.

### 参数

`channel`
  Identify which channel to normalize.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::oilpaintimage

(PECL gmagick >= Unknown)

Gmagick::oilpaintimage — Simulates an oil painting

### 说明

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.

### 参数

`radius`
  The radius of the circular neighborhood.

### 返回值

The Gmagick object on success

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::previousimage

(PECL gmagick >= Unknown)

Gmagick::previousimage — Move to the previous image in the object

### 说明

public function Gmagick::previousimage(): bool

Associates the previous image in an image list with the Gmagick object.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::profileimage

(PECL gmagick >= Unknown)

Gmagick::profileimage — Adds or removes a profile from an image

### 说明

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.

### 参数

`name`
  Name of profile to add or remove: ICC, IPTC, or generic profile.
`profile`
  The profile.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::quantizeimage

(PECL gmagick >= Unknown)

Gmagick::quantizeimage — Analyzes the colors within a reference image

### 说明

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.

### 参数

`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.

### 返回值

The Gmagick object on success

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::quantizeimages

(PECL gmagick >= Unknown)

Gmagick::quantizeimages — The quantizeimages purpose

### 说明

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.

### 参数

`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.

### 返回值

The Gmagick object on success

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::queryfontmetrics

(PECL gmagick >= Unknown)

Gmagick::queryfontmetrics — Returns an array representing the font metrics

### 说明

public function Gmagick::queryfontmetrics(GmagickDraw `$draw`, string `$text`): array

MagickQueryFontMetrics() returns an array representing the font metrics.

### 参数

此函数没有参数。

### 返回值

The Gmagick object on success

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::queryfonts

(PECL gmagick >= Unknown)

Gmagick::queryfonts — Returns the configured fonts

### 说明

public function Gmagick::queryfonts(string `$pattern` = "*"): array

Returns fonts supported by Gmagick.

### 参数

此函数没有参数。

### 返回值

The Gmagick object on success

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::queryformats

(PECL gmagick >= Unknown)

Gmagick::queryformats — Returns formats supported by Gmagick

### 说明

public function Gmagick::queryformats(string `$pattern` = "*"): array

Returns formats supported by Gmagick.

### 参数

`pattern`
  Specifies a string containing a pattern.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::radialblurimage

(PECL gmagick >= Unknown)

Gmagick::radialblurimage — Radial blurs an image

### 说明

public function Gmagick::radialblurimage(float `$angle`, int `$channel` = Gmagick::CHANNEL_DEFAULT): Gmagick

Radial blurs an image.

### 参数

`angle`
  The angle of the blur in degrees.
`channel`
  Related channel.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::raiseimage

(PECL gmagick >= Unknown)

Gmagick::raiseimage — Creates a simulated 3d button-like effect

### 说明

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.

### 参数

`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.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::read

(PECL gmagick >= Unknown)

Gmagick::read — Reads image from filename

### 说明

public function Gmagick::read(string `$filename`): Gmagick

Reads image from filename.

### 参数

`filename`
  The image filename.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::readimage

(PECL gmagick >= Unknown)

Gmagick::readimage — Reads image from filename

### 说明

public function Gmagick::readimage(string `$filename`): Gmagick

Reads image from filename.

### 参数

`filename`
  The image filename.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::readimageblob

(PECL gmagick >= Unknown)

Gmagick::readimageblob — Reads image from a binary string

### 说明

public function Gmagick::readimageblob(string `$imageContents`, string `$filename` = ?): Gmagick

Reads image from a binary string.

### 参数

`imageContents`
  Content of image.
`filename`
  The image filename.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::readimagefile

(PECL gmagick >= Unknown)

Gmagick::readimagefile — The readimagefile purpose

### 说明

public function Gmagick::readimagefile(resource `$fp`, string `$filename` = ?): Gmagick

Reads an image or image sequence from an open file descriptor.

### 参数

`fp`
  The file descriptor.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::reducenoiseimage

(PECL gmagick >= Unknown)

Gmagick::reducenoiseimage — Smooths the contours of an image

### 说明

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.

### 参数

`radius`
  The radius of the pixel neighborhood.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::removeimage

(PECL gmagick >= Unknown)

Gmagick::removeimage — Removes an image from the image list

### 说明

public function Gmagick::removeimage(): Gmagick

Removes an image from the image list.

### 参数

此函数没有参数。

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::removeimageprofile

(PECL gmagick >= Unknown)

Gmagick::removeimageprofile — Removes the named image profile and returns it

### 说明

public function Gmagick::removeimageprofile(string `$name`): string

Removes the named image profile and returns it.

### 参数

`name`
  Name of profile to return: ICC, IPTC, or generic profile.

### 返回值

The named profile.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::resampleimage

(PECL gmagick >= Unknown)

Gmagick::resampleimage — Resample image to desired resolution

### 说明

public function Gmagick::resampleimage(
float `$xResolution`,
float `$yResolution`,
int `$filter`,
float `$blur`
): Gmagick

Resample image to desired resolution.

### 参数

`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.

### 返回值

The Gmagick object on success

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::resizeimage

(PECL gmagick >= Unknown)

Gmagick::resizeimage — Scales an image

### 说明

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.

### 参数

`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.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::rollimage

(PECL gmagick >= Unknown)

Gmagick::rollimage — Offsets an image

### 说明

public function Gmagick::rollimage(int `$x`, int `$y`): Gmagick

Offsets an image as defined by x and y.

### 参数

`x`
  The x offset.
`y`
  The y offset.

### 返回值

The Gmagick object on success

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::rotateimage

(PECL gmagick >= Unknown)

Gmagick::rotateimage — Rotates an image

### 说明

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.

### 参数

`color`
  The background pixel.
`degrees`
  The number of degrees to rotate the image.

### 返回值

The Gmagick object on success

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::scaleimage

(PECL gmagick >= Unknown)

Gmagick::scaleimage — Scales the size of an image

### 说明

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.

### 参数

`width`
  The number of columns in the scaled image.
`height`
  The number of rows in the scaled image.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::separateimagechannel

(PECL gmagick >= Unknown)

Gmagick::separateimagechannel — Separates a channel from the image

### 说明

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.

### 参数

`channel`
  One of the Channel constant (`Gmagick::CHANNEL_*`).

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setCompressionQuality

(No version information available, might only be in Git)

Gmagick::setCompressionQuality — Sets the object's default compression quality

### 说明

function Gmagick::setCompressionQuality( int `$quality` ): Gmagick

Sets the object's default compression quality.

### 参数

`quality`
  The GraphicsMagick default value is 75.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

### 示例

示例 #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

### 说明

public function Gmagick::setfilename(string `$filename`): Gmagick

Sets the filename before you read or write an image file.

### 参数

`filename`
  The image filename.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimagebackgroundcolor

(PECL gmagick >= Unknown)

Gmagick::setimagebackgroundcolor — Sets the image background color

### 说明

public function Gmagick::setimagebackgroundcolor(GmagickPixel `$color`): Gmagick

Sets the image background color.

### 参数

`color`
  The background pixel wand.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimageblueprimary

(PECL gmagick >= Unknown)

Gmagick::setimageblueprimary — Sets the image chromaticity blue primary point

### 说明

public function Gmagick::setimageblueprimary(float `$x`, float `$y`): Gmagick

Sets the image chromaticity blue primary point.

### 参数

`x`
  The blue primary x-point.
`y`
  The blue primary y-point.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimagebordercolor

(PECL gmagick >= Unknown)

Gmagick::setimagebordercolor — Sets the image border color

### 说明

public function Gmagick::setimagebordercolor(GmagickPixel `$color`): Gmagick

Sets the image border color.

### 参数

`color`
  The border pixel wand.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimagechanneldepth

(PECL gmagick >= Unknown)

Gmagick::setimagechanneldepth — Sets the depth of a particular image channel

### 说明

public function Gmagick::setimagechanneldepth(int `$channel`, int `$depth`): Gmagick

Sets the depth of a particular image channel.

### 参数

`channel`
  One of the Channel constant (`Gmagick::CHANNEL_*`).
`depth`
  The image depth in bits.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimagecolorspace

(PECL gmagick >= Unknown)

Gmagick::setimagecolorspace — Sets the image colorspace

### 说明

public function Gmagick::setimagecolorspace(int `$colorspace`): Gmagick

Sets the image colorspace.

### 参数

`colorspace`
  One of the Colorspace constant (`Gmagick::COLORSPACE_*`).

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimagecompose

(PECL gmagick >= Unknown)

Gmagick::setimagecompose — Sets the image composite operator

### 说明

public function Gmagick::setimagecompose(int `$composite`): Gmagick

Sets the image composite operator.

### 参数

`composite`
  The image composite operator.

### 返回值

The Gmagick object on success

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimagedelay

(PECL gmagick >= Unknown)

Gmagick::setimagedelay — Sets the image delay

### 说明

public function Gmagick::setimagedelay(int `$delay`): Gmagick

Sets the image delay.

### 参数

`delay`
  The image delay in 1/100th of a second.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimagedepth

(PECL gmagick >= Unknown)

Gmagick::setimagedepth — Sets the image depth

### 说明

public function Gmagick::setimagedepth(int `$depth`): Gmagick

Sets the image depth.

### 参数

`depth`
  The image depth in bits: 8, 16, or 32.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimagedispose

(PECL gmagick >= Unknown)

Gmagick::setimagedispose — Sets the image disposal method

### 说明

public function Gmagick::setimagedispose(int `$disposeType`): Gmagick

Sets the image disposal method.

### 参数

`disposeType`
  The image disposal type.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimagefilename

(PECL gmagick >= Unknown)

Gmagick::setimagefilename — Sets the filename of a particular image in a sequence

### 说明

public function Gmagick::setimagefilename(string `$filename`): Gmagick

Sets the filename of a particular image in a sequence.

### 参数

`filename`
  The image filename.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimageformat

(PECL gmagick >= Unknown)

Gmagick::setimageformat — Sets the format of a particular image

### 说明

public function Gmagick::setimageformat(string `$imageFormat`): Gmagick

Sets the format of a particular image in a sequence.

### 参数

`imageFormat`
  The image format.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimagegamma

(PECL gmagick >= Unknown)

Gmagick::setimagegamma — Sets the image gamma

### 说明

public function Gmagick::setimagegamma(float `$gamma`): Gmagick

Sets the image gamma.

### 参数

`gamma`
  The image gamma.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimagegreenprimary

(PECL gmagick >= Unknown)

Gmagick::setimagegreenprimary — Sets the image chromaticity green primary point

### 说明

public function Gmagick::setimagegreenprimary(float `$x`, float `$y`): Gmagick

Sets the image chromaticity green primary point.

### 参数

`x`
  The chromaticity green primary x-point.
`y`
  The chromaticity green primary y-point.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimageindex

(PECL gmagick >= Unknown)

Gmagick::setimageindex — Set the iterator to the position in the image list specified with the index parameter

### 说明

public function Gmagick::setimageindex(int `$index`): Gmagick

Set the iterator to the position in the image list specified with the index parameter.

### 参数

`index`
  The scene number.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimageinterlacescheme

(PECL gmagick >= Unknown)

Gmagick::setimageinterlacescheme — Sets the interlace scheme of the image

### 说明

public function Gmagick::setimageinterlacescheme(int `$interlace`): Gmagick

Sets the interlace scheme of the image.

### 参数

`interlace`
  One of the Interlace constant (`Gmagick::INTERLACE_*`).

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimageiterations

(PECL gmagick >= Unknown)

Gmagick::setimageiterations — Sets the image iterations

### 说明

public function Gmagick::setimageiterations(int `$iterations`): Gmagick

Sets the image iterations.

### 参数

`iterations`
  The image delay in 1/100th of a second.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimageprofile

(PECL gmagick >= Unknown)

Gmagick::setimageprofile — Adds a named profile to the Gmagick object

### 说明

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.

### 参数

`name`
  Name of profile to add or remove: ICC, IPTC, or generic profile.
`profile`
  The profile.

### 返回值

The Gmagick object on success.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimageredprimary

(PECL gmagick >= Unknown)

Gmagick::setimageredprimary — Sets the image chromaticity red primary point

### 说明

public function Gmagick::setimageredprimary(float `$x`, float `$y`): Gmagick

Sets the image chromaticity red primary point.

### 参数

`x`
  The red primary x-point.
`y`
  The red primary y-point.

### 返回值

The Gmagick object on success.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimagerenderingintent

(PECL gmagick >= Unknown)

Gmagick::setimagerenderingintent — Sets the image rendering intent

### 说明

public function Gmagick::setimagerenderingintent(int `$rendering_intent`): Gmagick

Sets the image rendering intent.

### 参数

`rendering_intent`
  One of the Rendering Intent constant (`Gmagick::RENDERINGINTENT_*`).

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimageresolution

(PECL gmagick >= Unknown)

Gmagick::setimageresolution — Sets the image resolution

### 说明

public function Gmagick::setimageresolution(float `$xResolution`, float `$yResolution`): Gmagick

Sets the image resolution.

### 参数

`xResolution`
  The image x resolution.
`yResolution`
  The image y resolution.

### 返回值

The Gmagick object on success.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimagescene

(PECL gmagick >= Unknown)

Gmagick::setimagescene — Sets the image scene

### 说明

public function Gmagick::setimagescene(int `$scene`): Gmagick

Sets the image scene.

### 参数

`scene`
  The image scene number.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimagetype

(PECL gmagick >= Unknown)

Gmagick::setimagetype — Sets the image type

### 说明

public function Gmagick::setimagetype(int `$imgType`): Gmagick

Sets the image type.

### 参数

`imgType`
  One of the Image type constant (`Gmagick::IMGTYPE_*`).

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimageunits

(PECL gmagick >= Unknown)

Gmagick::setimageunits — Sets the image units of resolution

### 说明

public function Gmagick::setimageunits(int `$resolution`): Gmagick

Sets the image units of resolution.

### 参数

`resolution`
  One of the Resolution constant (`Gmagick::RESOLUTION_*`).

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setimagewhitepoint

(PECL gmagick >= Unknown)

Gmagick::setimagewhitepoint — Sets the image chromaticity white point

### 说明

public function Gmagick::setimagewhitepoint(float `$x`, float `$y`): Gmagick

Sets the image chromaticity white point.

### 参数

`x`
  The white x-point.
`y`
  The white y-point.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setsamplingfactors

(PECL gmagick >= Unknown)

Gmagick::setsamplingfactors — Sets the image sampling factors

### 说明

public function Gmagick::setsamplingfactors(array `$factors`): Gmagick

Sets the image sampling factors.

### 参数

`factors`
  An array of floats representing the sampling factor for each color component (in RGB order).

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::setsize

(PECL gmagick >= Unknown)

Gmagick::setsize — Sets the size of the Gmagick object

### 说明

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`.

### 参数

`columns`
  The width in pixels.
`rows`
  The height in pixels.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::shearimage

(PECL gmagick >= Unknown)

Gmagick::shearimage — Creating a parallelogram

### 说明

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.

### 参数

`color`
  The background pixel wand.
`xShear`
  The number of degrees to shear the image.
`yShear`
  The number of degrees to shear the image.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::solarizeimage

(PECL gmagick >= Unknown)

Gmagick::solarizeimage — Applies a solarizing effect to the image

### 说明

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.

### 参数

`threshold`
  Define the extent of the solarization.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::spreadimage

(PECL gmagick >= Unknown)

Gmagick::spreadimage — Randomly displaces each pixel in a block

### 说明

public function Gmagick::spreadimage(float `$radius`): Gmagick

Special effects method that randomly displaces each pixel in a block defined by the radius parameter.

### 参数

`radius`
  Choose a random pixel in a neighborhood of this extent.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::stripimage

(PECL gmagick >= Unknown)

Gmagick::stripimage — Strips an image of all profiles and comments

### 说明

public function Gmagick::stripimage(): Gmagick

Strips an image of all profiles and comments.

### 参数

此函数没有参数。

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::swirlimage

(PECL gmagick >= Unknown)

Gmagick::swirlimage — Swirls the pixels about the center of the image

### 说明

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.

### 参数

`degrees`
  Define the tightness of the swirling effect.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::thumbnailimage

(PECL gmagick >= Unknown)

Gmagick::thumbnailimage — Changes the size of an image

### 说明

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.

### 参数

`width`
  Image width.
`height`
  Image height.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::trimimage

(PECL gmagick >= Unknown)

Gmagick::trimimage — Remove edges from the image

### 说明

public function Gmagick::trimimage(float `$fuzz`): Gmagick

Remove edges that are the background color from the image.

### 参数

`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.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

# Gmagick::write

(PECL gmagick >= Unknown)

Gmagick::write — 别名 Gmagick::writeimage()

### 说明

此方法是该方法的别名： Gmagick::writeimage().

# Gmagick::writeimage

(PECL gmagick >= Unknown)

Gmagick::writeimage — Writes an image to the specified filename

### 说明

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().

### 参数

`filename`
  The image filename.

### 返回值

The Gmagick object.

### 错误／异常

错误时抛出 GmagickException。

## 目录

- 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 — 别名 Gmagick::writeimage
- Gmagick::writeimage — Writes an image to the specified filename

# The GmagickDraw class

(PECL gmagick >= Unknown)

## 简介

## 类摘要

class GmagickDraw {
/* 方法 */
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

### 说明

public function GmagickDraw::annotate(float `$x`, float `$y`, string `$text`): GmagickDraw

Draws text on the image.

### 参数

`x`
  x ordinate to left of text
`y`
  y ordinate to text baseline
`text`
  text to draw

### 返回值

The GmagickDraw object.

# GmagickDraw::arc

(PECL gmagick >= Unknown)

GmagickDraw::arc — Draws an arc

### 说明

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.

### 参数

`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

### 返回值

The GmagickDraw object.

# GmagickDraw::bezier

(PECL gmagick >= Unknown)

GmagickDraw::bezier — Draws a bezier curve

### 说明

public function GmagickDraw::bezier(array `$coordinate_array`): GmagickDraw

Draws a bezier curve through a set of points on the image.

### 参数

`coordinate_array`
  Coordinates array

### 返回值

The GmagickDraw object.

# GmagickDraw::ellipse

(PECL gmagick >= Unknown)

GmagickDraw::ellipse — Draws an ellipse on the image

### 说明

public function GmagickDraw::ellipse(
float `$ox`,
float `$oy`,
float `$rx`,
float `$ry`,
float `$start`,
float `$end`
): GmagickDraw

Draws an ellipse on the image.

### 参数

`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

### 返回值

The GmagickDraw object.

# GmagickDraw::getfillcolor

(PECL gmagick >= Unknown)

GmagickDraw::getfillcolor — Returns the fill color

### 说明

public function GmagickDraw::getfillcolor(): GmagickPixel

Returns the fill color used for drawing filled objects.

### 参数

此函数没有参数。

### 返回值

The GmagickPixel fill color used for drawing filled objects.

# GmagickDraw::getfillopacity

(PECL gmagick >= Unknown)

GmagickDraw::getfillopacity — Returns the opacity used when drawing

### 说明

public function GmagickDraw::getfillopacity(): float

Returns the opacity used when drawing

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function GmagickDraw::getfont(): mixed

Returns a string specifying the font used when annotating with text.

### 参数

此函数没有参数。

### 返回值

Returns a string on success and `false` if no font is set.

# GmagickDraw::getfontsize

(PECL gmagick >= Unknown)

GmagickDraw::getfontsize — Returns the font pointsize

### 说明

public function GmagickDraw::getfontsize(): float

Returns the font pointsize used when annotating with text.

### 参数

此函数没有参数。

### 返回值

Returns the font size associated with the current GmagickDraw object.

# GmagickDraw::getfontstyle

(PECL gmagick >= Unknown)

GmagickDraw::getfontstyle — Returns the font style

### 说明

public function GmagickDraw::getfontstyle(): int

Returns the font style used when annotating with text.

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function GmagickDraw::getfontweight(): int

Returns the font weight used when annotating with text.

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function GmagickDraw::getstrokecolor(): GmagickPixel

Returns the color used for stroking object outlines.

### 参数

此函数没有参数。

### 返回值

Returns an GmagickPixel object which describes the color.

# GmagickDraw::getstrokeopacity

(PECL gmagick >= Unknown)

GmagickDraw::getstrokeopacity — Returns the opacity of stroked object outlines

### 说明

public function GmagickDraw::getstrokeopacity(): float

Returns the opacity of stroked object outlines.

### 参数

此函数没有参数。

### 返回值

Returns a float describing the opacity.

# GmagickDraw::getstrokewidth

(PECL gmagick >= Unknown)

GmagickDraw::getstrokewidth — Returns the width of the stroke used to draw object outlines

### 说明

public function GmagickDraw::getstrokewidth(): float

Returns the width of the stroke used to draw object outlines.

### 参数

此函数没有参数。

### 返回值

Returns a float describing the stroke width.

# GmagickDraw::gettextdecoration

(PECL gmagick >= Unknown)

GmagickDraw::gettextdecoration — Returns the text decoration

### 说明

public function GmagickDraw::gettextdecoration(): int

Returns the decoration applied when annotating with text.

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function GmagickDraw::gettextencoding(): mixed

Returns a string which specifies the code set used for text annotations.

### 参数

此函数没有参数。

### 返回值

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

### 说明

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.

### 参数

`sx`
  starting x ordinate
`sy`
  starting y ordinate
`ex`
  ending x ordinate
`ey`
  ending y ordinate

### 返回值

The GmagickDraw object.

# GmagickDraw::point

(PECL gmagick >= Unknown)

GmagickDraw::point — Draws a point

### 说明

public function GmagickDraw::point(float `$x`, float `$y`): GmagickDraw

Draws a point using the current stroke color and stroke thickness at the specified coordinates.

### 参数

`x`
  target x coordinate
`y`
  target y coordinate

### 返回值

The GmagickDraw object.

# GmagickDraw::polygon

(PECL gmagick >= Unknown)

GmagickDraw::polygon — Draws a polygon

### 说明

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.

### 参数

`coordinates`
  coordinate array

### 返回值

The GmagickDraw object.

# GmagickDraw::polyline

(PECL gmagick >= Unknown)

GmagickDraw::polyline — Draws a polyline

### 说明

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.

### 参数

`coordinate_array`
  The array of coordinates

### 返回值

The GmagickDraw object.

# GmagickDraw::rectangle

(PECL gmagick >= Unknown)

GmagickDraw::rectangle — Draws a rectangle

### 说明

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.

### 参数

`x1`
  x ordinate of first coordinate
`y1`
  y ordinate of first coordinate
`x2`
  x ordinate of second coordinate
`y2`
  y ordinate of second coordinate

### 返回值

The GmagickDraw object.

# GmagickDraw::rotate

(PECL gmagick >= Unknown)

GmagickDraw::rotate — Applies the specified rotation to the current coordinate space

### 说明

public function GmagickDraw::rotate(float `$degrees`): GmagickDraw

Applies the specified rotation to the current coordinate space.

### 参数

`degrees`
  degrees of rotation

### 返回值

The GmagickDraw object.

# GmagickDraw::roundrectangle

(PECL gmagick >= Unknown)

GmagickDraw::roundrectangle — Draws a rounded rectangle

### 说明

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.

### 参数

`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

### 返回值

The GmagickDraw object.

# GmagickDraw::scale

(PECL gmagick >= Unknown)

GmagickDraw::scale — Adjusts the scaling factor

### 说明

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.

### 参数

`x`
  horizontal scale factor
`y`
  vertical scale factor

### 返回值

The GmagickDraw object.

# GmagickDraw::setfillcolor

(PECL gmagick >= Unknown)

GmagickDraw::setfillcolor — Sets the fill color to be used for drawing filled objects

### 说明

public function GmagickDraw::setfillcolor(mixed `$color`): GmagickDraw

Sets the fill color to be used for drawing filled objects.

### 参数

`color`
  GmagickPixel or string indicating color to use for filling.

### 返回值

The GmagickDraw object on success.

# GmagickDraw::setfillopacity

(PECL gmagick >= Unknown)

GmagickDraw::setfillopacity — The setfillopacity purpose

### 说明

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.

### 参数

`fill_opacity`
  Fill opacity

### 返回值

The GmagickDraw object.

# GmagickDraw::setfont

(PECL gmagick >= Unknown)

GmagickDraw::setfont — Sets the fully-specified font to use when annotating with text

### 说明

public function GmagickDraw::setfont(string `$font`): GmagickDraw

Sets the fully-specified font to use when annotating with text

### 参数

`font`
  font name

### 返回值

The GmagickDraw object.

# GmagickDraw::setfontsize

(PECL gmagick >= Unknown)

GmagickDraw::setfontsize — Sets the font pointsize to use when annotating with text

### 说明

public function GmagickDraw::setfontsize(float `$pointsize`): GmagickDraw

Sets the font pointsize to use when annotating with text.

### 参数

`pointsize`
  Text pointsize

### 返回值

The GmagickDraw object.

# GmagickDraw::setfontstyle

(PECL gmagick >= Unknown)

GmagickDraw::setfontstyle — Sets the font style to use when annotating with text

### 说明

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.

### 参数

`style`
  Font style (NormalStyle, ItalicStyle, ObliqueStyle, AnyStyle)

### 返回值

The GmagickDraw object.

# GmagickDraw::setfontweight

(PECL gmagick >= Unknown)

GmagickDraw::setfontweight — Sets the font weight

### 说明

public function GmagickDraw::setfontweight(int `$weight`): GmagickDraw

Sets the font weight to use when annotating with text.

### 参数

`weight`
  Font weight (valid range 100-900)

### 返回值

The GmagickDraw object.

# GmagickDraw::setstrokecolor

(PECL gmagick >= Unknown)

GmagickDraw::setstrokecolor — Sets the color used for stroking object outlines

### 说明

public function GmagickDraw::setstrokecolor(mixed `$color`): GmagickDraw

Sets the color used for stroking object outlines.

### 参数

`color`
  GmagickPixel or string representing the color for the stroke.

### 返回值

The GmagickDraw object on success.

# GmagickDraw::setstrokeopacity

(PECL gmagick >= Unknown)

GmagickDraw::setstrokeopacity — Specifies the opacity of stroked object outlines

### 说明

public function GmagickDraw::setstrokeopacity(float `$stroke_opacity`): GmagickDraw

Specifies the opacity of stroked object outlines.

### 参数

`stroke_opacity`
  Stroke opacity. The value 1.0 is opaque.

### 返回值

The GmagickDraw object.

# GmagickDraw::setstrokewidth

(PECL gmagick >= Unknown)

GmagickDraw::setstrokewidth — Sets the width of the stroke used to draw object outlines

### 说明

public function GmagickDraw::setstrokewidth(float `$width`): GmagickDraw

Sets the width of the stroke used to draw object outlines

### 参数

`width`
  Stroke width

### 返回值

The GmagickDraw object.

# GmagickDraw::settextdecoration

(PECL gmagick >= Unknown)

GmagickDraw::settextdecoration — Specifies a decoration

### 说明

public function GmagickDraw::settextdecoration(int `$decoration`): GmagickDraw

Specifies a decoration to be applied when annotating with text.

### 参数

`int`
  Text decoration. One of NoDecoration, UnderlineDecoration, OverlineDecoration, or LineThroughDecoration

### 返回值

The GmagickDraw object.

# GmagickDraw::settextencoding

(PECL gmagick >= Unknown)

GmagickDraw::settextencoding — Specifies the text code set

### 说明

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.

### 参数

`encoding`
  Character string specifying text encoding

### 返回值

The GmagickDraw object.

## 目录

- 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)

## 简介

## 类摘要

class GmagickPixel {
/* 方法 */
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 — The GmagickPixel constructor

### 说明

public function GmagickPixel::__construct(string `$color` = ?)

Constructs an GmagickPixel object. If a color is specified, the object is constructed and then initialised with that color before being returned.

### 参数

`color`
  The optional color string to use as the initial value of this object.

# GmagickPixel::getcolor

(PECL gmagick >= Unknown)

GmagickPixel::getcolor — Returns the color

### 说明

public function GmagickPixel::getcolor(bool `$as_array` = `false`, bool `$normalize_array` = `false`): mixed

Returns the color described by the GmagickPixel object, as a string or an array. If the color has an opacity channel set, this is provided as a fourth value in the list.

### 参数

`as_array`
  `true` to indicate return of array instead of string.
`normalize_array`
  `true` to normalize the color values.

### 返回值

A string or an array of channel values, each normalized if `true` is given as `normalize_array`. Throws GmagickPixelException on error.

# GmagickPixel::getcolorcount

(PECL gmagick >= Unknown)

GmagickPixel::getcolorcount — Returns the color count associated with this color

### 说明

public function GmagickPixel::getcolorcount(): int

Returns the color count associated with this color.

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function GmagickPixel::getcolorvalue(int `$color`): float

Retrieves the value of the color channel specified, as a floating-point number between 0 and 1.

### 参数

`color`
  The channel to check, specified as one of the Gmagick channel constants.

### 返回值

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

### 说明

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.).

### 参数

`color`
  The color definition to use in order to initialise the GmagickPixel object.

### 返回值

The GmagickPixel object.

# GmagickPixel::setcolorvalue

(PECL gmagick >= Unknown)

GmagickPixel::setcolorvalue — Sets the normalized value of one of the channels

### 说明

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.

### 参数

`color`
  One of the Gmagick channel color constants.
`value`
  The value to set this channel to, ranging from 0 to 1.

### 返回值

The GmagickPixel object.

## 目录

- GmagickPixel::__construct — The GmagickPixel constructor
- GmagickPixel::getcolor — Returns the color
- 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

- 安装/配置
  - 需求
  - 安装
- 预定义常量
- 示例
- 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 — 别名 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 — The GmagickPixel constructor
  - GmagickPixel::getcolor — Returns the color
  - 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

# 图像处理(ImageMagick)

# 简介

警告

此扩展是实验性的。 此扩展的行为，包括其函数的名称和围绕此扩展的相关文档都可能会在未来的 PHP 版本中发生变化而不另行通知。使用本扩展应自行承担风险。

Imagick 是用 ImageMagic API 来创建和修改图像的PHP官方扩展。

## 关于 ImageMagick

ImageMagick 是用来创建，编辑，合并位图图像的一套组件。 它能够用于读取，转换，写入多种不同格式的图像。 包含 DPX、EXR、GIF、JPEG、JPEG-2000、PDF、PhotoCD、PNG、Postscript、SVG 和 TIFF。

ImageMagick Studio LLC, a non-profit organization dedicated to making software imaging solutions freely available.

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置

## 需求

## 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.

## 安装

此 » PECL 扩展未与 PHP 捆绑。

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/imagick.

> 注意: 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.

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

Imagick configuration options
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
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

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`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.

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`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)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.0 or higher.
`imagick::COMPRESSION_DXT3` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.0 or higher.
`imagick::COMPRESSION_DXT5` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 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)
  此常量可用仅当Imagick编译于ImageMagick版本 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)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.4 or higher.
`imagick::EVALUATE_LOG` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.4 or higher.
`imagick::EVALUATE_THRESHOLD` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.4 or higher.
`imagick::EVALUATE_THRESHOLDBLACK` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.4 or higher.
`imagick::EVALUATE_THRESHOLDWHITE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.4 or higher.
`imagick::EVALUATE_GAUSSIANNOISE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.4 or higher.
`imagick::EVALUATE_IMPULSENOISE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.4 or higher.
`imagick::EVALUATE_LAPLACIANNOISE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.4 or higher.
`imagick::EVALUATE_MULTIPLICATIVENOISE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.4 or higher.
`imagick::EVALUATE_POISSONNOISE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.4 or higher.
`imagick::EVALUATE_UNIFORMNOISE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.4 or higher.
`imagick::EVALUATE_COSINE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.4 or higher.
`imagick::EVALUATE_SINE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.4 or higher.
`imagick::EVALUATE_ADDMODULUS` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 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)
  此常量可用仅当Imagick编译于ImageMagick版本 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)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.2 or higher.
`imagick::VIRTUALPIXELMETHOD_BLACK` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.2 or higher.
`imagick::VIRTUALPIXELMETHOD_GRAY` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.2 or higher.
`imagick::VIRTUALPIXELMETHOD_WHITE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.2 or higher.
`imagick::VIRTUALPIXELMETHOD_HORIZONTALTILE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.3 or higher.
`imagick::VIRTUALPIXELMETHOD_VERTICALTILE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 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)
  此常量可用仅当Imagick编译于ImageMagick版本 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. 此常量可用仅当Imagick编译于ImageMagick版本 6.7.8 or higher.

`LAYERMETHOD_*` constants

`imagick::LAYERMETHOD_UNDEFINED` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.2.9 or higher.
`imagick::LAYERMETHOD_COALESCE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.2.9 or higher.
`imagick::LAYERMETHOD_COMPAREANY` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.2.9 or higher.
`imagick::LAYERMETHOD_COMPARECLEAR` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.2.9 or higher.
`imagick::LAYERMETHOD_COMPAREOVERLAY` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.2.9 or higher.
`imagick::LAYERMETHOD_DISPOSE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.2.9 or higher.
`imagick::LAYERMETHOD_OPTIMIZE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.2.9 or higher.
`imagick::LAYERMETHOD_OPTIMIZEPLUS` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.2.9 or higher.
`imagick::LAYERMETHOD_OPTIMIZEIMAGE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.0 or higher.
`imagick::LAYERMETHOD_OPTIMIZETRANS` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.0 or higher.
`imagick::LAYERMETHOD_REMOVEDUPS` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.0 or higher.
`imagick::LAYERMETHOD_REMOVEZERO` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.0 or higher.
`imagick::LAYERMETHOD_COMPOSITE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.0 or higher.
`imagick::LAYERMETHOD_MERGE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.7 or higher.
`imagick::LAYERMETHOD_FLATTEN` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.7 or higher.
`imagick::LAYERMETHOD_MOSAIC` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.7 or higher.

`ORIENTATION_*` constants

`imagick::ORIENTATION_UNDEFINED` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.0 or higher.
`imagick::ORIENTATION_TOPLEFT` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.0 or higher.
`imagick::ORIENTATION_TOPRIGHT` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.0 or higher.
`imagick::ORIENTATION_BOTTOMRIGHT` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.0 or higher.
`imagick::ORIENTATION_BOTTOMLEFT` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.0 or higher.
`imagick::ORIENTATION_LEFTTOP` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.0 or higher.
`imagick::ORIENTATION_RIGHTTOP` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.0 or higher.
`imagick::ORIENTATION_RIGHTBOTTOM` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.0 or higher.
`imagick::ORIENTATION_LEFTBOTTOM` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.0 or higher.

`DISTORTION_*` constants

`imagick::DISTORTION_UNDEFINED` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.6 or higher.
`imagick::DISTORTION_AFFINE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.6 or higher.
`imagick::DISTORTION_AFFINEPROJECTION` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.6 or higher.
`imagick::DISTORTION_ARC` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.6 or higher.
`imagick::DISTORTION_BILINEAR` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.6 or higher.
`imagick::DISTORTION_PERSPECTIVE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.6 or higher.
`imagick::DISTORTION_PERSPECTIVEPROJECTION` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.6 or higher.
`imagick::DISTORTION_SCALEROTATETRANSLATE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.6 or higher.
`imagick::DISTORTION_POLYNOMIAL` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.
`imagick::DISTORTION_POLAR` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.
`imagick::DISTORTION_DEPOLAR` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.
`imagick::DISTORTION_BARREL` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.
`imagick::DISTORTION_BARRELINVERSE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.
`imagick::DISTORTION_SHEPARDS` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.
`imagick::DISTORTION_SENTINEL` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.

`ALPHACHANNEL_*` constants

`imagick::ALPHACHANNEL_ACTIVATE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.8 or higher.
`imagick::ALPHACHANNEL_DEACTIVATE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.8 or higher.
`imagick::ALPHACHANNEL_RESET` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.8 or higher.
`imagick::ALPHACHANNEL_SET` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.8 or higher.
`imagick::ALPHACHANNEL_UNDEFINED` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.
`imagick::ALPHACHANNEL_COPY` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.
`imagick::ALPHACHANNEL_EXTRACT` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.
`imagick::ALPHACHANNEL_OPAQUE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.
`imagick::ALPHACHANNEL_SHAPE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.
`imagick::ALPHACHANNEL_TRANSPARENT` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.
`imagick::ALPHACHANNEL_BACKGROUND` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.5.3 or higher.
`imagick::ALPHACHANNEL_REMOVE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.7.8 or higher.
`imagick::ALPHACHANNEL_ASSOCIATE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.9.0 or higher.
`imagick::ALPHACHANNEL_DISSOCIATE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.9.0 or higher.
`imagick::ALPHACHANNEL_ON` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 7.0.0 or higher.
`imagick::ALPHACHANNEL_OFF` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 7.0.0 or higher.
`imagick::ALPHACHANNEL_DISCRETE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 7.0.0 or higher.

`SPARSECOLORMETHOD_*` constants

`imagick::SPARSECOLORMETHOD_UNDEFINED` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.
`imagick::SPARSECOLORMETHOD_BARYCENTRIC` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.
`imagick::SPARSECOLORMETHOD_BILINEAR` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.
`imagick::SPARSECOLORMETHOD_POLYNOMIAL` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.
`imagick::SPARSECOLORMETHOD_SPEPARDS` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.
`imagick::SPARSECOLORMETHOD_VORONOI` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.

`FUNCTION_*` constants

`imagick::FUNCTION_UNDEFINED` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.9 or higher.
`imagick::FUNCTION_POLYNOMIAL` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.9 or higher.
`imagick::FUNCTION_SINUSOID` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.9 or higher.

`INTERPOLATE_*` constants

`imagick::INTERPOLATE_UNDEFINED` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.2 or higher.
`imagick::INTERPOLATE_AVERAGE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.2 or higher.
`imagick::INTERPOLATE_BICUBIC` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.2 or higher.
`imagick::INTERPOLATE_BILINEAR` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.2 or higher.
`imagick::INTERPOLATE_FILTER` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.2 or higher.
`imagick::INTERPOLATE_INTEGER` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.2 or higher.
`imagick::INTERPOLATE_MESH` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.2 or higher.
`imagick::INTERPOLATE_NEARESTNEIGHBOR` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.2 or higher.
`imagick::INTERPOLATE_SPLINE` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.3.4 or higher.

`DITHERMETHOD_*` constants

`imagick::DITHERMETHOD_UNDEFINED` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.
`imagick::DITHERMETHOD_NO` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.
`imagick::DITHERMETHOD_RIEMERSMA` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.
`imagick::DITHERMETHOD_FLOYDSTEINBERG` (int)
  此常量可用仅当Imagick编译于ImageMagick版本 6.4.6 or higher.

# 示例

## 目录

- 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:

示例 #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:

示例 #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 overlayed on a canvas.

示例 #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 overlayed 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;
    ?>

以上示例的输出类似于：

This example illustrates how to use fill patterns during drawing.

示例 #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;
    ?>

以上示例的输出类似于：

Working with animated GIF images

示例 #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

示例 #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;
    ?>

以上示例的输出类似于：

# The Imagick class

(PECL imagick 2, PECL imagick 3)

## 类摘要

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

### 说明

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. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

`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`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channel constants using bitwise operators. 缺省为`Imagick::CHANNEL_DEFAULT`. 参考此 通道常数列表

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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;

    ?>

以上示例的输出类似于：

### 参见

- 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

### 说明

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. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

> 注意: 参数 `bestfit` 的特性在 Imagick 3.0.0 中已改变。在此版本以前，当目标尺寸设为 400x400 时，原尺寸为 200x150 的图像将不会被改变。自 Imagick 3.0.0 起，源图像将会被放大到 400x300 因为这将更好的适合目标尺寸。当使用参数 `bestfit` 时，必须同时给出宽度和高度。

### 参数

`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.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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;
    ?>

### 参见

- Imagick::chopImage() - Removes a region of an image and trims
- Imagick::cropImage() - 截图图片的一块区域
- 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

### 说明

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. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

`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`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channel constants using bitwise operators. 缺省为`Imagick::CHANNEL_DEFAULT`. 参考此 通道常数列表

### 返回值

成功时返回 `true`。

### 示例

示例 #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;
    ?>

### 参见

- 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

### 说明

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.

### 参数

`width`

  Width of the local neighborhood.

`height`

  Height of the local neighborhood.

`offset`

  The mean offset

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`source`

  The source Imagick object

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::addNoiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::addNoiseImage — Adds random noise to the image

### 说明

public function Imagick::addNoiseImage(int `$noise_type`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Adds random noise to the image.

### 参数

`noise_type`

  The type of the noise. Refer to this list of noise constants.

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channel constants using bitwise operators. 缺省为`Imagick::CHANNEL_DEFAULT`. 参考此 通道常数列表

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function Imagick::affineTransformImage(ImagickDraw `$matrix`): bool

Transforms an image as dictated by the affine matrix.

### 参数

`matrix`

  The affine matrix

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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. 此方法在Imagick基于ImageMagick 6.3.6以上版本编译时可用。

### 参数

`x_server`

  X server address

### 返回值

成功时返回 `true`。

### 参见

- Imagick::displayImage() - Displays an image

# Imagick::annotateImage

(PECL imagick 2, PECL imagick 3)

Imagick::annotateImage — Annotates an image with text

### 说明

public function Imagick::annotateImage(
ImagickDraw `$draw_settings`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): bool

Annotates an image with text.

### 参数

`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

### 返回值

成功时返回 `true`。

### 示例

示例 #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;

    ?>

### 参见

- 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

### 说明

public function Imagick::appendImages(bool `$stack`): Imagick

Append a set of images into one larger image.

### 参数

`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.

### 返回值

Returns Imagick instance on success.

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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;
    ?>

以上示例的输出类似于：

# Imagick::autoLevelImage

(PECL imagick 3 >= 3.3.0)

Imagick::autoLevelImage — Adjusts the levels of a particular image channel

### 说明

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.

### 参数

`channel`

  Which channel should the auto-levelling should be done on.

### 返回值

成功时返回 `true`。

### 示例

示例 #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

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

public function Imagick::averageImages(): Imagick

Average a set of images.

### 参数

此函数没有参数。

### 返回值

Returns a new Imagick object on success.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::blackThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::blackThresholdImage — Forces all pixels below the threshold into black

### 说明

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.

### 参数

`threshold`

  The threshold below which everything turns black

### 返回值

成功时返回 `true`。

### 更新日志

版本 | 说明
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as a parameter. Previous versions allow only an ImagickPixel object.

### 示例

示例 #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

### 说明

public function Imagick::blueShiftImage(float `$factor` = 1.5): bool

Mutes the colors of the image to simulate a scene at nighttime in the moonlight.

### 参数

`factor`

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function Imagick::blurImage(float `$radius`, float `$sigma`, int `$channel` = ?): bool

Adds blur filter to image. Optional third parameter to blur a specific channel.

### 参数

`radius`

  Blur radius

`sigma`

  Standard deviation

`channel`

  The Channeltype constant. When not supplied, all channels are blurred.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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;

    ?>

### 参见

- 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

### 说明

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.

### 参数

`bordercolor`

  ImagickPixel object or a string containing the border color

`width`

  Border width

`height`

  Border height

### 返回值

成功时返回 `true`。

### 更新日志

版本 | 说明
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as the first parameter. Previous versions allow only an ImagickPixel object.

### 示例

示例 #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

### 说明

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 polynomical function to apply to the image.

### 参数

`brightness`

`contrast`

`channel`

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function Imagick::charcoalImage(float `$radius`, float `$sigma`): bool

Simulates a charcoal drawing.

### 参数

`radius`

  The radius of the Gaussian, in pixels, not counting the center pixel

`sigma`

  The standard deviation of the Gaussian, in pixels

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`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

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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;

    ?>

### 参见

- Imagick::cropImage() - 截图图片的一块区域

# Imagick::clampImage

(PECL imagick 3 >= 3.3.0)

Imagick::clampImage — Restricts the color range from 0 to the quantum depth.

### 说明

public function Imagick::clampImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Restricts the color range from 0 to the quantum depth.

### 参数

`channel`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# Imagick::clear

(PECL imagick 2, PECL imagick 3)

Imagick::clear — Clears all resources associated to Imagick object

### 说明

public function Imagick::clear(): bool

Clears all resources associated to Imagick object

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

# Imagick::clipImage

(PECL imagick 2, PECL imagick 3)

Imagick::clipImage — Clips along the first path from the 8BIM profile

### 说明

public function Imagick::clipImage(): bool

Clips along the first path from the 8BIM profile, if present.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::clipImagePath

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::clipImagePath — Clips along the named paths from the 8BIM profile, if present

### 说明

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.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`pathname`

`inside`

### 返回值

# Imagick::clipPathImage

(PECL imagick 2, PECL imagick 3)

Imagick::clipPathImage — Clips along the named paths from the 8BIM profile

### 说明

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.

### 参数

`pathname`

  The name of the path

`inside`

  If `true` later operations take effect inside clipping path. Otherwise later operations take effect outside clipping path.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::clone

(PECL imagick 2, PECL imagick 3)

Imagick::clone — Makes an exact copy of the Imagick object

### 说明

public function Imagick::clone(): Imagick

Makes an exact copy of the Imagick object.

警告

This function has been DEPRECATED as of imagick 3.1.0 in favour of using the clone keyword.

### 参数

此函数没有参数。

### 返回值

A copy of the Imagick object is returned.

### 更新日志

版本 | 说明
--- | ---
PECL imagick 3.1.0 | The method was deprecated in favour of the clone keyword.

### 示例

示例 #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

### 说明

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. 此方法在Imagick基于ImageMagick 6.3.6以上版本编译时可用。

### 参数

`lookup_table`

  Imagick object containing the color lookup table

`channel`

  The Channeltype constant. When not supplied, default channels are replaced.

### 返回值

成功时返回 `true`。

### 示例

示例 #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');
    ?>

### 参见

- 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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns a new Imagick object on success.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::colorFloodfillImage

(PECL imagick 2, PECL imagick 3)

Imagick::colorFloodfillImage — Changes the color value of any pixel that matches target

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

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.

### 参数

`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

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 更新日志

版本 | 说明
--- | ---
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

### 说明

public function Imagick::colorizeImage(mixed `$colorize`, mixed `$opacity`, bool `$legacy` = `false`): bool

Blends the fill color with each pixel in the image.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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

### 说明

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)

### 参数

`color_matrix`

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::commentImage

(PECL imagick 2, PECL imagick 3)

Imagick::commentImage — Adds a comment to your image

### 说明

public function Imagick::commentImage(string `$comment`): bool

Adds a comment to your image.

### 参数

`comment`

  The comment to add

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public function Imagick::compareImageChannels(Imagick `$image`, int `$channelType`, int `$metricType`): array

Compares one or more images and returns the difference image.

### 参数

`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.

### 返回值

Array consisting of `new_wand` and `distortion`.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::compareImageLayers

(PECL imagick 2, PECL imagick 3)

Imagick::compareImageLayers — Returns the maximum bounding region between images

### 说明

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. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

`method`

  One of the layer method constants.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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 */
    ?>

### 参见

- Imagick::optimizeImageLayers() - Removes repeated portions of images to optimize
- Imagick::writeImages() - Writes an image or image sequence
- Imagick::writeImage() - 把图片写入指定的文件

# Imagick::compareImages

(PECL imagick 2, PECL imagick 3)

Imagick::compareImages — Compares an image to a reconstructed image

### 说明

public function Imagick::compareImages(Imagick `$compare`, int `$metric`): array

Returns an array containing a reconstructed image and the difference between images.

### 参数

`compare`

  An image to compare to.

`metric`

  Provide a valid metric type constant. Refer to this list of metric constants.

### 返回值

Returns an array containing a reconstructed image and the difference between images.

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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 — 把一张图合并到一张图

### 说明

public function Imagick::compositeImage(
Imagick `$composite_object`,
int `$composite`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

以指定的偏移量（offset）将一幅图像合成到另一幅图像上。组合算法所需的任何额外参数都应传递给 setImageArtifact，其中“compose:args”作为第一个参数，数据作为第二个参数。

### 参数

`composite_object`

  用于合并的图片的Imagick对象

`composite`

  合并操作，定义操作常量。 具体请查看 合并操作常量列表

`x`

  相对图像顶点左上位置（0,0）的横坐标

`y`

  相对图像顶点左上位置（0,0）的纵坐标

`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）可以参考这个列表 通道常量列表.

### 返回值

成功时返回 `true`。

### 示例

示例 #1 使用 Imagick::compositeImage():

使用“mathematics”组合方法合成两个图像

    <?php

    // 等同于运行命令
    // 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");

    ?>

### 参见

- Imagick::setImageArtifact() - Set image artifact

# Imagick::__construct

(PECL imagick 2, PECL imagick 3)

Imagick::__construct — The Imagick constructor

### 说明

public function Imagick::__construct(mixed `$files` = ?)

Creates an Imagick instance for a specified image or set of images.

### 参数

`files`

  The path to an image to load or an array of paths. Paths can include wildcards for file names, or can be URLs.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::contrastImage

(PECL imagick 2, PECL imagick 3)

Imagick::contrastImage — Change the contrast of the image

### 说明

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.

### 参数

`sharpen`

  The sharpen value

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

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. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

`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.

### 返回值

成功时返回 `true`。

# Imagick::convolveImage

(PECL imagick 2, PECL imagick 3)

Imagick::convolveImage — Applies a custom convolution kernel to the image

### 说明

public function Imagick::convolveImage(array `$kernel`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Applies a custom convolution kernel to the image.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public function Imagick::count(int `$mode` = 0): int

Returns the number of images.

### 参数

`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.

### 返回值

Returns the number of images.

# Imagick::cropImage

(PECL imagick 2, PECL imagick 3)

Imagick::cropImage — 截图图片的一块区域

### 说明

public function Imagick::cropImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

截图图片的一块区域

### 参数

`width`

  截图的宽度

`height`

  截图的高度

`x`

  裁剪区域左上角的 X 轴坐标（以原图的左上角为原点）

`y`

  裁剪区域左上角的 X 轴坐标（以原图的左上角为原点）

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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 — 创建缩略图

### 说明

public function Imagick::cropThumbnailImage(int `$width`, int `$height`, bool `$legacy` = `false`): bool

首先将图片放大或者缩小，然后从图片的中间裁剪到指定的的大小。

### 参数

`width`

  缩略图的宽

`height`

  缩略图的高

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::current

(PECL imagick 2, PECL imagick 3)

Imagick::current — Returns a reference to the current Imagick object

### 说明

public function Imagick::current(): Imagick

Returns reference to the current imagick object with image pointer at the correct sequence.

### 参数

此函数没有参数。

### 返回值

Returns self on success.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::cycleColormapImage

(PECL imagick 2, PECL imagick 3)

Imagick::cycleColormapImage — Displaces an image's colormap

### 说明

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.

### 参数

`displace`

  The amount to displace the colormap.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::decipherImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::decipherImage — Deciphers an image

### 说明

public function Imagick::decipherImage(string `$passphrase`): bool

Deciphers image that has been enciphered before. The image must be enciphered using Imagick::encipherImage(). 此方法在Imagick基于ImageMagick 6.3.9以上版本编译时可用。

### 参数

`passphrase`

  The passphrase

### 返回值

成功时返回 `true`。

### 参见

- Imagick::encipherImage() - Enciphers an image

# Imagick::deconstructImages

(PECL imagick 2, PECL imagick 3)

Imagick::deconstructImages — Returns certain pixel differences between images

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns a new Imagick object on success.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::deleteImageArtifact

(PECL imagick 3)

Imagick::deleteImageArtifact — Delete image artifact

### 说明

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. 此方法在Imagick基于ImageMagick 6.5.7以上版本编译时可用。

### 参数

`artifact`

  The name of the artifact to delete

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 参见

- Imagick::setImageArtifact() - Set image artifact
- Imagick::getImageArtifact() - Get image artifact

# Imagick::deleteImageProperty

(PECL imagick 3 >= 3.3.0)

Imagick::deleteImageProperty — Deletes an image property

### 说明

public function Imagick::deleteImageProperty(string `$name`): bool

Deletes an image property.

### 参数

`name`

  The name of the property to delete.

### 返回值

成功时返回 `true`。

# Imagick::deskewImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.3.0)

Imagick::deskewImage — Removes skew from the image

### 说明

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. 此方法在Imagick基于ImageMagick 6.4.5以上版本编译时可用。

### 参数

`threshold`

  Deskew threshold

### 返回值

### 示例

示例 #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

### 说明

public function Imagick::despeckleImage(): bool

Reduces the speckle noise in an image while preserving the edges of the original image.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

# Imagick::displayImage

(PECL imagick 2, PECL imagick 3)

Imagick::displayImage — Displays an image

### 说明

public function Imagick::displayImage(string `$servername`): bool

This method displays an image on a X server.

### 参数

`servername`

  The X server name

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::displayImages

(PECL imagick 2, PECL imagick 3)

Imagick::displayImages — Displays an image or image sequence

### 说明

public function Imagick::displayImages(string `$servername`): bool

Displays an image or image sequence on a X server.

### 参数

`servername`

  The X server name

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::distortImage

(PECL imagick 2 >= 2.0.1, PECL imagick 3)

Imagick::distortImage — Distorts an image using various distortion methods

### 说明

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.

此方法在Imagick基于ImageMagick 6.3.6以上版本编译时可用。

### 参数

`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

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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);

    /* Ouput the image */
    header("Content-Type: image/png");
    echo $im;
    ?>

以上示例的输出类似于：

### 参见

- 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 — 把 ImagickDraw 对象渲染到当前图片上

### 说明

public function Imagick::drawImage(ImagickDraw `$draw`): bool

把 ImagickDraw 对象渲染到当前图片上。

### 参数

`draw`

  被渲染到图片上的 ImagickDraw 对象（在经过各种绘画操作之后的 ImagickDraw 对象）

### 返回值

成功时返回 `true`。

# Imagick::edgeImage

(PECL imagick 2, PECL imagick 3)

Imagick::edgeImage — Enhance edges within the image

### 说明

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.

### 参数

`radius`

  The radius of the operation.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

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.

### 参数

`radius`

  The radius of the effect

`sigma`

  The sigma of the effect

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

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() 此方法在Imagick基于ImageMagick 6.3.9以上版本编译时可用。

### 参数

`passphrase`

  The passphrase

### 返回值

成功时返回 `true`。

### 参见

- Imagick::decipherImage() - Deciphers an image

# Imagick::enhanceImage

(PECL imagick 2, PECL imagick 3)

Imagick::enhanceImage — Improves the quality of a noisy image

### 说明

public function Imagick::enhanceImage(): bool

Applies a digital filter that improves the quality of a noisy image.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public function Imagick::equalizeImage(): bool

Equalizes the image histogram.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public function Imagick::evaluateImage(int `$op`, float `$constant`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Applys 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.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

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)`. 此方法在Imagick基于ImageMagick 6.4.7以上版本编译时可用。

### 参数

`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

### 返回值

Returns an array containing the pixels values.

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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);
    ?>

以上示例会输出：

    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

### 说明

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. 此方法在Imagick基于ImageMagick 6.3.1以上版本编译时可用。

警告

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 betwen 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.

### 参数

`width`

  The new width

`height`

  The new height

`x`

  X position for the new size

`y`

  Y position for the new size

### 返回值

成功时返回 `true`。

### 参见

- Imagick::resizeImage() - Scales an image
- Imagick::thumbnailImage() - Changes the size of an image
- Imagick::cropImage() - 截图图片的一块区域

# Imagick::filter

(PECL imagick 3 >= 3.3.0)

Imagick::filter — Applies a custom convolution kernel to the image

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

public function Imagick::filter(ImagickKernel `$ImagickKernel`, int `$channel` = Imagick::CHANNEL_UNDEFINED): bool

Applies a custom convolution kernel to the image.

### 参数

`ImagickKernel`

  An instance of ImagickKernel that represents either a single kernel or a linked series of kernels.

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channel constants using bitwise operators. 缺省为`Imagick::CHANNEL_DEFAULT`. 参考此 通道常数列表

### 返回值

成功时返回 `true`。

### 示例

示例 #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

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

public function Imagick::flattenImages(): Imagick

Merges a sequence of images. This is useful for combining Photoshop layers into a single image.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::flipImage

(PECL imagick 2, PECL imagick 3)

Imagick::flipImage — Creates a vertical mirror image

### 说明

public function Imagick::flipImage(): bool

Creates a vertical mirror image by reflecting the pixels around the central x-axis.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #1 Imagick::flipImage()

    <?php
    function flipImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->flipImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### 参见

- 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

### 说明

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(). 此方法在Imagick基于ImageMagick 6.3.8以上版本编译时可用。

### 参数

`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.

`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`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channel constants using bitwise operators. 缺省为`Imagick::CHANNEL_DEFAULT`. 参考此 通道常数列表

### 返回值

成功时返回 `true`。

### 示例

示例 #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");
    ?>

以上示例的输出类似于：

# Imagick::flopImage

(PECL imagick 2, PECL imagick 3)

Imagick::flopImage — Creates a horizontal mirror image

### 说明

public function Imagick::flopImage(): bool

Creates a horizontal mirror image by reflecting the pixels around the central y-axis.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #1 Imagick::flopImage()

    <?php
    function flopImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->flopImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### 参见

- Imagick::flipimage() - Creates a vertical mirror image

# Imagick::forwardFourierTransformImage

(PECL imagick 3 >= 3.3.0)

Imagick::forwardFourierTransformImage — Implements the discrete Fourier transform (DFT)

### 说明

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.

### 参数

`magnitude`

  If true, return as magnitude / phase pair otherwise a real / imaginary image pair.

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`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

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 更新日志

版本 | 说明
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as the first parameter. Previous versions allow only an ImagickPixel object.

### 示例

示例 #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

### 说明

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

此方法在Imagick基于ImageMagick 6.4.9以上版本编译时可用。

### 参数

`function`

  Refer to this list of function constants

`arguments`

  Array of arguments to pass to this function.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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();
    ?>

以上示例的输出类似于：

示例 #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();
    ?>

以上示例的输出类似于：

示例 #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();
    ?>

以上示例的输出类似于：

# Imagick::fxImage

(PECL imagick 2, PECL imagick 3)

Imagick::fxImage — Evaluate expression for each pixel in the image

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public function Imagick::getColorspace(): int

Gets the global colorspace value. 此方法在Imagick基于ImageMagick 6.5.7以上版本编译时可用。

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function Imagick::getCompression(): int

Gets the object compression type.

### 参数

此函数没有参数。

### 返回值

Returns the compression constant

# Imagick::getCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::getCompressionQuality — Gets the object compression quality

### 说明

public function Imagick::getCompressionQuality(): int

Gets the object compression quality.

### 参数

此函数没有参数。

### 返回值

Returns integer describing the compression quality

# Imagick::getCopyright

(PECL imagick 2, PECL imagick 3)

Imagick::getCopyright — Returns the ImageMagick API copyright as a string

### 说明

public static function Imagick::getCopyright(): string

Returns the ImageMagick API copyright as a string.

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function Imagick::getFilename(): string

Returns the filename associated with an image sequence.

### 参数

此函数没有参数。

### 返回值

Returns a string on success.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getFont

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::getFont — Gets font

### 说明

public function Imagick::getFont(): string

Returns the objects font property. 此方法在Imagick基于ImageMagick 6.3.7以上版本编译时可用。

### 参数

此函数没有参数。

### 返回值

Returns the string containing the font name or `false` if not font is set.

### 参见

- 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

### 说明

public function Imagick::getFormat(): string

Returns the format of the Imagick object.

### 参数

此函数没有参数。

### 返回值

Returns the format of the image.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getGravity

(PECL imagick 2, PECL imagick 3)

Imagick::getGravity — Gets the gravity

### 说明

public function Imagick::getGravity(): int

Gets the global gravity property for the Imagick object. 此方法在Imagick基于ImageMagick 6.4.0以上版本编译时可用。

### 参数

此函数没有参数。

### 返回值

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

### 说明

public static function Imagick::getHomeURL(): string

Returns the ImageMagick home URL.

### 参数

此函数没有参数。

### 返回值

Returns a link to the imagemagick homepage.

# Imagick::getImage

(PECL imagick 2, PECL imagick 3)

Imagick::getImage — Returns a new Imagick object

### 说明

public function Imagick::getImage(): Imagick

Returns a new Imagick object with the current image sequence.

### 参数

此函数没有参数。

### 返回值

Returns a new Imagick object with the current image sequence.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageAlphaChannel

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageAlphaChannel — 检查图像是否有 alpha 通道

### 说明

public function Imagick::getImageAlphaChannel(): bool

返回图像是否有 alpha 通道。

### 参数

此函数没有参数。

### 返回值

如果图像具有 alpha 通道值，则返回 `true`，否则返回 `false`，即图像是 RGB 而不是 RGBA 或 CMYK 而不是 CMYKA。

### 错误／异常

错误时抛出 ImagickException。

### 更新日志

版本 | 说明
--- | ---
PECL imagick 3.6.0 | 现在返回 bool；之前返回 int。

# Imagick::getImageArtifact

(PECL imagick 3)

Imagick::getImageArtifact — Get image artifact

### 说明

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. 此方法在Imagick基于ImageMagick 6.5.7以上版本编译时可用。

### 参数

`artifact`

  The name of the artifact

### 返回值

Returns the artifact value on success.

### 错误／异常

错误时抛出 ImagickException。

### 参见

- Imagick::setImageArtifact() - Set image artifact
- Imagick::deleteImageArtifact() - Delete image artifact

# Imagick::getImageAttribute

(PECL imagick 2, PECL imagick 3)

Imagick::getImageAttribute — Returns a named attribute

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

public function Imagick::getImageAttribute(string `$key`): string

Returns a named attribute.

### 参数

`key`

  The key of the attribute to get.

### 返回值

# Imagick::getImageBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBackgroundColor — Returns the image background color

### 说明

public function Imagick::getImageBackgroundColor(): ImagickPixel

Returns the image background color.

### 参数

此函数没有参数。

### 返回值

Returns an ImagickPixel set to the background color of the image.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBlob — Returns the image sequence as a blob

### 说明

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().

### 参数

此函数没有参数。

### 返回值

Returns a string containing the image.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageBluePrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBluePrimary — Returns the chromaticy blue primary point

### 说明

public function Imagick::getImageBluePrimary(): array

Returns the chromaticity blue primary point for the image.

### 参数

`x`

  The chromaticity blue primary x-point.

`y`

  The chromaticity blue primary y-point.

### 返回值

Array consisting of "x" and "y" coordinates of point.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageBorderColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBorderColor — Returns the image border color

### 说明

public function Imagick::getImageBorderColor(): ImagickPixel

Returns the image border color.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageChannelDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelDepth — Gets the depth for a particular image channel

### 说明

public function Imagick::getImageChannelDepth(int `$channel`): int

Gets the depth for a particular image channel.

### 参数

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channel constants using bitwise operators. 缺省为`Imagick::CHANNEL_DEFAULT`. 参考此 通道常数列表

### 返回值

成功时返回 `true`。

# Imagick::getImageChannelDistortion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelDistortion — Compares image channels of an image to a reconstructed image

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageChannelDistortions

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageChannelDistortions — Gets channel distortions

### 说明

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 此方法在Imagick基于ImageMagick 6.4.4以上版本编译时可用。

### 参数

`reference`

  Imagick object containing the reference image

`metric`

  Refer to this list of metric type constants.

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channel constants using bitwise operators. 缺省为`Imagick::CHANNEL_DEFAULT`. 参考此 通道常数列表

### 返回值

Returns a float describing the channel distortion.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageChannelExtrema

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelExtrema — Gets the extrema for one or more image channels

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

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".

### 参数

`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.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageChannelKurtosis

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageChannelKurtosis — The getImageChannelKurtosis purpose

### 说明

public function Imagick::getImageChannelKurtosis(int `$channel` = Imagick::CHANNEL_DEFAULT): array

Get the kurtosis and skewness of a specific channel. 此方法在Imagick基于ImageMagick 6.4.9以上版本编译时可用。

### 参数

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channel constants using bitwise operators. 缺省为`Imagick::CHANNEL_DEFAULT`. 参考此 通道常数列表

### 返回值

Returns an array with `kurtosis` and `skewness` members.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageChannelMean

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelMean — Gets the mean and standard deviation

### 说明

public function Imagick::getImageChannelMean(int `$channel`): array

Gets the mean and standard deviation of one or more image channels.

### 参数

`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.

### 返回值

Returns an array with `"mean"` and `"standardDeviation"` members.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageChannelRange

(PECL imagick 2 >= 2.2.1, PECL imagick 3)

Imagick::getImageChannelRange — Gets channel range

### 说明

public function Imagick::getImageChannelRange(int `$channel`): array

Gets the range for one or more image channels. 此方法在Imagick基于ImageMagick 6.4.0以上版本编译时可用。

### 参数

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channel constants using bitwise operators. 缺省为`Imagick::CHANNEL_DEFAULT`. 参考此 通道常数列表

### 返回值

Returns an array containing minima and maxima values of the channel(s).

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageChannelStatistics

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelStatistics — Returns statistics for each channel in the image

### 说明

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.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

# Imagick::getImageClipMask

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageClipMask — Gets image clip mask

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

public function Imagick::getImageClipMask(): Imagick

Returns the image clip mask. The clip mask is an Imagick object containing the clip mask. 此方法在Imagick基于ImageMagick 6.3.6以上版本编译时可用。

### 参数

此函数没有参数。

### 返回值

Returns an Imagick object containing the clip mask.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageColormapColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColormapColor — Returns the color of the specified colormap index

### 说明

public function Imagick::getImageColormapColor(int `$index`): ImagickPixel

Returns the color of the specified colormap index.

### 参数

`index`

  The offset into the image colormap.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageColors

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColors — Gets the number of unique colors in the image

### 说明

public function Imagick::getImageColors(): int

Gets the number of unique colors in the image.

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function Imagick::getImageColorspace(): int

Gets the image colorspace.

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function Imagick::getImageCompose(): int

Returns the composite operator associated with the image.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

# Imagick::getImageCompression

(PECL imagick 3 >= 3.3.0)

Imagick::getImageCompression — Gets the current image's compression type

### 说明

public function Imagick::getImageCompression(): int

Gets the current image's compression type.

### 参数

此函数没有参数。

### 返回值

Returns the compression constant

# Imagick::getImageCompressionQuality

(PECL imagick 2 >= 2.2.2, PECL imagick 3)

Imagick::getImageCompressionQuality — Gets the current image's compression quality

### 说明

public function Imagick::getImageCompressionQuality(): int

Gets the current image's compression quality

### 参数

此函数没有参数。

### 返回值

Returns integer describing the images compression quality

# Imagick::getImageDelay

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDelay — Gets the image delay

### 说明

public function Imagick::getImageDelay(): int

Gets the image delay.

### 参数

此函数没有参数。

### 返回值

Returns the image delay.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDepth — Gets the image depth

### 说明

public function Imagick::getImageDepth(): int

Gets the image depth.

### 参数

此函数没有参数。

### 返回值

The image depth.

# Imagick::getImageDispose

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDispose — Gets the image disposal method

### 说明

public function Imagick::getImageDispose(): int

Gets the image disposal method.

### 参数

此函数没有参数。

### 返回值

Returns the dispose method on success.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageDistortion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDistortion — Compares an image to a reconstructed image

### 说明

public function Imagick::getImageDistortion(MagickWand `$reference`, int `$metric`): float

Compares an image to a reconstructed image and returns the specified distortion metric.

### 参数

`reference`

  Imagick object to compare to.

`metric`

  One of the metric type constants.

### 返回值

Returns the distortion metric used on the image (or the best guess thereof).

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageExtrema

(PECL imagick 2, PECL imagick 3)

Imagick::getImageExtrema — Gets the extrema for the image

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

public function Imagick::getImageExtrema(): array

Gets the extrema for the image. Returns an associative array with the keys "min" and "max".

### 参数

此函数没有参数。

### 返回值

Returns an associative array with the keys "min" and "max".

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageFilename

(PECL imagick 2, PECL imagick 3)

Imagick::getImageFilename — Returns the filename of a particular image in a sequence

### 说明

public function Imagick::getImageFilename(): string

Returns the filename of a particular image in a sequence.

### 参数

此函数没有参数。

### 返回值

Returns a string with the filename of the image.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageFormat

(PECL imagick 2, PECL imagick 3)

Imagick::getImageFormat — Returns the format of a particular image in a sequence

### 说明

public function Imagick::getImageFormat(): string

Returns the format of a particular image in a sequence.

### 参数

此函数没有参数。

### 返回值

Returns a string containing the image format on success.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageGamma

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGamma — Gets the image gamma

### 说明

public function Imagick::getImageGamma(): float

Gets the image gamma.

### 参数

此函数没有参数。

### 返回值

Returns the image gamma on success.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageGeometry

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGeometry — Gets the width and height as an associative array

### 说明

public function Imagick::getImageGeometry(): array

Returns the width and height as an associative array.

### 参数

此函数没有参数。

### 返回值

Returns an array with the width/height of the image.

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #1 Using Imagick::getImageGeometry()

    <?php
    $imagick = new Imagick();
    $imagick->newImage(100, 200, "black");
    print_r($imagick->getImageGeometry());
    ?>

以上示例会输出：

    Array
    (
        [width] => 100
        [height] => 200
    )

# Imagick::getImageGravity

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageGravity — Gets the image gravity

### 说明

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. 此方法在Imagick基于ImageMagick 6.4.4以上版本编译时可用。

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function Imagick::getImageGreenPrimary(): array

Returns the chromaticity green primary point. Returns an array with the keys "x" and "y".

### 参数

此函数没有参数。

### 返回值

Returns an array with the keys "x" and "y" on success, throws an ImagickException on failure.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageHeight

(PECL imagick 2, PECL imagick 3)

Imagick::getImageHeight — Returns the image height

### 说明

public function Imagick::getImageHeight(): int

Returns the image height.

### 参数

此函数没有参数。

### 返回值

Returns the image height in pixels.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageHistogram

(PECL imagick 2, PECL imagick 3)

Imagick::getImageHistogram — Gets the image histogram

### 说明

public function Imagick::getImageHistogram(): array

Returns the image histogram as an array of ImagickPixel objects.

### 参数

此函数没有参数。

### 返回值

Returns the image histogram as an array of ImagickPixel objects.

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

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().

### 参数

此函数没有参数。

### 返回值

Returns an integer containing the index of the image in the stack.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::getImageInterlaceScheme — Gets the image interlace scheme

### 说明

public function Imagick::getImageInterlaceScheme(): int

Gets the image interlace scheme.

### 参数

此函数没有参数。

### 返回值

Returns the interlace scheme as an integer on success. 错误时抛出 ImagickException。

# Imagick::getImageInterpolateMethod

(PECL imagick 2, PECL imagick 3)

Imagick::getImageInterpolateMethod — Returns the interpolation method

### 说明

public function Imagick::getImageInterpolateMethod(): int

Returns the interpolation method for the specified image. The method is one of the `Imagick::INTERPOLATE_*` constants.

### 参数

此函数没有参数。

### 返回值

Returns the interpolate method on success.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageIterations

(PECL imagick 2, PECL imagick 3)

Imagick::getImageIterations — Gets the image iterations

### 说明

public function Imagick::getImageIterations(): int

Gets the image iterations.

### 参数

此函数没有参数。

### 返回值

Returns the image iterations as an integer.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageLength

(PECL imagick 2, PECL imagick 3)

Imagick::getImageLength — Returns the image length in bytes

### 说明

public function Imagick::getImageLength(): int

Returns the image length in bytes

### 参数

此函数没有参数。

### 返回值

Returns an int containing the current image size.

### 示例

示例 #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

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

public function Imagick::getImageMatte(): bool

Returns `true` if the image has a matte channel otherwise false. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

# Imagick::getImageMatteColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageMatteColor — Returns the image matte color

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

public function Imagick::getImageMatteColor(): ImagickPixel

Returns the image matte color.

### 参数

此函数没有参数。

### 返回值

Returns ImagickPixel object on success.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageMimeType

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageMimeType — Returns the image mime-type

### 说明

public function Imagick::getImageMimeType(): string

Returns the image mime-type.

### 参数

此函数没有参数。

### 返回值

# Imagick::getImageOrientation

(PECL imagick 2, PECL imagick 3)

Imagick::getImageOrientation — Gets the image orientation

### 说明

public function Imagick::getImageOrientation(): int

Gets the image orientation. The return value is one of the orientation constants.

### 参数

此函数没有参数。

### 返回值

Returns an int on success.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImagePage

(PECL imagick 2, PECL imagick 3)

Imagick::getImagePage — Returns the page geometry

### 说明

public function Imagick::getImagePage(): array

Returns the page geometry associated with the image in an array with the keys "width", "height", "x", and "y".

### 参数

此函数没有参数。

### 返回值

Returns the page geometry associated with the image in an array with the keys "width", "height", "x", and "y".

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImagePixelColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImagePixelColor — Returns the color of the specified pixel

### 说明

public function Imagick::getImagePixelColor(int `$x`, int `$y`): ImagickPixel

Returns the color of the specified pixel.

### 参数

`x`

  The x-coordinate of the pixel

`y`

  The y-coordinate of the pixel

### 返回值

Returns an ImagickPixel instance for the color at the coordinates given.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProfile — Returns the named image profile

### 说明

public function Imagick::getImageProfile(string `$name`): string

Returns the named image profile.

### 参数

`name`

  The name of the profile to return.

### 返回值

Returns a string containing the image profile.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageProfiles

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProfiles — Returns the image profiles

### 说明

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. 此方法在Imagick基于ImageMagick 6.3.6以上版本编译时可用。

### 参数

`pattern`

  The pattern for profile names.

`include_values`

  Whether to return only profile names. If `false` then only profile names will be returned.

### 返回值

Returns an array containing the image profiles or profile names.

# Imagick::getImageProperties

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProperties — Returns the image properties

### 说明

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. 此方法在Imagick基于ImageMagick 6.3.6以上版本编译时可用。

### 参数

`pattern`

  The pattern for property names.

`include_values`

  Whether to return only property names. If `false` then only property names will be returned.

### 返回值

Returns an array containing the image properties or property names.

### 示例

示例 #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 trough 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

### 说明

public function Imagick::getImageProperty(string `$name`): string

Returns the named image property. 此方法在Imagick基于ImageMagick 6.3.2以上版本编译时可用。

### 参数

`name`

  name of the property (for example Exif:DateTime)

### 返回值

Returns a string containing the image property, false if a property with the given name does not exist.

### 示例

示例 #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');
    ?>

### 参见

- Imagick::setImageProperty() - Sets an image property

# Imagick::getImageRedPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRedPrimary — Returns the chromaticity red primary point

### 说明

public function Imagick::getImageRedPrimary(): array

Returns the chromaticity red primary point as an array with the keys "x" and "y".

### 参数

此函数没有参数。

### 返回值

Returns the chromaticity red primary point as an array with the keys "x" and "y". 错误时抛出 ImagickException。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageRegion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRegion — Extracts a region of the image

### 说明

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.

### 参数

`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.

### 返回值

Extracts a region of the image and returns it as a new wand.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageRenderingIntent

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRenderingIntent — Gets the image rendering intent

### 说明

public function Imagick::getImageRenderingIntent(): int

Gets the image rendering intent.

### 参数

此函数没有参数。

### 返回值

Returns the image rendering intent.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageResolution

(PECL imagick 2, PECL imagick 3)

Imagick::getImageResolution — 获取图像的x,y轴分辨率

### 说明

public function Imagick::getImageResolution(): array

获取图像的x,y轴分辨率

### 参数

此函数没有参数。

### 返回值

返回分辨率值的数组

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImagesBlob

(PECL imagick 2, PECL imagick 3)

Imagick::getImagesBlob — Returns all image sequences as a blob

### 说明

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().

### 参数

此函数没有参数。

### 返回值

Returns a string containing the images. On failure, throws ImagickException.

# Imagick::getImageScene

(PECL imagick 2, PECL imagick 3)

Imagick::getImageScene — Gets the image scene

### 说明

public function Imagick::getImageScene(): int

Gets the image scene.

### 参数

此函数没有参数。

### 返回值

Returns the image scene.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageSignature

(PECL imagick 2, PECL imagick 3)

Imagick::getImageSignature — Generates an SHA-256 message digest

### 说明

public function Imagick::getImageSignature(): string

Generates an SHA-256 message digest for the image pixel stream.

### 参数

此函数没有参数。

### 返回值

Returns a string containing the SHA-256 hash of the file.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageSize

(PECL imagick 2, PECL imagick 3)

Imagick::getImageSize — Returns the image length in bytes

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

public function Imagick::getImageSize(): int

Returns the image length in bytes. Deprecated in favour of Imagick::getImageLength()

### 参数

此函数没有参数。

### 返回值

Returns an int containing the current image size.

# Imagick::getImageTicksPerSecond

(PECL imagick 2, PECL imagick 3)

Imagick::getImageTicksPerSecond — Gets the image ticks-per-second

### 说明

public function Imagick::getImageTicksPerSecond(): int

Gets the image ticks-per-second.

### 参数

此函数没有参数。

### 返回值

Returns the image ticks-per-second.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageTotalInkDensity

(PECL imagick 2, PECL imagick 3)

Imagick::getImageTotalInkDensity — Gets the image total ink density

### 说明

public function Imagick::getImageTotalInkDensity(): float

Gets the image total ink density.

### 参数

此函数没有参数。

### 返回值

Returns the image total ink density of the image. 错误时抛出 ImagickException。

# Imagick::getImageType

(PECL imagick 2, PECL imagick 3)

Imagick::getImageType — Gets the potential image type

### 说明

public function Imagick::getImageType(): int

Gets the potential image type.

### 参数

此函数没有参数。

### 返回值

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`

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageUnits

(PECL imagick 2, PECL imagick 3)

Imagick::getImageUnits — 获取图像的分辨率单位

### 说明

public function Imagick::getImageUnits(): int

获取图像的分辨率单位。

### 参数

此函数没有参数。

### 返回值

返回分辨率的单位

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageVirtualPixelMethod

(PECL imagick 2, PECL imagick 3)

Imagick::getImageVirtualPixelMethod — Returns the virtual pixel method

### 说明

public function Imagick::getImageVirtualPixelMethod(): int

Returns the virtual pixel method for the specified image.

### 参数

此函数没有参数。

### 返回值

Returns the virtual pixel method on success.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageWhitePoint

(PECL imagick 2, PECL imagick 3)

Imagick::getImageWhitePoint — Returns the chromaticity white point

### 说明

public function Imagick::getImageWhitePoint(): array

Returns the chromaticity white point as an associative array with the keys "x" and "y".

### 参数

此函数没有参数。

### 返回值

Returns the chromaticity white point as an associative array with the keys "x" and "y".

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getImageWidth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageWidth — Returns the image width

### 说明

public function Imagick::getImageWidth(): int

Returns the image width.

### 参数

此函数没有参数。

### 返回值

Returns the image width.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::getInterlaceScheme — Gets the object interlace scheme

### 说明

public function Imagick::getInterlaceScheme(): int

Gets the object interlace scheme.

### 参数

此函数没有参数。

### 返回值

Gets the wand interlace scheme.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getIteratorIndex

(PECL imagick 2, PECL imagick 3)

Imagick::getIteratorIndex — Gets the index of the current active image

### 说明

public function Imagick::getIteratorIndex(): int

Returns the index of the current active image within the Imagick object. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

此函数没有参数。

### 返回值

Returns an integer containing the index of the image in the stack.

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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();
    ?>

### 参见

- 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

### 说明

public function Imagick::getNumberImages(): int

Returns the number of images associated with Imagick object.

### 参数

此函数没有参数。

### 返回值

Returns the number of images associated with Imagick object.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getOption

(PECL imagick 2, PECL imagick 3)

Imagick::getOption — Returns a value associated with the specified key

### 说明

public function Imagick::getOption(string `$key`): string

Returns a value associated within the object for the specified key.

### 参数

`key`

  The name of the option

### 返回值

Returns a value associated with a wand and the specified key.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getPackageName

(PECL imagick 2, PECL imagick 3)

Imagick::getPackageName — Returns the ImageMagick package name

### 说明

public static function Imagick::getPackageName(): string

Returns the ImageMagick package name.

### 参数

此函数没有参数。

### 返回值

Returns the ImageMagick package name as a string.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getPage

(PECL imagick 2, PECL imagick 3)

Imagick::getPage — Returns the page geometry

### 说明

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".

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function Imagick::getPixelIterator(): ImagickPixelIterator

Returns a MagickPixelIterator.

### 参数

此函数没有参数。

### 返回值

Returns an ImagickPixelIterator on success.

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public function Imagick::getPixelRegionIterator(
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): ImagickPixelIterator

Get an ImagickPixelIterator for an image section.

### 参数

`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.

### 返回值

Returns an ImagickPixelIterator for an image section.

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public function Imagick::getPointSize(): float

Returns the objects point size property. 此方法在Imagick基于ImageMagick 6.3.7以上版本编译时可用。

### 参数

此函数没有参数。

### 返回值

Returns a float containing the point size.

### 参见

- Imagick::setPointSize() - Sets point size

# Imagick::getQuantum

(PECL imagick 3 >= 3.3.0)

Imagick::getQuantum — Returns the ImageMagick quantum range

### 说明

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.

### 参数

此函数没有参数。

### 返回值

# Imagick::getQuantumDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getQuantumDepth — Gets the quantum depth

### 说明

public static function Imagick::getQuantumDepth(): array

Returns the Imagick quantum depth.

### 参数

此函数没有参数。

### 返回值

Returns an array with `"quantumDepthLong"` and `"quantumDepthString"` members.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getQuantumRange

(PECL imagick 2, PECL imagick 3)

Imagick::getQuantumRange — Returns the Imagick quantum range

### 说明

public static function Imagick::getQuantumRange(): array

Returns the quantum range for the Imagick instance.

### 参数

此函数没有参数。

### 返回值

Returns an associative array containing the quantum range as an int (`"quantumRangeLong"`) and as a string (`"quantumRangeString"`).

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::getRegistry — Get a StringRegistry entry

### 说明

public static function Imagick::getRegistry(string `$key`): string

Get the StringRegistry entry for the named key or false if not set.

### 参数

`key`

  The entry to get.

### 返回值

# Imagick::getReleaseDate

(PECL imagick 2, PECL imagick 3)

Imagick::getReleaseDate — Returns the ImageMagick release date

### 说明

public static function Imagick::getReleaseDate(): string

Returns the ImageMagick release date as a string.

### 参数

此函数没有参数。

### 返回值

Returns the ImageMagick release date as a string.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getResource

(PECL imagick 2, PECL imagick 3)

Imagick::getResource — Returns the specified resource's memory usage

### 说明

public static function Imagick::getResource(int `$type`): int

Returns the specified resource's memory usage in megabytes.

### 参数

`type`

  Refer to the list of resourcetype constants.

### 返回值

Returns the specified resource's memory usage in megabytes.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getResourceLimit

(PECL imagick 2, PECL imagick 3)

Imagick::getResourceLimit — Returns the specified resource limit

### 说明

public static function Imagick::getResourceLimit(int `$type`): int

Returns the specified resource limit.

### 参数

`type`

  One of the resourcetype constants.

### 返回值

Returns the specified resource limit. The unit depends on the type of the resource being limited.

### 错误／异常

错误时抛出 ImagickException。

### 参见

- 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

### 说明

public function Imagick::getSamplingFactors(): array

Gets the horizontal and vertical sampling factor.

### 参数

此函数没有参数。

### 返回值

Returns an associative array with the horizontal and vertical sampling factors of the image.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getSize

(PECL imagick 2, PECL imagick 3)

Imagick::getSize — Returns the size associated with the Imagick object

### 说明

public function Imagick::getSize(): array

Get the size in pixels associated with the Imagick object, previously set by Imagick::setSize().

> 注意:

> 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().

### 参数

此函数没有参数。

### 返回值

Returns the size associated with the Imagick object as an array with the keys "columns" and "rows".

### 示例

示例 #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();
    ?>

以上示例会输出：

    Array
    (
        [columns] => 200
        [rows] => 400
    )
    400x800

# Imagick::getSizeOffset

(PECL imagick 2, PECL imagick 3)

Imagick::getSizeOffset — Returns the size offset

### 说明

public function Imagick::getSizeOffset(): int

Returns the size offset associated with the Imagick object. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

此函数没有参数。

### 返回值

Returns the size offset associated with the Imagick object.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::getVersion

(PECL imagick 2, PECL imagick 3)

Imagick::getVersion — Returns the ImageMagick API version

### 说明

public static function Imagick::getVersion(): array

Returns the ImageMagick API version as a string and as a number.

### 参数

此函数没有参数。

### 返回值

Returns the ImageMagick API version as a string and as a number.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::haldClutImage

(PECL imagick 3)

Imagick::haldClutImage — Replaces colors in the image

### 说明

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.

### 参数

`clut`

  Imagick object containing the Hald lookup image.

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channel constants using bitwise operators. 缺省为`Imagick::CHANNEL_DEFAULT`. 参考此 通道常数列表

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public function Imagick::hasNextImage(): bool

Returns `true` if the object has more images when traversing the list in the forward direction.

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function Imagick::hasPreviousImage(): bool

Returns `true` if the object has more images when traversing the list in the reverse direction

### 参数

此函数没有参数。

### 返回值

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

### 说明

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.

### 参数

`embedText`

  A string containing formatting sequences e.g. "Trim box: %@ number of unique colors: %k".

### 返回值

Returns format 或者在失败时返回 `false`.

### 示例

示例 #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

### 说明

public function Imagick::identifyImage(bool `$appendRawOutput` = `false`): array

Identifies an image and returns the attributes. Attributes include the image width, height, size, and others.

### 参数

`appendRawOutput`

  If `true` then the raw output is appended to the array.

### 返回值

Identifies an image and returns the attributes. Attributes include the image width, height, size, and others.

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

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.

### 参数

`radius`

  The radius of the implode

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

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. 此方法在Imagick基于ImageMagick 6.4.5以上版本编译时可用。

### 参数

`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

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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;

    ?>

以上示例的输出类似于：

# Imagick::inverseFourierTransformImage

(PECL imagick 3 >= 3.3.0)

Imagick::inverseFourierTransformImage — Implements the inverse discrete Fourier transform (DFT)

### 说明

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.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`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.

### 返回值

成功时返回 `true`。

# Imagick::labelImage

(PECL imagick 2, PECL imagick 3)

Imagick::labelImage — Adds a label to an image

### 说明

public function Imagick::labelImage(string `$label`): bool

Adds a label to an image.

### 参数

`label`

  The label to add

### 返回值

成功时返回 `true`。

# Imagick::levelImage

(PECL imagick 2, PECL imagick 3)

Imagick::levelImage — Adjusts the levels of an image

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public function Imagick::linearStretchImage(float `$blackPoint`, float `$whitePoint`): bool

Stretches with saturation the image intensity.

### 参数

`blackPoint`

  The image black point

`whitePoint`

  The image white point

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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. 此方法在Imagick基于ImageMagick 6.3.9以上版本编译时可用。

### 参数

`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.

### 返回值

成功时返回 `true`。

### 参见

- Imagick::resizeImage() - Scales an image

# Imagick::listRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::listRegistry — List all the registry settings

### 说明

public static function Imagick::listRegistry(): array

List all the registry settings. Returns an array of all the key/value pairs in the registry

### 参数

此函数没有参数。

### 返回值

An array containing the key/values from the registry.

# Imagick::magnifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::magnifyImage — Scales an image proportionally 2x

### 说明

public function Imagick::magnifyImage(): bool

Is a convenience method that scales an image proportionally to twice its original size.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

public function Imagick::mapImage(Imagick `$map`, bool `$dither`): bool

### 参数

`map`

`dither`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::matteFloodfillImage

(PECL imagick 2, PECL imagick 3)

Imagick::matteFloodfillImage — Changes the transparency value of a color

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 更新日志

版本 | 说明
--- | ---
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

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

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.

### 参数

`radius`

  The radius of the pixel neighborhood.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

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. 此方法在Imagick基于ImageMagick 6.3.7以上版本编译时可用。

### 参数

`layer_method`

  One of the `Imagick::LAYERMETHOD_*` constants

### 返回值

Returns an Imagick object containing the merged image.

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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();
    }

    ?>

### 参见

- 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

### 说明

public function Imagick::minifyImage(): bool

Is a convenience method that scales an image proportionally to one-half its original size

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

# Imagick::modulateImage

(PECL imagick 2, PECL imagick 3)

Imagick::modulateImage — Control the brightness, saturation, and hue

### 说明

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.

### 参数

`brightness`

`saturation`

`hue`

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`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.

### 返回值

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

### 说明

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.

### 参数

`number_frames`

  The number of in-between images to generate.

### 返回值

This method returns a new Imagick object on success. 错误时抛出 ImagickException。

# Imagick::morphology

(PECL imagick 3 >= 3.3.0)

Imagick::morphology — Applies a user supplied kernel to the image according to the given morphology method.

### 说明

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.

### 参数

`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`

### 返回值

成功时返回 `true`。

### 示例

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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();

    ?>

示例 #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

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

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.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

# Imagick::motionBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::motionBlurImage — Simulates motion blur

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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 — 创建一张图片

### 说明

public function Imagick::newImage(
int `$cols`,
int `$rows`,
mixed `$background`,
string `$format` = ?
): bool

创建一个 Imagick 图片对象，同时可以附带设置一个 ImagickPixel 值作为其背景色。

### 参数

`cols`

  新建图片对象列的值（宽多少像素）

`rows`

  新建图片对象行的值（高多少像素）

`background`

  新建图片独享的背景色

`format`

  图片格式。这个参数是在 Imagick 2.0.1 版本添加的。

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 更新日志

版本 | 说明
--- | ---
PECL imagick 2.1.0 | 现在可以似乎用了一个字符串作为颜色传入第三个参数。在此之前的版本只允许以一个 ImagickPixel 对象的形式传入。

### 示例

示例 #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

### 说明

public function Imagick::newPseudoImage(int `$columns`, int `$rows`, string `$pseudoString`): bool

Creates a new image using ImageMagick pseudo-formats.

### 参数

`columns`

  columns in the new image

`rows`

  rows in the new image

`pseudoString`

  string containing pseudo image definition.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public function Imagick::nextImage(): bool

Associates the next image in the image list with an Imagick object.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

# Imagick::normalizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::normalizeImage — Enhances the contrast of a color image

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`radius`

  The radius of the circular neighborhood.

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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. 此方法在Imagick基于ImageMagick 6.3.8以上版本编译时可用。

### 参数

`target`

  ImagickPixel object or a string containing the color to change

`fill`

  The replacement 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.

`invert`

  If `true` paints any pixel that does not match the target color.

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channel constants using bitwise operators. 缺省为`Imagick::CHANNEL_DEFAULT`. 参考此 通道常数列表

### 返回值

成功时返回 `true`。

# Imagick::optimizeImageLayers

(PECL imagick 2, PECL imagick 3)

Imagick::optimizeImageLayers — Removes repeated portions of images to optimize

### 说明

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. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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);
    ?>

### 参见

- Imagick::compareImageLayers() - Returns the maximum bounding region between images
- Imagick::writeImages() - Writes an image or image sequence
- Imagick::writeImage() - 把图片写入指定的文件

# Imagick::orderedPosterizeImage

(PECL imagick 2 >= 2.2.2, PECL imagick 3)

Imagick::orderedPosterizeImage — Performs an ordered dither

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

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. 此方法在Imagick基于ImageMagick 6.3.1以上版本编译时可用。

### 参数

`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.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

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.

### 参数

`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`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channel constants using bitwise operators. 缺省为`Imagick::CHANNEL_DEFAULT`. 参考此 通道常数列表

### 返回值

成功时返回 `true`。

# Imagick::paintOpaqueImage

(PECL imagick 2, PECL imagick 3)

Imagick::paintOpaqueImage — Change any pixel that matches color

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 更新日志

版本 | 说明
--- | ---
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

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

public function Imagick::paintTransparentImage(mixed `$target`, float `$alpha`, float `$fuzz`): bool

Changes any pixel that matches color with the color defined by fill.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 更新日志

版本 | 说明
--- | ---
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 — Fetch basic attributes about the image

### 说明

public function Imagick::pingImage(string `$filename`): bool

This method can be used to query image width, height, size, and format without reading the whole image in to memory.

### 参数

`filename`

  The filename to read the information from.

### 返回值

成功时返回 `true`。

# Imagick::pingImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::pingImageBlob — Quickly fetch attributes

### 说明

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. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

`image`

  A string containing the image.

### 返回值

成功时返回 `true`。

### 示例

示例 #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();
    ?>

### 参见

- Imagick::pingImage() - Fetch basic attributes about the image
- Imagick::pingImageFile() - Get basic image attributes in a lightweight manner
- Imagick::readImage() - Reads image from filename
- Imagick::readImageBlob() - 从二进制字符串里读取图片
- 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

### 说明

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. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

`filehandle`

  An open filehandle to the image.

`fileName`

  Optional filename for this image.

### 返回值

成功时返回 `true`。

### 示例

示例 #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);
    ?>

### 参见

- Imagick::pingImage() - Fetch basic attributes about the image
- Imagick::pingImageBlob() - Quickly fetch attributes
- Imagick::readImage() - Reads image from filename
- Imagick::readImageBlob() - 从二进制字符串里读取图片
- Imagick::readImageFile() - Reads image from open filehandle

# Imagick::polaroidImage

(PECL imagick 2, PECL imagick 3)

Imagick::polaroidImage — Simulates a Polaroid picture

### 说明

public function Imagick::polaroidImage(ImagickDraw `$properties`, float `$angle`): bool

Simulates a Polaroid picture. 此方法在Imagick基于ImageMagick 6.3.2以上版本编译时可用。

### 参数

`properties`

  The polaroid properties

`angle`

  The polaroid angle

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function Imagick::posterizeImage(int `$levels`, bool `$dither`): bool

Reduces the image to a limited number of color level.

### 参数

`levels`

`dither`

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`preview`

  Preview type. See Preview type constants

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::previousImage

(PECL imagick 2, PECL imagick 3)

Imagick::previousImage — Move to the previous image in the object

### 说明

public function Imagick::previousImage(): bool

Associates the previous image in an image list with the Imagick object.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

# Imagick::profileImage

(PECL imagick 2, PECL imagick 3)

Imagick::profileImage — Adds or removes a profile from an image

### 说明

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`.

### 参数

`name`
  The profile name.
`profile`
  The profile data. If `null`, the specified profile will be deleted.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::quantizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::quantizeImage — Analyzes the colors within a reference image

### 说明

public function Imagick::quantizeImage(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool

### 参数

`numberColors`

`colorspace`

`treedepth`

`dither`

`measureError`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public function Imagick::quantizeImages(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool

### 参数

`numberColors`

`colorspace`

`treedepth`

`dither`

`measureError`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::queryFontMetrics

(PECL imagick 2, PECL imagick 3)

Imagick::queryFontMetrics — Returns an array representing the font metrics

### 说明

public function Imagick::queryFontMetrics(ImagickDraw `$properties`, string `$text`, bool `$multiline` = ?): array

Returns a multi-dimensional array representing the font metrics.

### 参数

`properties`

  ImagickDraw object containing font properties

`text`

  The text

`multiline`

  Multiline parameter. If left empty it is autodetected

### 返回值

Returns a multi-dimensional array representing the font metrics.

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public static function Imagick::queryFonts(string `$pattern` = "*"): array

Returns the configured fonts.

### 参数

`pattern`

  The query pattern

### 返回值

Returns an array containing the configured fonts.

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public static function Imagick::queryFormats(string `$pattern` = "*"): array

Returns formats supported by Imagick.

### 参数

`pattern`

### 返回值

Returns an array containing the formats supported by Imagick.

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

public function Imagick::radialBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Radial blurs an image.

### 参数

`angle`

`channel`

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`width`

`height`

`x`

`y`

`raise`

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

`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.

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function Imagick::readImage(string `$filename`): bool

Reads image from filename

### 参数

`filename`

### 返回值

成功时返回 `true`。

# Imagick::readImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::readImageBlob — 从二进制字符串里读取图片

### 说明

public function Imagick::readImageBlob(string `$image`, string `$filename` = ?): bool

从二进制字符串里读取图片

### 参数

`image`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public function Imagick::readImageFile(resource `$filehandle`, string `$fileName` = `null`): bool

Reads image from open filehandle

### 参数

`filehandle`

`fileName`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::readimages

(PECL imagick 2, PECL imagick 3)

Imagick::readimages — Reads image from an array of filenames

### 说明

public function Imagick::readImages(array `$filenames`): bool

Reads image from an array of filenames. All the images are held in a single Imagick object.

### 参数

`filenames`

### 返回值

成功时返回 `true`。

# Imagick::recolorImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::recolorImage — Recolors image

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

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. 此方法在Imagick基于ImageMagick 6.3.6以上版本编译时可用。

### 参数

`matrix`

  The matrix containing the color values

### 返回值

成功时返回 `true`。

### 示例

示例 #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();
    }

    ?>

### 参见

- Imagick::displayImage() - Displays an image

# Imagick::reduceNoiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::reduceNoiseImage — Smooths the contours of an image

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

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.

### 参数

`radius`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

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. 此方法在Imagick基于ImageMagick 6.4.5以上版本编译时可用。

### 参数

`replacement`

  An Imagick object containing the replacement colors

`DITHER`

  Refer to this list of dither method constants

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::removeImage

(PECL imagick 2, PECL imagick 3)

Imagick::removeImage — Removes an image from the image list

### 说明

public function Imagick::removeImage(): bool

Removes an image from the image list.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::removeImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::removeImageProfile — Removes the named image profile and returns it

### 说明

public function Imagick::removeImageProfile(string `$name`): string

Removes the named image profile and returns it.

### 参数

`name`

### 返回值

Returns a string containing the profile of the image.

### 错误／异常

错误时抛出 ImagickException。

# Imagick::render

(PECL imagick 2, PECL imagick 3)

Imagick::render — Renders all preceding drawing commands

### 说明

public function Imagick::render(): bool

Renders all preceding drawing commands.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

# Imagick::resampleImage

(PECL imagick 2, PECL imagick 3)

Imagick::resampleImage — Resample image to desired resolution

### 说明

public function Imagick::resampleImage(
float `$x_resolution`,
float `$y_resolution`,
int `$filter`,
float `$blur`
): bool

Resample image to desired resolution.

### 参数

`x_resolution`

`y_resolution`

`filter`

`blur`

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function Imagick::resetImagePage(string `$page`): bool

The page definition as a string. The string is in format WxH+x+y. 此方法在Imagick基于ImageMagick 6.3.6以上版本编译时可用。

### 参数

`page`

  The page definition. For example `7168x5147+0+0`

### 返回值

成功时返回 `true`。

# Imagick::resizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::resizeImage — Scales an image

### 说明

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.

> 注意: 参数 `bestfit` 的特性在 Imagick 3.0.0 中已改变。在此版本以前，当目标尺寸设为 400x400 时，原尺寸为 200x150 的图像将不会被改变。自 Imagick 3.0.0 起，源图像将会被放大到 400x300 因为这将更好的适合目标尺寸。当使用参数 `bestfit` 时，必须同时给出宽度和高度。

### 参数

`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.

### 返回值

成功时返回 `true`。

### 更新日志

版本 | 说明
--- | ---
PECL imagick 2.1.0 | Added optional fit parameter. This method now supports proportional scaling. Pass zero as either parameter for proportional scaling.

### 示例

示例 #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

### 说明

public function Imagick::rollImage(int `$x`, int `$y`): bool

Offsets an image as defined by x and y.

### 参数

`x`

  The X offset.

`y`

  The Y offset.

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`background`

  The background color

`degrees`

  Rotation angle, in degrees. The rotation angle is interpreted as the number of degrees to rotate the image clockwise.

### 返回值

成功时返回 `true`。

### 更新日志

版本 | 说明
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as the first parameter. Previous versions allow only an ImagickPixel object.

### 示例

示例 #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

### 说明

public function Imagick::rotationalBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Rotational blurs an image.

### 参数

`angle`

  The angle to apply the blur over.

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channel constants using bitwise operators. 缺省为`Imagick::CHANNEL_DEFAULT`. 参考此 通道常数列表

### 返回值

成功时返回 `true`。

### 示例

示例 #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

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

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. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。 此方法在 Imagick 基于 ImageMagick 7.0.0 或以上版本编译时不可用。

### 参数

`x_rounding`

  x rounding

`y_rounding`

  y rounding

`stroke_width`

  stroke width

`displace`

  image displace

`size_correction`

  size correction

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`columns`

`rows`

### 返回值

成功时返回 `true`。

# Imagick::scaleImage

(PECL imagick 2, PECL imagick 3)

Imagick::scaleImage — Scales the size of an image

### 说明

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.

> 注意: 参数 `bestfit` 的特性在 Imagick 3.0.0 中已改变。在此版本以前，当目标尺寸设为 400x400 时，原尺寸为 200x150 的图像将不会被改变。自 Imagick 3.0.0 起，源图像将会被放大到 400x300 因为这将更好的适合目标尺寸。当使用参数 `bestfit` 时，必须同时给出宽度和高度。

### 参数

`columns`

`rows`

`bestfit`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 更新日志

版本 | 说明
--- | ---
PECL imagick 2.1.0 | Added optional fit parameter. This method now supports proportional scaling. Pass zero as either parameter for proportional scaling.

### 示例

示例 #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

### 说明

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. 此方法在Imagick基于ImageMagick 6.4.5以上版本编译时可用。

### 参数

`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.

### 返回值

### 示例

示例 #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

### 说明

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.

### 参数

`radius`

`sigma`

`threshold`

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channel constants using bitwise operators. 缺省为`Imagick::CHANNEL_DEFAULT`. 参考此 通道常数列表

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

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.

### 参数

`threshold`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public function Imagick::setBackgroundColor(mixed `$background`): bool

Sets the object's default background color.

### 参数

`background`

### 返回值

成功时返回 `true`。

### 更新日志

版本 | 说明
--- | ---
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

### 说明

public function Imagick::setColorspace(int `$COLORSPACE`): bool

Sets the global colorspace value for the object. 此方法在Imagick基于ImageMagick 6.5.7以上版本编译时可用。

### 参数

`COLORSPACE`

  One of the COLORSPACE constants

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setCompression

(PECL imagick 2, PECL imagick 3)

Imagick::setCompression — Sets the object's default compression type

### 说明

public function Imagick::setCompression(int `$compression`): bool

Sets the object's default compression type

### 参数

`compression`

  The compression type. See the Imagick::COMPRESSION_* constants.

### 返回值

成功时返回 `true`。

# Imagick::setCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::setCompressionQuality — Sets the object's default compression quality

### 说明

public function Imagick::setCompressionQuality(int `$quality`): bool

Sets the object's default compression quality.

警告

This method only works for new images e.g. those created through Imagick::newPseudoImage. For existing images you should use Imagick::setImageCompressionQuality().

### 参数

`quality`

  An int between 1 and 100, 1 = high compression, 100 low compression.

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function Imagick::setFilename(string `$filename`): bool

Sets the filename before you read or write an image file.

### 参数

`filename`

### 返回值

成功时返回 `true`。

# Imagick::setFirstIterator

(PECL imagick 2, PECL imagick 3)

Imagick::setFirstIterator — Sets the Imagick iterator to the first image

### 说明

public function Imagick::setFirstIterator(): bool

Sets the Imagick iterator to the first image.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

# Imagick::setFont

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setFont — Sets font

### 说明

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. 此方法在Imagick基于ImageMagick 6.3.7以上版本编译时可用。

### 参数

`font`

  Font name or a filename

### 返回值

成功时返回 `true`。

### 示例

示例 #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 */
    ?>

### 参见

- 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

### 说明

public function Imagick::setFormat(string `$format`): bool

Sets the format of the Imagick object.

### 参数

`format`

### 返回值

成功时返回 `true`。

# Imagick::setGravity

(PECL imagick 2 >= 2.2.0, PECL imagick 3)

Imagick::setGravity — Sets the gravity

### 说明

public function Imagick::setGravity(int `$gravity`): bool

Sets the global gravity property for the Imagick object. 此方法在Imagick基于ImageMagick 6.4.0以上版本编译时可用。

### 参数

`gravity`

  The gravity property. Refer to the list of gravity constants.

### 返回值

没有返回值。

# Imagick::setImage

(PECL imagick 2, PECL imagick 3)

Imagick::setImage — Replaces image in the object

### 说明

public function Imagick::setImage(Imagick `$replace`): bool

Replaces the current image sequence with the image from replace object.

### 参数

`replace`

  The replace Imagick object

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public function Imagick::setImageAlphaChannel(int `$mode`): bool

Activate or deactivate image alpha channel. The `mode` is one of the `Imagick::ALPHACHANNEL_*` constants. 此方法在Imagick基于ImageMagick 6.3.8以上版本编译时可用。

### 参数

`mode`

  One of the `Imagick::ALPHACHANNEL_*` constants

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 参见

- Imagick::setImageMatte() - Sets the image matte channel
- Imagick Alpha Channel Constants

# Imagick::setImageArtifact

(PECL imagick 3)

Imagick::setImageArtifact — Set image artifact

### 说明

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. 此方法在Imagick基于ImageMagick 6.5.7以上版本编译时可用。

### 参数

`artifact`

  The name of the artifact

`value`

  The value of the artifact

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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();
    }

    ?>

### 参见

- Imagick::getImageArtifact() - Get image artifact
- Imagick::deleteImageArtifact() - Delete image artifact

# Imagick::setImageAttribute

(PECL imagick 2, PECL imagick 3)

Imagick::setImageAttribute — Sets an image attribute

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

public function Imagick::setImageAttribute(string `$key`, string `$value`): bool

Sets an image attribute.

### 参数

`key`

`value`

### 返回值

成功时返回 `true`。

# Imagick::setImageBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBackgroundColor — Sets the image background color

### 说明

public function Imagick::setImageBackgroundColor(mixed `$background`): bool

Sets the image background color.

### 参数

`background`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 更新日志

版本 | 说明
--- | ---
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

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

public function Imagick::setImageBias(float `$bias`): bool

Sets the image bias for any method that convolves an image (e.g. Imagick::ConvolveImage()).

### 参数

`bias`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

public function Imagick::setImageBiasQuantum(float `$bias`): void

Sets the image bias. Bias should be scaled with `0` (no adjustment) to `1` (quantum value).

### 参数

`bias`

### 返回值

# Imagick::setImageBluePrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBluePrimary — Sets the image chromaticity blue primary point

### 说明

public function Imagick::setImageBluePrimary(float `$x`, float `$y`): bool

Sets the image chromaticity blue primary point.

### 参数

`x`

`y`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setImageBorderColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBorderColor — Sets the image border color

### 说明

public function Imagick::setImageBorderColor(mixed `$border`): bool

Sets the image border color.

### 参数

`border`

  The border color

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 更新日志

版本 | 说明
--- | ---
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

### 说明

public function Imagick::setImageChannelDepth(int `$channel`, int `$depth`): bool

Sets the depth of a particular image channel.

### 参数

`channel`

`depth`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setImageClipMask

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::setImageClipMask — Sets image clip mask

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

public function Imagick::setImageClipMask(Imagick `$clip_mask`): bool

Sets image clip mask from another Imagick object. 此方法在Imagick基于ImageMagick 6.3.6以上版本编译时可用。

### 参数

`clip_mask`

  The Imagick object containing the clip mask

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public function Imagick::setImageColormapColor(int `$index`, ImagickPixel `$color`): bool

Sets the color of the specified colormap index.

### 参数

`index`

`color`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setImageColorspace

(PECL imagick 2, PECL imagick 3)

Imagick::setImageColorspace — Sets the image colorspace

### 说明

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().

### 参数

`colorspace`

  One of the COLORSPACE constants

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setImageCompose

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompose — Sets the image composite operator

### 说明

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.

### 参数

`compose`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setImageCompression

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompression — 设置图片压缩的类型

### 说明

public function Imagick::setImageCompression(int `$compression`): bool

### 参数

`compression`

  `COMPRESSION` 常量里的一种

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setImageCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompressionQuality — 设置图片压缩的质量

### 说明

public function Imagick::setImageCompressionQuality(int `$quality`): bool

设置图片压缩的质量

### 参数

`quality`

  配置压缩质量的整数

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public function Imagick::setImageDepth(int `$depth`): bool

Sets the image depth.

### 参数

`depth`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setImageDispose

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDispose — Sets the image disposal method

### 说明

public function Imagick::setImageDispose(int `$dispose`): bool

Sets the image disposal method.

### 参数

`dispose`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setImageExtent

(PECL imagick 2, PECL imagick 3)

Imagick::setImageExtent — Sets the image size

### 说明

public function Imagick::setImageExtent(int `$columns`, int `$rows`): bool

Sets the image size (i.e. columns & rows).

### 参数

`columns`

`rows`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setImageFilename

(PECL imagick 2, PECL imagick 3)

Imagick::setImageFilename — Sets the filename of a particular image

### 说明

public function Imagick::setImageFilename(string `$filename`): bool

Sets the filename of a particular image in a sequence.

### 参数

`filename`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setImageFormat

(PECL imagick 2, PECL imagick 3)

Imagick::setImageFormat — 为图片设置指定的格式

### 说明

public function Imagick::setImageFormat(string `$format`): bool

为图片设置指定的格式

### 参数

`format`

  表示图片格式的一个字符串。支持的格式依赖于 ImageMagick 的安装。

### 返回值

成功时返回 `true`。

# Imagick::setImageGamma

(PECL imagick 2, PECL imagick 3)

Imagick::setImageGamma — Sets the image gamma

### 说明

public function Imagick::setImageGamma(float `$gamma`): bool

Sets the image gamma.

### 参数

`gamma`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setImageGravity

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::setImageGravity — Sets the image gravity

### 说明

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. 此方法在Imagick基于ImageMagick 6.4.4以上版本编译时可用。

### 参数

`gravity`

  The gravity property. Refer to the list of gravity constants.

### 返回值

没有返回值。

# Imagick::setImageGreenPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageGreenPrimary — Sets the image chromaticity green primary point

### 说明

public function Imagick::setImageGreenPrimary(float `$x`, float `$y`): bool

Sets the image chromaticity green primary point.

### 参数

`x`

`y`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setImageIndex

(PECL imagick 2, PECL imagick 3)

Imagick::setImageIndex — Set the iterator position

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

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().

### 参数

`index`

  The position to set the iterator to

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setImageInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::setImageInterlaceScheme — Sets the image compression

### 说明

public function Imagick::setImageInterlaceScheme(int `$interlace_scheme`): bool

Sets the image compression.

### 参数

`interlace_scheme`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setImageInterpolateMethod

(PECL imagick 2, PECL imagick 3)

Imagick::setImageInterpolateMethod — Sets the image interpolate pixel method

### 说明

public function Imagick::setImageInterpolateMethod(int `$method`): bool

Sets the image interpolate pixel method.

### 参数

`method`

  The method is one of the `Imagick::INTERPOLATE_*` constants

### 返回值

成功时返回 `true`。

# Imagick::setImageIterations

(PECL imagick 2, PECL imagick 3)

Imagick::setImageIterations — Sets the image iterations

### 说明

public function Imagick::setImageIterations(int `$iterations`): bool

Sets the number of iterations an animated image is repeated.

### 参数

`iterations`

  The number of iterations the image should loop over. Set to '0' to loop continuously.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public function Imagick::setImageMatte(bool `$matte`): bool

Sets the image matte channel. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

`matte`

  True activates the matte channel and false disables it.

### 返回值

成功时返回 `true`。

# Imagick::setImageMatteColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageMatteColor — Sets the image matte color

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

public function Imagick::setImageMatteColor(mixed `$matte`): bool

Sets the image matte color.

### 参数

`matte`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 更新日志

版本 | 说明
--- | ---
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

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

public function Imagick::setImageOpacity(float `$opacity`): bool

Sets the image to the specified opacity level. 此方法在Imagick基于ImageMagick 6.3.1以上版本编译时可用。 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()

### 参数

`opacity`

  The level of transparency: 1.0 is fully opaque and 0.0 is fully transparent.

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function Imagick::setImageOrientation(int `$orientation`): bool

Sets the image orientation.

### 参数

`orientation`

  One of the orientation constants

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function Imagick::setImagePage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Sets the page geometry of the image.

### 参数

`width`

`height`

`x`

`y`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::setImageProfile — Adds a named profile to the Imagick object

### 说明

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.

### 参数

`name`

`profile`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setImageProperty

(PECL imagick 2, PECL imagick 3)

Imagick::setImageProperty — Sets an image property

### 说明

public function Imagick::setImageProperty(string `$name`, string `$value`): bool

Sets a named property to the image. 此方法在Imagick基于ImageMagick 6.3.2以上版本编译时可用。

### 参数

`name`

`value`

### 返回值

成功时返回 `true`。

### 示例

示例 #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');
    ?>

### 参见

- Imagick::getImageProperty() - Returns the named image property

# Imagick::setImageRedPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageRedPrimary — Sets the image chromaticity red primary point

### 说明

public function Imagick::setImageRedPrimary(float `$x`, float `$y`): bool

Sets the image chromaticity red primary point.

### 参数

`x`

`y`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setImageRenderingIntent

(PECL imagick 2, PECL imagick 3)

Imagick::setImageRenderingIntent — Sets the image rendering intent

### 说明

public function Imagick::setImageRenderingIntent(int `$rendering_intent`): bool

Sets the image rendering intent.

### 参数

`rendering_intent`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setImageResolution

(PECL imagick 2, PECL imagick 3)

Imagick::setImageResolution — Sets the image resolution

### 说明

public function Imagick::setImageResolution(float `$x_resolution`, float `$y_resolution`): bool

Sets the image resolution.

### 参数

`x_resolution`

`y_resolution`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public function Imagick::setImageScene(int `$scene`): bool

Sets the image scene.

### 参数

`scene`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setImageTicksPerSecond

(PECL imagick 2, PECL imagick 3)

Imagick::setImageTicksPerSecond — Sets the image ticks-per-second

### 说明

public function Imagick::setImageTicksPerSecond(int `$ticks_per_second`): bool

Adjust the amount of time that a frame of an animated image is displayed for.

> 注意:

> 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.

### 参数

`ticks_per_second`

  The duration for which an image should be displayed expressed in ticks per second.

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function Imagick::setImageType(int `$image_type`): bool

Sets the image type.

### 参数

`image_type`

### 返回值

成功时返回 `true`。

# Imagick::setImageUnits

(PECL imagick 2, PECL imagick 3)

Imagick::setImageUnits — Sets the image units of resolution

### 说明

public function Imagick::setImageUnits(int `$units`): bool

Sets the image units of resolution.

### 参数

`units`

### 返回值

成功时返回 `true`。

# Imagick::setImageVirtualPixelMethod

(PECL imagick 2, PECL imagick 3)

Imagick::setImageVirtualPixelMethod — Sets the image virtual pixel method

### 说明

public function Imagick::setImageVirtualPixelMethod(int `$method`): bool

Sets the image virtual pixel method.

### 参数

`method`

### 返回值

成功时返回 `true`。

# Imagick::setImageWhitePoint

(PECL imagick 2, PECL imagick 3)

Imagick::setImageWhitePoint — Sets the image chromaticity white point

### 说明

public function Imagick::setImageWhitePoint(float `$x`, float `$y`): bool

Sets the image chromaticity white point.

### 参数

`x`

`y`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::setInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::setInterlaceScheme — Sets the image compression

### 说明

public function Imagick::setInterlaceScheme(int `$interlace_scheme`): bool

Sets the image compression.

### 参数

`interlace_scheme`

### 返回值

成功时返回 `true`。

# Imagick::setIteratorIndex

(PECL imagick 2, PECL imagick 3)

Imagick::setIteratorIndex — Set the iterator position

### 说明

public function Imagick::setIteratorIndex(int `$index`): bool

Set the iterator to the position in the image list specified with the index parameter. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

`index`

  The position to set the iterator to

### 返回值

成功时返回 `true`。

### 示例

示例 #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();
    ?>

### 参见

- 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

### 说明

public function Imagick::setLastIterator(): bool

Sets the Imagick iterator to the last image.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

# Imagick::setOption

(PECL imagick 2, PECL imagick 3)

Imagick::setOption — Set an option

### 说明

public function Imagick::setOption(string `$key`, string `$value`): bool

Associates one or more options with the wand.

### 参数

`key`

`value`

### 返回值

成功时返回 `true`。

### 示例

示例 #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();
        }

    ?>

示例 #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');

    ?>

示例 #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

### 说明

public function Imagick::setPage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Sets the page geometry of the Imagick object.

### 参数

`width`

`height`

`x`

`y`

### 返回值

成功时返回 `true`。

# Imagick::setPointSize

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setPointSize — Sets point size

### 说明

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. 此方法在Imagick基于ImageMagick 6.3.7以上版本编译时可用。

### 参数

`point_size`

  Point size

### 返回值

成功时返回 `true`。

### 示例

示例 #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 */
    ?>

### 参见

- Imagick::getPointSize() - Gets point size

# Imagick::setProgressMonitor

(PECL imagick 3 >= 3.3.0)

Imagick::setProgressMonitor — Set a callback to be called during processing

### 说明

public function Imagick::setProgressMonitor(callable `$callback`): bool

Set a callback that will be called during the processing of the Imagick image.

### 参数

`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
  警告

  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.

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`key`

`value`

### 返回值

成功时返回 `true`。

# Imagick::setResolution

(PECL imagick 2, PECL imagick 3)

Imagick::setResolution — Sets the image resolution

### 说明

public function Imagick::setResolution(float `$x_resolution`, float `$y_resolution`): bool

Sets the image resolution.

### 参数

`x_resolution`

  The horizontal resolution.

`y_resolution`

  The vertical resolution.

### 返回值

成功时返回 `true`。

### 注释

Imagick::setResolution() must be called before loading or creating an image.

### 参见

- Imagick::setImageResolution() - Sets the image resolution
- Imagick::getImageResolution() - 获取图像的x,y轴分辨率

# Imagick::setResourceLimit

(PECL imagick 2, PECL imagick 3)

Imagick::setResourceLimit — Sets the limit for a particular resource

### 说明

public static function Imagick::setResourceLimit(int `$type`, int `$limit`): bool

This method is used to modify the resource limits of the underlying ImageMagick library.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 参见

- Imagick::getResourceLimit() - Returns the specified resource limit

# Imagick::setSamplingFactors

(PECL imagick 2, PECL imagick 3)

Imagick::setSamplingFactors — Sets the image sampling factors

### 说明

public function Imagick::setSamplingFactors(array `$factors`): bool

Sets the image sampling factors.

### 参数

`factors`

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`columns`

`rows`

### 返回值

成功时返回 `true`。

# Imagick::setSizeOffset

(PECL imagick 2, PECL imagick 3)

Imagick::setSizeOffset — Sets the size and offset of the Imagick object

### 说明

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. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

`columns`

  The width in pixels.

`rows`

  The height in pixels.

`offset`

  The image offset.

### 返回值

成功时返回 `true`。

# Imagick::setType

(PECL imagick 2, PECL imagick 3)

Imagick::setType — Sets the image type attribute

### 说明

public function Imagick::setType(int `$image_type`): bool

Sets the image type attribute.

### 参数

`image_type`

### 返回值

成功时返回 `true`。

# Imagick::shadeImage

(PECL imagick 2, PECL imagick 3)

Imagick::shadeImage — Creates a 3D effect

### 说明

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. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

`gray`

  A value other than zero shades the intensity of each pixel.

`azimuth`

  Defines the light source direction.

`elevation`

  Defines the light source direction.

### 返回值

成功时返回 `true`。

### 错误／异常

Throws ImagickException on failure.

### 示例

示例 #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

### 说明

public function Imagick::shadowImage(
float `$opacity`,
float `$sigma`,
int `$x`,
int `$y`
): bool

Simulates an image shadow.

### 参数

`opacity`

`sigma`

`x`

`y`

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`radius`

`sigma`

`channel`

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`columns`

`rows`

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`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

### 返回值

成功时返回 `true`。

### 更新日志

版本 | 说明
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as the first parameter. Previous versions allow only an ImagickPixel object.

### 示例

示例 #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

### 说明

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

### 参数

`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 - mutliplied by the quantum value for ImageMagick.

`channel`

  Which color channels the contrast will be applied to.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

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. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

`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.

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`stack`

`offset`

### 返回值

The new smushed image.

### 示例

示例 #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

### 说明

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.

### 参数

`threshold`

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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`. 此方法在Imagick基于ImageMagick 6.4.5以上版本编译时可用。

### 参数

`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`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channel constants using bitwise operators. 缺省为`Imagick::CHANNEL_DEFAULT`. 参考此 通道常数列表

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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();
        }

    ?>

示例 #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();
        }

    ?>

示例 #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();
        }

    ?>

示例 #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();
        }

    ?>

示例 #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();
        }

    ?>

示例 #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

### 说明

public function Imagick::spliceImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Splices a solid color into the image.

### 参数

`width`

`height`

`x`

`y`

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function Imagick::spreadImage(float `$radius`): bool

Special effects method that randomly displaces each pixel in a block defined by the radius parameter.

### 参数

`radius`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

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.

### 参数

`type`

`width`

`height`

`channel`

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`watermark_wand`

`offset`

### 返回值

成功时返回 `true`。

# Imagick::stereoImage

(PECL imagick 2, PECL imagick 3)

Imagick::stereoImage — Composites two images

### 说明

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.

### 参数

`offset_wand`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::stripImage

(PECL imagick 2, PECL imagick 3)

Imagick::stripImage — 去掉图片的所有配置和设置

### 说明

public function Imagick::stripImage(): bool

去掉图片的所有配置和设置

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

# Imagick::subImageMatch

(PECL imagick 3 >= 3.3.0)

Imagick::subImageMatch — Searches for a subimage in the current image and returns a similarity image

### 说明

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.

### 参数

`Imagick`

`offset`

`similarity`

  A new image that displays the amount of similarity at each pixel.

### 返回值

### 示例

示例 #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

### 说明

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.

### 参数

`degrees`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

function Imagick::textureImage(Imagick `$texture_wand`): Imagick

Repeatedly tiles the texture image across and down the image canvas.

### 参数

`texture_wand`

  Imagick object to use as texture image

### 返回值

Returns a new Imagick object that has the repeated texture applied.

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

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.

### 参数

`threshold`

`channel`

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

> 注意: 参数 `bestfit` 的特性在 Imagick 3.0.0 中已改变。在此版本以前，当目标尺寸设为 400x400 时，原尺寸为 200x150 的图像将不会被改变。自 Imagick 3.0.0 起，源图像将会被放大到 400x300 因为这将更好的适合目标尺寸。当使用参数 `bestfit` 时，必须同时给出宽度和高度。

### 参数

`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.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

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)))).

### 参数

`tint`

`opacity`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the string content on success or an empty string on failure.

### 参见

- 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

警告

此函数在 Imagick 3.4.4 中被 废弃，强烈建议不要应用此函数。

### 说明

public function Imagick::transformImage(string `$crop`, string `$geometry`): Imagick

A convenience method for setting crop size and the image geometry from strings. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

`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.

### 返回值

Returns an Imagick object containing the transformed image.

### 示例

示例 #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');
    ?>

### 参见

- Imagick::cropImage() - 截图图片的一块区域
- 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

### 说明

public function Imagick::transformImageColorspace(int `$colorspace`): bool

Transforms an image to a new colorspace.

### 参数

`colorspace`

  The colorspace the image should be transformed to, one of the COLORSPACE constants e.g. Imagick::COLORSPACE_CMYK.

### 返回值

成功时返回 `true`。

### 示例

示例 #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();
    }
    ?>

### 参见

- Imagick::setColorSpace() - Set colorspace

# Imagick::transparentPaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::transparentPaintImage — Paints pixels transparent

### 说明

public function Imagick::transparentPaintImage(
mixed `$target`,
float `$alpha`,
float `$fuzz`,
bool `$invert`
): bool

Paints pixels matching the target color transparent. 此方法在Imagick基于ImageMagick 6.3.8以上版本编译时可用。

### 参数

`target`

  The target color to paint

`alpha`

  透明级别：1.0 是完全不透明，0.0 是完全透明。

`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.

`invert`

  If `true` paints any pixel that does not match the target color.

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function Imagick::transposeImage(): bool

Creates a vertical mirror image by reflecting the pixels around the central x-axis while rotating them 90-degrees. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

### 示例

示例 #1 Imagick::transposeImage()

    <?php
    function transposeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->transposeImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### 参见

- Imagick::transverseImage() - Creates a horizontal mirror image

# Imagick::transverseImage

(PECL imagick 2, PECL imagick 3)

Imagick::transverseImage — Creates a horizontal mirror image

### 说明

public function Imagick::transverseImage(): bool

Creates a horizontal mirror image by reflecting the pixels around the central y-axis while rotating them 270-degrees. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

### 示例

示例 #1 Imagick::transverseImage()

    <?php
    function transverseImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->transverseImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### 参见

- Imagick::transposeImage() - Creates a vertical mirror image

# Imagick::trimImage

(PECL imagick 2, PECL imagick 3)

Imagick::trimImage — Remove edges from the image

### 说明

public function Imagick::trimImage(float `$fuzz`): bool

Remove edges that are the background color from the image. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

`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.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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);

    /* Ouput the image */
    header("Content-Type: image/" . $im->getImageFormat());
    echo $im;
    ?>

### 参见

- 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

### 说明

public function Imagick::uniqueImageColors(): bool

Discards all but one of any pixel color. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`radius`

`sigma`

`amount`

`threshold`

`channel`

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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

### 说明

public function Imagick::valid(): bool

Checks if the current item is valid.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

# Imagick::vignetteImage

(PECL imagick 2, PECL imagick 3)

Imagick::vignetteImage — Adds vignette filter to the image

### 说明

public function Imagick::vignetteImage(
float `$blackPoint`,
float `$whitePoint`,
int `$x`,
int `$y`
): bool

Softens the edges of the image in vignette style. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

`blackPoint`

  The black point.

`whitePoint`

  The white point

`x`

  X offset of the ellipse

`y`

  Y offset of the ellipse

### 返回值

成功时返回 `true`。

### 示例

示例 #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();
    }

    ?>

### 参见

- 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

### 说明

public function Imagick::waveImage(float `$amplitude`, float `$length`): bool

Applies a wave filter to the image. 此方法在Imagick基于ImageMagick 6.2.9以上版本编译时可用。

### 参数

`amplitude`

  The amplitude of the wave.

`length`

  The length of the wave.

### 返回值

成功时返回 `true`。

### 错误／异常

错误时抛出 ImagickException。

### 示例

示例 #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();
    }

    ?>

### 参见

- 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

### 说明

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.

### 参数

`threshold`

### 返回值

成功时返回 `true`。

### 更新日志

版本 | 说明
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as a parameter. Previous versions allow only an ImagickPixel object.

### 示例

示例 #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 — 把图片写入指定的文件

### 说明

public function Imagick::writeImage(string `$filename` = NULL): bool

把图片写入指定的文件。如果指定文件参数的值是 NULL ，图片将会写入通过 Imagick::readImage() 或者 Imagick::setImageFilename() 设定的文件。

### 参数

`filename`

  图片将被写入的文件名。文件的后缀指定了文件的类型。 可以强制指定图片的格式而不管文件的后缀名。在文件名前面加上一个前缀，例如 “jpg:test.png”。

### 返回值

成功时返回 `true`。

# Imagick::writeImageFile

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImageFile — Writes an image to a filehandle

### 说明

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. 此方法在Imagick基于ImageMagick 6.3.6以上版本编译时可用。

### 参数

`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().

### 返回值

成功时返回 `true`。

### 参见

- 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

### 说明

public function Imagick::writeImages(string `$filename`, bool `$adjoin`): bool

Writes an image or image sequence.

### 参数

`filename`

`adjoin`

### 返回值

成功时返回 `true`。

# Imagick::writeImagesFile

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImagesFile — Writes frames to a filehandle

### 说明

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. 此方法在Imagick基于ImageMagick 6.3.6以上版本编译时可用。

### 参数

`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().

### 返回值

成功时返回 `true`。

### 参见

- Imagick::queryFormats() - Returns formats supported by Imagick

## 目录

- 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 — 把一张图合并到一张图
- 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 — 截图图片的一块区域
- Imagick::cropThumbnailImage — 创建缩略图
- 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 — 把 ImagickDraw 对象渲染到当前图片上
- 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 — 检查图像是否有 alpha 通道
- 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 — 获取图像的x,y轴分辨率
- 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 — 获取图像的分辨率单位
- 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 — 创建一张图片
- 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 — Fetch basic attributes about the image
- 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 — 从二进制字符串里读取图片
- 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 — 设置图片压缩的类型
- Imagick::setImageCompressionQuality — 设置图片压缩的质量
- 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 — 为图片设置指定的格式
- 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 — 去掉图片的所有配置和设置
- 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 — 把图片写入指定的文件
- Imagick::writeImageFile — Writes an image to a filehandle
- Imagick::writeImages — Writes an image or image sequence
- Imagick::writeImagesFile — Writes frames to a filehandle

# The ImagickDraw class

(PECL imagick 2, PECL imagick 3)

## 类摘要

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

### 说明

public function ImagickDraw::affine(array `$affine`): bool
警告

本函数还未编写文档，仅有参数列表。

Adjusts the current affine transformation matrix with the specified affine transformation matrix.

### 参数

`affine`

  Affine matrix parameters

### 返回值

没有返回值。

### 示例

示例 #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 identiy 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

### 说明

public function ImagickDraw::annotation(float `$x`, float `$y`, string `$text`): bool
警告

本函数还未编写文档，仅有参数列表。

Draws text on the image.

### 参数

`x`

  The x coordinate where text is drawn

`y`

  The y coordinate where text is drawn

`text`

  The text to draw on the image

### 返回值

没有返回值。

# ImagickDraw::arc

(PECL imagick 2, PECL imagick 3)

ImagickDraw::arc — Draws an arc

### 说明

public function ImagickDraw::arc(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`,
float `$start_angle`,
float `$end_angle`
): bool
警告

本函数还未编写文档，仅有参数列表。

Draws an arc falling within a specified bounding rectangle on the image.

### 参数

`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

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::bezier(array `$coordinates`): bool
警告

本函数还未编写文档，仅有参数列表。

Draws a bezier curve through a set of points on the image.

### 参数

`coordinates`

  Multidimensional array like array( array( 'x' => 1, 'y' => 2 ), array( 'x' => 3, 'y' => 4 ) )

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::circle(
float `$origin_x`,
float `$origin_y`,
float `$perimeter_x`,
float `$perimeter_y`
): bool
警告

本函数还未编写文档，仅有参数列表。

Draws a circle on the image.

### 参数

`origin_x`

  origin x coordinate

`origin_y`

  origin y coordinate

`perimeter_x`

  perimeter x coordinate

`perimeter_y`

  perimeter y coordinate

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::clear(): bool
警告

本函数还未编写文档，仅有参数列表。

Clears the ImagickDraw object of any accumulated commands, and resets the settings it contains to their defaults.

### 返回值

Returns an ImagickDraw object.

# ImagickDraw::clone

(PECL imagick 2, PECL imagick 3)

ImagickDraw::clone — Makes an exact copy of the specified ImagickDraw object

### 说明

public function ImagickDraw::clone(): ImagickDraw
警告

本函数还未编写文档，仅有参数列表。

Makes an exact copy of the specified ImagickDraw object.

### 返回值

returns an exact copy of the specified ImagickDraw object.

# ImagickDraw::color

(PECL imagick 2, PECL imagick 3)

ImagickDraw::color — Draws color on image

### 说明

public function ImagickDraw::color(float `$x`, float `$y`, int `$paint`): bool
警告

本函数还未编写文档，仅有参数列表。

Draws color on image using the current fill color, starting at specified position, and using specified paint method.

### 参数

`x`

  x coordinate of the paint

`y`

  y coordinate of the paint

`paint`

  One of the PAINT constant (`imagick::PAINT_*`).

### 返回值

没有返回值。

# ImagickDraw::comment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::comment — Adds a comment

### 说明

public function ImagickDraw::comment(string `$comment`): bool
警告

本函数还未编写文档，仅有参数列表。

Adds a comment to a vector output stream.

### 参数

`comment`

  The comment string to add to vector output stream

### 返回值

没有返回值。

# ImagickDraw::composite

(PECL imagick 2, PECL imagick 3)

ImagickDraw::composite — Composites an image onto the current image

### 说明

public function ImagickDraw::composite(
int `$composite`,
float `$x`,
float `$y`,
float `$width`,
float `$height`,
Imagick `$image`
): bool
警告

本函数还未编写文档，仅有参数列表。

Composites an image onto the current image, using the specified composition operator, specified position, and at the specified size.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function ImagickDraw::__construct()
警告

本函数还未编写文档，仅有参数列表。

The ImagickDraw constructor.

### 返回值

没有返回值。

# ImagickDraw::destroy

(PECL imagick 2, PECL imagick 3)

ImagickDraw::destroy — Frees all associated resources

### 说明

public function ImagickDraw::destroy(): bool
警告

本函数还未编写文档，仅有参数列表。

Frees all resources associated with the ImagickDraw object.

### 返回值

没有返回值。

# ImagickDraw::ellipse

(PECL imagick 2, PECL imagick 3)

ImagickDraw::ellipse — Draws an ellipse on the image

### 说明

public function ImagickDraw::ellipse(
float `$origin_x`,
float `$origin_y`,
float `$radius_x`,
float `$radius_y`,
float `$angle_start`,
float `$angle_end`
): bool
警告

本函数还未编写文档，仅有参数列表。

Draws an ellipse on the image.

### 参数

`origin_x`

`origin_y`

`radius_x`

`radius_y`

`angle_start`

`angle_end`

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::getClipPath(): false|string
警告

本函数还未编写文档，仅有参数列表。

Obtains the current clipping path ID.

### 返回值

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

### 说明

public function ImagickDraw::getClipRule(): int
警告

本函数还未编写文档，仅有参数列表。

Returns the current polygon fill rule to be used by the clipping path.

### 返回值

Returns a FILLRULE constant (`imagick::FILLRULE_*`).

# ImagickDraw::getClipUnits

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipUnits — Returns the interpretation of clip path units

### 说明

public function ImagickDraw::getClipUnits(): int
警告

本函数还未编写文档，仅有参数列表。

Returns the interpretation of clip path units.

### 返回值

Returns an int on success.

# ImagickDraw::getFillColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillColor — Returns the fill color

### 说明

public function ImagickDraw::getFillColor(): ImagickPixel
警告

本函数还未编写文档，仅有参数列表。

Returns the fill color used for drawing filled objects.

### 返回值

Returns an ImagickPixel object.

# ImagickDraw::getFillOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillOpacity — Returns the opacity used when drawing

### 说明

public function ImagickDraw::getFillOpacity(): float
警告

本函数还未编写文档，仅有参数列表。

Returns the opacity used when drawing using the fill color or fill texture. Fully opaque is 1.0.

### 返回值

The opacity.

# ImagickDraw::getFillRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillRule — Returns the fill rule

### 说明

public function ImagickDraw::getFillRule(): int
警告

本函数还未编写文档，仅有参数列表。

Returns the fill rule used while drawing polygons.

### 返回值

Returns a FILLRULE constant (`imagick::FILLRULE_*`).

# ImagickDraw::getFont

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFont — Returns the font

### 说明

public function ImagickDraw::getFont(): string
警告

本函数还未编写文档，仅有参数列表。

Returns a string specifying the font used when annotating with text.

### 返回值

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

### 说明

public function ImagickDraw::getFontFamily(): string
警告

本函数还未编写文档，仅有参数列表。

Returns the font family to use when annotating with text.

### 返回值

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

### 说明

public function ImagickDraw::getFontSize(): float
警告

本函数还未编写文档，仅有参数列表。

Returns the font pointsize used when annotating with text.

### 返回值

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

### 说明

public function ImagickDraw::getFontStretch(): int

Gets the font stretch to use when annotating with text. Returns a StretchType.

### 参数

此函数没有参数。

### 返回值

# ImagickDraw::getFontStyle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontStyle — Returns the font style

### 说明

public function ImagickDraw::getFontStyle(): int
警告

本函数还未编写文档，仅有参数列表。

Returns the font style used when annotating with text.

### 返回值

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

### 说明

public function ImagickDraw::getFontWeight(): int
警告

本函数还未编写文档，仅有参数列表。

Returns the font weight used when annotating with text.

### 返回值

Returns an int on success and 0 if no weight is set.

# ImagickDraw::getGravity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getGravity — Returns the text placement gravity

### 说明

public function ImagickDraw::getGravity(): int
警告

本函数还未编写文档，仅有参数列表。

Returns the text placement gravity used when annotating with text.

### 返回值

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

### 说明

public function ImagickDraw::getStrokeAntialias(): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 返回值

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

### 说明

public function ImagickDraw::getStrokeColor(): ImagickPixel
警告

本函数还未编写文档，仅有参数列表。

Returns the color used for stroking object outlines.

### 参数

`stroke_color`

### 返回值

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

### 说明

public function ImagickDraw::getStrokeDashArray(): array
警告

本函数还未编写文档，仅有参数列表。

Returns an array representing the pattern of dashes and gaps used to stroke paths.

### 返回值

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

### 说明

public function ImagickDraw::getStrokeDashOffset(): float
警告

本函数还未编写文档，仅有参数列表。

Returns the offset into the dash pattern to start the dash.

### 返回值

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

### 说明

public function ImagickDraw::getStrokeLineCap(): int
警告

本函数还未编写文档，仅有参数列表。

Returns the shape to be used at the end of open subpaths when they are stroked.

### 返回值

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

### 说明

public function ImagickDraw::getStrokeLineJoin(): int
警告

本函数还未编写文档，仅有参数列表。

Returns the shape to be used at the corners of paths (or other vector shapes) when they are stroked.

### 返回值

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

### 说明

public function ImagickDraw::getStrokeMiterLimit(): int
警告

本函数还未编写文档，仅有参数列表。

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'.

### 返回值

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

### 说明

public function ImagickDraw::getStrokeOpacity(): float
警告

本函数还未编写文档，仅有参数列表。

Returns the opacity of stroked object outlines.

### 返回值

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

### 说明

public function ImagickDraw::getStrokeWidth(): float
警告

本函数还未编写文档，仅有参数列表。

Returns the width of the stroke used to draw object outlines.

### 返回值

Returns a float describing the stroke width.

# ImagickDraw::getTextAlignment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextAlignment — Returns the text alignment

### 说明

public function ImagickDraw::getTextAlignment(): int
警告

本函数还未编写文档，仅有参数列表。

Returns the alignment applied when annotating with text.

### 返回值

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

### 说明

public function ImagickDraw::getTextAntialias(): bool
警告

本函数还未编写文档，仅有参数列表。

Returns the current text antialias setting, which determines whether text is antialiased. Text is antialiased by default.

### 返回值

Returns `true` if text is antialiased and `false` if not.

# ImagickDraw::getTextDecoration

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextDecoration — Returns the text decoration

### 说明

public function ImagickDraw::getTextDecoration(): int
警告

本函数还未编写文档，仅有参数列表。

Returns the decoration applied when annotating with text.

### 返回值

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

### 说明

public function ImagickDraw::getTextEncoding(): false|string
警告

本函数还未编写文档，仅有参数列表。

Returns a string which specifies the code set used for text annotations.

### 返回值

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

### 说明

public function ImagickDraw::getTextInterlineSpacing(): float

Gets the text interline spacing.

### 参数

此函数没有参数。

### 返回值

# ImagickDraw::getTextInterwordSpacing

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextInterwordSpacing — Gets the text interword spacing

### 说明

public function ImagickDraw::getTextInterwordSpacing(): float

Gets the text interword spacing.

### 参数

此函数没有参数。

### 返回值

# ImagickDraw::getTextKerning

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextKerning — Gets the text kerning

### 说明

public function ImagickDraw::getTextKerning(): float

Gets the text kerning.

### 参数

此函数没有参数。

### 返回值

# ImagickDraw::getTextUnderColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextUnderColor — Returns the text under color

### 说明

public function ImagickDraw::getTextUnderColor(): ImagickPixel
警告

本函数还未编写文档，仅有参数列表。

Returns the color of a background rectangle to place under text annotations.

### 返回值

Returns an ImagickPixel object describing the color.

# ImagickDraw::getVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getVectorGraphics — Returns a string containing vector graphics

### 说明

public function ImagickDraw::getVectorGraphics(): string
警告

本函数还未编写文档，仅有参数列表。

Returns a string which specifies the vector graphics generated by any graphics calls made since the ImagickDraw object was instantiated.

### 返回值

Returns a string containing the vector graphics.

# ImagickDraw::line

(PECL imagick 2, PECL imagick 3)

ImagickDraw::line — Draws a line

### 说明

public function ImagickDraw::line(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`
): bool
警告

本函数还未编写文档，仅有参数列表。

Draws a line on the image using the current stroke color, stroke opacity, and stroke width.

### 参数

`start_x`

  starting x coordinate

`start_y`

  starting y coordinate

`end_x`

  ending x coordinate

`end_y`

  ending y coordinate

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::matte(float `$x`, float `$y`, int `$paint`): bool
警告

本函数还未编写文档，仅有参数列表。

Paints on the image's opacity channel in order to set effected pixels to transparent, to influence the opacity of pixels.

### 参数

`x`

  x coordinate of the matte

`y`

  y coordinate of the matte

`paint`

  One of the PAINT constant (`imagick::PAINT_*`).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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

### 说明

public function ImagickDraw::pathClose(): bool
警告

本函数还未编写文档，仅有参数列表。

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).

### 返回值

没有返回值。

# ImagickDraw::pathCurveToAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToAbsolute — Draws a cubic Bezier curve

### 说明

public function ImagickDraw::pathCurveToAbsolute(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`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

### 返回值

没有返回值。

# ImagickDraw::pathCurveToQuadraticBezierAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierAbsolute — Draws a quadratic Bezier curve

### 说明

public function ImagickDraw::pathCurveToQuadraticBezierAbsolute(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`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

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::pathCurveToQuadraticBezierRelative(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`x1`

  starting x coordinate

`y1`

  starting y coordinate

`x_end`

  ending x coordinate

`y`

  ending y coordinate

### 返回值

没有返回值。

# ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute — Draws a quadratic Bezier curve

### 说明

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.

### 参数

`x`

  ending x coordinate

`y`

  ending y coordinate

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::pathCurveToQuadraticBezierSmoothRelative(float `$x`, float `$y`): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`x`

  ending x coordinate

`y`

  ending y coordinate

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::pathCurveToRelative(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`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

### 返回值

没有返回值。

# ImagickDraw::pathCurveToSmoothAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToSmoothAbsolute — Draws a cubic Bezier curve

### 说明

public function ImagickDraw::pathCurveToSmoothAbsolute(
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`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

### 返回值

没有返回值。

# ImagickDraw::pathCurveToSmoothRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToSmoothRelative — Draws a cubic Bezier curve

### 说明

public function ImagickDraw::pathCurveToSmoothRelative(
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`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

### 返回值

没有返回值。

# ImagickDraw::pathEllipticArcAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathEllipticArcAbsolute — Draws an elliptical arc

### 说明

public function ImagickDraw::pathEllipticArcAbsolute(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`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

### 返回值

没有返回值。

# ImagickDraw::pathEllipticArcRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathEllipticArcRelative — Draws an elliptical arc

### 说明

public function ImagickDraw::pathEllipticArcRelative(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`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

### 返回值

没有返回值。

# ImagickDraw::pathFinish

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathFinish — Terminates the current path

### 说明

public function ImagickDraw::pathFinish(): bool
警告

本函数还未编写文档，仅有参数列表。

Terminates the current path.

### 返回值

没有返回值。

# ImagickDraw::pathLineToAbsolute

(PECL imagick 2)

ImagickDraw::pathLineToAbsolute — Draws a line path

### 说明

public function ImagickDraw::pathLineToAbsolute(float `$x`, float `$y`): bool
警告

本函数还未编写文档，仅有参数列表。

Draws a line path from the current point to the given coordinate using absolute coordinates. The coordinate then becomes the new current point.

### 参数

`x`

  starting x coordinate

`y`

  ending x coordinate

### 返回值

没有返回值。

# ImagickDraw::pathLineToHorizontalAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToHorizontalAbsolute — Draws a horizontal line path

### 说明

public function ImagickDraw::pathLineToHorizontalAbsolute(float `$x`): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`x`

  x coordinate

### 返回值

没有返回值。

# ImagickDraw::pathLineToHorizontalRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToHorizontalRelative — Draws a horizontal line

### 说明

public function ImagickDraw::pathLineToHorizontalRelative(float `$x`): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`x`

  x coordinate

### 返回值

没有返回值。

# ImagickDraw::pathLineToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToRelative — Draws a line path

### 说明

public function ImagickDraw::pathLineToRelative(float `$x`, float `$y`): bool
警告

本函数还未编写文档，仅有参数列表。

Draws a line path from the current point to the given coordinate using relative coordinates. The coordinate then becomes the new current point.

### 参数

`x`

  starting x coordinate

`y`

  starting y coordinate

### 返回值

没有返回值。

# ImagickDraw::pathLineToVerticalAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToVerticalAbsolute — Draws a vertical line

### 说明

public function ImagickDraw::pathLineToVerticalAbsolute(float `$y`): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`y`

  y coordinate

### 返回值

没有返回值。

# ImagickDraw::pathLineToVerticalRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToVerticalRelative — Draws a vertical line path

### 说明

public function ImagickDraw::pathLineToVerticalRelative(float `$y`): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`y`

  y coordinate

### 返回值

没有返回值。

# ImagickDraw::pathMoveToAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathMoveToAbsolute — Starts a new sub-path

### 说明

public function ImagickDraw::pathMoveToAbsolute(float `$x`, float `$y`): bool
警告

本函数还未编写文档，仅有参数列表。

Starts a new sub-path at the given coordinate using absolute coordinates. The current point then becomes the specified coordinate.

### 参数

`x`

  x coordinate of the starting point

`y`

  y coordinate of the starting point

### 返回值

没有返回值。

# ImagickDraw::pathMoveToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathMoveToRelative — Starts a new sub-path

### 说明

public function ImagickDraw::pathMoveToRelative(float `$x`, float `$y`): bool
警告

本函数还未编写文档，仅有参数列表。

Starts a new sub-path at the given coordinate using relative coordinates. The current point then becomes the specified coordinate.

### 参数

`x`

  target x coordinate

`y`

  target y coordinate

### 返回值

没有返回值。

# ImagickDraw::pathStart

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathStart — Declares the start of a path drawing list

### 说明

public function ImagickDraw::pathStart(): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::point(float `$x`, float `$y`): bool
警告

本函数还未编写文档，仅有参数列表。

Draws a point using the current stroke color and stroke thickness at the specified coordinates.

### 参数

`x`

  point's x coordinate

`y`

  point's y coordinate

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::polygon(array `$coordinates`): bool
警告

本函数还未编写文档，仅有参数列表。

Draws a polygon using the current stroke, stroke width, and fill color or texture, using the specified array of coordinates.

### 参数

`coordinates`

  multidimensional array like array( array( 'x' => 3, 'y' => 4 ), array( 'x' => 2, 'y' => 6 ) );

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function ImagickDraw::polyline(array `$coordinates`): bool
警告

本函数还未编写文档，仅有参数列表。

Draws a polyline using the current stroke, stroke width, and fill color or texture, using the specified array of coordinates.

### 参数

`coordinates`

  array of x and y coordinates: array( array( 'x' => 4, 'y' => 6 ), array( 'x' => 8, 'y' => 10 ) )

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function ImagickDraw::pop(): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# ImagickDraw::popClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popClipPath — Terminates a clip path definition

### 说明

public function ImagickDraw::popClipPath(): bool
警告

本函数还未编写文档，仅有参数列表。

Terminates a clip path definition.

### 返回值

没有返回值。

# ImagickDraw::popDefs

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popDefs — Terminates a definition list

### 说明

public function ImagickDraw::popDefs(): bool
警告

本函数还未编写文档，仅有参数列表。

Terminates a definition list.

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::popPattern(): bool
警告

本函数还未编写文档，仅有参数列表。

Terminates a pattern definition.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# ImagickDraw::push

(PECL imagick 2, PECL imagick 3)

ImagickDraw::push — Clones the current ImagickDraw and pushes it to the stack

### 说明

public function ImagickDraw::push(): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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

### 说明

public function ImagickDraw::pushClipPath(string `$clip_mask_id`): bool
警告

本函数还未编写文档，仅有参数列表。

Starts a clip path definition which is comprised of any number of drawing commands and terminated by a ImagickDraw::popClipPath() command.

### 参数

`clip_mask_id`

  Clip mask Id

### 返回值

没有返回值。

# ImagickDraw::pushDefs

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushDefs — Indicates that following commands create named elements for early processing

### 说明

public function ImagickDraw::pushDefs(): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 返回值

没有返回值。

# 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

### 说明

public function ImagickDraw::pushPattern(
string `$pattern_id`,
float `$x`,
float `$y`,
float `$width`,
float `$height`
): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`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

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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

### 说明

public function ImagickDraw::rectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`
): bool
警告

本函数还未编写文档，仅有参数列表。

Draws a rectangle given two coordinates and using the current stroke, stroke width, and fill settings.

### 参数

`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

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::render(): bool
警告

本函数还未编写文档，仅有参数列表。

Renders all preceding drawing commands onto the image.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# ImagickDraw::resetVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::resetVectorGraphics — Resets the vector graphics

### 说明

public function ImagickDraw::resetVectorGraphics(): bool

Resets the vector graphics.

### 参数

此函数没有参数。

### 返回值

成功时返回 `true`。

# ImagickDraw::rotate

(PECL imagick 2, PECL imagick 3)

ImagickDraw::rotate — Applies the specified rotation to the current coordinate space

### 说明

public function ImagickDraw::rotate(float `$degrees`): bool
警告

本函数还未编写文档，仅有参数列表。

Applies the specified rotation to the current coordinate space.

### 参数

`degrees`

  degrees to rotate.

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

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
警告

本函数还未编写文档，仅有参数列表。

Draws a rounded rectangle given two coordinates, x & y corner radiuses and using the current stroke, stroke width, and fill settings.

### 参数

`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

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::scale(float `$x`, float `$y`): bool
警告

本函数还未编写文档，仅有参数列表。

Adjusts the scaling factor to apply in the horizontal and vertical directions to the current coordinate space.

### 参数

`x`

  horizontal factor

`y`

  vertical factor

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setClipPath(string `$clip_mask`): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`clip_mask`

  the clipping path name

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setClipRule(int `$fillrule`): bool
警告

本函数还未编写文档，仅有参数列表。

Set the polygon fill rule to be used by the clipping path.

### 参数

`fillrule`

  One of the FILLRULE constant (`imagick::FILLRULE_*`).

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setClipUnits(int `$pathunits`): bool
警告

本函数还未编写文档，仅有参数列表。

Sets the interpretation of clip path units.

### 参数

`pathunits`

  the number of clip units

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setFillAlpha(float `$alpha`): bool
警告

本函数还未编写文档，仅有参数列表。

Sets the opacity to use when drawing using the fill color or fill texture. Fully opaque is 1.0.

### 参数

`alpha`

  fill alpha

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setFillColor(ImagickPixel|string `$fill_color`): bool
警告

本函数还未编写文档，仅有参数列表。

Sets the fill color to be used for drawing filled objects.

### 参数

`fill_color`

  ImagickPixel to use to set the color

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setFillOpacity(float `$opacity`): bool
警告

本函数还未编写文档，仅有参数列表。

Sets the opacity to use when drawing using the fill color or fill texture. Fully opaque is 1.0.

### 参数

`opacity`

  the fill opacity

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setFillPatternURL(string `$fill_url`): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`fill_url`

  URL to use to obtain fill pattern.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# ImagickDraw::setFillRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillRule — Sets the fill rule to use while drawing polygons

### 说明

public function ImagickDraw::setFillRule(int `$fillrule`): bool
警告

本函数还未编写文档，仅有参数列表。

Sets the fill rule to use while drawing polygons.

### 参数

`fillrule`

  One of the FILLRULE constant (`imagick::FILLRULE_*`).

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setFont(string `$font_name`): bool
警告

本函数还未编写文档，仅有参数列表。

Sets the fully-specified font to use when annotating with text.

### 参数

`font_name`

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function ImagickDraw::setFontFamily(string `$font_family`): bool
警告

本函数还未编写文档，仅有参数列表。

Sets the font family to use when annotating with text.

### 参数

`font_family`

  the font family

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function ImagickDraw::setFontSize(float `$point_size`): bool
警告

本函数还未编写文档，仅有参数列表。

Sets the font pointsize to use when annotating with text.

### 参数

`point_size`

  the point size

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setFontStretch(int `$stretch`): bool
警告

本函数还未编写文档，仅有参数列表。

Sets the font stretch to use when annotating with text. The AnyStretch enumeration acts as a wild-card "don't care" option.

### 参数

`stretch`

  One of the STRETCH constant (`imagick::STRETCH_*`).

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setFontStyle(int `$style`): bool
警告

本函数还未编写文档，仅有参数列表。

Sets the font style to use when annotating with text. The AnyStyle enumeration acts as a wild-card "don't care" option.

### 参数

`style`

  One of the STYLE constant (`imagick::STYLE_*`).

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setFontWeight(int `$weight`): bool
警告

本函数还未编写文档，仅有参数列表。

Sets the font weight to use when annotating with text.

### 参数

`weight`

### 返回值

### 示例

示例 #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

### 说明

public function ImagickDraw::setGravity(int `$gravity`): bool
警告

本函数还未编写文档，仅有参数列表。

Sets the text placement gravity to use when annotating with text.

### 参数

`gravity`

  One of the GRAVITY constant (`imagick::GRAVITY_*`).

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setResolution(float `$resolution_x`, float `$resolution_y`): bool

Sets the resolution.

### 参数

`resolution_x`

`resolution_y`

### 返回值

成功时返回 `true`。

# ImagickDraw::setStrokeAlpha

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeAlpha — Specifies the opacity of stroked object outlines

### 说明

public function ImagickDraw::setStrokeAlpha(float `$alpha`): bool
警告

本函数还未编写文档，仅有参数列表。

Specifies the opacity of stroked object outlines.

### 参数

`alpha`

  opacity

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setStrokeAntialias(bool `$enabled`): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`enabled`

  the antialias setting

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setStrokeColor(ImagickPixel|string `$color`): bool
警告

本函数还未编写文档，仅有参数列表。

Sets the color used for stroking object outlines.

### 参数

`color`

  the stroke color

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setStrokeDashArray(?array `$dashes`): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`dashes`

  array of floats

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function ImagickDraw::setStrokeDashOffset(float `$dash_offset`): bool
警告

本函数还未编写文档，仅有参数列表。

Specifies the offset into the dash pattern to start the dash.

### 参数

`dash_offset`

  dash offset

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setStrokeLineCap(int `$linecap`): bool
警告

本函数还未编写文档，仅有参数列表。

Specifies the shape to be used at the end of open subpaths when they are stroked.

### 参数

`linecap`

  One of the LINECAP constant (`imagick::LINECAP_*`).

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setStrokeLineJoin(int `$linejoin`): bool
警告

本函数还未编写文档，仅有参数列表。

Specifies the shape to be used at the corners of paths (or other vector shapes) when they are stroked.

### 参数

`linejoin`

  One of the LINEJOIN constant (`imagick::LINEJOIN_*`).

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setStrokeMiterLimit(int `$miterlimit`): bool
警告

本函数还未编写文档，仅有参数列表。

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'.

### 参数

`miterlimit`

  the miter limit

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setStrokeOpacity(float `$opacity`): bool
警告

本函数还未编写文档，仅有参数列表。

Specifies the opacity of stroked object outlines.

### 参数

`opacity`

  stroke opacity. 1.0 is fully opaque

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setStrokePatternURL(string `$stroke_url`): bool
警告

本函数还未编写文档，仅有参数列表。

Sets the pattern used for stroking object outlines.

### 参数

`stroke_url`

  stroke URL

### 返回值

成功时返回 `true`。

# ImagickDraw::setStrokeWidth

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeWidth — Sets the width of the stroke used to draw object outlines

### 说明

public function ImagickDraw::setStrokeWidth(float `$width`): bool
警告

本函数还未编写文档，仅有参数列表。

Sets the width of the stroke used to draw object outlines.

### 参数

`width`

  stroke width

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setTextAlignment(int `$align`): bool
警告

本函数还未编写文档，仅有参数列表。

Specifies a text alignment to be applied when annotating with text.

### 参数

`align`

  One of the ALIGN constant (`imagick::ALIGN_*`).

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setTextAntialias(bool `$antialias`): bool
警告

本函数还未编写文档，仅有参数列表。

Controls whether text is antialiased. Text is antialiased by default.

### 参数

`antialias`

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setTextDecoration(int `$decoration`): bool
警告

本函数还未编写文档，仅有参数列表。

Specifies a decoration to be applied when annotating with text.

### 参数

`decoration`

  One of the DECORATION constant (`imagick::DECORATION_*`).

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setTextEncoding(string `$encoding`): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`encoding`

  the encoding name

### 返回值

没有返回值。

# ImagickDraw::setTextInterlineSpacing

(PECL imagick 3 >= 3.1.0)

ImagickDraw::setTextInterlineSpacing — Sets the text interline spacing

### 说明

public function ImagickDraw::setTextInterlineSpacing(float `$spacing`): bool

Sets the text interline spacing.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`spacing`

### 返回值

成功时返回 `true`。

# ImagickDraw::setTextInterwordSpacing

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickDraw::setTextInterwordSpacing — Sets the text interword spacing

### 说明

public function ImagickDraw::setTextInterwordSpacing(float `$spacing`): bool

Sets the text interword spacing.

### 参数

`spacing`

### 返回值

成功时返回 `true`。

# ImagickDraw::setTextKerning

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickDraw::setTextKerning — Sets the text kerning

### 说明

public function ImagickDraw::setTextKerning(float `$kerning`): bool

Sets the text kerning

警告

本函数还未编写文档，仅有参数列表。

### 参数

`kerning`

### 返回值

成功时返回 `true`。

# ImagickDraw::setTextUnderColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextUnderColor — Specifies the color of a background rectangle

### 说明

public function ImagickDraw::setTextUnderColor(ImagickPixel|string `$under_color`): bool
警告

本函数还未编写文档，仅有参数列表。

Specifies the color of a background rectangle to place under text annotations.

### 参数

`under_color`

  the under color

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::setVectorGraphics(string `$xml`): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`xml`

  xml containing the vector graphics

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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

### 说明

public function ImagickDraw::setViewbox(
int `$left_x`,
int `$top_y`,
int `$right_x`,
int `$bottom_y`
): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 参数

`left_x`

  left x coordinate

`top_y`

  left y coordinate

`right_x`

  right x coordinate

`bottom_y`

  right y coordinate

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::skewX(float `$degrees`): bool
警告

本函数还未编写文档，仅有参数列表。

Skews the current coordinate system in the horizontal direction.

### 参数

`degrees`

  degrees to skew

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::skewY(float `$degrees`): bool
警告

本函数还未编写文档，仅有参数列表。

Skews the current coordinate system in the vertical direction.

### 参数

`degrees`

  degrees to skew

### 返回值

没有返回值。

### 示例

示例 #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

### 说明

public function ImagickDraw::translate(float `$x`, float `$y`): bool
警告

本函数还未编写文档，仅有参数列表。

Applies a translation to the current coordinate system which moves the coordinate system origin to the specified coordinate.

### 参数

`x`

  horizontal translation

`y`

  vertical translation

### 返回值

没有返回值。

### 示例

示例 #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();
    }

    ?>

## 目录

- 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)

## 简介

## 类摘要

class ImagickDrawException extends Exception implements Throwable {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 方法 */
/* 继承的方法 */
}

# The ImagickException class

(PECL imagick 3)

## 简介

## 类摘要

class ImagickException extends Exception implements Throwable {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 方法 */
/* 继承的方法 */
}

# The ImagickKernel class

(PECL imagick >= 3.3.0)

## 简介

## 类摘要

class ImagickKernel {
/* 方法 */
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

### 说明

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.

### 参数

`ImagickKernel`

### 返回值

### 示例

示例 #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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

### 示例

示例 #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;

    ?>

示例 #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

### 说明

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");

### 参数

`kerneltype`

  The type of kernel to build e.g. \Imagick::KERNEL_DIAMOND

`kernelString`

  A string that describes the parameters e.g. "4,2.5"

### 返回值

### 示例

示例 #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

### 说明

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.

### 参数

`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.

### 返回值

The generated ImagickKernel.

### 示例

示例 #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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

A matrix (2d array) of the values that represent the kernel.

### 示例

示例 #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

### 说明

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.

### 参数

`scale`

`normalizeFlag`

  - Imagick::NORMALIZE_KERNEL_NONE
  - Imagick::NORMALIZE_KERNEL_VALUE
  - Imagick::NORMALIZE_KERNEL_CORRELATE
  - Imagick::NORMALIZE_KERNEL_PERCENT

### 返回值

### 示例

示例 #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

### 说明

public function ImagickKernel::separate(): array

Separates a linked set of kernels and returns an array of ImagickKernels.

### 参数

此函数没有参数。

### 返回值

### 示例

示例 #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;

    ?>

## 目录

- 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

# The ImagickKernelException class

(PECL imagick 3)

## 简介

## 类摘要

class ImagickKernelException extends Exception {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 方法 */
/* 继承的方法 */
}

# The ImagickPixel class

(PECL imagick 2, PECL imagick 3)

## 类摘要

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

### 说明

public function ImagickPixel::clear(): bool
警告

本函数还未编写文档，仅有参数列表。

Clears the ImagickPixel object, leaving it in a fresh state. This also unsets any color associated with the object.

### 返回值

成功时返回 `true`。

# ImagickPixel::__construct

(PECL imagick 2, PECL imagick 3)

ImagickPixel::__construct — The ImagickPixel constructor

### 说明

public function ImagickPixel::__construct(string `$color` = ?)
警告

本函数还未编写文档，仅有参数列表。

Constructs an ImagickPixel object. If a color is specified, the object is constructed and then initialised with that color before being returned.

### 参数

`color`

  The optional color string to use as the initial value of this object.

### 返回值

Returns an ImagickPixel object on success, throwing ImagickPixelException on failure.

### 示例

示例 #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

### 说明

public function ImagickPixel::destroy(): bool
警告

本函数还未编写文档，仅有参数列表。

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.

### 返回值

成功时返回 `true`。

# ImagickPixel::getColor

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColor — Returns the color

### 说明

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.

### 参数

`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.)

### 返回值

An array of channel values. Throws ImagickPixelException on error.

### 示例

示例 #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);

    ?>

以上示例会输出：

    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

### 说明

public function ImagickPixel::getColorAsString(): string

Returns the color of the ImagickPixel object as a string.

### 参数

此函数没有参数。

### 返回值

Returns the color of the ImagickPixel object as a string.

### 示例

示例 #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);
    ?>

以上示例会输出：

    rgb(165,42,42)

### 注释

> 注意: 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

### 说明

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()

### 参数

此函数没有参数。

### 返回值

Returns the color count as an integer on success, throws ImagickPixelException on failure.

### 示例

示例 #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

### 说明

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.

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function ImagickPixel::getColorValue(int `$color`): float

Retrieves the value of the color channel specified, as a floating-point number between 0 and 1.

### 参数

`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).

### 返回值

The value of the channel, as a normalized floating-point number, throwing ImagickPixelException on error.

### 示例

示例 #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;

    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

The quantum value of the color element. Float if ImageMagick was compiled with HDRI, otherwise an int.

### 示例

示例 #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

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Returns the HSL value in an array with the keys "hue", "saturation", and "luminosity". Throws ImagickPixelException on failure.

### 示例

示例 #1 Basic Imagick::getHSL() example

    <?php

    $color = new ImagickPixel('rgb(90%, 10%, 10%)');

    $colorInfo = $color->getHSL();

    print_r($colorInfo);

    ?>

以上示例会输出：

    Array
    (
        [hue] => 0
        [saturation] => 0.80001220740379
        [luminosity] => 0.50000762951095
    )

### 注释

> 注意:

> 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

### 说明

public function ImagickPixel::getIndex(): int

Gets the colormap index of the pixel wand.

### 参数

此函数没有参数。

### 返回值

# ImagickPixel::isPixelSimilar

(PECL imagick 3 >= 3.3.0)

ImagickPixel::isPixelSimilar — Check the distance between this color and another

### 说明

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.

### 参数

`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).

### 返回值

成功时返回 `true`。

# ImagickPixel::isPixelSimilarQuantum

(PECL imagick 3 >= 3.3.0)

ImagickPixel::isPixelSimilarQuantum — Returns whether two colors differ by less than the specified distance

### 说明

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

### 参数

`color`

`fuzz`

### 返回值

# ImagickPixel::isSimilar

(PECL imagick 2, PECL imagick 3)

ImagickPixel::isSimilar — Check the distance between this color and another

### 说明

public function ImagickPixel::isSimilar(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. Deprecated in favour of ImagickPixel::isPixelSimilar().

### 参数

`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).

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function ImagickPixel::setColor(string `$color`): bool
警告

本函数还未编写文档，仅有参数列表。

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.).

### 参数

`color`

  The color definition to use in order to initialise the ImagickPixel object.

### 返回值

Returns `true` if the specified color was set, `false` otherwise.

### 示例

示例 #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

### 说明

public function ImagickPixel::setcolorcount(int `$colorCount`): bool

Sets the color count associated with this color.

### 参数

`colorCount`

### 返回值

成功时返回 `true`。

# ImagickPixel::setColorValue

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColorValue — Sets the normalized value of one of the channels

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 示例

示例 #1 Basic Imagick::setColorValue() usage

    <?php

    $color  = new \ImagickPixel('firebrick');

    $color->setColorValue(Imagick::COLOR_ALPHA, 0.5);

    print_r($color->getcolor(true));
    ?>

以上示例会输出：

    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

### 说明

public function ImagickPixel::setColorValueQuantum(int `$color`, int|float `$value`): bool

Sets the quantum value of a color element of the ImagickPixel.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`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().

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`。

### 示例

示例 #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);

    ?>

以上示例会输出：

    Array
    (
        [r] => 26
        [g] => 230
        [b] => 230
        [a] => 255
    )

### 注释

> 注意:

> 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

### 说明

public function ImagickPixel::setIndex(int `$index`): bool

Sets the colormap index of the pixel wand.

### 参数

`index`

### 返回值

成功时返回 `true`。

## 目录

- 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)

## 简介

## 类摘要

class ImagickPixelException extends Exception implements Throwable {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 方法 */
/* 继承的方法 */
}

# The ImagickPixelIterator class

(PECL imagick 2, PECL imagick 3)

## 类摘要

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

### 说明

public function ImagickPixelIterator::clear(): bool
警告

本函数还未编写文档，仅有参数列表。

Clear resources associated with a PixelIterator.

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function ImagickPixelIterator::__construct(Imagick `$wand`)
警告

本函数还未编写文档，仅有参数列表。

The ImagickPixelIterator constructor

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function ImagickPixelIterator::destroy(): bool
警告

本函数还未编写文档，仅有参数列表。

Deallocates resources associated with a PixelIterator.

### 返回值

成功时返回 `true`。

# ImagickPixelIterator::getCurrentIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getCurrentIteratorRow — Returns the current row of ImagickPixel objects

### 说明

public function ImagickPixelIterator::getCurrentIteratorRow(): array
警告

本函数还未编写文档，仅有参数列表。

Returns the current row as an array of ImagickPixel objects from the pixel iterator.

### 返回值

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

### 说明

public function ImagickPixelIterator::getIteratorRow(): int
警告

本函数还未编写文档，仅有参数列表。

Returns the current pixel iterator row.

### 返回值

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

### 说明

public function ImagickPixelIterator::getNextIteratorRow(): array
警告

本函数还未编写文档，仅有参数列表。

Returns the next row as an array of pixel wands from the pixel iterator.

### 返回值

Returns the next row as an array of ImagickPixel objects, throwing ImagickPixelIteratorException on error.

### 示例

示例 #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

### 说明

public function ImagickPixelIterator::getPreviousIteratorRow(): array
警告

本函数还未编写文档，仅有参数列表。

Returns the previous row as an array of pixel wands from the pixel iterator.

### 返回值

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

### 说明

public function ImagickPixelIterator::newPixelIterator(Imagick `$wand`): bool
警告

本函数还未编写文档，仅有参数列表。

Returns a new pixel iterator.

### 返回值

成功时返回 `true`。 Throwing ImagickPixelIteratorException.

# ImagickPixelIterator::newPixelRegionIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::newPixelRegionIterator — Returns a new pixel iterator

### 说明

public function ImagickPixelIterator::newPixelRegionIterator(
Imagick `$wand`,
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): bool
警告

本函数还未编写文档，仅有参数列表。

Returns a new pixel iterator.

### 参数

`wand`

`x`

`y`

`columns`

`rows`

### 返回值

Returns a new ImagickPixelIterator on success; on failure, throws ImagickPixelIteratorException.

# ImagickPixelIterator::resetIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::resetIterator — Resets the pixel iterator

### 说明

public function ImagickPixelIterator::resetIterator(): bool
警告

本函数还未编写文档，仅有参数列表。

Resets the pixel iterator. Use it in conjunction with ImagickPixelIterator::getNextIteratorRow() to iterate over all the pixels in a pixel container.

### 返回值

成功时返回 `true`。

### 示例

示例 #1 ImagickPixelIterator::resetIterator()

    <?php
    function resetIterator($imagePath) {

        $imagick = new \Imagick(realpath($imagePath));

        $imageIterator = $imagick->getPixelIterator();

        /* Loop trough 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 trough 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

### 说明

public function ImagickPixelIterator::setIteratorFirstRow(): bool
警告

本函数还未编写文档，仅有参数列表。

Sets the pixel iterator to the first pixel row.

### 返回值

成功时返回 `true`。

# ImagickPixelIterator::setIteratorLastRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorLastRow — Sets the pixel iterator to the last pixel row

### 说明

public function ImagickPixelIterator::setIteratorLastRow(): bool
警告

本函数还未编写文档，仅有参数列表。

Sets the pixel iterator to the last pixel row.

### 返回值

成功时返回 `true`。

# ImagickPixelIterator::setIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorRow — Set the pixel iterator row

### 说明

public function ImagickPixelIterator::setIteratorRow(int `$row`): bool
警告

本函数还未编写文档，仅有参数列表。

Set the pixel iterator row.

### 参数

`row`

### 返回值

成功时返回 `true`。

### 示例

示例 #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

### 说明

public function ImagickPixelIterator::syncIterator(): bool
警告

本函数还未编写文档，仅有参数列表。

Syncs the pixel iterator.

### 返回值

成功时返回 `true`。

## 目录

- 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)

## 简介

## 类摘要

class ImagickPixelIteratorException extends Exception implements Throwable {
/* 继承的属性 */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 方法 */
/* 继承的方法 */
}

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
- 预定义常量
- 示例
  - 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 — 把一张图合并到一张图
  - 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 — 截图图片的一块区域
  - Imagick::cropThumbnailImage — 创建缩略图
  - 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 — 把 ImagickDraw 对象渲染到当前图片上
  - 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 — 检查图像是否有 alpha 通道
  - 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 — 获取图像的x,y轴分辨率
  - 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 — 获取图像的分辨率单位
  - 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 — 创建一张图片
  - 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 — Fetch basic attributes about the image
  - 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 — 从二进制字符串里读取图片
  - 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 — 设置图片压缩的类型
  - Imagick::setImageCompressionQuality — 设置图片压缩的质量
  - 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 — 为图片设置指定的格式
  - 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 — 去掉图片的所有配置和设置
  - 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 — 把图片写入指定的文件
  - Imagick::writeImageFile — Writes an image to a filehandle
  - Imagick::writeImages — Writes an image or image sequence
  - Imagick::writeImagesFile — Writes frames to a filehandle
- ImagickDraw — The ImagickDraw class
  - 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 — The ImagickKernel class
  - 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 — The ImagickKernelException class
- ImagickPixel — The ImagickPixel class
  - 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 — The ImagickPixelIterator class
  - 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 — 可交换图像信息
  - 安装/配置
  - 预定义常量
  - Exif 函数
- GD — 图像处理和 GD
  - 安装/配置
  - 预定义常量
  - 示例
  - GD 和图像处理 函数
  - GdImage — GdImage 类
  - GdFont — The GdFont class
- Gmagick
  - 安装/配置
  - 预定义常量
  - 示例
  - Gmagick — The Gmagick class
  - GmagickDraw — The GmagickDraw class
  - GmagickPixel — The GmagickPixel class
- ImageMagick — 图像处理(ImageMagick)
  - 安装/配置
  - 预定义常量
  - 示例
  - Imagick — The Imagick class
  - ImagickDraw — The ImagickDraw class
  - ImagickDrawException — The ImagickDrawException class
  - ImagickException — The ImagickException class
  - ImagickKernel — The ImagickKernel class
  - ImagickKernelException — The ImagickKernelException class
  - ImagickPixel — The ImagickPixel class
  - ImagickPixelException — The ImagickPixelException class
  - ImagickPixelIterator — The ImagickPixelIterator class
  - ImagickPixelIteratorException — The ImagickPixelIteratorException class

# 邮件相关扩展

# IMAP, POP3 和 NNTP

# 简介

警告

此扩展自 PHP 8.4.0 起弃用并且不再捆绑。

这些函数提供了可以操作 IMAP 以及 NNTP，POP3 和本地邮箱的方法。

注意，有些 IMAP 函数在 POP3 协议下将不能正常的工作。

警告

IMAP 扩展不是线程安全的；它不应该被用于 ZTS 构建。

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置
- 资源类型

## 需求

This extension requires the c-client library to be installed. Grab the latest version from » https://github.com/uw-imap/imap and compile it.

It's important that you do not copy the IMAP source files directly into the system include directory as there may be conflicts. Instead, create a new directory inside the system include directory, such as /usr/local/imap-2000b/ (location and name depend on your setup and IMAP version), and inside this new directory create additional directories named lib/ and include/. From the c-client directory from your IMAP source tree, copy all the *.h files into include/ and all the *.c files into lib/. Additionally when you compiled IMAP, a file named c-client.a was created. Also put this in the lib/ directory but rename it as libc-client.a.

> 注意:

> To build the c-client library with SSL or/and Kerberos support read the docs supplied with the package.

> 注意: In Mandrake Linux, the IMAP library (libc-client.a) is compiled without Kerberos support. A separate version with SSL (client-PHP4.a) is installed. The library must be recompiled in order to add Kerberos support.

## 安装

## PHP 8.4

此扩展已被移至 » PECL 资源库；不再与 PHP 捆绑，从 PHP 8.4.0

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/imap。

## PHP < 8.4

要使这些函数生效，必须在编译 PHP 的时候添加 --with-imap[=DIR] 选项, DIR 表示 c-client 安装前缀。比如上面提到的例子中，可以使用 --with-imap=/usr/local/imap-2000b。根据以上描述，这个路径是指向你先前创建的文件夹。对于 Windows 用户，应该在 php.ini 文件中引入php_imap.dll。

> 注意: 因为取决于 c-client 是如何配置的，所以应该向 PHP 配置行添加 --with-imap-ssl=/path/to/openssl/ 或者 --with-kerberos=/path/to/kerberos 配置信息。

警告

IMAP 扩展不是线程安全的；它不应该被用于 ZTS 构建。

警告

IMAP，recode，和 YAZ 扩展不能同时使用，因为它们共享了相同 的内部符号。注意：Yaz 2.0 及以上版本不存在此问题。

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

IMAP 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
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.

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`imap.enable_insecure_rsh` bool

  Establishing a connection to a server may invoke rsh or ssh commands, unless this php.ini option is disabled.

  警告

  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.

## 资源类型

Prior to PHP 8.1.0, this extension defined the resource type `imap` as returned by imap_open() references an opened IMAP stream.

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`NIL` (int)
  Deprecated as of PHP 8.1.0.
`OP_DEBUG` (int)
`OP_READONLY` (int)
  Open mailbox read-only
`OP_ANONYMOUS` (int)
  Don't use or update a .newsrc for news (NNTP only)
`OP_SHORTCACHE` (int)
`OP_SILENT` (int)
`OP_PROTOTYPE` (int)
`OP_HALFOPEN` (int)
  For IMAP and NNTP names, open a connection but don't open a mailbox.
`OP_EXPUNGE` (int)
`OP_SECURE` (int)
`CL_EXPUNGE` (int)
  silently expunge the mailbox before closing when calling imap_close()
`FT_UID` (int)
  The parameter is a UID
`FT_PEEK` (int)
  Do not set the \Seen flag if not already set
`FT_NOT` (int)
`FT_INTERNAL` (int)
  The return string is in internal format, will not canonicalize to CRLF.
`FT_PREFETCHTEXT` (int)
`ST_UID` (int)
  The sequence argument contains UIDs instead of sequence numbers
`ST_SILENT` (int)
`ST_SET` (int)
`CP_UID` (int)
  the sequence numbers contain UIDS
`CP_MOVE` (int)
  Delete the messages from the current mailbox after copying with imap_mail_copy()
`SE_UID` (int)
  Return UIDs instead of sequence numbers
`SE_FREE` (int)
`SE_NOPREFETCH` (int)
  Don't prefetch searched messages
`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)
  This mailbox has no "children" (there are no mailboxes below this one).
`LATT_NOSELECT` (int)
  This is only a container, not a mailbox - you cannot open it.
`LATT_MARKED` (int)
  This mailbox is marked. Only used by UW-IMAPD.
`LATT_UNMARKED` (int)
  This mailbox is not marked. Only used by UW-IMAPD.
`LATT_REFERRAL` (int)
  This container has a referral to a remote mailbox.
`LATT_HASCHILDREN` (int)
  This mailbox has selectable inferiors.
`LATT_HASNOCHILDREN` (int)
  This mailbox has no selectable inferiors.
`SORTDATE` (int)
  Sort criteria for imap_sort(): message Date
`SORTARRIVAL` (int)
  Sort criteria for imap_sort(): arrival date
`SORTFROM` (int)
  Sort criteria for imap_sort(): mailbox in first From address
`SORTSUBJECT` (int)
  Sort criteria for imap_sort(): message subject
`SORTTO` (int)
  Sort criteria for imap_sort(): mailbox in first To address
`SORTCC` (int)
  Sort criteria for imap_sort(): mailbox in first cc address
`SORTSIZE` (int)
  Sort criteria for imap_sort(): size of message in octets
`TYPETEXT` (int)
  Primary body type: unformatted text
`TYPEMULTIPART` (int)
  Primary body type: multiple part
`TYPEMESSAGE` (int)
  Primary body type: encapsulated message
`TYPEAPPLICATION` (int)
  Primary body type: application data
`TYPEAUDIO` (int)
  Primary body type: audio
`TYPEIMAGE` (int)
  Primary body type: static image
`TYPEVIDEO` (int)
  Primary body type: video
`TYPEMODEL` (int)
  Primary body type: model
`TYPEOTHER` (int)
  Primary body type: unknown
`ENC7BIT` (int)
  Body encoding: 7 bit SMTP semantic data
`ENC8BIT` (int)
  Body encoding: 8 bit SMTP semantic data
`ENCBINARY` (int)
  Body encoding: 8 bit binary data
`ENCBASE64` (int)
  Body encoding: base-64 encoded data
`ENCQUOTEDPRINTABLE` (int)
  Body encoding: human-readable 8-as-7 bit data
`ENCOTHER` (int)
  Body encoding: unknown
`IMAP_OPENTIMEOUT` (int)
`IMAP_READTIMEOUT` (int)
`IMAP_WRITETIMEOUT` (int)
`IMAP_CLOSETIMEOUT` (int)
`IMAP_GC_ELT` (int)
  Garbage collector, clear message cache elements.
`IMAP_GC_ENV` (int)
  Garbage collector, clear envelopes and bodies.
`IMAP_GC_TEXTS` (int)
  Garbage collector, clear texts.

# IMAP 函数

# 参见

This document can't go into detail on all the topics touched by the provided functions. Further information is provided by the documentation of the c-client library source (docs/internal.txt). and the following RFC documents:

- » 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).

A detailed overview is also available in the books » `Programming Internet Email` by David Wood and » Managing IMAP by Dianna Mullet & Kevin Mullet.

# imap_8bit

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_8bit — Convert an 8bit string to a quoted-printable string

### 说明

function imap_8bit(string `$string`): string|false

Convert an 8bit string to a quoted-printable string (according to » RFC2045, section 6.7).

### 参数

`string`

  The 8bit string to convert

### 返回值

Returns a quoted-printable string, 或者在失败时返回 `false`.

### 参见

- imap_qprint() - Convert a quoted-printable string to an 8 bit string

# imap_alerts

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_alerts — Returns all IMAP alert messages that have occurred

### 说明

function imap_alerts(): array|false

Returns all of the IMAP alert messages generated since the last imap_alerts() call, or the beginning of the page.

When imap_alerts() is called, the alert stack is subsequently cleared. The IMAP specification requires that these messages be passed to the user.

### 参数

此函数没有参数。

### 返回值

Returns an array of all of the IMAP alert messages generated or `false` if no alert messages are available.

### 参见

- imap_errors() - Returns all of the IMAP errors that have occurred

# imap_append

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_append — Append a string message to a specified mailbox

### 说明

function imap_append(
IMAP\Connection `$imap`,
string `$folder`,
string `$message`,
?string `$options` = `null`,
?string `$internal_date` = `null`
): bool

Appends a string `message` to the specified `folder`.

### 参数

`imap`
  IMAP\Connection 实例。
`folder`

  The mailbox name, see imap_open() for more information

  警告

  Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

`message`

  The message to be append, as a string

  When talking to the Cyrus IMAP server, you must use "\r\n" as your end-of-line terminator instead of "\n" or the operation will fail

`options`

  If provided, the `options` will also be written to the `folder`

`internal_date`

  If this parameter is set, it will set the INTERNALDATE on the appended message. The parameter should be a date string that conforms to the rfc2060 specifications for a date_time value.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。
8.0.0 | `options` and `internal_date` are now nullable.

### 示例

示例 #1 imap_append() example

    <?php
    $imap = imap_open("{imap.example.org}INBOX.Drafts", "username", "password");

    $check = imap_check($imap);
    echo "Msg Count before append: ". $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 "Msg Count after append : ". $check->Nmsgs . "\n";

    imap_close($imap);
    ?>

# imap_base64

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_base64 — Decode BASE64 encoded text

### 说明

function imap_base64(string `$string`): string|false

Decodes the given BASE-64 encoded `string`.

### 参数

`string`

  The encoded text

### 返回值

Returns the decoded message as a string, 或者在失败时返回 `false`.

### 参见

- imap_binary() - Convert an 8bit string to a base64 string
- base64_encode() - 使用 MIME base64 对数据进行编码
- base64_decode() - 对使用 MIME base64 编码的数据进行解码
- » RFC2045, Section 6.8

# imap_binary

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_binary — Convert an 8bit string to a base64 string

### 说明

function imap_binary(string `$string`): string|false

Convert an 8bit string to a base64 string according to » RFC2045, Section 6.8.

### 参数

`string`

  The 8bit string

### 返回值

Returns a base64 encoded string, 或者在失败时返回 `false`.

### 参见

- imap_base64() - Decode BASE64 encoded text

# imap_body

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_body — Read the message body

### 说明

function imap_body(IMAP\Connection `$imap`, int `$message_num`, int `$flags` = 0): string|false

imap_body() returns the body of the message, numbered `message_num` in the current mailbox.

imap_body() will only return a verbatim copy of the message body. To extract single parts of a multipart MIME-encoded message you have to use imap_fetchstructure() to analyze its structure and imap_fetchbody() to extract a copy of a single body component.

### 参数

`imap`
  IMAP\Connection 实例。
`message_num`

  The message number

`flags`

  The optional `flags` are a bit mask 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.

### 返回值

Returns the body of the specified message, as a string, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

# imap_bodystruct

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_bodystruct — Read the structure of a specified body section of a specific message

### 说明

function imap_bodystruct(IMAP\Connection `$imap`, int `$message_num`, string `$section`): stdClass|false

Read the structure of a specified body section of a specific message.

### 参数

`imap`
  IMAP\Connection 实例。
`message_num`

  The message number

`section`

  The body section to read

### 返回值

Returns the information in an object, 或者在失败时返回 `false`. For a detailed description of the object structure and properties see imap_fetchstructure().

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 参见

- imap_fetchstructure() - Read the structure of a particular message

# imap_check

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_check — Check current mailbox

### 说明

function imap_check(IMAP\Connection `$imap`): stdClass|false

Checks information about the current mailbox.

### 参数

`imap`
  IMAP\Connection 实例。

### 返回值

Returns the information in an object with following properties:

- `Date` - current system time formatted according to » RFC2822
- `Driver` - protocol used to access this mailbox: POP3, IMAP, NNTP
- `Mailbox` - the mailbox name
- `Nmsgs` - number of messages in the mailbox
- `Recent` - number of recent messages in the mailbox

Returns `false` on failure.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 示例

示例 #1 imap_check() example

    <?php

    $imap = imap_check($imap_stream);
    var_dump($imap);

    ?>

以上示例的输出类似于：

    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 — Clears flags on messages

### 说明

function imap_clearflag_full(
IMAP\Connection `$imap`,
string `$sequence`,
string `$flag`,
int `$options` = 0
): true

This function causes a store to delete the specified `flag` to the flags set for the messages in the specified `sequence`.

### 参数

`imap`
  IMAP\Connection 实例。
`sequence`

  A sequence of message numbers. You can enumerate desired messages with the `X,Y` syntax, or retrieve all messages within an interval with the `X:Y` syntax

`flag`

  The flags which you can unset are "\\Seen", "\\Answered", "\\Flagged", "\\Deleted", and "\\Draft" (as defined by » RFC2060)

`options`

  `options` are a bit mask and may contain the single option:

  - `ST_UID` - The sequence argument contains UIDs instead of sequence numbers

### 返回值

总是返回 `true`。

### 错误／异常

Throws a ValueError if `options` is invalid.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。
8.0.0 | A ValueError is now thrown on invalid `options` parameter values. Previously, a warning was emitted and the function returned `false`.

### 参见

- imap_setflag_full() - Sets flags on messages

# imap_close

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_close — Close an IMAP stream

### 说明

function imap_close(IMAP\Connection `$imap`, int `$flags` = 0): true

Closes the imap stream.

### 参数

`imap`
  IMAP\Connection 实例。
`flags`

  If set to `CL_EXPUNGE`, the function will silently expunge the mailbox before closing, removing all messages marked for deletion. You can achieve the same thing by using imap_expunge()

### 返回值

总是返回 `true`。

### 错误／异常

Throws a ValueError if `flags` is invalid.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。
8.0.0 | A ValueError is now thrown on invalid `flags` parameter values. Previously, a warning was emitted and the function returned `false`.

### 参见

- imap_open() - Open an IMAP stream to a mailbox

# imap_create

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_create — 别名 imap_createmailbox()

### 说明

此函数是该函数的别名： imap_createmailbox().

# imap_createmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_createmailbox — Create a new mailbox

### 说明

function imap_createmailbox(IMAP\Connection `$imap`, string `$mailbox`): bool

Creates a new mailbox specified by `mailbox`.

### 参数

`imap`
  IMAP\Connection 实例。
`mailbox`

  The mailbox name, see imap_open() for more information. Names containing international characters should be encoded by imap_utf7_encode()

  警告

  Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 示例

示例 #1 imap_createmailbox() example

    <?php
    $mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
         or die("can't connect: " . imap_last_error());

    $name1 = "phpnewbox";
    $name2 = imap_utf7_encode("phpnewböx"); // phpnewb&w7Y-x

    $newname = $name1;

    echo "Newname will be '$name1'<br />\n";

    // we will now create a new mailbox "phptestbox" in your inbox folder,
    // check its status after creation and finally remove it to restore
    // your inbox to its initial state

    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 "your new mailbox '$name1' has the following status:<br />\n";
            echo "Messages:   " . $status->messages    . "<br />\n";
            echo "Recent:     " . $status->recent      . "<br />\n";
            echo "Unseen:     " . $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 "renamed new mailbox from '$name1' to '$name2'<br />\n";
                $newname = $name2;
            } else {
                echo "imap_renamemailbox on new mailbox failed: " . imap_last_error() . "<br />\n";
            }
        } else {
            echo "imap_status on new mailbox failed: " . imap_last_error() . "<br />\n";
        }

        if (@imap_deletemailbox($mbox, "{imap.example.org}INBOX.$newname")) {
            echo "new mailbox removed to restore initial state<br />\n";
        } else {
            echo "imap_deletemailbox on new mailbox failed: " . implode("<br />\n", imap_errors()) . "<br />\n";
        }

    } else {
        echo "could not create new mailbox: " . implode("<br />\n", imap_errors()) . "<br />\n";
    }

    imap_close($mbox);
    ?>

### 参见

- imap_renamemailbox() - Rename an old mailbox to new mailbox
- imap_deletemailbox() - Delete a mailbox

# imap_delete

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_delete — Mark a message for deletion from current mailbox

### 说明

function imap_delete(IMAP\Connection `$imap`, string `$message_nums`, int `$flags` = 0): true

Marks messages listed in `message_nums` for deletion. Messages marked for deletion will stay in the mailbox until either imap_expunge() is called or imap_close() is called with the optional parameter `CL_EXPUNGE`.

### 参数

`imap`
  IMAP\Connection 实例。
`message_nums`

  A string representing one or more messages in IMAP4-style sequence format (`"n"`, `"n:m"`, or combination of these delimited by commas).

`flags`

  You can set the `FT_UID` which tells the function to treat the `message_nums` argument as a `UID`.

### 返回值

总是返回 `true`。

### 错误／异常

Throws a ValueError if `flags` is invalid.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。
8.0.0 | A ValueError is now thrown on invalid `flags` parameter values. Previously, a warning was emitted and the function returned `false`.

### 示例

示例 #1 imap_delete() example

    <?php

    $mbox = imap_open("{imap.example.org}INBOX", "username", "password")
        or die("Can't connect: " . imap_last_error());

    $check = imap_mailboxmsginfo($mbox);
    echo "Messages before delete: " . $check->Nmsgs . "<br />\n";

    imap_delete($mbox, 1);

    $check = imap_mailboxmsginfo($mbox);
    echo "Messages after  delete: " . $check->Nmsgs . "<br />\n";

    imap_expunge($mbox);

    $check = imap_mailboxmsginfo($mbox);
    echo "Messages after expunge: " . $check->Nmsgs . "<br />\n";

    imap_close($mbox);
    ?>

### 注释

> 注意:

> IMAP mailboxes may not have their message flags saved between connections, so imap_expunge() should be called during the same connection in order to guarantee that messages marked for deletion will actually be purged.

### 参见

- imap_undelete() - Unmark the message which is marked deleted
- imap_expunge() - Delete all messages marked for deletion
- imap_close() - Close an IMAP stream

# imap_deletemailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_deletemailbox — Delete a mailbox

### 说明

function imap_deletemailbox(IMAP\Connection `$imap`, string `$mailbox`): bool

Deletes the specified `mailbox`.

### 参数

`imap`
  IMAP\Connection 实例。
`mailbox`

  The mailbox name, see imap_open() for more information

  警告

  Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 参见

- imap_createmailbox() - Create a new mailbox
- imap_renamemailbox() - Rename an old mailbox to new mailbox
- imap_open() - Open an IMAP stream to a mailbox for the format of `mbox`

# imap_errors

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_errors — Returns all of the IMAP errors that have occurred

### 说明

function imap_errors(): array|false

Gets all of the IMAP errors (if any) that have occurred during this page request or since the error stack was reset.

When imap_errors() is called, the error stack is subsequently cleared.

### 参数

此函数没有参数。

### 返回值

This function returns an array of all of the IMAP error messages generated since the last imap_errors() call, or the beginning of the page. Returns `false` if no error messages are available.

### 参见

- imap_last_error() - Gets the last IMAP error that occurred during this page request
- imap_alerts() - Returns all IMAP alert messages that have occurred

# imap_expunge

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_expunge — Delete all messages marked for deletion

### 说明

function imap_expunge(IMAP\Connection `$imap`): true

Deletes all the messages marked for deletion by imap_delete(), imap_mail_move(), or imap_setflag_full().

### 参数

`imap`
  IMAP\Connection 实例。

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

# imap_fetch_overview

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetch_overview — Read an overview of the information in the headers of the given message

### 说明

function imap_fetch_overview(IMAP\Connection `$imap`, string `$sequence`, int `$flags` = 0): array|false

This function fetches mail headers for the given `sequence` and returns an overview of their contents.

### 参数

`imap`
  IMAP\Connection 实例。
`sequence`

  A message sequence description. You can enumerate desired messages with the `X,Y` syntax, or retrieve all messages within an interval with the `X:Y` syntax

`flags`

  `sequence` will contain a sequence of message indices or UIDs, if this parameter is set to `FT_UID`.

### 返回值

Returns an array of objects describing one message header each. The object will only define a property if it exists. The possible properties are:

- `subject` - the messages subject
- `from` - who sent it
- `to` - recipient
- `date` - when was it sent
- `message_id` - Message-ID
- `references` - is a reference to this message id
- `in_reply_to` - is a reply to this message id
- `size` - size in bytes
- `uid` - UID the message has in the mailbox
- `msgno` - message sequence number in the mailbox
- `recent` - this message is flagged as recent
- `flagged` - this message is flagged
- `answered` - this message is flagged as answered
- `deleted` - this message is flagged for deletion
- `seen` - this message is flagged as already read
- `draft` - this message is flagged as being a draft
- `udate` - the UNIX timestamp of the arrival date

The function returns `false` on failure.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 示例

示例 #1 imap_fetch_overview() example

    <?php
    $mbox = imap_open("{imap.example.org:143}INBOX", "username", "password")
         or die("can't connect: " . imap_last_error());

    $MC = imap_check($mbox);

    // Fetch an overview for all messages in INBOX
    $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);
    ?>

### 参见

- imap_fetchheader() - Returns header for a message

# imap_fetchbody

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchbody — Fetch a particular section of the body of the message

### 说明

function imap_fetchbody(
IMAP\Connection `$imap`,
int `$message_num`,
string `$section`,
int `$flags` = 0
): string|false

Fetch of a particular section of the body of the specified messages. Body parts are not decoded by this function.

### 参数

`imap`
  IMAP\Connection 实例。
`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.

### 返回值

Returns a particular section of the body of the specified messages as a text string, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 参见

- imap_savebody() - Save a specific body section to a file
- imap_fetchstructure() - Read the structure of a particular message

# imap_fetchheader

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchheader — Returns header for a message

### 说明

function imap_fetchheader(IMAP\Connection `$imap`, int `$message_num`, int `$flags` = 0): string|false

This function causes a fetch of the complete, unfiltered » RFC2822 format header of the specified message.

### 参数

`imap`
  IMAP\Connection 实例。
`message_num`

  The message number

`flags`

  The possible `flags` are:

  - `FT_UID` - The `message_num` argument is a UID
  - `FT_INTERNAL` - The return string is in "internal" format, without any attempt to canonicalize to CRLF newlines
  - `FT_PREFETCHTEXT` - The RFC822.TEXT should be pre-fetched at the same time. This avoids an extra RTT on an IMAP connection if a full message text is desired (e.g. in a "save to local file" operation)

### 返回值

Returns the header of the specified message as a text string, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 参见

- imap_fetch_overview() - Read an overview of the information in the headers of the given message

# imap_fetchmime

(PHP 5 >= 5.3.6, PHP 7, PHP 8)

imap_fetchmime — Fetch MIME headers for a particular section of the message

### 说明

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.

### 参数

`imap`
  IMAP\Connection 实例。
`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.

### 返回值

Returns the MIME headers of a particular section of the body of the specified messages as a text string, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 参见

- imap_fetchbody() - Fetch a particular section of the body of the message
- imap_fetchstructure() - Read the structure of a particular message
- imap_fetchheader() - Returns header for a message

# imap_fetchstructure

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchstructure — Read the structure of a particular message

### 说明

function imap_fetchstructure(IMAP\Connection `$imap`, int `$message_num`, int `$flags` = 0): stdClass|false

Fetches all the structured information for a given message.

### 参数

`imap`
  IMAP\Connection 实例。
`message_num`

  The message number

`flags`

  This optional parameter only has a single option, `FT_UID`, which tells the function to treat the `message_num` argument as a `UID`.

### 返回值

Returns an object with properties listed in the table below, 或者在失败时返回 `false`.

Returned Object for imap_fetchstructure()
type | Primary body type
encoding | Body transfer encoding
ifsubtype | `true` if there is a subtype string
subtype | MIME subtype
ifdescription | `true` if there is a description string
description | Content description string
ifid | `true` if there is an identification string
id | Identification string
lines | Number of lines
bytes | Number of bytes
ifdisposition | `true` if there is a disposition string
disposition | Disposition string
ifdparameters | `true` if the dparameters array exists
dparameters | An array of objects where each object has an `"attribute"` and a `"value"` property corresponding to the parameters on the `Content-disposition` MIME header.
ifparameters | `true` if the parameters array exists
parameters | An array of objects where each object has an `"attribute"` and a `"value"` property.
parts | An array of objects identical in structure to the top-level object, each of which corresponds to a MIME body part.

Primary body type (value may vary with used library, use of constants is recommended)
Value | Type | Constant
--- | --- | ---
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

Transfer encodings (value may vary with used library, use of constants is recommended)
Value | Type | Constant
--- | --- | ---
0 | 7bit | ENC7BIT
1 | 8bit | ENC8BIT
2 | Binary | ENCBINARY
3 | Base64 | ENCBASE64
4 | Quoted-Printable | ENCQUOTEDPRINTABLE
5 | other | ENCOTHER

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 参见

- imap_fetchbody() - Fetch a particular section of the body of the message
- imap_bodystruct() - Read the structure of a specified body section of a specific message

# imap_fetchtext

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchtext — 别名 imap_body()

### 说明

此函数是该函数的别名： imap_body().

# imap_gc

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_gc — Clears IMAP cache

### 说明

function imap_gc(IMAP\Connection `$imap`, int `$flags`): true

Purges the cache of entries of a specific type.

### 参数

`imap`
  IMAP\Connection 实例。
`flags`

  Specifies the cache to purge. It may one or a combination of the following constants: `IMAP_GC_ELT` (message cache elements), `IMAP_GC_ENV` (envelope and bodies), `IMAP_GC_TEXTS` (texts).

### 返回值

总是返回 `true`。

### 错误／异常

Throws a ValueError if `flags` is invalid.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。
8.0.0 | A ValueError is now thrown on invalid `flags` parameter values. Previously, a warning was emitted and the function returned `false`.

### 示例

示例 #1 imap_gc() example

    <?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 — Retrieve the quota level settings, and usage statics per mailbox

### 说明

function imap_get_quota(IMAP\Connection `$imap`, string `$quota_root`): array|false

Retrieve the quota level settings, and usage statics per mailbox.

For a non-admin user version of this function, please see the imap_get_quotaroot() function of PHP.

### 参数

`imap`
  IMAP\Connection 实例。
`quota_root`

  `quota_root` should normally be in the form of `user.name` where name is the mailbox you wish to retrieve information about.

### 返回值

Returns an array with integer values limit and usage for the given mailbox. The value of limit represents the total amount of space allowed for this mailbox. The usage value represents the mailboxes current level of capacity. Will return `false` in the case of failure.

As of PHP 4.3, the function more properly reflects the functionality as dictated by the » RFC2087. The array return value has changed to support an unlimited number of returned resources (i.e. messages, or sub-folders) with each named resource receiving an individual array key. Each key value then contains an another array with the usage and limit values within it.

For backwards compatibility reasons, the original access methods are still available for use, although it is suggested to update.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 示例

示例 #1 imap_get_quota() example

    <?php
    $mbox = imap_open("{imap.example.org}", "mailadmin", "password", OP_HALFOPEN)
          or die("can't connect: " . imap_last_error());

    $quota_value = imap_get_quota($mbox, "user.kalowsky");
    if (is_array($quota_value)) {
        echo "Usage level is: " . $quota_value['usage'];
        echo "Limit level is: " . $quota_value['limit'];
    }

    imap_close($mbox);
    ?>

示例 #2 imap_get_quota() 4.3 or greater example

    <?php
    $mbox = imap_open("{imap.example.org}", "mailadmin", "password", OP_HALFOPEN)
          or die("can't connect: " . imap_last_error());

    $quota_values = imap_get_quota($mbox, "user.kalowsky");
    if (is_array($quota_values)) {
       $storage = $quota_values['STORAGE'];
       echo "STORAGE usage level is: " .  $storage['usage'];
       echo "STORAGE limit level is: " .  $storage['limit'];

       $message = $quota_values['MESSAGE'];
       echo "MESSAGE usage level is: " .  $message['usage'];
       echo "MESSAGE limit is: " .  $message['limit'];

       /* ...  */
    }

    imap_close($mbox);
    ?>

### 注释

This function is currently only available to users of the c-client2000 or greater library.

The given `imap` must be opened as the mail administrator, otherwise this function will fail.

### 参见

- imap_open() - Open an IMAP stream to a mailbox
- imap_set_quota() - Sets a quota for a given mailbox
- imap_get_quotaroot() - Retrieve the quota settings per user

# imap_get_quotaroot

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imap_get_quotaroot — Retrieve the quota settings per user

### 说明

function imap_get_quotaroot(IMAP\Connection `$imap`, string `$mailbox`): array|false

Retrieve the quota settings per user. The limit value represents the total amount of space allowed for this user's total mailbox usage. The usage value represents the user's current total mailbox capacity.

### 参数

`imap`
  IMAP\Connection 实例。
`mailbox`

  `mailbox` should normally be in the form of which mailbox (i.e. INBOX).

### 返回值

Returns an array of integer values pertaining to the specified user mailbox. All values contain a key based upon the resource name, and a corresponding array with the usage and limit values within.

This function will return `false` in the case of call failure, and an array of information about the connection upon an un-parsable response from the server.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 示例

示例 #1 imap_get_quotaroot() example

    <?php
    $mbox = imap_open("{imap.example.org}", "kalowsky", "password", OP_HALFOPEN)
          or die("can't connect: " . imap_last_error());

    $quota = imap_get_quotaroot($mbox, "INBOX");
    if (is_array($quota)) {
       $storage = $quota['STORAGE'];
       echo "STORAGE usage level is: " .  $storage['usage'];
       echo "STORAGE limit level is: " .  $storage['limit'];

       $message = $quota['MESSAGE'];
       echo "MESSAGE usage level is: " .  $message['usage'];
       echo "MESSAGE limit level is: " .  $message['limit'];

       /* ...  */

    }

    imap_close($mbox);
    ?>

### 注释

This function is currently only available to users of the c-client2000 or greater library.

The `imap` should be opened as the user whose mailbox you wish to check.

### 参见

- imap_open() - Open an IMAP stream to a mailbox
- imap_set_quota() - Sets a quota for a given mailbox
- imap_get_quota() - Retrieve the quota level settings, and usage statics per mailbox

# imap_getacl

(PHP 5, PHP 7, PHP 8)

imap_getacl — Gets the ACL for a given mailbox

### 说明

function imap_getacl(IMAP\Connection `$imap`, string `$mailbox`): array|false

Gets the ACL for a given mailbox.

### 参数

`imap`
  IMAP\Connection 实例。
`mailbox`

  The mailbox name, see imap_open() for more information

  警告

  Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

### 返回值

Returns an associative array of "folder" => "acl" pairs, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 示例

示例 #1 imap_getacl() example

    <?php

    print_r(imap_getacl($imap, 'user.joecool'));

    ?>

以上示例的输出类似于：

    Array
    (
        [asubfolder] => lrswipcda
        [anothersubfolder] => lrswipcda
    )

### 注释

This function is currently only available to users of the c-client2000 or greater library.

### 参见

- imap_setacl() - Sets the ACL for a given mailbox

# imap_getmailboxes

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_getmailboxes — Read the list of mailboxes, returning detailed information on each one

### 说明

function imap_getmailboxes(IMAP\Connection `$imap`, string `$reference`, string `$pattern`): array|false

Gets information on the mailboxes.

### 参数

`imap`
  IMAP\Connection 实例。
`reference`

  `reference` should normally be just the server specification as described in imap_open()

  警告

  Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

`pattern`
  指定在邮箱层级的何处开始查找。 在组成 `pattern` 的字符中可使用两个特殊字符： '`*`' 和 '`%`'。 '`*`' 是指返回所有邮箱目录. 如果将 '`*`' 作为 `pattern` 参数时, 则会返回整个邮箱层级结构。 '`%`' 是指只返回当前级次。 '`%`' 作为 `pattern` 参数则只会返回顶层邮箱； '`~/mail/%`' 用于 `UW_IMAPD` 则会返回名为 ~/mail 的目录, 但不包含其子目录。

### 返回值

Returns an array of objects containing mailbox information. Each object has the attributes `name`, specifying the full name of the mailbox; `delimiter`, which is the hierarchy delimiter for the part of the hierarchy this mailbox is in; and `attributes`. `Attributes` is a bitmask that can be tested against:

- `LATT_NOINFERIORS` - This mailbox not contains, and may not contain any "children" (there are no mailboxes below this one). Calling imap_createmailbox() will not work on this mailbox.

- `LATT_NOSELECT` - This is only a container, not a mailbox - you cannot open it.

- `LATT_MARKED` - This mailbox is marked. This means that it may contain new messages since the last time it was checked. Not provided by all IMAP servers.

- `LATT_UNMARKED` - This mailbox is not marked, does not contain new messages. If either `MARKED` or `UNMARKED` is provided, you can assume the IMAP server supports this feature for this mailbox.

- `LATT_REFERRAL` - This container has a referral to a remote mailbox.

- `LATT_HASCHILDREN` - This mailbox has selectable inferiors.

- `LATT_HASNOCHILDREN` - This mailbox has no selectable inferiors.

The function returns `false` on failure.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 示例

示例 #1 imap_getmailboxes() example

    <?php
    $mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
          or die("can't connect: " . 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 failed: " . imap_last_error() . "\n";
    }

    imap_close($mbox);
    ?>

### 参见

- imap_getsubscribed() - List all the subscribed mailboxes

# imap_getsubscribed

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_getsubscribed — List all the subscribed mailboxes

### 说明

function imap_getsubscribed(IMAP\Connection `$imap`, string `$reference`, string `$pattern`): array|false

Gets information about the subscribed mailboxes.

Identical to imap_getmailboxes(), except that it only returns mailboxes that the user is subscribed to.

### 参数

`imap`
  IMAP\Connection 实例。
`reference`

  `reference` should normally be just the server specification as described in imap_open()

  警告

  Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

`pattern`
  指定在邮箱层级的何处开始查找。 在组成 `pattern` 的字符中可使用两个特殊字符： '`*`' 和 '`%`'。 '`*`' 是指返回所有邮箱目录. 如果将 '`*`' 作为 `pattern` 参数时, 则会返回整个邮箱层级结构。 '`%`' 是指只返回当前级次。 '`%`' 作为 `pattern` 参数则只会返回顶层邮箱； '`~/mail/%`' 用于 `UW_IMAPD` 则会返回名为 ~/mail 的目录, 但不包含其子目录。

### 返回值

Returns an array of objects containing mailbox information. Each object has the attributes `name`, specifying the full name of the mailbox; `delimiter`, which is the hierarchy delimiter for the part of the hierarchy this mailbox is in; and `attributes`. `Attributes` is a bitmask that can be tested against:

- `LATT_NOINFERIORS` - This mailbox has no "children" (there are no mailboxes below this one).
- `LATT_NOSELECT` - This is only a container, not a mailbox - you cannot open it.
- `LATT_MARKED` - This mailbox is marked. Only used by UW-IMAPD.
- `LATT_UNMARKED` - This mailbox is not marked. Only used by UW-IMAPD.
- `LATT_REFERRAL` - This container has a referral to a remote mailbox.
- `LATT_HASCHILDREN` - This mailbox has selectable inferiors.
- `LATT_HASNOCHILDREN` - This mailbox has no selectable inferiors.

The function returns `false` on failure.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

# imap_header

(PHP 4, PHP 5, PHP 7)

imap_header — 别名 imap_headerinfo()

警告

该别名已在 PHP 8.0.0 中被 移除。

### 说明

此函数是该函数的别名： imap_headerinfo().

# imap_headerinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_headerinfo — Read the header of the message

### 说明

function imap_headerinfo(
IMAP\Connection `$imap`,
int `$message_num`,
int `$from_length` = 0,
int `$subject_length` = 0
): stdClass|false

Gets information about the given message number by reading its headers.

### 参数

`imap`
  IMAP\Connection 实例。
`message_num`

  The message number

`from_length`

  Number of characters for the `fetchfrom` property. Must be greater than or equal to zero.

`subject_length`

  Number of characters for the `fetchsubject` property Must be greater than or equal to zero.

### 返回值

Returns `false` on error or, if successful, the information in an object with following properties:

- toaddress - full to: line, up to 1024 characters
- to - an array of objects from the To: line, with the following properties: `personal`, `adl`, `mailbox`, and `host`
- fromaddress - full from: line, up to 1024 characters
- from - an array of objects from the From: line, with the following properties: `personal`, `adl`, `mailbox`, and `host`
- ccaddress - full cc: line, up to 1024 characters
- cc - an array of objects from the Cc: line, with the following properties: `personal`, `adl`, `mailbox`, and `host`
- bccaddress - full bcc: line, up to 1024 characters
- bcc - an array of objects from the Bcc: line, with the following properties: `personal`, `adl`, `mailbox`, and `host`
- reply_toaddress - full Reply-To: line, up to 1024 characters
- reply_to - an array of objects from the Reply-To: line, with the following properties: `personal`, `adl`, `mailbox`, and `host`
- senderaddress - full sender: line, up to 1024 characters
- sender - an array of objects from the Sender: line, with the following properties: `personal`, `adl`, `mailbox`, and `host`
- return_pathaddress - full Return-Path: line, up to 1024 characters
- return_path - an array of objects from the Return-Path: line, with the following properties: `personal`, `adl`, `mailbox`, and `host`
- remail -
- date - The message date as found in its headers
- Date - Same as date
- subject - The message subject
- Subject - Same as subject
- in_reply_to -
- message_id -
- newsgroups -
- followup_to -
- references -
- Recent - `R` if recent and seen, `N` if recent and not seen, ' ' if not recent.
- Unseen - `U` if not seen AND not recent, ' ' if seen OR not seen and recent
- Flagged - `F` if flagged, ' ' if not flagged
- Answered - `A` if answered, ' ' if unanswered
- Deleted - `D` if deleted, ' ' if not deleted
- Draft - `X` if draft, ' ' if not draft
- Msgno - The message number
- MailDate -
- Size - The message size
- udate - mail message date in Unix time
- fetchfrom - from line formatted to fit `from_length` characters
- fetchsubject - subject line formatted to fit `subject_length` characters

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。
8.0.0 | The unused `defaulthost` parameter has been removed.

### 参见

- imap_fetch_overview() - Read an overview of the information in the headers of the given message

# imap_headers

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_headers — Returns headers for all messages in a mailbox

### 说明

function imap_headers(IMAP\Connection `$imap`): array|false

Returns headers for all messages in a mailbox.

### 参数

`imap`
  IMAP\Connection 实例。

### 返回值

Returns an array of string formatted with header info. One element per mail message. Returns `false` on failure.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

# imap_is_open

(PHP 8 >= 8.2.1)

imap_is_open — Check if the IMAP stream is still valid

### 说明

function imap_is_open(IMAP\Connection `$imap`): bool

Check if the IMAP stream is still valid.

### 参数

`imap`
  IMAP\Connection 实例。

### 返回值

Returns `true` if the stream is still valid, `false` otherwise.

### 示例

示例 #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 — Gets the last IMAP error that occurred during this page request

### 说明

function imap_last_error(): string|false

Gets the full text of the last IMAP error message that occurred on the current page. The error stack is untouched; calling imap_last_error() subsequently, with no intervening errors, will return the same error.

### 参数

此函数没有参数。

### 返回值

Returns the full text of the last IMAP error message that occurred on the current page. Returns `false` if no error messages are available.

### 参见

- imap_errors() - Returns all of the IMAP errors that have occurred

# imap_list

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_list — Read the list of mailboxes

### 说明

function imap_list(IMAP\Connection `$imap`, string `$reference`, string `$pattern`): array|false

Read the list of mailboxes.

### 参数

`imap`
  IMAP\Connection 实例。
`reference`

  `reference` should normally be just the server specification as described in imap_open().

  警告

  Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

`pattern`
  指定在邮箱层级的何处开始查找。 在组成 `pattern` 的字符中可使用两个特殊字符： '`*`' 和 '`%`'。 '`*`' 是指返回所有邮箱目录. 如果将 '`*`' 作为 `pattern` 参数时, 则会返回整个邮箱层级结构。 '`%`' 是指只返回当前级次。 '`%`' 作为 `pattern` 参数则只会返回顶层邮箱； '`~/mail/%`' 用于 `UW_IMAPD` 则会返回名为 ~/mail 的目录, 但不包含其子目录。

### 返回值

Returns an array containing the names of the mailboxes or `false` in case of failure.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 示例

示例 #1 imap_list() example

    <?php
    $mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
          or die("can't connect: " . 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 failed: " . imap_last_error() . "\n";
    }

    imap_close($mbox);
    ?>

### 参见

- imap_getmailboxes() - Read the list of mailboxes, returning detailed information on each one
- imap_lsub() - List all the subscribed mailboxes

# imap_listmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listmailbox — 别名 imap_list()

### 说明

此函数是该函数的别名： imap_list().

# imap_listscan

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listscan — Returns the list of mailboxes that matches the given text

### 说明

function imap_listscan(
IMAP\Connection `$imap`,
string `$reference`,
string `$pattern`,
string `$content`
): array|false

Returns an array containing the names of the mailboxes that have `content` in the text of the mailbox.

This function is similar to imap_listmailbox(), but it will additionally check for the presence of the string `content` inside the mailbox data.

### 参数

`imap`
  IMAP\Connection 实例。
`reference`

  `reference` should normally be just the server specification as described in imap_open()

  警告

  Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

`pattern`
  指定在邮箱层级的何处开始查找。 在组成 `pattern` 的字符中可使用两个特殊字符： '`*`' 和 '`%`'。 '`*`' 是指返回所有邮箱目录. 如果将 '`*`' 作为 `pattern` 参数时, 则会返回整个邮箱层级结构。 '`%`' 是指只返回当前级次。 '`%`' 作为 `pattern` 参数则只会返回顶层邮箱； '`~/mail/%`' 用于 `UW_IMAPD` 则会返回名为 ~/mail 的目录, 但不包含其子目录。
`content`

  The searched string

### 返回值

Returns an array containing the names of the mailboxes that have `content` in the text of the mailbox, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 参见

- imap_listmailbox() - 别名 imap_list
- imap_search() - This function returns an array of messages matching the given search criteria

# imap_listsubscribed

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listsubscribed — 别名 imap_lsub()

### 说明

此函数是该函数的别名： imap_lsub().

# imap_lsub

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_lsub — List all the subscribed mailboxes

### 说明

function imap_lsub(IMAP\Connection `$imap`, string `$reference`, string `$pattern`): array|false

Gets an array of all the mailboxes that you have subscribed.

### 参数

`imap`
  IMAP\Connection 实例。
`reference`

  `reference` should normally be just the server specification as described in imap_open()

  警告

  Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

`pattern`
  指定在邮箱层级的何处开始查找。 在组成 `pattern` 的字符中可使用两个特殊字符： '`*`' 和 '`%`'。 '`*`' 是指返回所有邮箱目录. 如果将 '`*`' 作为 `pattern` 参数时, 则会返回整个邮箱层级结构。 '`%`' 是指只返回当前级次。 '`%`' 作为 `pattern` 参数则只会返回顶层邮箱； '`~/mail/%`' 用于 `UW_IMAPD` 则会返回名为 ~/mail 的目录, 但不包含其子目录。

### 返回值

Returns an array of all the subscribed mailboxes, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 参见

- imap_list() - Read the list of mailboxes
- imap_getmailboxes() - Read the list of mailboxes, returning detailed information on each one

# imap_mail

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail — Send an email message

### 说明

function imap_mail(
string `$to`,
string `$subject`,
string `$message`,
?string `$additional_headers` = `null`,
?string `$cc` = `null`,
?string `$bcc` = `null`,
?string `$return_path` = `null`
): bool

This function allows sending of emails with correct handling of Cc and Bcc receivers.

The parameters `to`, `cc` and `bcc` are all strings and are all parsed as » RFC822 address lists.

### 参数

`to`

  The receiver

`subject`

  The mail subject

`message`

  The mail body, see imap_mail_compose()

`additional_headers`

  As string with additional headers to be set on the mail

`cc`

`bcc`

  The receivers specified in `bcc` will get the mail, but are excluded from the headers.

`return_path`

  Use this parameter to specify return path upon mail delivery failure. This is useful when using PHP as a mail client for multiple users.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `additional_headers`, `cc`, `bcc`, and `return_path` are now nullable.

### 参见

- mail() - 发送邮件
- imap_mail_compose() - Create a MIME message based on given envelope and body sections

# imap_mail_compose

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_compose — Create a MIME message based on given envelope and body sections

### 说明

function imap_mail_compose(array `$envelope`, array `$bodies`): string|false

Create a MIME message based on the given `envelope` and `bodies` sections.

### 参数

`envelope`

  An associative array of header fields. Valid keys are: `"remail"`, `"return_path"`, `"date"`, `"from"`, `"reply_to"`, `"in_reply_to"`, `"subject"`, `"to"`, `"cc"`, `"bcc"` and `"message_id"`, which set the respective message headers to the given string. To set additional headers, the key `"custom_headers"` is supported, which expects an array of those headers, e.g. `["User-Agent: My Mail Client"]`.

`bodies`

  An indexed array of bodies. The first body is the main body of the message; only if it has a type of `TYPEMULTIPART`, further bodies are processed; these bodies constitute the bodies of the parts.

  Body Array Structure
  Key | Type | Description
  --- | --- | ---
  `type` | int | The MIME type. One of `TYPETEXT` (default), `TYPEMULTIPART`, `TYPEMESSAGE`, `TYPEAPPLICATION`, `TYPEAUDIO`, `TYPEIMAGE`, `TYPEMODEL` or `TYPEOTHER`.
  `encoding` | int | The `Content-Transfer-Encoding`. One of `ENC7BIT` (default), `ENC8BIT`, `ENCBINARY`, `ENCBASE64`, `ENCQUOTEDPRINTABLE` or `ENCOTHER`.
  `charset` | string | The charset parameter of the MIME type.
  `type.parameters` | array | An associative array of `Content-Type` parameter names and their values.
  `subtype` | string | The MIME subtype, e.g. `'jpeg'` for `TYPEIMAGE`.
  `id` | string | The `Content-ID`.
  `description` | string | The `Content-Description`.
  `disposition.type` | string | The `Content-Disposition`, e.g. `'attachment'`.
  `disposition` | array | An associative array of `Content-Disposition` parameter names and values.
  `contents.data` | string | The payload.
  `lines` | int | The size of the payload in lines.
  `bytes` | int | The size of the payload in bytes.
  `md5` | string | The MD5 checksum of the payload.

### 返回值

Returns the MIME message as string, 或者在失败时返回 `false`.

### 示例

示例 #1 imap_mail_compose() example

    <?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 — Copy specified messages to a mailbox

### 说明

function imap_mail_copy(
IMAP\Connection `$imap`,
string `$message_nums`,
string `$mailbox`,
int `$flags` = 0
): bool

Copies mail messages specified by `message_nums` to specified mailbox.

### 参数

`imap`
  IMAP\Connection 实例。
`message_nums`

  `message_nums` is a range not just message numbers (as described in » RFC2060).

`mailbox`

  The mailbox name, see imap_open() for more information

  警告

  Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

`flags`

  `flags` is a bitmask of one or more of

  - `CP_UID` - the sequence numbers contain UIDS
  - `CP_MOVE` - Delete the messages from the current mailbox after copying. If this flag is set, the function behaves identically to imap_mail_move().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 参见

- imap_mail_move() - Move specified messages to a mailbox

# imap_mail_move

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_move — Move specified messages to a mailbox

### 说明

function imap_mail_move(
IMAP\Connection `$imap`,
string `$message_nums`,
string `$mailbox`,
int `$flags` = 0
): bool

Moves mail messages specified by `message_nums` to the specified `mailbox`. Note that the mail messages are actually copied to the `mailbox`, and the original messages are flagged for deletion. That implies that the messages in `mailbox` are assigned new UIDs.

### 参数

`imap`
  IMAP\Connection 实例。
`message_nums`

  `message_nums` is a range not just message numbers (as described in » RFC2060).

`mailbox`

  The mailbox name, see imap_open() for more information

  警告

  Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

`flags`

  `flags` is a bitmask and may contain the single option:

  - `CP_UID` - the sequence numbers contain UIDS

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 注释

> 注意:

> imap_mail_move() will flag the original mail with a delete flag, to successfully delete it a call to the imap_expunge() function must be made.

### 参见

- imap_mail_copy() - Copy specified messages to a mailbox

# imap_mailboxmsginfo

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mailboxmsginfo — Get information about the current mailbox

### 说明

function imap_mailboxmsginfo(IMAP\Connection `$imap`): stdClass

Checks the current mailbox status on the server. It is similar to imap_status(), but will additionally sum up the size of all messages in the mailbox, which will take some additional time to execute.

### 参数

`imap`
  IMAP\Connection 实例。

### 返回值

Returns the information in an object with following properties:

Mailbox properties
Date | date of last change (current datetime)
Driver | driver
Mailbox | name of the mailbox
Nmsgs | number of messages
Recent | number of recent messages
Unread | number of unread messages
Deleted | number of deleted messages
Size | mailbox size

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 示例

示例 #1 imap_mailboxmsginfo() example

    <?php

    $mbox = imap_open("{imap.example.org}INBOX", "username", "password")
          or die("can't connect: " . imap_last_error());

    $check = imap_mailboxmsginfo($mbox);

    if ($check) {
        echo "Date: "     . $check->Date    . "<br />\n" ;
        echo "Driver: "   . $check->Driver  . "<br />\n" ;
        echo "Mailbox: "  . $check->Mailbox . "<br />\n" ;
        echo "Messages: " . $check->Nmsgs   . "<br />\n" ;
        echo "Recent: "   . $check->Recent  . "<br />\n" ;
        echo "Unread: "   . $check->Unread  . "<br />\n" ;
        echo "Deleted: "  . $check->Deleted . "<br />\n" ;
        echo "Size: "     . $check->Size    . "<br />\n" ;
    } else {
        echo "imap_mailboxmsginfo() failed: " . imap_last_error() . "<br />\n";
    }

    imap_close($mbox);

    ?>

# imap_mime_header_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mime_header_decode — Decode MIME header elements

### 说明

function imap_mime_header_decode(string `$string`): array|false

Decodes MIME message header extensions that are non ASCII text (see » RFC2047).

### 参数

`string`

  The MIME text

### 返回值

The decoded elements are returned in an array of objects, where each object has two properties, `charset` and `text`.

If the element hasn't been encoded, and in other words is in plain US-ASCII, the `charset` property of that element is set to `default`.

The function returns `false` on failure.

### 示例

示例 #1 imap_mime_header_decode() example

    <?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 "Charset: {$elements[$i]->charset}\n";
        echo "Text: {$elements[$i]->text}\n\n";
    }
    ?>

以上示例会输出：

    Charset: ISO-8859-1
    Text: Keld Jørn Simonsen

    Charset: default
    Text:  <keld@example.com>

In the above example we would have two elements, whereas the first element had previously been encoded with ISO-8859-1, and the second element would be plain US-ASCII.

### 参见

- imap_utf8() - Converts MIME-encoded text to UTF-8

# imap_msgno

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_msgno — Gets the message sequence number for the given UID

### 说明

function imap_msgno(IMAP\Connection `$imap`, int `$message_uid`): int

Returns the message sequence number for the given `message_uid`.

This function is the inverse of imap_uid().

### 参数

`imap`
  IMAP\Connection 实例。
`message_uid`

  The message UID

### 返回值

Returns the message sequence number for the given `message_uid`.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 参见

- imap_uid() - This function returns the UID for the given message sequence number

# 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

### 说明

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.

> 注意:

> This function is only available, if libcclient exports utf8_to_mutf7().

### 参数

`string`

  A string encoded in modified UTF-7.

### 返回值

Returns `string` converted to UTF-8, 或者在失败时返回 `false`.

### 参见

- 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 — Gets the number of messages in the current mailbox

### 说明

function imap_num_msg(IMAP\Connection `$imap`): int|false

Gets the number of messages in the current mailbox.

### 参数

`imap`
  IMAP\Connection 实例。

### 返回值

Return the number of messages in the current mailbox, as an integer, or `false` on error.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 参见

- imap_num_recent() - Gets the number of recent messages in current mailbox
- imap_status() - Returns status information on a mailbox

# imap_num_recent

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_num_recent — Gets the number of recent messages in current mailbox

### 说明

function imap_num_recent(IMAP\Connection `$imap`): int

Gets the number of recent messages in the current mailbox.

### 参数

`imap`
  IMAP\Connection 实例。

### 返回值

Returns the number of recent messages in the current mailbox, as an integer.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 参见

- imap_num_msg() - Gets the number of messages in the current mailbox
- imap_status() - Returns status information on a mailbox

# imap_open

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_open — Open an IMAP stream to a mailbox

### 说明

function imap_open(
string `$mailbox`,
string `$user`,
string `$password`,
int `$flags` = 0,
int `$retries` = 0,
array `$options` = []
): IMAP\Connection|false

Opens an IMAP stream to a `mailbox`.

This function can also be used to open streams to POP3 and NNTP servers, but some functions and features are only available on IMAP servers.

### 参数

`mailbox`

  A mailbox name consists of a server and a mailbox path on this server. The special name `INBOX` stands for the current users personal mailbox. Mailbox names that contain international characters besides those in the printable ASCII space have to be encoded with imap_utf7_encode().

  警告

  Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

  The server part, which is enclosed in '{' and '}', consists of the servers name or ip address, an optional port (prefixed by ':'), and an optional protocol specification (prefixed by '/').

  The server part is mandatory in all mailbox parameters.

  All names which start with `{` are remote names, and are in the form `"{" remote_system_name [":" port] [flags] "}" [mailbox_name]` where:

  - `remote_system_name` - Internet domain name or bracketed IP address of server.
  - `port` - optional TCP port number, default is the default port for that service
  - `flags` - optional flags, see following table.
  - `mailbox_name` - remote mailbox name, default is INBOX

  Optional flags for names
  Flag | Description
  --- | ---
  `/service=`service | mailbox access service, default is "imap"
  `/user=`user | remote user name for login on the server
  `/authuser=`user | remote authentication user; if specified this is the user name whose password is used (e.g. administrator)
  `/anonymous` | remote access as anonymous user
  `/debug` | record protocol telemetry in application's debug log
  `/secure` | do not transmit a plaintext password over the network
  `/imap`, `/imap2`, `/imap2bis`, `/imap4`, `/imap4rev1` | equivalent to `/service=imap`
  `/pop3` | equivalent to `/service=pop3`
  `/nntp` | equivalent to `/service=nntp`
  `/norsh` | do not use rsh or ssh to establish a preauthenticated IMAP session
  `/ssl` | use the `Secure Socket Layer` to encrypt the session
  `/validate-cert` | validate certificates from TLS/SSL server (this is the default behavior)
  `/novalidate-cert` | do not validate certificates from TLS/SSL server, needed if server uses self-signed certificates
  `/tls` | force use of `start-TLS` to encrypt the session, and reject connection to servers that do not support it
  `/notls` | do not do `start-TLS` to encrypt the session, even with servers that support it
  `/readonly` | request read-only mailbox open (IMAP only; ignored on NNTP, and an error with SMTP and POP3)

`user`

  The user name

`password`

  The password associated with the `user`

`flags`

  The `flags` are a bit mask with one or more of the following:

  - `OP_READONLY` - Open mailbox read-only
  - `OP_ANONYMOUS` - Don't use or update a .newsrc for news (NNTP only)
  - `OP_HALFOPEN` - For IMAP and NNTP names, open a connection but don't open a mailbox.
  - `CL_EXPUNGE` - Expunge mailbox automatically upon mailbox close (see also imap_delete() and imap_expunge())
  - `OP_DEBUG` - Debug protocol negotiations
  - `OP_SHORTCACHE` - Short (`elt`-only) caching
  - `OP_SILENT` - Don't pass up events (internal use)
  - `OP_PROTOTYPE` - Return driver prototype
  - `OP_SECURE` - Don't do non-secure authentication
`retries`

  Number of maximum connect attempts

`options`

  Connection parameters, the following (string) keys maybe used to set one or more connection parameters:

  - `DISABLE_AUTHENTICATOR` - Disable authentication properties

### 返回值

Returns an IMAP\Connection instance on success, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | Returns an IMAP\Connection instance now; previously, a resource was returned.

### 示例

示例 #1 Different use of imap_open()

    <?php
    // To connect to an IMAP server running on port 143 on the local machine,
    // do the following:
    $mbox = imap_open("{localhost:143}INBOX", "user_id", "password");

    // To connect to a POP3 server on port 110 on the local server, use:
    $mbox = imap_open ("{localhost:110/pop3}INBOX", "user_id", "password");

    // To connect to an SSL IMAP or POP3 server, add /ssl after the protocol
    // specification:
    $mbox = imap_open ("{localhost:993/imap/ssl}INBOX", "user_id", "password");

    // To connect to an SSL IMAP or POP3 server with a self-signed certificate,
    // add /ssl/novalidate-cert after the protocol specification:
    $mbox = imap_open ("{localhost:995/pop3/ssl/novalidate-cert}", "user_id", "password");

    // To connect to an NNTP server on port 119 on the local server, use:
    $nntp = imap_open ("{localhost:119/nntp}comp.test", "", "");
    // To connect to a remote server replace "localhost" with the name or the
    // IP address of the server you want to connect to.
    ?>

示例 #2 imap_open() example

    <?php
    $mbox = imap_open("{imap.example.org:143}", "username", "password");

    echo "<h1>Mailboxes</h1>\n";
    $folders = imap_listmailbox($mbox, "{imap.example.org:143}", "*");

    if ($folders == false) {
        echo "Call failed<br />\n";
    } else {
        foreach ($folders as $val) {
            echo $val . "<br />\n";
        }
    }

    echo "<h1>Headers in INBOX</h1>\n";
    $headers = imap_headers($mbox);

    if ($headers == false) {
        echo "Call failed<br />\n";
    } else {
        foreach ($headers as $val) {
            echo $val . "<br />\n";
        }
    }

    imap_close($mbox);
    ?>

### 参见

- imap_close() - Close an IMAP stream

# imap_ping

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_ping — Check if the IMAP stream is still active

### 说明

function imap_ping(IMAP\Connection `$imap`): bool

imap_ping() pings the stream to see if it's still active. It may discover new mail; this is the preferred method for a periodic "new mail check" as well as a "keep alive" for servers which have inactivity timeout.

### 参数

`imap`
  IMAP\Connection 实例。

### 返回值

Returns `true` if the stream is still alive, `false` otherwise.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 示例

示例 #1 imap_ping() Example

    <?php

    $imap = imap_open("{imap.example.org}", "mailadmin", "password");

    // after some sleeping
    if (!imap_ping($imap)) {
        // do some stuff to reconnect
    }

    ?>

# imap_qprint

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_qprint — Convert a quoted-printable string to an 8 bit string

### 说明

function imap_qprint(string `$string`): string|false

Convert a quoted-printable string to an 8 bit string according to » RFC2045, section 6.7.

### 参数

`string`

  A quoted-printable string

### 返回值

Returns an 8 bits string, 或者在失败时返回 `false`.

### 参见

- imap_8bit() - Convert an 8bit string to a quoted-printable string

# imap_rename

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rename — 别名 imap_renamemailbox()

### 说明

此函数是该函数的别名： imap_renamemailbox().

# imap_renamemailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_renamemailbox — Rename an old mailbox to new mailbox

### 说明

function imap_renamemailbox(IMAP\Connection `$imap`, string `$from`, string `$to`): bool

This function renames on old mailbox to new mailbox (see imap_open() for the format of `mbox` names).

### 参数

`imap`
  IMAP\Connection 实例。
`from`

  The old mailbox name, see imap_open() for more information

  警告

  Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

`to`

  The new mailbox name, see imap_open() for more information

  警告

  Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 参见

- imap_createmailbox() - Create a new mailbox
- imap_deletemailbox() - Delete a mailbox

# imap_reopen

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_reopen — Reopen IMAP stream to new mailbox

### 说明

function imap_reopen(
IMAP\Connection `$imap`,
string `$mailbox`,
int `$flags` = 0,
int `$retries` = 0
): bool

Reopens the specified stream to a new `mailbox` on an IMAP or NNTP server.

### 参数

`imap`
  IMAP\Connection 实例。
`mailbox`

  The mailbox name, see imap_open() for more information

  警告

  Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

`flags`

  The `flags` are a bit mask with one or more of the following:

  - `OP_READONLY` - Open mailbox read-only
  - `OP_ANONYMOUS` - Don't use or update a .newsrc for news (NNTP only)
  - `OP_HALFOPEN` - For IMAP and NNTP names, open a connection but don't open a mailbox.
  - `OP_EXPUNGE` - Silently expunge recycle stream
  - `CL_EXPUNGE` - Expunge mailbox automatically upon mailbox close (see also imap_delete() and imap_expunge())
`retries`

  Number of maximum connect attempts

### 返回值

Returns `true` if the stream is reopened, `false` otherwise.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 示例

示例 #1 imap_reopen() example

    <?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 — Parses an address string

### 说明

function imap_rfc822_parse_adrlist(string `$string`, string `$default_hostname`): array

Parses the address string as defined in » RFC2822 and for each address.

### 参数

`string`

  A string containing addresses

`default_hostname`

  The default host name

### 返回值

Returns an array of objects. The objects properties are:

- mailbox - the mailbox name (username)
- host - the host name
- personal - the personal name
- adl - at domain source route

### 示例

示例 #1 imap_rfc822_parse_adrlist() example

    <?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";
    }
    ?>

以上示例会输出：

    # 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     :

### 参见

- imap_rfc822_parse_headers() - Parse mail headers from a string

# imap_rfc822_parse_headers

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_parse_headers — Parse mail headers from a string

### 说明

function imap_rfc822_parse_headers(string `$headers`, string `$default_hostname` = "UNKNOWN"): stdClass

Gets an object of various header elements, similar to imap_header().

### 参数

`headers`

  The parsed headers data

`default_hostname`

  The default host name

### 返回值

Returns an object similar to the one returned by imap_header(), except for the flags and other properties that come from the IMAP server.

### 参见

- imap_rfc822_parse_adrlist() - Parses an address string

# imap_rfc822_write_address

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_write_address — Returns a properly formatted email address given the mailbox, host, and personal info

### 说明

function imap_rfc822_write_address(string `$mailbox`, string `$hostname`, string `$personal`): string|false

Returns a properly formatted email address as defined in » RFC2822 given the needed information.

### 参数

`mailbox`

  The mailbox name, see imap_open() for more information

  警告

  Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

`hostname`

  The email host part

`personal`

  The name of the account owner

### 返回值

Returns a string properly formatted email address as defined in » RFC2822, 或者在失败时返回 `false`.

### 示例

示例 #1 imap_rfc822_write_address() example

    <?php
    echo imap_rfc822_write_address("hartmut", "example.com", "Hartmut Holzgraefe");
    ?>

以上示例会输出：

    Hartmut Holzgraefe <hartmut@example.com>

# imap_savebody

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

imap_savebody — Save a specific body section to a file

### 说明

function imap_savebody(
IMAP\Connection `$imap`,
resource|string|int `$file`,
int `$message_num`,
string `$section` = "",
int `$flags` = 0
): bool

Saves a part or the whole body of the specified message.

### 参数

`imap`
  IMAP\Connection 实例。
`file`

  The path to the saved file as a string, or a valid file descriptor returned by fopen().

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 参见

- imap_fetchbody() - Fetch a particular section of the body of the message

# imap_scan

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_scan — 别名 imap_listscan()

### 说明

此函数是该函数的别名： imap_listscan().

# imap_scanmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_scanmailbox — 别名 imap_listscan()

### 说明

此函数是该函数的别名： imap_listscan().

# imap_search

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_search — This function returns an array of messages matching the given search criteria

### 说明

function imap_search(
IMAP\Connection `$imap`,
string `$criteria`,
int `$flags` = `SE_FREE`,
string `$charset` = ""
): array|false

This function performs a search on the mailbox currently opened in the given IMAP stream.

For example, to match all unanswered messages sent by Mom, you'd use: "UNANSWERED FROM mom". Searches appear to be case insensitive. This list of criteria is from a reading of the UW c-client source code and may be incomplete or inaccurate (see also » RFC1176, section "tag SEARCH search_criteria").

### 参数

`imap`
  IMAP\Connection 实例。
`criteria`

  A string, delimited by spaces, in which the following keywords are allowed. Any multi-word arguments (e.g. `FROM "joey smith"`) must be quoted. Results will match all `criteria` entries.

  - ALL - return all messages matching the rest of the criteria
  - ANSWERED - match messages with the \\ANSWERED flag set
  - BCC "string" - match messages with "string" in the Bcc: field
  - BEFORE "date" - match messages with Date: before "date"
  - BODY "string" - match messages with "string" in the body of the message
  - CC "string" - match messages with "string" in the Cc: field
  - DELETED - match deleted messages
  - FLAGGED - match messages with the \\FLAGGED (sometimes referred to as Important or Urgent) flag set
  - FROM "string" - match messages with "string" in the From: field
  - KEYWORD "string" - match messages with "string" as a keyword
  - NEW - match new messages
  - OLD - match old messages
  - ON "date" - match messages with Date: matching "date"
  - RECENT - match messages with the \\RECENT flag set
  - SEEN - match messages that have been read (the \\SEEN flag is set)
  - SINCE "date" - match messages with Date: after "date"
  - SUBJECT "string" - match messages with "string" in the Subject:
  - TEXT "string" - match messages with text "string"
  - TO "string" - match messages with "string" in the To:
  - UNANSWERED - match messages that have not been answered
  - UNDELETED - match messages that are not deleted
  - UNFLAGGED - match messages that are not flagged
  - UNKEYWORD "string" - match messages that do not have the keyword "string"
  - UNSEEN - match messages which have not been read yet
`flags`

  Valid values for `flags` are `SE_UID`, which causes the returned array to contain UIDs instead of messages sequence numbers.

`charset`

  MIME character set to use when searching strings.

### 返回值

Returns an array of message numbers or UIDs.

Return `false` if it does not understand the search `criteria` or no messages have been found.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 示例

示例 #1 imap_search() example

    <?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);
    ?>

以上示例的输出类似于：

    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
    )

### 参见

- imap_listscan() - Returns the list of mailboxes that matches the given text

# imap_set_quota

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

imap_set_quota — Sets a quota for a given mailbox

### 说明

function imap_set_quota(IMAP\Connection `$imap`, string `$quota_root`, int `$mailbox_size`): bool

Sets an upper limit quota on a per mailbox basis.

### 参数

`imap`
  IMAP\Connection 实例。
`quota_root`

  The mailbox to have a quota set. This should follow the IMAP standard format for a mailbox: `user.name`.

`mailbox_size`

  The maximum size (in KB) for the `quota_root`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 示例

示例 #1 imap_set_quota() example

    <?php
    $mbox = imap_open("{imap.example.org:143}", "mailadmin", "password");

    if (!imap_set_quota($mbox, "user.kalowsky", 3000)) {
        echo "Error in setting quota\n";
        return;
    }

    imap_close($mbox);
    ?>

### 注释

This function is currently only available to users of the c-client2000 or greater library.

The given `imap` must be opened as the mail administrator, other wise this function will fail.

### 参见

- imap_open() - Open an IMAP stream to a mailbox
- imap_get_quota() - Retrieve the quota level settings, and usage statics per mailbox

# imap_setacl

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imap_setacl — Sets the ACL for a given mailbox

### 说明

function imap_setacl(
IMAP\Connection `$imap`,
string `$mailbox`,
string `$user_id`,
string `$rights`
): bool

Sets the ACL for a giving mailbox.

### 参数

`imap`
  IMAP\Connection 实例。
`mailbox`

  The mailbox name, see imap_open() for more information

  警告

  Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

`user_id`

  The user to give the rights to.

`rights`

  The rights to give to the user. Passing an empty string will delete acl.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 注释

This function is currently only available to users of the c-client2000 or greater library.

### 参见

- imap_getacl() - Gets the ACL for a given mailbox

# imap_setflag_full

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_setflag_full — Sets flags on messages

### 说明

function imap_setflag_full(
IMAP\Connection `$imap`,
string `$sequence`,
string `$flag`,
int `$options` = 0
): true

Causes a store to add the specified `flag` to the flags set for the messages in the specified `sequence`.

### 参数

`imap`
  IMAP\Connection 实例。
`sequence`

  A sequence of message numbers. You can enumerate desired messages with the `X,Y` syntax, or retrieve all messages within an interval with the `X:Y` syntax

`flag`

  The flags which you can set are `\Seen`, `\Answered`, `\Flagged`, `\Deleted`, and `\Draft` as defined by » RFC2060.

`options`

  A bit mask that may contain the single option:

  - `ST_UID` - The sequence argument contains UIDs instead of sequence numbers

### 返回值

总是返回 `true`。

### 错误／异常

Throws a ValueError if `options` is invalid.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。
8.0.0 | A ValueError is now thrown on invalid `options` parameter values. Previously, a warning was emitted and the function returned `false`.

### 示例

示例 #1 imap_setflag_full() example

    <?php
    $mbox = imap_open("{imap.example.org:143}", "username", "password")
         or die("can't connect: " . imap_last_error());

    $status = imap_setflag_full($mbox, "2,5", "\\Seen \\Flagged");

    echo gettype($status) . "\n";
    echo $status . "\n";

    imap_close($mbox);
    ?>

### 参见

- imap_clearflag_full() - Clears flags on messages

# imap_sort

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_sort — Gets and sort messages

### 说明

function imap_sort(
IMAP\Connection `$imap`,
int `$criteria`,
bool `$reverse`,
int `$flags` = 0,
?string `$search_criteria` = `null`,
?string `$charset` = `null`
): array|false

Gets and sorts message numbers by the given parameters.

### 参数

`imap`
  IMAP\Connection 实例。
`criteria`

  Criteria can be one (and only one) of the following:

  - `SORTDATE` - message Date
  - `SORTARRIVAL` - arrival date
  - `SORTFROM` - mailbox in first From address
  - `SORTSUBJECT` - message subject
  - `SORTTO` - mailbox in first To address
  - `SORTCC` - mailbox in first cc address
  - `SORTSIZE` - size of message in octets
`reverse`

  Whether to sort in reverse order.

`flags`

  The `flags` are a bitmask of one or more of the following:

  - `SE_UID` - Return UIDs instead of sequence numbers
  - `SE_NOPREFETCH` - Don't prefetch searched messages
`search_criteria`

  IMAP2-format search criteria string. For details see imap_search().

`charset`

  MIME character set to use when sorting strings.

### 返回值

Returns an array of message numbers sorted by the given parameters, 或者在失败时返回 `false`.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。
8.0.0 | `reverse` is now bool instead of int.
8.0.0 | `search_criteria` and `charset` are now nullable.

# imap_status

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_status — Returns status information on a mailbox

### 说明

function imap_status(IMAP\Connection `$imap`, string `$mailbox`, int `$flags`): stdClass|false

Gets status information about the given `mailbox`.

### 参数

`imap`
  IMAP\Connection 实例。
`mailbox`

  The mailbox name, see imap_open() for more information

  警告

  Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

`flags`

  Valid flags are:

  - `SA_MESSAGES` - set $status->messages to the number of messages in the mailbox
  - `SA_RECENT` - set $status->recent to the number of recent messages in the mailbox
  - `SA_UNSEEN` - set $status->unseen to the number of unseen (new) messages in the mailbox
  - `SA_UIDNEXT` - set $status->uidnext to the next uid to be used in the mailbox
  - `SA_UIDVALIDITY` - set $status->uidvalidity to a constant that changes when uids for the mailbox may no longer be valid
  - `SA_ALL` - set all of the above

### 返回值

This function returns an object containing status information, 或者在失败时返回 `false`. The object has the following properties: `messages`, `recent`, `unseen`, `uidnext`, and `uidvalidity`.

`flags` is also set, which contains a bitmask which can be checked against any of the above constants.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 示例

示例 #1 imap_status() example

    <?php
    $mbox = imap_open("{imap.example.com}", "username", "password", OP_HALFOPEN)
          or die("can't connect: " . imap_last_error());

    $status = imap_status($mbox, "{imap.example.org}INBOX", SA_ALL);
    if ($status) {
      echo "Messages:   " . $status->messages    . "<br />\n";
      echo "Recent:     " . $status->recent      . "<br />\n";
      echo "Unseen:     " . $status->unseen      . "<br />\n";
      echo "UIDnext:    " . $status->uidnext     . "<br />\n";
      echo "UIDvalidity:" . $status->uidvalidity . "<br />\n";
    } else {
      echo "imap_status failed: " . imap_last_error() . "\n";
    }

    imap_close($mbox);
    ?>

# imap_subscribe

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_subscribe — Subscribe to a mailbox

### 说明

function imap_subscribe(IMAP\Connection `$imap`, string `$mailbox`): bool

Subscribe to a new mailbox.

### 参数

`imap`
  IMAP\Connection 实例。
`mailbox`

  The mailbox name, see imap_open() for more information

  警告

  Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 参见

- imap_unsubscribe() - Unsubscribe from a mailbox

# imap_thread

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imap_thread — Returns a tree of threaded message

### 说明

function imap_thread(IMAP\Connection `$imap`, int `$flags` = `SE_FREE`): array|false

Gets a tree of a threaded message.

### 参数

`imap`
  IMAP\Connection 实例。
`flags`

### 返回值

imap_thread() returns an associative array containing a tree of messages threaded by `REFERENCES`, or `false` on error.

Every message in the current mailbox will be represented by three entries in the resulting array:

- $thread["XX.num"] - current message number

- $thread["XX.next"]

- $thread["XX.branch"]

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 示例

示例 #1 imap_thread() Example

    <?php

    // Here we're outputting the threads of a 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 — Set or fetch imap timeout

### 说明

function imap_timeout(int `$timeout_type`, int `$timeout` = -1): int|bool

Sets or fetches the imap timeout.

### 参数

`timeout_type`

  One of the following: `IMAP_OPENTIMEOUT`, `IMAP_READTIMEOUT`, `IMAP_WRITETIMEOUT`, or `IMAP_CLOSETIMEOUT`.

`timeout`

  The timeout, in seconds.

### 返回值

If the `timeout` parameter is set, this function returns `true` on success and `false` on failure.

If `timeout` is not provided or evaluates to -1, the current timeout value of `timeout_type` is returned as an integer.

### 示例

示例 #1 imap_timeout() example

    <?php

    echo "The current read timeout is " . imap_timeout(IMAP_READTIMEOUT) . "\n";

    ?>

# imap_uid

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_uid — This function returns the UID for the given message sequence number

### 说明

function imap_uid(IMAP\Connection `$imap`, int `$message_num`): int|false

This function returns the UID for the given message sequence number. An UID is a unique identifier that will not change over time while a message sequence number may change whenever the content of the mailbox changes.

This function is the inverse of imap_msgno().

### 参数

`imap`
  IMAP\Connection 实例。
`message_num`

  The message number.

### 返回值

The UID of the given message.

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 注释

> 注意:

> This function is not supported by POP3 mailboxes.

### 参见

- imap_msgno() - Gets the message sequence number for the given UID

# imap_undelete

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_undelete — Unmark the message which is marked deleted

### 说明

function imap_undelete(IMAP\Connection `$imap`, string `$message_nums`, int `$flags` = 0): true

Removes the deletion flag for a specified message, which is set by imap_delete() or imap_mail_move().

### 参数

`imap`
  IMAP\Connection 实例。
`message_nums`

  A string representing one or more messages in IMAP4-style sequence format (`"n"`, `"n:m"`, or combination of these delimited by commas).

`flags`

### 返回值

总是返回 `true`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 参见

- imap_delete() - Mark a message for deletion from current mailbox
- imap_mail_move() - Move specified messages to a mailbox

# imap_unsubscribe

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_unsubscribe — Unsubscribe from a mailbox

### 说明

function imap_unsubscribe(IMAP\Connection `$imap`, string `$mailbox`): bool

Unsubscribe from the specified `mailbox`.

### 参数

`imap`
  IMAP\Connection 实例。
`mailbox`

  The mailbox name, see imap_open() for more information

  警告

  Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 更新日志

版本 | 说明
--- | ---
8.1.0 | 现在 `imap` 参数接受 IMAP\Connection 实例，之前接受有效的 `imap` resource。

### 参见

- imap_subscribe() - Subscribe to a mailbox

# imap_utf7_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf7_decode — Decodes a modified UTF-7 encoded string

### 说明

function imap_utf7_decode(string `$string`): string|false

Decodes modified UTF-7 `string` into ISO-8859-1 string.

This function is needed to decode mailbox names that contain certain characters which are not in range of printable ASCII characters.

### 参数

`string`

  A modified UTF-7 encoding string, as defined in » RFC 2060, section 5.1.3.

### 返回值

Returns a string that is encoded in ISO-8859-1 and consists of the same sequence of characters in `string`, or `false` if `string` contains invalid modified UTF-7 sequence or `string` contains a character that is not part of ISO-8859-1 character set.

### 参见

- imap_utf7_encode() - Converts ISO-8859-1 string to modified UTF-7 text

# imap_utf7_encode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf7_encode — Converts ISO-8859-1 string to modified UTF-7 text

### 说明

function imap_utf7_encode(string `$string`): string

Converts `string` to modified UTF-7 text.

This is needed to encode mailbox names that contain certain characters which are not in range of printable ASCII characters.

### 参数

`string`

  An ISO-8859-1 string.

### 返回值

Returns `string` encoded with the modified UTF-7 encoding as defined in » RFC 2060, section 5.1.3.

### 参见

- imap_utf7_decode() - Decodes a modified UTF-7 encoded string

# imap_utf8

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf8 — Converts MIME-encoded text to UTF-8

### 说明

function imap_utf8(string `$mime_encoded_text`): string

Converts the given `mime_encoded_text` to UTF-8, if the declared charset is known to libc-client. Otherwise the given text is decoded, but not converted to UTF-8.

### 参数

`mime_encoded_text`

  A MIME encoded string. MIME encoding method and the UTF-8 specification are described in » RFC2047 and » RFC2044 respectively.

### 返回值

Returns the decoded string, if possible converted to UTF-8.

### 示例

示例 #1 Basic imap_utf8() Usage

    <?php
    echo imap_utf8("Johannes =?ISO-8859-1?Q?Schl=FCter?=");
    ?>

以上示例的输出类似于：

    Johannes Schlüter

### 参见

- imap_mime_header_decode() - Decode MIME header elements

# 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

### 说明

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).

> 注意:

> This function is only available, if libcclient exports utf8_to_mutf7().

### 参数

`string`

  A UTF-8 encoded string.

### 返回值

Returns `string` converted to modified UTF-7, 或者在失败时返回 `false`.

### 参见

- imap_mutf7_to_utf8() - Decode a modified UTF-7 string to UTF-8

## 目录

- imap_8bit — Convert an 8bit string to a quoted-printable string
- imap_alerts — Returns all IMAP alert messages that have occurred
- imap_append — Append a string message to a specified mailbox
- imap_base64 — Decode BASE64 encoded text
- imap_binary — Convert an 8bit string to a base64 string
- imap_body — Read the message body
- imap_bodystruct — Read the structure of a specified body section of a specific message
- imap_check — Check current mailbox
- imap_clearflag_full — Clears flags on messages
- imap_close — Close an IMAP stream
- imap_create — 别名 imap_createmailbox
- imap_createmailbox — Create a new mailbox
- imap_delete — Mark a message for deletion from current mailbox
- imap_deletemailbox — Delete a mailbox
- imap_errors — Returns all of the IMAP errors that have occurred
- imap_expunge — Delete all messages marked for deletion
- imap_fetch_overview — Read an overview of the information in the headers of the given message
- imap_fetchbody — Fetch a particular section of the body of the message
- imap_fetchheader — Returns header for a message
- imap_fetchmime — Fetch MIME headers for a particular section of the message
- imap_fetchstructure — Read the structure of a particular message
- imap_fetchtext — 别名 imap_body
- imap_gc — Clears IMAP cache
- imap_get_quota — Retrieve the quota level settings, and usage statics per mailbox
- imap_get_quotaroot — Retrieve the quota settings per user
- imap_getacl — Gets the ACL for a given mailbox
- imap_getmailboxes — Read the list of mailboxes, returning detailed information on each one
- imap_getsubscribed — List all the subscribed mailboxes
- imap_header — 别名 imap_headerinfo
- imap_headerinfo — Read the header of the message
- imap_headers — Returns headers for all messages in a mailbox
- imap_is_open — Check if the IMAP stream is still valid
- imap_last_error — Gets the last IMAP error that occurred during this page request
- imap_list — Read the list of mailboxes
- imap_listmailbox — 别名 imap_list
- imap_listscan — Returns the list of mailboxes that matches the given text
- imap_listsubscribed — 别名 imap_lsub
- imap_lsub — List all the subscribed mailboxes
- imap_mail — Send an email message
- imap_mail_compose — Create a MIME message based on given envelope and body sections
- imap_mail_copy — Copy specified messages to a mailbox
- imap_mail_move — Move specified messages to a mailbox
- imap_mailboxmsginfo — Get information about the current mailbox
- imap_mime_header_decode — Decode MIME header elements
- imap_msgno — Gets the message sequence number for the given UID
- imap_mutf7_to_utf8 — Decode a modified UTF-7 string to UTF-8
- imap_num_msg — Gets the number of messages in the current mailbox
- imap_num_recent — Gets the number of recent messages in current mailbox
- imap_open — Open an IMAP stream to a mailbox
- imap_ping — Check if the IMAP stream is still active
- imap_qprint — Convert a quoted-printable string to an 8 bit string
- imap_rename — 别名 imap_renamemailbox
- imap_renamemailbox — Rename an old mailbox to new mailbox
- imap_reopen — Reopen IMAP stream to new mailbox
- imap_rfc822_parse_adrlist — Parses an address string
- imap_rfc822_parse_headers — Parse mail headers from a string
- imap_rfc822_write_address — Returns a properly formatted email address given the mailbox, host, and personal info
- imap_savebody — Save a specific body section to a file
- imap_scan — 别名 imap_listscan
- imap_scanmailbox — 别名 imap_listscan
- imap_search — This function returns an array of messages matching the given search criteria
- imap_set_quota — Sets a quota for a given mailbox
- imap_setacl — Sets the ACL for a given mailbox
- imap_setflag_full — Sets flags on messages
- imap_sort — Gets and sort messages
- imap_status — Returns status information on a mailbox
- imap_subscribe — Subscribe to a mailbox
- imap_thread — Returns a tree of threaded message
- imap_timeout — Set or fetch imap timeout
- imap_uid — This function returns the UID for the given message sequence number
- imap_undelete — Unmark the message which is marked deleted
- imap_unsubscribe — Unsubscribe from a mailbox
- imap_utf7_decode — Decodes a modified UTF-7 encoded string
- imap_utf7_encode — Converts ISO-8859-1 string to modified UTF-7 text
- imap_utf8 — Converts MIME-encoded text to UTF-8
- imap_utf8_to_mutf7 — Encode a UTF-8 string to modified UTF-7

# The IMAP\Connection class

(PHP 8 >= 8.1.0)

## 简介

A fully opaque class which replaces a `imap` resource as of PHP 8.1.0.

## 类摘要

final class IMAP\Connection {
}

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
  - 资源类型
- 预定义常量
- IMAP 函数
  - imap_8bit — Convert an 8bit string to a quoted-printable string
  - imap_alerts — Returns all IMAP alert messages that have occurred
  - imap_append — Append a string message to a specified mailbox
  - imap_base64 — Decode BASE64 encoded text
  - imap_binary — Convert an 8bit string to a base64 string
  - imap_body — Read the message body
  - imap_bodystruct — Read the structure of a specified body section of a specific message
  - imap_check — Check current mailbox
  - imap_clearflag_full — Clears flags on messages
  - imap_close — Close an IMAP stream
  - imap_create — 别名 imap_createmailbox
  - imap_createmailbox — Create a new mailbox
  - imap_delete — Mark a message for deletion from current mailbox
  - imap_deletemailbox — Delete a mailbox
  - imap_errors — Returns all of the IMAP errors that have occurred
  - imap_expunge — Delete all messages marked for deletion
  - imap_fetch_overview — Read an overview of the information in the headers of the given message
  - imap_fetchbody — Fetch a particular section of the body of the message
  - imap_fetchheader — Returns header for a message
  - imap_fetchmime — Fetch MIME headers for a particular section of the message
  - imap_fetchstructure — Read the structure of a particular message
  - imap_fetchtext — 别名 imap_body
  - imap_gc — Clears IMAP cache
  - imap_get_quota — Retrieve the quota level settings, and usage statics per mailbox
  - imap_get_quotaroot — Retrieve the quota settings per user
  - imap_getacl — Gets the ACL for a given mailbox
  - imap_getmailboxes — Read the list of mailboxes, returning detailed information on each one
  - imap_getsubscribed — List all the subscribed mailboxes
  - imap_header — 别名 imap_headerinfo
  - imap_headerinfo — Read the header of the message
  - imap_headers — Returns headers for all messages in a mailbox
  - imap_is_open — Check if the IMAP stream is still valid
  - imap_last_error — Gets the last IMAP error that occurred during this page request
  - imap_list — Read the list of mailboxes
  - imap_listmailbox — 别名 imap_list
  - imap_listscan — Returns the list of mailboxes that matches the given text
  - imap_listsubscribed — 别名 imap_lsub
  - imap_lsub — List all the subscribed mailboxes
  - imap_mail — Send an email message
  - imap_mail_compose — Create a MIME message based on given envelope and body sections
  - imap_mail_copy — Copy specified messages to a mailbox
  - imap_mail_move — Move specified messages to a mailbox
  - imap_mailboxmsginfo — Get information about the current mailbox
  - imap_mime_header_decode — Decode MIME header elements
  - imap_msgno — Gets the message sequence number for the given UID
  - imap_mutf7_to_utf8 — Decode a modified UTF-7 string to UTF-8
  - imap_num_msg — Gets the number of messages in the current mailbox
  - imap_num_recent — Gets the number of recent messages in current mailbox
  - imap_open — Open an IMAP stream to a mailbox
  - imap_ping — Check if the IMAP stream is still active
  - imap_qprint — Convert a quoted-printable string to an 8 bit string
  - imap_rename — 别名 imap_renamemailbox
  - imap_renamemailbox — Rename an old mailbox to new mailbox
  - imap_reopen — Reopen IMAP stream to new mailbox
  - imap_rfc822_parse_adrlist — Parses an address string
  - imap_rfc822_parse_headers — Parse mail headers from a string
  - imap_rfc822_write_address — Returns a properly formatted email address given the mailbox, host, and personal info
  - imap_savebody — Save a specific body section to a file
  - imap_scan — 别名 imap_listscan
  - imap_scanmailbox — 别名 imap_listscan
  - imap_search — This function returns an array of messages matching the given search criteria
  - imap_set_quota — Sets a quota for a given mailbox
  - imap_setacl — Sets the ACL for a given mailbox
  - imap_setflag_full — Sets flags on messages
  - imap_sort — Gets and sort messages
  - imap_status — Returns status information on a mailbox
  - imap_subscribe — Subscribe to a mailbox
  - imap_thread — Returns a tree of threaded message
  - imap_timeout — Set or fetch imap timeout
  - imap_uid — This function returns the UID for the given message sequence number
  - imap_undelete — Unmark the message which is marked deleted
  - imap_unsubscribe — Unsubscribe from a mailbox
  - imap_utf7_decode — Decodes a modified UTF-7 encoded string
  - imap_utf7_encode — Converts ISO-8859-1 string to modified UTF-7 text
  - imap_utf8 — Converts MIME-encoded text to UTF-8
  - imap_utf8_to_mutf7 — Encode a UTF-8 string to modified UTF-7
- IMAP\Connection — The IMAP\Connection class

# Mail

# 简介

mail() 函数可以发送邮件。

# 安装/配置

## 目录

- 需求
- 运行时配置

## 需求

为了使邮件功能可用，PHP 在编译时必须能够访问系统上的 `sendmail` 二进制文件。如果使用其他邮件程序，例如 qmail 或 postfix， 请确保使用相应的包装器。PHP 首先会在你的 PATH 中查找 sendmail，然后在以下位置查找： `/usr/bin:/usr/sbin:/usr/etc:/etc:/usr/ucblib:/usr/lib`。 强烈建议将 sendmail 添加到你的 PATH 中。 另外，编译 PHP 的用户必须有权限访问 sendmail 二进制文件。

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

Mail 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
mail.add_x_header | "0" | `INI_PERDIR` |
mail.mixed_lf_and_crlf | "0" | `INI_SYSTEM`|`INI_PERDIR` | 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` |

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`mail.add_x_header` bool

  添加 `X-PHP-Originating-Script`，将会包含脚本的 UID 以及文件名。

`mail.log` string

  记录所有调用 mail() 的日志文件路径。日志条目包含脚本的完整路径、行号、`To` 地址和报头。

`mail.mixed_lf_and_crlf` bool

  允许将邮件 header 和邮件正文的行分隔符还原为 LF（换行符），以模拟 PHP 7 的非标准行为。此选项作为兼容性措施提供，用于适配某些不符合标准的邮件传输代理（MTA），这些 MTA 无法正确处理邮件 header 和正文内容中作为行分隔符的 CRLF（回车符 + 换行符）。

`mail.force_extra_parameters` string

  强制添加指定参数作为额外参数传递给 sendmail 二进制文件。这些参数将始终代替 mail() 第五个参数的值。

  除了 `INI_SYSTEM` 的默认行为外，该值也可通过在 httpd.conf 中使用 `php_value` 进行设置（但不建议这样做）。
`SMTP` string

  仅用于 Windows：PHP 在 mail() 函数中用来发送邮件的 SMTP 服务器的主机名称或者 IP 地址。

`smtp_port` int

  仅用于 Windows：使用 mail() 发送邮件时，连接到使用 `SMTP` 的指定服务器的端口号，默认为 25。

`sendmail_from` string

  通过 STMP 直接用 PHP 发送邮件时的 `"From:"` 邮件地址的值（仅限 Windows）。该选项同时设置了 `"Return-Path:"` 头。

`sendmail_path` string

  sendmail 程序的路径，通常为 /usr/sbin/sendmail 或 /usr/lib/sendmail。configure 脚本会尝试找到该程序并设定为默认值，但是如果失败的话，可以在这里设定。

  不使用 sendmail 的系统应将此指令设定为其邮件系统提供的 sendmail 替代程序，如果有的话。例如，» Qmail 用户通常可以设为 /var/qmail/bin/sendmail 或 /var/qmail/bin/qmail-inject。

  qmail-inject 不需要任何选项就能正确处理邮件。

  此指令也可用于 Windows。如果设定，smtp，smtp_port 和 sendmail_from 都被忽略并运行指定的命令。

# Mail 函数

# ezmlm_hash

(PHP 4 >= 4.0.2, PHP 5, PHP 7)

ezmlm_hash — 计算 EZMLM 所需的散列值

警告

本函数已自 PHP 7.4.0 起弃用，自 PHP 8.0.0 起移除。强烈建议不要依赖本函数。

### 说明

function ezmlm_hash(string `$addr`): int

ezmlm_hash() 计算用于在 MySQL 数据库中保存 EZMLM 邮件列表的散列值。

### 参数

`addr`

  要进行散列算法的电子邮件地址。

### 返回值

`addr` 的散列值。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 此函数已移除。
7.2.0 | 此函数已废弃。

### 示例

示例 #1 计算散列值并订阅一个用户

    <?php

    $user = "joecool@example.com";
    $hash = ezmlm_hash($user);
    $query = sprintf("INSERT INTO sample VALUES (%s, '%s')", $hash, $user);
    $db->query($query); // using PHPLIB db interface

    ?>

# mail

(PHP 4, PHP 5, PHP 7, PHP 8)

mail — 发送邮件

### 说明

function mail(
string `$to`,
string `$subject`,
string `$message`,
array|string `$additional_headers` = [],
string `$additional_params` = ""
): bool

发送邮件。

### 参数

`to`

  电子邮件收件人，或收件人列表。

  本字符串的格式必须符合 » RFC 2822。例如：

  - user@example.com
  - user@example.com, anotheruser@example.com
  - User
  - User , Another User
`subject`

  电子邮件的主题。

  警告

  本项不能包含任何换行符，否则邮件可能无法正确发送。

`message`

  所要发送的消息。

  行之间必须以一个 CRLF（\r\n）分隔。每行不能超过 70 个字符。

  警告

  （Windows 下）当 PHP 直接连接到 SMTP 服务器时，如果在一行开头发现一个句号，则会被删掉。要避免此问题，将单个句号替换成两个句号。

      <?php
      $text = str_replace("\n.", "\n..", $text);
      ?>

`additional_headers`（可选项）

  要插入到邮件 header 尾部的 String 或 array。

  这通常用于添加额外的 header（From、Cc 和 Bcc）。多个额外的 header 应使用 CRLF（\r\n）分隔。如果使用外部数据来组成此 header，则应对数据进行清理，避免注入不需要的 header。

  如果传递 array，则 key 是 header 名称，value 对应的 header 值。

  > 注意:

  > 发送邮件时，邮件必须包含 `From` header。这可以使用 `additional_headers` 参数来设置，或者可以在 php.ini 中设置默认值。

  > 如果不这样做，将导致类似于 `Warning: mail(): "sendmail_from" not set in php.ini or custom "From:" header missing` 的错误消息。当直接通过 SMTP（仅限 Windows）发送时，`From` header 还会设置 `Return-Path`。

  > 注意:

  > 如果未收到消息，请尝试仅使用 LF（\n）。一些 Unix 邮件传输代理（最著名的是 » qmail）会自动用 CRLF 替换 LF（如果使用 CRLF，则会导致 CR 重复）。这应该是最后的手段，因为它不符合 » RFC 2822。

`additional_params`（可选）

  发送邮件时，`additional_params` 参数可用于将额外的 flag 作为命令行选项传递给通过 `sendmail_path` 配置项指定的邮件发送程序。例如，当使用 sendmail 并配合 `-f` 选项时，可通过此参数设置邮件发件人地址。

  该参数在内部会经过 escapeshellcmd() 转义，以防止命令注入执行。escapeshellcmd() 虽可阻止命令执行，但仍允许添加额外的参数。出于安全考虑，建议用户自行对该参数进行过滤和清理，避免向 shell 命令中注入非预期的参数。

  由于会自动应用 escapeshellcmd()，某些符合互联网 RFC 标准、允许在电子邮件地址中使用的字符将无法通过此方式使用。mail() 无法支持这些字符，因此，若程序中必须使用此类字符，建议改用其他发送邮件的方式（例如使用框架或第三方库）。

  应将运行 Web 服务器的用户添加到 sendmail 配置的受信任用户列表中，以避免通过此方法设置信封发件人（-f）时，邮件自动带上 “X-Warning” 头部。对于使用 sendmail 的用户，该文件路径为 /etc/mail/trusted-users。

### 返回值

如果邮件成功接受投递，返回 `true`，否则返回 `false`。

同样重要的是要注意到，邮件仅接受了投递并不意味着邮件实际上达到预定目的地。

### 更新日志

版本 | 说明
--- | ---
7.2.0 | 现在 `additional_headers` 参数开始支持 array。

### 示例

示例 #1 发送邮件

使用 mail() 发送简单的邮件：

    <?php
    // 消息
    $message = "Line 1\r\nLine 2\r\nLine 3";

    // 如果任何一行超过 70 个字符，应该使用 wordwrap()
    $message = wordwrap($message, 70, "\r\n");

    // 发送
    mail('caffeinated@example.com', 'My Subject', $message);
    ?>

示例 #2 使用额外标头发送邮件

添加基本 header，告诉 MUA 发件人和回复地址：

    <?php
    $to      = 'nobody@example.com';
    $subject = 'the subject';
    $message = 'hello';
    $headers = 'From: webmaster@example.com' . "\r\n" .
        'Reply-To: webmaster@example.com' . "\r\n" .
        'X-Mailer: PHP/' . phpversion();

    mail($to, $subject, $message, $headers);
    ?>

示例 #3 使用 array 形式的额外标头发送邮件

此示例与上面示例发送邮件相同，但将附加 header 作为数组传递（自 PHP 7.2.0 起可用）。

    <?php
    $to      = 'nobody@example.com';
    $subject = 'the subject';
    $message = 'hello';
    $headers = array(
        'From' => 'webmaster@example.com',
        'Reply-To' => 'webmaster@example.com',
        'X-Mailer' => 'PHP/' . phpversion()
    );

    mail($to, $subject, $message, $headers);
    ?>

示例 #4 使用附加命令行参数发送邮件。

`additional_params` 参数可用于在使用 `sendmail_path` 配置的程序发送邮件时，传递额外参数。

    <?php
    mail('nobody@example.com', 'the subject', 'the message', null,
       '-fwebmaster@example.com');
    ?>

示例 #5 发送 HTML 邮件

也可以使用 mail() 发送 HTML 邮件。

    <?php
    // 多个收件人
    $to = 'johny@example.com, sally@example.com'; // note the comma

    // 主题
    $subject = 'Birthday Reminders for August';

    // 消息
    $message = '
    <html>
    <head>
      <title>Birthday Reminders for August</title>
    </head>
    <body>
      <p>Here are the birthdays upcoming in August!</p>
      <table>
        <tr>
          <th>Person</th><th>Day</th><th>Month</th><th>Year</th>
        </tr>
        <tr>
          <td>Johny</td><td>10th</td><td>August</td><td>1970</td>
        </tr>
        <tr>
          <td>Sally</td><td>17th</td><td>August</td><td>1973</td>
        </tr>
      </table>
    </body>
    </html>
    ';

    // 发送 HTML 邮件，必须设置 Content-type header
    $headers[] = 'MIME-Version: 1.0';
    $headers[] = 'Content-type: text/html; charset=iso-8859-1';

    // 附加 header
    $headers[] = 'To: Mary <mary@example.com>, Kelly <kelly@example.com>';
    $headers[] = 'From: Birthday Reminder <birthday@example.com>';
    $headers[] = 'Cc: birthdayarchive@example.com';
    $headers[] = 'Bcc: birthdaycheck@example.com';

    // 发送
    mail($to, $subject, $message, implode("\r\n", $headers));
    ?>

> 注意:

> 若需发送 HTML 或其他复杂格式的邮件，建议使用 PEAR 包 » PEAR::Mail。

### 注释

> 注意:

> mail() 的 SMTP 实现（仅限 Windows）在多个方面与 sendmail 实现不同。首先，它不使用本地二进制程序来构造邮件，而是直接通过套接字操作，这意味着需要在网络套接字上监听的邮件传输代理 `MTA`（可在本地主机或远程机器上）。

> 其次，`From:`、`Cc:`、`Bcc:` 和 `Date:` 等自定义 header 并非由 `MTA` 解释，而是由 PHP 进行解析。

> 因此，`to` 参数不应采用 "Something <someone@example.com>" 这类地址格式。在与 MTA 通信时，mail 命令可能无法正确解析此类格式。

> 注意:

> 值得注意的是，mail() 不适合在循环中发送大量邮件。发送每封邮件，此函数为打开和关闭一个套接字，效率不高。

> 要发送大量邮件，请参阅 » PEAR::Mail 和 » PEAR::Mail_Queue 包。

> 注意:

> 以下 RFC 可能有用： » RFC 1896、» RFC 2045、 » RFC 2046、» RFC 2047、 » RFC 2048、» RFC 2049 和 » RFC 2822。

### 参见

- mb_send_mail() - 发送编码过的邮件
- imap_mail() - Send an email message
- » PEAR::Mail
- » PEAR::Mail_Mime

## 目录

- ezmlm_hash — 计算 EZMLM 所需的散列值
- mail — 发送邮件

- 安装/配置
  - 需求
  - 运行时配置
- Mail 函数
  - ezmlm_hash — 计算 EZMLM 所需的散列值
  - mail — 发送邮件

# Mailparse

# 简介

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.

> 注意: Mailparse requires the mbstring extension, and mbstring must be loaded before mailparse.

# 安装/配置

## 目录

- 安装
- 运行时配置
- 资源类型

## 安装

此 » PECL 扩展未与 PHP 捆绑。 安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » 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 平台的二进制扩展 (DLL 文件) PECL 可以在 PECL 官方网站上下载。

It is necessary that the mbstring extension is loaded before mailparse.

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

Mailparse 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
mailparse.def_charset | "us-ascii" | `INI_SYSTEM` |

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`mailparse.def_charset` string
  The default character set.

## 资源类型

Mailparse defines the resource type `mailparse_mail_structure`, which is returned by mailparse_msg_create() and mailparse_msg_parse_file().

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`MAILPARSE_EXTRACT_OUTPUT` (int)
`MAILPARSE_EXTRACT_STREAM` (int)
`MAILPARSE_EXTRACT_RETURN` (int)

# Mailparse 函数

# mailparse_determine_best_xfer_encoding

(PECL mailparse >= 0.9.0)

mailparse_determine_best_xfer_encoding — Gets the best way of encoding

### 说明

function mailparse_determine_best_xfer_encoding(resource `$fp`): string

Figures out the best way of encoding the content read from the given file pointer.

### 参数

`fp`
  A valid file pointer, which must be seek-able.

### 返回值

Returns one of the character encodings supported by the mbstring module.

### 示例

示例 #1 mailparse_determine_best_xfer_encoding() example

    <?php

    $fp = fopen('somemail.eml', 'r');
    echo 'Best encoding: ' . mailparse_determine_best_xfer_encoding($fp);

    ?>

以上示例的输出类似于：

    Best encoding: 7bit

# mailparse_msg_create

(PECL mailparse >= 0.9.0)

mailparse_msg_create — Create a mime mail resource

### 说明

function mailparse_msg_create(): resource

Create a `MIME` mail resource.

### 参数

此函数没有参数。

### 返回值

Returns a handle that can be used to parse a message.

### 注释

> 注意: It is recommended to call mailparse_msg_free() on the result of this function, when it is no longer needed, to avoid memory leaks.

### 参见

- 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

### 说明

function mailparse_msg_extract_part(resource `$mimemail`, string `$msgbody`, callable `$callbackfunc` = ?): void
警告

本函数还未编写文档，仅有参数列表。

### 参数

`mimemail`
  A valid `MIME` resource.
`msgbody`
`callbackfunc`

### 返回值

没有返回值。

### 参见

- 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

### 说明

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.

### 参数

`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".

### 返回值

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.

### 参见

- 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

### 说明

function mailparse_msg_extract_whole_part_file(resource `$mimemail`, string `$filename`, callable `$callbackfunc` = ?): string
警告

本函数还未编写文档，仅有参数列表。

### 参数

`mimemail`
  A valid `MIME` resource.
`filename`
`callbackfunc`

### 返回值

### 参见

- 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

### 说明

function mailparse_msg_free(resource `$mimemail`): bool

Frees a `MIME` resource.

### 参数

`mimemail`
  A valid `MIME` resource allocated by mailparse_msg_create() or mailparse_msg_parse_file().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function mailparse_msg_get_part(resource `$mimemail`, string `$mimesection`): resource
警告

本函数还未编写文档，仅有参数列表。

### 参数

`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

### 说明

function mailparse_msg_get_part_data(resource `$mimemail`): array
警告

本函数还未编写文档，仅有参数列表。

### 参数

`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

### 说明

function mailparse_msg_get_structure(resource `$mimemail`): array
警告

本函数还未编写文档，仅有参数列表。

### 参数

`mimemail`
  A valid `MIME` resource.

# mailparse_msg_parse

(PECL mailparse >= 0.9.0)

mailparse_msg_parse — Incrementally parse data into buffer

### 说明

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.

### 参数

`mimemail`
  A valid `MIME` resource.
`data`

  > 注意: The final chunk of `data` is supposed to end with a newline (`CRLF`); otherwise the last line of the message will not be parsed.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# mailparse_msg_parse_file

(PECL mailparse >= 0.9.0)

mailparse_msg_parse_file — Parses a file

### 说明

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.

### 参数

`filename`
  Path to the file holding the message. The file is opened and streamed through the parser.

  > 注意: The message contained in `filename` is supposed to end with a newline (`CRLF`); otherwise the last line of the message will not be parsed.

### 返回值

Returns a `MIME` resource representing the structure, or `false` on error.

### 注释

> 注意: It is recommended to call mailparse_msg_free() on the result of this function, when it is no longer needed, to avoid memory leaks.

### 参见

- 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

### 说明

function mailparse_rfc822_parse_addresses(string `$addresses`): array

Parses a » RFC 822 compliant recipient list, such as that found in the `To:` header.

### 参数

`addresses`
  A string containing addresses, like in: `Wez Furlong <wez@example.com>, doe@example.com`

  > 注意: This string must not include the header name.

### 返回值

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.

### 示例

示例 #1 mailparse_rfc822_parse_addresses() example

    <?php

    $to = 'Wez Furlong <wez@example.com>, doe@example.com';
    var_dump(mailparse_rfc822_parse_addresses($to));

    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);

    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`fp`
  A valid file pointer.

### 返回值

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.

### 示例

示例 #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"]);

    ?>

以上示例会输出：

    BODY
    To: fred@example.com

    hello, this is some text hello.
    blah blah blah.

    UUE (test.txt)
    this is a test

## 目录

- 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

- 安装/配置
  - 安装
  - 运行时配置
  - 资源类型
- 预定义常量
- Mailparse 函数
  - 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 和 NNTP
  - 安装/配置
  - 预定义常量
  - IMAP 函数
  - IMAP\Connection — The IMAP\Connection class
- Mail
  - 安装/配置
  - Mail 函数
- Mailparse
  - 安装/配置
  - 预定义常量
  - Mailparse 函数

# 数学扩展

# BCMath 任意精度数学

# 简介

对于任意精度的数学， 如果有足够多的内存，PHP 提供的 BCMath 支持用字符串的形式表示任意大小和精度的数字，最大尺寸为 `2147483647`（即 `0x7FFFFFFF`）。

有效（即格式良好）的 BCMath 数字是匹配正则表达式 `/^[+-]?[0-9]*(\.[0-9]*)?$/` 的字符串。

警告

BCMath 函数想要操作的是 string，如果传入了 float 可能无法达到想要的效果， 因为 PHP 会将 float 的值转换为 string。 也就意味着 string 可能会带科学计数法符号（BCMath 并不支持）， 另外在 PHP 8.0.0 之前，小数点分隔符也不支持本地化（BCMath 只能识别英文句号小数点）。

    <?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'); // 使用逗号小数点
    $num2 = 1.2; // (string) 1.2 => '1,2'
    echo bcsub($num1, $num2, 1); // => '0.0'
    ?>

# 安装/配置

## 目录

- 安装
- 运行时配置

## 安装

本类函数仅在 PHP 编译时配置了 --enable-bcmath 时可用。

PHP 的 Windows 版本已内建对此扩展的支持。不需要载入额外的扩展来使用这些函数。

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

BC 数学库配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
bcmath.scale | "0" | `INI_ALL` |

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`bcmath.scale` int

  所有 bcmath 函数中十进制数字的数目。参见 bcscale()。

  > 注意: BcMath\Number 不受此设置的影响。

# BC 数学 函数

# bcadd

(PHP 4, PHP 5, PHP 7, PHP 8)

bcadd — 两个任意精度数字的加法计算

### 说明

function bcadd(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

对 `num1` 和 `num2` 求和。

### 参数

`num1`

  左操作数，字符串类型。

`num2`

  右操作数，字符串类型。

`scale`
  此参数用于设置结果小数点后的位数。 如果为 `null`，则默认为使用 bcscale() 设置的默认精度， 或者回退到 `bcmath.scale` INI 指令的值。

### 返回值

以字符串返回两个操作数求和之后的结果。

### 错误／异常

此函数在下列情况下抛出 ValueError：

- `num1` 或 `num2` 不是格式正确的 BCMath 数字字符串。
- `scale` 超出有效范围。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `scale` 可以为 null。

### 示例

示例 #1 bcadd() 示例

    <?php

    $a = '1.234';
    $b = '5';

    echo bcadd($a, $b);     // 6
    echo bcadd($a, $b, 4);  // 6.2340

    ?>

### 参见

- bcsub() - 两个任意精度数字的减法
- BcMath\Number::add() - Adds an arbitrary precision number

# bcceil

(PHP 8 >= 8.4.0)

bcceil — Round up arbitrary precision number

### 说明

function bcceil(string `$num`): string

Returns the next highest integer value by rounding up `num` if necessary.

### 参数

`num`
  The value to round.

### 返回值

Returns a numeric string representing `num` rounded up to the nearest integer.

### 错误／异常

This function throws a ValueError if `num` is not a well-formed BCMath numeric string.

### 示例

示例 #1 bcceil() example

    <?php
    var_dump(bcceil('4.3'));
    var_dump(bcceil('9.999'));
    var_dump(bcceil('-3.14'));
    ?>

以上示例会输出：

    string(1) "5"
    string(2) "10"
    string(2) "-3"

### 参见

- 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 — 比较两个任意精度的数字

### 说明

function bccomp(string `$num1`, string `$num2`, ?int `$scale` = `null`): int

将 `num1` 与 `num2` 进行比较，并返回整型数字的比较结果。

### 参数

`num1`

  左操作数，字符串类型。

`num2`

  右操作数，字符串类型。

`scale`
  此参数用于设置结果小数点后的位数。 如果为 `null`，则默认为使用 bcscale() 设置的默认精度， 或者回退到 `bcmath.scale` INI 指令的值。

### 返回值

如果所有的操作数相等返回 `0`；如果 `num1` 大于 `num2` 时返回 `1`，否则返回 `-1`。

### 错误／异常

此函数在下列情况下抛出 ValueError：

- `num1` 或 `num2` 不是格式正确的 BCMath 数字字符串。
- `scale` 超出有效范围。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `scale` 可以为 null。

### 示例

示例 #1 bccomp() 示例

    <?php

    echo bccomp('1', '2') . "\n";   // -1
    echo bccomp('1.00001', '1', 3); // 0
    echo bccomp('1.00001', '1', 5); // 1

    ?>

### 参见

- BcMath\Number::compare() - Compares two arbitrary precision numbers

# bcdiv

(PHP 4, PHP 5, PHP 7, PHP 8)

bcdiv — 两个任意精度的数字除法计算

### 说明

function bcdiv(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

`num1` 除以 `num2`。

### 参数

`num1`

  被除数，字符串类型。

`num2`

  除数，字符串类型。

`scale`
  此参数用于设置结果小数点后的位数。 如果为 `null`，则默认为使用 bcscale() 设置的默认精度， 或者回退到 `bcmath.scale` INI 指令的值。

### 返回值

返回字符串类型的除法结果。

### 错误／异常

此函数在下列情况下抛出 ValueError：

- `num1` 或 `num2` 不是格式正确的 BCMath 数字字符串。
- `scale` 超出有效范围。

如果 `num2` 为 `0`，此函数会抛出 DivisionByZeroError 异常。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `scale` 可以为 null。
8.0.0 | 现在，除以 `0` 会引发 DivisionByZeroError 异常，而不是返回 `null`。

### 示例

示例 #1 bcdiv() 示例

    <?php

    echo bcdiv('105', '6.55957', 3);  // 16.007

    ?>

### 参见

- bcdivmod() - Get the quotient and modulus of an arbitrary precision number
- bcmod() - 任意精度数字取模
- bcmul() - 两个任意精度数字乘法计算
- 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

### 说明

function bcdivmod(string `$num1`, string `$num2`, ?int `$scale` = `null`): array

Get the quotient and remainder of dividing `num1` by `num2`.

### 参数

`num1`

  被除数，字符串类型。

`num2`

  除数，字符串类型。

`scale`
  此参数用于设置结果小数点后的位数。 如果为 `null`，则默认为使用 bcscale() 设置的默认精度， 或者回退到 `bcmath.scale` INI 指令的值。

### 返回值

Returns an indexed array where the first element is the quotient as a string and the second element is the remainder as a string.

### 错误／异常

此函数在下列情况下抛出 ValueError：

- `num1` 或 `num2` 不是格式正确的 BCMath 数字字符串。
- `scale` 超出有效范围。

如果 `num2` 为 `0`，此函数会抛出 DivisionByZeroError 异常。

### 示例

示例 #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
    ?>

示例 #2 bcdivmod() with decimals

    <?php
    [$quot, $rem] = bcdivmod('5.7', '1.3', 1);
    echo $quot; // 4
    echo $rem;  // 0.5
    ?>

### 参见

- bcdiv() - 两个任意精度的数字除法计算
- bcmod() - 任意精度数字取模
- 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

### 说明

function bcfloor(string `$num`): string

Returns the next lowest integer value by rounding down `num` if necessary.

### 参数

`num`
  The value to round.

### 返回值

Returns a numeric string representing `num` rounded down to the nearest integer.

### 错误／异常

This function throws a ValueError if `num` is not a well-formed BCMath numeric string.

### 示例

示例 #1 bcfloor() example

    <?php
    var_dump(bcfloor('4.3'));
    var_dump(bcfloor('9.999'));
    var_dump(bcfloor('-3.14'));
    ?>

以上示例会输出：

    string(1) "4"
    string(1) "9"
    string(2) "-4"

### 参见

- 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 — 任意精度数字取模

### 说明

function bcmod(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

对 `num1` 使用 `num2` 取模。结果与 `num1` 的符号相同。

### 参数

`num1`

  左操作数，字符串类型。

`num2`

  右操作数，字符串类型。

`scale`
  此参数用于设置结果小数点后的位数。 如果为 `null`，则默认为使用 bcscale() 设置的默认精度， 或者回退到 `bcmath.scale` INI 指令的值。

### 返回值

返回字符串类型取模后的结果。

### 错误／异常

此函数在下列情况下抛出 ValueError：

- `num1` 或 `num2` 不是格式正确的 BCMath 数字字符串。
- `scale` 超出有效范围。

如果 `num2` 为 `0`，此函数会抛出 DivisionByZeroError 异常。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `scale` 可以为 null。
8.0.0 | 现在，除以 `0` 会引发 DivisionByZeroError 异常，而不是返回 `null`。
7.2.0 | 现在 `num1` 和 `num2` 不会截断成整数。 所以现在 bcmod() 的表现更接近 fmod() 而不是 `%` 操作符。
7.2.0 | 新增参数 `scale`。

### 示例

示例 #1 bcmod() 示例

    <?php
    bcscale(0);
    echo bcmod( '5',  '3'); //  2
    echo bcmod( '5', '-3'); //  2
    echo bcmod('-5',  '3'); // -2
    echo bcmod('-5', '-3'); // -2
    ?>

示例 #2 带小数点的 bcmod()

    <?php
    bcscale(1);
    echo bcmod('5.7', '1.3'); // PHP 7.2.0 起是 0.5；之前是 0
    ?>

### 参见

- bcdiv() - 两个任意精度的数字除法计算
- 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 — 两个任意精度数字乘法计算

### 说明

function bcmul(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

`num1` 乘以 `num2`。

### 参数

`num1`

  左操作数，字符串类型。

`num2`

  右操作数，字符串类型。

`scale`
  此参数用于设置结果小数点后的位数。 如果为 `null`，则默认为使用 bcscale() 设置的默认精度， 或者回退到 `bcmath.scale` INI 指令的值。

### 返回值

返回字符串类型的结果。

### 错误／异常

此函数在下列情况下抛出 ValueError：

- `num1` 或 `num2` 不是格式正确的 BCMath 数字字符串。
- `scale` 超出有效范围。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `scale` 可以为 null。
7.3.0 | 现在 bcmul() 可以按想要的小数点位数返回数字。 而之前，返回的数字会忽略尾随零（trailing decimal zeroes）。

### 示例

示例 #1 bcmul() 示例

    <?php
    echo bcmul('1.34747474747', '35', 3); // 47.161
    echo bcmul('2', '4'); // 8
    ?>

### 注释

> 注意:

> PHP 7.3.0 之前，bcmul() 返回的结果中小数位数可能比 `scale` 参数指定的少。只有当结果不需要 `scale` 允许的所有精度时，才会发生这种情况。例如：

> 示例 #2 bcmul() 进位制示例

>     <?php
>     echo bcmul('5', '2', 2);     // 打印“10”而不是“10.00”
>     ?>

### 参见

- bcdiv() - 两个任意精度的数字除法计算
- BcMath\Number::mul() - Multiplies an arbitrary precision number

# bcpow

(PHP 4, PHP 5, PHP 7, PHP 8)

bcpow — 任意精度数字的乘方

### 说明

function bcpow(string `$num`, string `$exponent`, ?int `$scale` = `null`): string

`num` 的 `exponent` 次方运算。

### 参数

`num`

  string 类型的底数。

`exponent`

  string 类型的指数。必须是没有小数部分的值。指数的有效范围取决于平台，但起码支持 `-2147483648` 到 `2147483647` 的范围。

`scale`
  此参数用于设置结果小数点后的位数。 如果为 `null`，则默认为使用 bcscale() 设置的默认精度， 或者回退到 `bcmath.scale` INI 指令的值。

### 返回值

返回字符串类型的结果。

### 错误／异常

函数在下列情况会抛出 ValueError：

- `num` 或 `exponent` 不是格式正确的 BCMath 数字字符串
- `exponent` 有小数部分
- `exponent` 或 `scale` 超出有效范围

如果 `num` 为 `0` 且 `exponent` 为负值，则此函数抛出 DivisionByZeroError 异常。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | `0` 的负幂以前返回 `0`，但现在会引发 DivisionByZeroError 异常。
8.0.0 | 当 `exponent` 有小数部分时，现在会抛出 ValueError 而不是截断。
7.3.0 | 现在 bcpow() 可以按想要的小数点位数返回数字。 而之前，返回的数字会忽略尾随零（trailing decimal zeroes）。

### 示例

示例 #1 bcpow() 示例

    <?php

    echo bcpow('4.2', '3', 2); // 74.08

    ?>

### 注释

> 注意:

> PHP 7.3.0 之前，bcpow() 返回的结果，小数点后的小数位数可能比 `scale` 参数指定的少。只有当结果不需要 `scale` 允许的所有小数位数时，才会发生这种情况。例如：

> 示例 #2 bcpow() 小数位数示例

>     <?php
>     echo bcpow('5', '2', 2);     // 打印 "25" 而不是 "25.00"
>     ?>

### 参见

- bcpowmod() - Raise an arbitrary precision number to another, reduced by a specified modulus
- bcsqrt() - 任意精度数字的二次方根
- BcMath\Number::pow() - Raises an arbitrary precision number

# bcpowmod

(PHP 5, PHP 7, PHP 8)

bcpowmod — Raise an arbitrary precision number to another, reduced by a specified modulus

### 说明

function bcpowmod(
string `$num`,
string `$exponent`,
string `$modulus`,
?int `$scale` = `null`
): string

Use the fast-exponentiation method to raise `num` to the power `exponent` with respect to the modulus `modulus`.

### 参数

`num`

  The base, as an integral string (i.e. the scale has to be zero).

`exponent`

  The exponent, as an non-negative, integral string (i.e. the scale has to be zero).

`modulus`

  The modulus, as an integral string (i.e. the scale has to be zero).

`scale`
  此参数用于设置结果小数点后的位数。 如果为 `null`，则默认为使用 bcscale() 设置的默认精度， 或者回退到 `bcmath.scale` INI 指令的值。

### 返回值

Returns the result as a string.

### 错误／异常

This function throws a ValueError in the following cases:

- `num`, `exponent` or `modulus` is not a well-formed BCMath numeric string
- `num`, `exponent` or `modulus` has a fractional part
- `exponent` is a negative value
- `scale` is outside the valid range

This function throws a DivisionByZeroError exception if `modulus` is `0`.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `scale` is now nullable.
8.0.0 | Now throws a ValueError instead of returning `false` if `exponent` is a negative value.
8.0.0 | Dividing by `0` now throws a DivisionByZeroError exception instead of returning `false`.

### 示例

The following two statements are functionally identical. The bcpowmod() version however, executes in less time and can accept larger parameters.

    <?php
    $a = bcpowmod($x, $y, $mod);

    $b = bcmod(bcpow($x, $y), $mod);

    // $a and $b are equal to each other.

    ?>

### 注释

> 注意:

> Because this method uses the modulus operation, numbers which are not positive integers may give unexpected results.

### 参见

- bcpow() - 任意精度数字的乘方
- bcmod() - 任意精度数字取模
- BcMath\Number::powmod() - Raises an arbitrary precision number, reduced by a specified modulus

# bcround

(PHP 8 >= 8.4.0)

bcround — Round arbitrary precision number

### 说明

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).

### 参数

`num`

  要处理的值。

`precision`

  可选的十进制小数点后数字的数目。

  如果 `precision` 是正数，则 `num` 会四舍五入到小数点后 `precision` 位有效数字。

  如果 `precision` 是负数，则 `num` 四舍五入到小数点前 `precision` 位有效数字。即 `pow(10, -$precision)` 最接近的倍数，例如，`precision` 为 -1，`num` 可以四舍五入到十位，`precision` 为 -2，`num` 可以四舍五入到百位，等等。

`mode`
  Specifies the rounding mode. For more information about modes, see RoundingMode.

### 返回值

Returns a numeric string representing `num` rounded to the given precision.

### 错误／异常

This function throws a ValueError in the following cases:

- `num` is not a well-formed BCMath numeric string.
- An invalid `mode` is specified.

### 示例

示例 #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));
    ?>

以上示例会输出：

    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"

示例 #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));
    ?>

以上示例会输出：

    string(7) "123.450"
    string(6) "123.45"
    string(5) "123.5"
    string(3) "123"
    string(3) "120"
    string(3) "100"
    string(1) "0"

示例 #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));
    ?>

以上示例会输出：

    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"

示例 #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));
    ?>

以上示例会输出：

    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"

### 参见

- 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 — 设置/获取所有 bc math 函数的默认小数点保留位数

### 说明

function bcscale(int `$scale`): int

设置所有 bc math 函数在未设定情况下的小数点保留位数。

function bcscale(null `$scale` = `null`): int

获取当前的小数点保留位数。

### 参数

`scale`

  小数点保留位数。

### 返回值

设置的时候，返回之前的小数点保留位数。否则就是返回当前的位数。

### 错误／异常

如果 `scale` 超出有效范围，函数抛出 ValueError。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `scale` 可以为 null。
7.3.0 | 现在 bcscale() 不仅可以设置，还可以获取当前的小数点保留位数。 用于设置的时候，现在会返回之前的位数。 之前 `scale` 是强制的参数， 且 bcscale() 总是返回 `true`。

### 示例

示例 #1 bcscale() 示例

    <?php

    // 默认小数点位数： 3
    bcscale(3);
    echo bcdiv('105', '6.55957'); // 16.007

    // 不调用 bcscale() 也一样
    echo bcdiv('105', '6.55957', 3); // 16.007

    ?>

# bcsqrt

(PHP 4, PHP 5, PHP 7, PHP 8)

bcsqrt — 任意精度数字的二次方根

### 说明

function bcsqrt(string `$num`, ?int `$scale` = `null`): string

返回 `num` 的二次方根。

### 参数

`num`

  操作数，格式良好的 BCMath 数字字符串。

`scale`
  此参数用于设置结果小数点后的位数。 如果为 `null`，则默认为使用 bcscale() 设置的默认精度， 或者回退到 `bcmath.scale` INI 指令的值。

### 返回值

返回平方根，作为格式良好的 BCMath 数字字符串。

### 错误／异常

此函数在以下情况下引发 ValueError 错误：

- `num` 不是格式良好的 BCMath 数字字符串
- `num` 小于 `0`
- `scale` 超出有效范围

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 如果 `num` 不是格式良好的 BCMath 数字字符串，或小于 `0`，则会引发 ValueError 错误。之前，会引发 `E_WARNING` 错误。
8.0.0 | 现在，`scale` 的取值范围必须在 `0` 到 `2147483647` 之间；之前，负数的 scale 值会被静默处理为 `0`。
8.0.0 | 现在 `scale` 可以为 null。

### 示例

示例 #1 bcsqrt() 示例

    <?php

    echo bcsqrt('2', 3); // 1.414

    ?>

### 参见

- bcpow() - 任意精度数字的乘方
- BcMath\Number::sqrt() - Gets the square root of an arbitrary precision number

# bcsub

(PHP 4, PHP 5, PHP 7, PHP 8)

bcsub — 两个任意精度数字的减法

### 说明

function bcsub(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

`num1` 减去 `num2`。

### 参数

`num1`

  左操作数，字符串类型。

`num2`

  右操作数，字符串类型。

`scale`
  此参数用于设置结果小数点后的位数。 如果为 `null`，则默认为使用 bcscale() 设置的默认精度， 或者回退到 `bcmath.scale` INI 指令的值。

### 返回值

以 string 类型返回减法之后的结果。

### 错误／异常

此函数在下列情况下抛出 ValueError：

- `num1` 或 `num2` 不是格式正确的 BCMath 数字字符串。
- `scale` 超出有效范围。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | 现在 `scale` 可以为 null。

### 示例

示例 #1 bcsub() 示例

    <?php

    $a = '1.234';
    $b = '5';

    echo bcsub($a, $b);     // -3
    echo bcsub($a, $b, 4);  // -3.7660

    ?>

### 参见

- bcadd() - 两个任意精度数字的加法计算
- BcMath\Number::sub() - Subtracts an arbitrary precision number

## 目录

- bcadd — 两个任意精度数字的加法计算
- bcceil — Round up arbitrary precision number
- bccomp — 比较两个任意精度的数字
- bcdiv — 两个任意精度的数字除法计算
- bcdivmod — Get the quotient and modulus of an arbitrary precision number
- bcfloor — Round down arbitrary precision number
- bcmod — 任意精度数字取模
- bcmul — 两个任意精度数字乘法计算
- bcpow — 任意精度数字的乘方
- bcpowmod — Raise an arbitrary precision number to another, reduced by a specified modulus
- bcround — Round arbitrary precision number
- bcscale — 设置/获取所有 bc math 函数的默认小数点保留位数
- bcsqrt — 任意精度数字的二次方根
- bcsub — 两个任意精度数字的减法

# The BcMath\Number class

(PHP 8 >= 8.4.0)

## 简介

A class for an arbitrary precision number. These objects support overloaded arithmetic and comparison operators.

> 注意: This class is not affected by the bcmath.scale INI directive set in php.ini.

> 注意: The behavior of an overloaded operator is the same as specifying `null` for the `scale` parameter on the corresponding method.

## 类摘要

namespace BcMath;
final readonly class Number implements Stringable {
/* 属性 */
public string $value;
public int $scale;
/* 方法 */
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
}

## 属性

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

### 说明

public function BcMath\Number::add(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Adds $this and `num`.

### 参数

`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.

### 返回值

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`.

### 错误／异常

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

### 示例

示例 #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);
    ?>

以上示例会输出：

    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)
    }

示例 #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);
    ?>

以上示例会输出：

    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)
    }

### 参见

- bcadd() - 两个任意精度数字的加法计算
- 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

### 说明

public function BcMath\Number::ceil(): BcMath\Number

Returns the next highest integer value by rounding up $this if necessary.

### 参数

此函数没有参数。

### 返回值

Returns the result as a new BcMath\Number object. The BcMath\Number::scale of the result is always `0`.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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)
    }

### 参见

- 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

### 说明

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.

### 参数

`num`
  The value to be compared to.
`scale`
  Specify the `scale` to use for comparison. If `null`, all digits are used in the comparison.

### 返回值

Returns `0` if the two numbers are equal, `1` if $this is greater than `num`, `-1` otherwise.

### 错误／异常

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

### 示例

示例 #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),
    );
    ?>

以上示例会输出：

    int(0)
    int(0)
    int(-1)
    int(1)

示例 #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),
    );
    ?>

以上示例会输出：

    int(0)
    int(-1)
    int(1)
    int(0)

### 参见

- bccomp() - 比较两个任意精度的数字

# BcMath\Number::__construct

(PHP 8 >= 8.4.0)

BcMath\Number::__construct — Creates a BcMath\Number object

### 说明

public function BcMath\Number::__construct(string|int `$num`)

Creates a BcMath\Number object from an int or string value.

### 参数

`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.

### 错误／异常

This method throws a ValueError if `num` is string and not a well-formed BCMath numeric string.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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)
    }

### 参见

- 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

### 说明

public function BcMath\Number::div(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Divides $this by `num`.

### 参数

`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.

### 返回值

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.

### 错误／异常

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`.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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)
    }

示例 #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);
    ?>

以上示例会输出：

    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)
    }

示例 #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'),
    );
    ?>

以上示例会输出：

    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)
    }

### 参见

- bcdiv() - 两个任意精度的数字除法计算
- 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

### 说明

public function BcMath\Number::divmod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): array

Gets the quotient and remainder of dividing $this by `num`.

### 参数

`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.

### 返回值

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`.

### 错误／异常

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`.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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)
    }

示例 #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);
    ?>

以上示例会输出：

    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)
    }

### 参见

- 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

### 说明

public function BcMath\Number::floor(): BcMath\Number

Returns the next highest integer value by rounding down $this if necessary.

### 参数

此函数没有参数。

### 返回值

Returns the result as a new BcMath\Number object. The BcMath\Number::scale of the result is always `0`.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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)
    }

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

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`.

### 错误／异常

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`.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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)
    }

示例 #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);
    ?>

以上示例会输出：

    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)
    }

### 参见

- bcmod() - 任意精度数字取模
- 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

### 说明

public function BcMath\Number::mul(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Multiplies $this by `num`.

### 参数

`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.

### 返回值

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`.

### 错误／异常

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

### 示例

示例 #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);
    ?>

以上示例会输出：

    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)
    }

示例 #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);
    ?>

以上示例会输出：

    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)
    }

### 参见

- bcmul() - 两个任意精度数字乘法计算
- 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

### 说明

public function BcMath\Number::pow(BcMath\Number|string|int `$exponent`, ?int `$scale` = `null`): BcMath\Number

Raises $this to the `exponent` power.

### 参数

`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.

### 返回值

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.

### 错误／异常

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.

### 示例

示例 #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);
    ?>

以上示例会输出：

    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)
    }

示例 #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);
    ?>

以上示例会输出：

    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)
    }

### 参见

- bcpow() - 任意精度数字的乘方
- 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

### 说明

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`.

### 参数

`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.

### 返回值

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`.

### 错误／异常

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`.

### 示例

示例 #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),
    );
    ?>

以上示例会输出：

    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)
    }

示例 #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),
    );
    ?>

以上示例会输出：

    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)
    }

### 参见

- bcpowmod() - Raise an arbitrary precision number to another, reduced by a specified modulus
- 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

### 说明

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).

### 参数

`precision`

  可选的十进制小数点后数字的数目。

  如果 `precision` 是正数，则 `num` 会四舍五入到小数点后 `precision` 位有效数字。

  如果 `precision` 是负数，则 `num` 四舍五入到小数点前 `precision` 位有效数字。即 `pow(10, -$precision)` 最接近的倍数，例如，`precision` 为 -1，`num` 可以四舍五入到十位，`precision` 为 -2，`num` 可以四舍五入到百位，等等。

`mode`
  Specifies the rounding mode. For more information about modes, see RoundingMode.

### 返回值

Returns the result as a new BcMath\Number object.

### 错误／异常

This method throws a ValueError if an invalid `mode` is specified.

### 示例

示例 #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),
    );
    ?>

以上示例会输出：

    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)
    }

示例 #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),
    );
    ?>

以上示例会输出：

    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)
    }

示例 #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),
    );
    ?>

以上示例会输出：

    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)
    }

示例 #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),
    );
    ?>

以上示例会输出：

    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)
    }

### 参见

- 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

### 说明

public function BcMath\Number::__serialize(): array

Serializes $this.

### 参数

此函数没有参数。

### 参见

- 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

### 说明

public function BcMath\Number::sqrt(?int `$scale` = `null`): BcMath\Number

Return the square root of $this.

### 参数

`scale`
  BcMath\Number::scale explicitly specified for calculation results. If `null`, the BcMath\Number::scale of the calculation result will be set automatically.

### 返回值

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`.

### 错误／异常

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

### 示例

示例 #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),
    );
    ?>

以上示例会输出：

    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)
    }

### 参见

- bcsqrt() - 任意精度数字的二次方根
- 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

### 说明

public function BcMath\Number::sub(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Subtracts `num` from $this.

### 参数

`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.

### 返回值

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`.

### 错误／异常

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

### 示例

示例 #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);
    ?>

以上示例会输出：

    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)
    }

示例 #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);
    ?>

以上示例会输出：

    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)
    }

### 参见

- bcsub() - 两个任意精度数字的减法
- BcMath\Number::add() - Adds an arbitrary precision number

# BcMath\Number::__toString

(PHP 8 >= 8.4.0)

BcMath\Number::__toString — Converts BcMath\Number to string

### 说明

public function BcMath\Number::__toString(): string

Converts BcMath\Number to string.

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function BcMath\Number::__unserialize(array `$data`): void

Deserializes a data parameter into a BcMath\Number object.

### 参数

`data`
  The serialized data parameter as an associative array

### 错误／异常

This method throws a ValueError if invalid serialized data is passed.

### 参见

- BcMath\Number::__construct() - Creates a BcMath\Number object
- BcMath\Number::serialize()

## 目录

- 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

- 安装/配置
  - 安装
  - 运行时配置
- BC 数学 函数
  - bcadd — 两个任意精度数字的加法计算
  - bcceil — Round up arbitrary precision number
  - bccomp — 比较两个任意精度的数字
  - bcdiv — 两个任意精度的数字除法计算
  - bcdivmod — Get the quotient and modulus of an arbitrary precision number
  - bcfloor — Round down arbitrary precision number
  - bcmod — 任意精度数字取模
  - bcmul — 两个任意精度数字乘法计算
  - bcpow — 任意精度数字的乘方
  - bcpowmod — Raise an arbitrary precision number to another, reduced by a specified modulus
  - bcround — Round arbitrary precision number
  - bcscale — 设置/获取所有 bc math 函数的默认小数点保留位数
  - bcsqrt — 任意精度数字的二次方根
  - bcsub — 两个任意精度数字的减法
- 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

# 简介

These functions allow for arbitrary-length integers to be worked with using the GNU MP library.

> 注意:

> Most GMP functions accept GMP number arguments. These are shown in this documentation as GMP objects. Most of these functions will also accept numeric and string arguments, so long as it is possible to convert the latter to a number. Also, if there is a more performant function that can operate on the arguments (integers only), then it will be used instead (this is done transparently). See also the gmp_init() function.

> 注意:

> The arithmetic, bitwise, and comparison operators may be used with the GMP objects returned from gmp_init() and other GMP functions.

警告

Large integers must be specified as strings - otherwise, PHP will coerce them to floats, resulting in a loss of precision.

# 安装/配置

## 目录

- 需求
- 安装

## 需求

The GMP library can be downloaded from » http://gmplib.org/#DOWNLOAD. This site also has the GMP manual available.

At least GMP version 4.2 is required, with some functions requiring a more recent version of the GMP library.

On Windows, MPIR is required instead of GMP.

## 安装

In order to have these functions available, PHP must be compiled with GMP support by using the --with-gmp option.

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`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)
  The GMP library version
`GMP_MPIR_VERSION` (string)
  The MPIR library version.

# 示例

示例 #1 Factorial function using 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";
    ?>

This will calculate factorial of 1000 (pretty big number) very fast.

# GMP 函数

## 参见

More mathematical functions can be found in the 数学扩展 section

# gmp_abs

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_abs — Absolute value

### 说明

function gmp_abs(GMP|int|string `$num`): GMP

Get the absolute value of a number.

### 参数

`num`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

Returns the absolute value of `num`, as a GMP number.

### 示例

示例 #1 gmp_abs() example

    <?php
    $abs1 = gmp_abs("274982683358");
    $abs2 = gmp_abs("-274982683358");

    echo gmp_strval($abs1) . "\n";
    echo gmp_strval($abs2) . "\n";
    ?>

以上示例会输出：

    274982683358
    274982683358

# gmp_add

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_add — Add numbers

### 说明

function gmp_add(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Add two numbers.

### 参数

`num1`
  The first summand (augend). GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`num2`

  The second summand (addend).

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

A GMP number representing the sum of the arguments.

### 示例

示例 #1 gmp_add() example

    <?php
    $sum = gmp_add("123456789012345", "76543210987655");
    echo gmp_strval($sum) . "\n";
    ?>

以上示例会输出：

    200000000000000

# gmp_and

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_and — Bitwise AND

### 说明

function gmp_and(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Calculates bitwise AND of two GMP numbers.

### 参数

`num1`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`num2`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

A GMP number representing the bitwise `AND` comparison.

### 示例

示例 #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";
    ?>

以上示例会输出：

    4
    0

# gmp_binomial

(PHP 7 >= 7.3.0, PHP 8)

gmp_binomial — Calculates binomial coefficient

### 说明

function gmp_binomial(GMP|int|string `$n`, int `$k`): GMP

Calculates the binomial coefficient C(n, k).

### 参数

`n`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`k`

### 返回值

Returns the binomial coefficient C(n, k).

### 错误／异常

Throws ValueError if `k` is negative. Prior to PHP 8.0.0, `E_WARNING` was issued instead.

### 更新日志

版本 | 说明
--- | ---
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

### 说明

function gmp_clrbit(GMP `$num`, int `$index`): void

Clears (sets to 0) bit `index` in `num`. The index starts at 0.

### 参数

`num`

  A GMP object.

`index`

  The index of the bit to clear. Index 0 represents the least significant bit.

### 返回值

没有返回值。

### 示例

示例 #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";
    ?>

以上示例会输出：

    254

### 注释

> 注意:

> 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.

### 参见

- 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

### 说明

function gmp_cmp(GMP|int|string `$num1`, GMP|int|string `$num2`): int

Compares two numbers.

### 参数

`num1`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`num2`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

Returns a positive value if `a > b`, zero if `a = b` and a negative value if `a < b`.

### 示例

示例 #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";
    ?>

以上示例会输出：

    1 -1 0

# gmp_com

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_com — Calculates one's complement

### 说明

function gmp_com(GMP|int|string `$num`): GMP

Returns the one's complement of `num`.

### 参数

`num`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

Returns the one's complement of `num`, as a GMP number.

### 示例

示例 #1 gmp_com() example

    <?php
    $com = gmp_com("1234");
    echo gmp_strval($com) . "\n";
    ?>

以上示例会输出：

    -1235

# gmp_div

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div — 别名 gmp_div_q()

### 说明

此函数是该函数的别名： gmp_div_q().

# gmp_div_q

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_q — Divide numbers

### 说明

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.

### 参数

`num1`

  The number being divided.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`num2`

  The number that `num1` is being divided by.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`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`.
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

GMP 对象。

### 示例

示例 #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";
    ?>

以上示例会输出：

    20
    0
    1
    0
    -1

### 注释

> 注意:

> This function can also be called as gmp_div().

### 参见

- 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

### 说明

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`.

### 参数

`num1`

  The number being divided.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`num2`

  The number that `num1` is being divided by.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`rounding_mode`

  See the gmp_div_q() function for description of the `rounding_mode` argument.

### 返回值

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).

### 示例

示例 #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]));
    ?>

### 参见

- 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

### 说明

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.

### 参数

`num1`

  The number being divided.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`num2`

  The number that `num1` is being divided by.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`rounding_mode`

  See the gmp_div_q() function for description of the `rounding_mode` argument.

### 返回值

The remainder, as a GMP number.

### 示例

示例 #1 gmp_div_r() example

    <?php
    $div = gmp_div_r("105", "20");
    echo gmp_strval($div) . "\n";
    ?>

以上示例会输出：

    5

### 参见

- 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

### 说明

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`.

### 参数

`num1`

  The number being divided.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`num2`

  The number that `num1` is being divided by.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

GMP 对象。

### 示例

示例 #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";
    ?>

以上示例会输出：

    5
    2863311534

# gmp_export

(PHP 5 >= 5.6.1, PHP 7, PHP 8)

gmp_export — Export to a binary string

### 说明

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

### 参数

`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`.

### 返回值

Returns a string.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | This function no longer returns `false` on failure.

### 示例

示例 #1 gmp_export() example

    <?php
    $number = gmp_init(16705);
    echo gmp_export($number) . "\n";
    ?>

以上示例会输出：

    AA

### 参见

- gmp_import() - Import from a binary string

# gmp_fact

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_fact — Factorial

### 说明

function gmp_fact(GMP|int|string `$num`): GMP

Calculates factorial (`num!`) of `num`.

### 参数

`num`

  The factorial number.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

GMP 对象。

### 示例

示例 #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";
    ?>

以上示例会输出：

    120
    30414093201713378043612608166064768844377641568960512000000000000

# gmp_gcd

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_gcd — Calculate GCD

### 说明

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.

### 参数

`num1`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`num2`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

A positive GMP number that divides into both `num1` and `num2`.

### 示例

示例 #1 gmp_gcd() example

    <?php
    $gcd = gmp_gcd("12", "21");
    echo gmp_strval($gcd) . "\n";
    ?>

以上示例会输出：

    3

### 参见

- gmp_lcm() - Calculate LCM

# gmp_gcdext

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_gcdext — Calculate GCD and multipliers

### 说明

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

### 参数

`num1`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`num2`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

An array of GMP numbers.

### 示例

示例 #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

### 说明

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.

### 参数

`num1`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

  It should be positive.

`num2`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

  It should be positive.

### 返回值

The hamming distance between `num1` and `num2`, as an int.

### 示例

示例 #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";
    ?>

以上示例会输出：

    6
    6

### 参见

- 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

### 说明

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

### 参数

`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`.

### 返回值

Returns a GMP number.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | This function no longer returns `false` on failure.

### 示例

示例 #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";
    ?>

以上示例会输出：

    0
    258

### 参见

- 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

### 说明

function gmp_init(int|string `$num`, int `$base` = 0): GMP

Creates a GMP number from an integer or string.

### 参数

`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.

### 返回值

GMP 对象。

### 更新日志

版本 | 说明
--- | ---
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.

### 示例

示例 #1 Creating GMP number

    <?php
    $a = gmp_init(123456);
    $b = gmp_init("0xFFFFDEBACDFEDF7200");
    ?>

### 注释

> 注意:

> 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().

### 参见

- 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

### 说明

function gmp_intval(GMP|int|string `$num`): int

This function converts GMP number into native PHP ints.

### 参数

`num`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

The int value of `num`.

### 示例

示例 #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";
    ?>

以上示例会输出：

    2147483647
    2147483647
    2147483648

### 注释

警告

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

### 说明

function gmp_invert(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP|false

Computes the inverse of `num1` modulo `num2`.

### 参数

`num1`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`num2`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

A GMP number on success or `false` if an inverse does not exist.

### 示例

示例 #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";
    ?>

以上示例会输出：

    9

# gmp_jacobi

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_jacobi — Jacobi symbol

### 说明

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.

### 参数

`num1`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`num2`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

  Should be odd and must be positive.

### 返回值

GMP 对象。

### 示例

示例 #1 gmp_jacobi() example

    <?php
    echo gmp_jacobi("1", "3") . "\n";
    echo gmp_jacobi("2", "3") . "\n";
    ?>

以上示例会输出：

    1
    0

### 参见

- gmp_kronecker() - Kronecker symbol
- gmp_legendre() - Legendre symbol

# gmp_kronecker

(PHP 7 >= 7.3.0, PHP 8)

gmp_kronecker — Kronecker symbol

### 说明

function gmp_kronecker(GMP|int|string `$num1`, GMP|int|string `$num2`): int

This function computes the Kronecker symbol of `num1` and `num2`.

### 参数

`num1`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`num2`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

Returns the Kronecker symbol of `num1` and `num2`

### 参见

- gmp_jacobi() - Jacobi symbol
- gmp_legendre() - Legendre symbol

# gmp_lcm

(PHP 7 >= 7.3.0, PHP 8)

gmp_lcm — Calculate LCM

### 说明

function gmp_lcm(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

This function computes the least common multiple (lcm) of `num1` and `num2`.

### 参数

`num1`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`num2`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

GMP 对象。

### 参见

- gmp_gcd() - Calculate GCD

# gmp_legendre

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_legendre — Legendre symbol

### 说明

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.

### 参数

`num1`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`num2`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

  Should be odd and must be positive.

### 返回值

GMP 对象。

### 示例

示例 #1 gmp_legendre() example

    <?php
    echo gmp_legendre("1", "3") . "\n";
    echo gmp_legendre("2", "3") . "\n";
    ?>

以上示例会输出：

    1
    0

### 参见

- 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

### 说明

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.

### 参数

`num1`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`num2`

  The modulo that is being evaluated.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

GMP 对象。

### 示例

示例 #1 gmp_mod() example

    <?php
    $mod = gmp_mod("8", "3");
    echo gmp_strval($mod) . "\n";
    ?>

以上示例会输出：

    2

# gmp_mul

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_mul — Multiply numbers

### 说明

function gmp_mul(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Multiplies `num1` by `num2` and returns the result.

### 参数

`num1`

  A number that will be multiplied by `num2`.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`num2`

  A number that will be multiplied by `num1`.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

GMP 对象。

### 示例

示例 #1 gmp_mul() example

    <?php
    $mul = gmp_mul("12345678", "2000");
    echo gmp_strval($mul) . "\n";
    ?>

以上示例会输出：

    24691356000

# gmp_neg

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_neg — Negate number

### 说明

function gmp_neg(GMP|int|string `$num`): GMP

Returns the negative value of a number.

### 参数

`num`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

Returns -`num`, as a GMP number.

### 示例

示例 #1 gmp_neg() example

    <?php
    $neg1 = gmp_neg("1");
    echo gmp_strval($neg1) . "\n";
    $neg2 = gmp_neg("-1");
    echo gmp_strval($neg2) . "\n";
    ?>

以上示例会输出：

    -1
    1

# gmp_nextprime

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

gmp_nextprime — Find next prime number

### 说明

function gmp_nextprime(GMP|int|string `$num`): GMP

Find next prime number

### 参数

`num`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

Return the next prime number greater than `num`, as a GMP number.

### 示例

示例 #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";
    ?>

以上示例会输出：

    11
    2

### 注释

> 注意:

> 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

### 说明

function gmp_or(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Calculates bitwise inclusive OR of two GMP numbers.

### 参数

`num1`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`num2`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

GMP 对象。

### 示例

示例 #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";
    ?>

以上示例会输出：

    fffffff6
    fffffff2

# gmp_perfect_power

(PHP 7 >= 7.3.0, PHP 8)

gmp_perfect_power — Perfect power check

### 说明

function gmp_perfect_power(GMP|int|string `$num`): bool

Checks whether `num` is a perfect power.

### 参数

`num`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

Returns `true` if `num` is a perfect power, `false` otherwise.

### 参见

- 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

### 说明

function gmp_perfect_square(GMP|int|string `$num`): bool

Check if a number is a perfect square.

### 参数

`num`

  The number being checked as a perfect square.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

Returns `true` if `num` is a perfect square, `false` otherwise.

### 示例

示例 #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"));
    ?>

以上示例会输出：

    bool(true)
    bool(false)
    bool(true)

### 参见

- 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

### 说明

function gmp_popcount(GMP|int|string `$num`): int

Get the population count.

### 参数

`num`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

The population count of `num`, as an int.

### 示例

示例 #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";
    ?>

以上示例会输出：

    3
    7

# gmp_pow

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_pow — Raise number into power

### 说明

function gmp_pow(GMP|int|string `$num`, int `$exponent`): GMP

Raise `num` into power `exponent`.

### 参数

`num`

  The base number.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`exponent`

  The positive power to raise the `num`.

### 返回值

The new (raised) number, as a GMP number. The case of `0^0` yields 1.

### 示例

示例 #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";
    ?>

以上示例会输出：

    2147483648
    1

# gmp_powm

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_powm — Raise number into power with modulo

### 说明

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.

### 参数

`num`

  The base number.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`exponent`

  The positive power to raise the `num`.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`modulus`

  The modulo.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

The new (raised) number, as a GMP number.

### 示例

示例 #1 gmp_powm() example

    <?php
    $pow1 = gmp_powm("2", "31", "2147483649");
    echo gmp_strval($pow1) . "\n";
    ?>

以上示例会输出：

    2147483648

# gmp_prob_prime

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_prob_prime — Check if number is "probably prime"

### 说明

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.

### 参数

`num`

  The number being checked as a prime.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`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.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

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.

### 示例

示例 #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";
    ?>

以上示例会输出：

    0
    1
    2

# gmp_random

(PHP 4 >= 4.0.4, PHP 5, PHP 7)

gmp_random — Random number

警告

本函数已自 PHP 7.2.0 起被废弃，并自 PHP 8.0.0 起被移除。 强烈建议不要依赖本函数。

### 说明

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.

警告

本函数并不会生成安全加密的值，并且不可用于加密或者要求返回值不可猜测的目的。

如果需要加密安全随机，则可以将 Random\Engine\Secure 引擎用于 Random\Randomizer。对于简单的用例，random_int() 和 random_bytes() 函数提供了操作系统的 CSPRNG 支持的方便且安全的 API。

### 参数

`limiter`

  The limiter.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

A random GMP number.

### 示例

示例 #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";
    ?>

以上示例会输出：

    1915834968
    8642564075890328087

# gmp_random_bits

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

gmp_random_bits — Random number

### 说明

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.

警告

本函数并不会生成安全加密的值，并且不可用于加密或者要求返回值不可猜测的目的。

如果需要加密安全随机，则可以将 Random\Engine\Secure 引擎用于 Random\Randomizer。对于简单的用例，random_int() 和 random_bytes() 函数提供了操作系统的 CSPRNG 支持的方便且安全的 API。

### 参数

`bits`

  The number of bits to generate.

### 返回值

A random GMP number.

### 错误／异常

If `bits` is less than `1`, a ValueError will be thrown.

### 示例

示例 #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";
    ?>

以上示例会输出：

    3
    15

# gmp_random_range

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

gmp_random_range — Get a uniformly selected integer

### 说明

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`.

警告

本函数并不会生成安全加密的值，并且不可用于加密或者要求返回值不可猜测的目的。

如果需要加密安全随机，则可以将 Random\Engine\Secure 引擎用于 Random\Randomizer。对于简单的用例，random_int() 和 random_bytes() 函数提供了操作系统的 CSPRNG 支持的方便且安全的 API。

### 参数

`min`

  A GMP number representing the lower bound for the random number

`max`

  A GMP number representing the upper bound for the random number

### 返回值

Returns a GMP object which contains a uniformly selected integer from the closed interval [`min`, `max`]. Both `min` and `max` are possible return values.

### 错误／异常

If `max` is less than `min`, a ValueError will be thrown.

### 示例

示例 #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";
    ?>

以上示例会输出：

    42
    -67

# gmp_random_seed

(PHP 7, PHP 8)

gmp_random_seed — Sets the RNG seed

### 说明

function gmp_random_seed(GMP|int|string `$seed`): void

### 参数

`seed`

  The seed to be set for the gmp_random(), gmp_random_bits(), and gmp_random_range() functions.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

没有返回值。

### 错误／异常

Throws a ValueError if `seed` is invalid.

### 更新日志

版本 | 说明
--- | ---
8.0.0 | If `seed` is invalid, gmp_random_seed() now throws a ValueError. Previously it emitted an `E_WARNING` and returned `false`.

### 示例

示例 #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'));

以上示例会输出：

    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)

### 参见

- 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

### 说明

function gmp_root(GMP|int|string `$num`, int `$nth`): GMP

Takes the `nth` root of `num` and returns the integer component of the result.

### 参数

`num`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`nth`

  The positive root to take of `num`.

### 返回值

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

### 说明

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.

### 参数

`num`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`nth`

  The positive root to take of `num`.

### 返回值

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

### 说明

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.

### 参数

`num1`

  The number to scan.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`start`

  The starting bit.

### 返回值

Returns the index of the found bit, as an int. The index starts from 0.

### 示例

示例 #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";
    ?>

以上示例会输出：

    3
    7

# gmp_scan1

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_scan1 — Scan for 1

### 说明

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.

### 参数

`num1`

  The number to scan.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`start`

  The starting bit.

### 返回值

Returns the index of the found bit, as an int. If no set bit is found, -1 is returned.

### 示例

示例 #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";
    ?>

以上示例会输出：

    3
    9

# gmp_setbit

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_setbit — Set bit

### 说明

function gmp_setbit(GMP `$num`, int `$index`, bool `$value` = `true`): void

Sets bit `index` in `num`.

### 参数

`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).

### 返回值

没有返回值。

### 示例

示例 #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";
    ?>

以上示例会输出：

    2 -> 0b10
    3 -> 0b11

示例 #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";
    ?>

以上示例会输出：

    253 -> 0b11111101
    255 -> 0b11111111

示例 #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";
    ?>

以上示例会输出：

    255 -> 0b11111111
    254 -> 0b11111110

### 注释

> 注意:

> 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.

### 参见

- 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

### 说明

function gmp_sign(GMP|int|string `$num`): int

Checks the sign of a number.

### 参数

`num`

  Either a GMP object, or a numeric string provided that it is possible to convert the latter to an int.

### 返回值

Returns 1 if `num` is positive, -1 if `num` is negative, and 0 if `num` is zero.

### 示例

示例 #1 gmp_sign() example

    <?php
    // positive
    echo gmp_sign("500") . "\n";

    // negative
    echo gmp_sign("-500") . "\n";

    // zero
    echo gmp_sign("0") . "\n";
    ?>

以上示例会输出：

    1
    -1
    0

### 参见

- gmp_abs() - Absolute value
- abs() - 绝对值

# gmp_sqrt

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sqrt — Calculate square root

### 说明

function gmp_sqrt(GMP|int|string `$num`): GMP

Calculates square root of `num`.

### 参数

`num`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

The integer portion of the square root, as a GMP number.

### 示例

示例 #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";
    ?>

以上示例会输出：

    3
    2
    1234567890

# gmp_sqrtrem

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sqrtrem — Square root with remainder

### 说明

function gmp_sqrtrem(GMP|int|string `$num`): array

Calculate the square root of a number, with remainder.

### 参数

`num`

  The number being square rooted.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

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).

### 示例

示例 #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";
    ?>

以上示例会输出：

    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

### 说明

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.

### 参数

`num`

  The GMP number that will be converted to a string.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`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.

### 返回值

The number, as a string.

### 示例

示例 #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

### 说明

function gmp_sub(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Subtracts `num2` from `num1` and returns the result.

### 参数

`num1`

  The number being subtracted from.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`num2`

  The number subtracted from `num1`.

  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

GMP 对象。

### 示例

示例 #1 gmp_sub() example

    <?php
    $sub = gmp_sub("281474976710656", "4294967296"); // 2^48 - 2^32
    echo gmp_strval($sub) . "\n";
    ?>

以上示例会输出：

    281470681743360

# gmp_testbit

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gmp_testbit — Tests if a bit is set

### 说明

function gmp_testbit(GMP|int|string `$num`, int `$index`): bool

Tests if the specified bit is set.

### 参数

`num`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`index`

  The bit to test

### 返回值

Returns `true` if the bit is set in `num`, otherwise `false`.

### 错误／异常

An `E_WARNING` level error is issued when `index` is less than zero, and `false` is returned.

### 示例

示例 #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));
    ?>

以上示例会输出：

    bool(false)
    bool(true)

### 参见

- 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

### 说明

function gmp_xor(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Calculates bitwise exclusive OR (XOR) of two GMP numbers.

### 参数

`num1`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。
`num2`
  GMP 对象、int 或 string，可以按照跟在 gmp_init() 中使用字符串并自动检测 base（即当 base 等于 0 时）相同的逻辑将其解释为数字。

### 返回值

GMP 对象。

### 示例

示例 #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";
    ?>

以上示例会输出：

    1011110111000100

## 目录

- 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 — 别名 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)

## 简介

A GMP number. These objects support overloaded arithmetic, bitwise and comparison operators.

> 注意:

> No object-oriented interface is provided to manipulate GMP objects. Please use the procedural GMP API.

## 类摘要

final class GMP {
/* 方法 */
public function __construct(int|string `$num` = 0, int `$base` = 0)
public function __serialize(): array
public function __unserialize(array `$data`): void
}

## 更新日志

版本 | 说明
--- | ---
8.4.0 | GMP is now marked final

# GMP::__construct

(PHP 8 >= 8.2.4)

GMP::__construct — Create GMP number

### 说明

public function GMP::__construct(int|string `$num` = 0, int `$base` = 0)

Creates a GMP number from an integer or string.

### 参数

`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.

### 参见

- gmp_init() - Create GMP number

# GMP::__serialize

(PHP 8 >= 8.1.0)

GMP::__serialize — Serializes the GMP object

### 说明

public function GMP::__serialize(): array

警告

本函数还未编写文档，仅有参数列表。

### 参数

此函数没有参数。

### 返回值

没有返回值。

# GMP::__unserialize

(PHP 8 >= 8.1.0)

GMP::__unserialize — Deserializes the `data` parameter into a GMP object

### 说明

public function GMP::__unserialize(array `$data`): void

警告

本函数还未编写文档，仅有参数列表。

### 参数

`data`

  The value being deserialized.

### 返回值

没有返回值。

## 目录

- GMP::__construct — Create GMP number
- GMP::__serialize — Serializes the GMP object
- GMP::__unserialize — Deserializes the data parameter into a GMP object

- 安装/配置
  - 需求
  - 安装
- 预定义常量
- 示例
- GMP 函数
  - 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 — 别名 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

# 数学函数

# 简介

这些数学函数将只处理 int 和 float 类型范围内的值。要处理更大的数字，请查看任意精度数学函数或 GNU 多精度函数。

## 参见

- 算术运算符
- 任意精度数学函数
- GNU 多精度函数

# 预定义常量

下列常量作为 PHP 核心的一部分总是可用的。

数学常量
`M_PI` (float)
  π（圆周率）的近似值（`3.14159265358979323846`）。
`M_E` (float)
  自然常数 `e`的近似值（`2.7182818284590452354`）。
`M_LOG2E` (float)
  `log2(e)` 的近似值（`1.4426950408889634074`）。
`M_LOG10E` (float)
  `log10(e)` 的近似值（`0.43429448190325182765`）。
`M_LN2` (float)
  `ln(2)` 的近似值（`0.69314718055994530942`）。
`M_LN10` (float)
  `ln(10)` 的近似值（`2.30258509299404568402`）。
`M_PI_2` (float)
  `π/2` 的近似值（`1.57079632679489661923`）。
`M_PI_4` (float)
  `π/4` 的近似值（`0.78539816339744830962`）。
`M_1_PI` (float)
  `1/π` 的近似值（`0.31830988618379067154`）。
`M_2_PI` (float)
  `2/π` 的近似值（`0.63661977236758134308`）。
`M_SQRTPI` (float)
  `sqrt(π)` 的近似值（`1.77245385090551602729`）。
`M_2_SQRTPI` (float)
  `2/sqrt(π)` 的近似值（`1.12837916709551257390`）。
`M_SQRT2` (float)
  `sqrt(2)` 的近似值（`1.41421356237309504880`).
`M_SQRT3` (float)
  `sqrt(3)` 的近似值（`1.73205080756887729352`）。
`M_SQRT1_2` (float)
  `1/sqrt(2)` 的近似值（`0.70710678118654752440`）。
`M_LNPI` (float)
  `ln(π)` 的近似值（`1.14472988584940017414`）。
`M_EULER` (float)
  欧拉常数 γ 的近似值（`0.57721566490153286061`）。

IEEE 754 浮点数常量
`NAN` (float)
  不是数字
`INF` (float)
  无穷

舍入常量

> 注意: 自 PHP 8.4.0 起，建议改用 RoundingMode 枚举。

`PHP_ROUND_HALF_UP` (int)
  四舍五入（当值为 .5 时，向远离 0 的方向舍入。如 -2.5 舍入为 -3，2.5 舍入为 3）
`PHP_ROUND_HALF_DOWN` (int)
  四舍五入（当值为 .5 时，向朝向 0 的方向舍入。如 -2.5 舍入为 -2，2.5 舍入为 2）
`PHP_ROUND_HALF_EVEN` (int)
  银行家舍入（四舍六入五取偶法）
`PHP_ROUND_HALF_ODD` (int)
  四舍六入五取奇法（跟四舍六入五取偶法相对。但是中文并没有相关示例）

# The RoundingMode Enum

(PHP 8 >= 8.4.0)

## 简介

The RoundingMode enum is used to specify how rounding should be performed for round(), bcround(), and BcMath\Number::round().

## 注解摘要

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.
}

# Math 函数

# abs

(PHP 4, PHP 5, PHP 7, PHP 8)

abs — 绝对值

### 说明

function abs(int|float `$num`): int|float

返回参数 `num` 的绝对值。

### 参数

`num`

  要处理的数字值

### 返回值

`num` 的绝对值。 如果参数 `num` 是 float，则返回的类型也是 float，否则返回 int（因为 float 通常比 int 有更大的取值范围）。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `num` 不再接受支持数字转换的内部对象。

### 示例

示例 #1 abs() 示例

    <?php
    var_dump(abs(-4.2));
    var_dump(abs(5));
    var_dump(abs(-5));
    ?>

以上示例会输出：

    float(4.2)
    int(5)
    int(5)

### 参见

- gmp_abs() - Absolute value
- gmp_sign() - Sign of number

# acos

(PHP 4, PHP 5, PHP 7, PHP 8)

acos — 反余弦

### 说明

function acos(float `$num`): float

返回 `num` 的反余弦值，单位是弧度。acos() 是 cos() 的反函数，它的意思是对于 acos() 的定义域中的每个 `num` 值，`$num == cos(acos($num))`。

### 参数

`num`

  要处理的参数

### 返回值

`num` 的反余弦弧度。

### 参见

- cos() - 余弦
- acosh() - 反双曲余弦
- asin() - 反正弦
- atan() - 反正切

# acosh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

acosh — 反双曲余弦

### 说明

function acosh(float `$num`): float

返回 `num` 的反双曲余弦值，即其双曲余弦为 `num` 的那个值。

### 参数

`num`

  要处理的值

### 返回值

`num` 反双曲余弦

### 参见

- cosh() - 双曲余弦
- acos() - 反余弦
- asinh() - 反双曲正弦
- atanh() - 反双曲正切

# asin

(PHP 4, PHP 5, PHP 7, PHP 8)

asin — 反正弦

### 说明

function asin(float `$num`): float

返回 `num` 的反正弦值，单位是弧度。asin() 是 sin() 的反函数，它的意思是对于 asin() 的定义域中的每个 `num` 值，`$num == sin(asin($num))`。

### 参数

`num`

  待处理的参数

### 返回值

`num` 的反正弦弧度。

### 参见

- sin() - 正弦
- asinh() - 反双曲正弦
- acos() - 反余弦
- atan() - 反正切

# asinh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

asinh — 反双曲正弦

### 说明

function asinh(float `$num`): float

返回 `num` 的反双曲正弦值，即，其双曲正弦为 `num` 的那个值。

### 参数

`num`

  要处理的参数

### 返回值

返回 `num` 的反双曲正弦

### 参见

- sinh() - 双曲正弦
- asin() - 反正弦
- acosh() - 反双曲余弦
- atanh() - 反双曲正切

# atan

(PHP 4, PHP 5, PHP 7, PHP 8)

atan — 反正切

### 说明

function atan(float `$num`): float

返回 `num` 的反正切值，单位是弧度。atan() 是 tan() 的反函数，它的意思是对于 atan() 的定义域中的每个 `num` 值，`$num == tan(atan($num))`。

### 参数

`num`

  要处理的参数

### 返回值

`num` 的反正切弧度。

### 参见

- tan() - 正切
- atanh() - 反双曲正切
- asin() - 反正弦
- acos() - 反余弦

# atan2

(PHP 4, PHP 5, PHP 7, PHP 8)

atan2 — 两个参数的反正切

### 说明

function atan2(float `$y`, float `$x`): float

本函数计算两个变量 `x` 和 `y` 的反正切值。和计算 `y` / `x` 的反正切相似，只除了两个参数的符号是用来确定结果的象限之外。

本函数的结果为弧度，其值在 -PI 和 PI 之间（包括 -PI 和 PI）。

### 参数

`y`

  Dividend parameter

`x`

  Divisor parameter

### 返回值

`x` 和 `y` 的反正切弧度值。

### 参见

- atan() - 反正切

# atanh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

atanh — 反双曲正切

### 说明

function atanh(float `$num`): float

返回 `num` 的反双曲正切值，即，其双曲正切为 `num` 的那个值。

### 参数

`num`

  要处理的参数

### 返回值

`num` 的反双曲正切

### 参见

- tanh() - 双曲正切
- atan() - 反正切
- asinh() - 反双曲正弦
- acosh() - 反双曲余弦

# base_convert

(PHP 4, PHP 5, PHP 7, PHP 8)

base_convert — 在任意进制之间转换数字

### 说明

function base_convert(string `$num`, int `$from_base`, int `$to_base`): string

返回字符串，包含 `num` 以 `to_base` 进制的表示。`num` 本身的进制由 `from_base` 指定。`from_base` 和 `to_base` 都只能在 2 和 36 之间（包括 2 和 36）。高于十进制的数字用字母 a-z 表示，例如 a 表示 10，b 表示 11 以及 z 表示 35。字母的大小无关紧要，即 `num` 不区分大小写。

警告

由于使用内部的 float 类型，base_convert() 的操作可能会导致大数值中的精度丢失。请参见本手册的浮点数章节以便获得更多详细信息。

### 参数

`num`

  要转换的数字。`num` 中的任何无效字符都会默认忽略。自 PHP 7.4.0 起，弃用使用任何无效字符。

`from_base`

  `num` 的进制数

`to_base`

  `num` 要转换为的进制数

### 返回值

`num` 转换为 `to_base` 进制

### 更新日志

版本 | 说明
--- | ---
7.4.0 | 传递任何无效字符现在将生成弃用通知。但仍会计算结果，就好像无效字符不存在一样。

### 示例

示例 #1 base_convert() 示例

    <?php
    $hexadecimal = 'a37334';
    echo base_convert($hexadecimal, 16, 2);
    ?>

以上示例会输出：

    101000110111001100110100

### 参见

- intval() - 获取变量的整数值

# bindec

(PHP 4, PHP 5, PHP 7, PHP 8)

bindec — 二进制转换为十进制

### 说明

function bindec(string `$binary_string`): int|float

返回 `binary_string` 参数所表示的二进制数的十进制等价值。

bindec() 将一个二进制数转换成 int，或者出于大小的需要，转换为 float 类型。

bindec() 将所有的 `binary_string` 值解释为无符号整数。这是由于 bindec() 函数将其最高有效位视为数量级而非符号位。

### 参数

`binary_string`

  要转换的二进制字符串。`binary_string` 中的任何无效字符都会默认忽略。自 PHP 7.4.0 起，弃用使用任何无效字符。

警告

参数必须为字符串。使用其他数据类型会导致不可预知的结果。

### 返回值

`binary_string` 的十进制数值

### 更新日志

版本 | 说明
--- | ---
7.4.0 | 传递任何无效字符现在将生成弃用通知。但仍会计算结果，就好像无效字符不存在一样。

### 示例

示例 #1 bindec() 示例

    <?php
    echo bindec('110011') . "\n";
    echo bindec('000110011') . "\n";

    echo bindec('111');
    ?>

以上示例会输出：

    51
    51
    7

示例 #2 bindec() 将输入解读为无符号整数

    <?php
    /*
     * The lesson from this example is in the output
     * rather than the PHP code itself.
     */

    $magnitude_lower = pow(2, (PHP_INT_SIZE * 8) - 2);
    p($magnitude_lower - 1);
    p($magnitude_lower, 'See the rollover?  Watch it next time around...');

    p(PHP_INT_MAX, 'PHP_INT_MAX');
    p(~PHP_INT_MAX, 'interpreted to be one more than PHP_INT_MAX');

    if (PHP_INT_SIZE == 4) {
        $note = 'interpreted to be the largest unsigned integer';
    } else {
        $note = 'interpreted to be the largest unsigned integer
                  (18446744073709551615) but skewed by float precision';
    }
    p(-1, $note);

    function p($input, $note = '') {
        echo "input:        $input\n";

        $format = '%0' . (PHP_INT_SIZE * 8) . 'b';
        $bin = sprintf($format, $input);
        echo "binary:       $bin\n";

        ini_set('precision', 20);  // For readability on 64 bit boxes.
        $dec = bindec($bin);
        echo 'bindec():     ' . $dec . "\n";

        if ($note) {
            echo "NOTE:         $note\n";
        }

        echo "\n";
    }
    ?>

以上示例在 32 位机器上的输出:

    input:        1073741823
    binary:       00111111111111111111111111111111
    bindec():     1073741823

    input:        1073741824
    binary:       01000000000000000000000000000000
    bindec():     1073741824
    NOTE:         See the rollover?  Watch it next time around...

    input:        2147483647
    binary:       01111111111111111111111111111111
    bindec():     2147483647
    NOTE:         PHP_INT_MAX

    input:        -2147483648
    binary:       10000000000000000000000000000000
    bindec():     2147483648
    NOTE:         interpreted to be one more than PHP_INT_MAX

    input:        -1
    binary:       11111111111111111111111111111111
    bindec():     4294967295
    NOTE:         interpreted to be the largest unsigned integer

以上示例在 64 位机器上的输出:

    input:        4611686018427387903
    binary:       0011111111111111111111111111111111111111111111111111111111111111
    bindec():     4611686018427387903

    input:        4611686018427387904
    binary:       0100000000000000000000000000000000000000000000000000000000000000
    bindec():     4611686018427387904
    NOTE:         See the rollover?  Watch it next time around...

    input:        9223372036854775807
    binary:       0111111111111111111111111111111111111111111111111111111111111111
    bindec():     9223372036854775807
    NOTE:         PHP_INT_MAX

    input:        -9223372036854775808
    binary:       1000000000000000000000000000000000000000000000000000000000000000
    bindec():     9223372036854775808
    NOTE:         interpreted to be one more than PHP_INT_MAX

    input:        -1
    binary:       1111111111111111111111111111111111111111111111111111111111111111
    bindec():     18446744073709551616
    NOTE:         interpreted to be the largest unsigned integer
                  (18446744073709551615) but skewed by float precision

### 注释

> 注意:

> 此函数可以将太大的数字转换为适应平台的 int 类型，在这种情况下，较大值将会作为 float 返回。

### 参见

- decbin() - 十进制转换为二进制
- octdec() - 八进制转换为十进制
- hexdec() - 十六进制转换为十进制
- base_convert() - 在任意进制之间转换数字

# ceil

(PHP 4, PHP 5, PHP 7, PHP 8)

ceil — 进一法取整

### 说明

function ceil(int|float `$num`): float

如果有必要，通过对 `num` 向上取整返回下一个最高的整数。

### 参数

`num`

  要进一法取整的值

### 返回值

返回不小于 `num` 的下一个整数。ceil() 返回的类型仍然是 float，因为 float 值的范围通常比 int 要大。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `num` 不再接受支持数字转换的内部对象。

### 示例

示例 #1 ceil() 示例

    <?php
    echo ceil(4.3), PHP_EOL;    // 5
    echo ceil(9.999), PHP_EOL;  // 10
    echo ceil(-3.14), PHP_EOL;  // -3
    ?>

### 参见

- floor() - 舍去法取整
- round() - 对浮点数进行四舍五入

# cos

(PHP 4, PHP 5, PHP 7, PHP 8)

cos — 余弦

### 说明

function cos(float `$num`): float

cos() 返回参数 `num` 的余弦值。参数 `num` 的单位为弧度。

### 参数

`num`

  以弧度表示的角度

### 返回值

`num` 的余弦值

### 示例

示例 #1 cos() 示例

    <?php

    echo cos(M_PI); // -1

    ?>

### 参见

- acos() - 反余弦
- sin() - 正弦
- tan() - 正切
- deg2rad() - 将角度转换为弧度

# cosh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cosh — 双曲余弦

### 说明

function cosh(float `$num`): float

返回 `num` 的双曲余弦值，定义为 `(exp($num) + exp(-$num))/2`。

### 参数

`num`

  要处理的参数

### 返回值

`num` 的双曲余弦值。

### 参见

- cos() - 余弦
- acosh() - 反双曲余弦
- sinh() - 双曲正弦
- tanh() - 双曲正切

# decbin

(PHP 4, PHP 5, PHP 7, PHP 8)

decbin — 十进制转换为二进制

### 说明

function decbin(int `$num`): string

返回字符串，包含有给定 `num` 参数的二进制表示。

### 参数

`num`

  要转换的十进制值

  32 位机器上的输入范围
  正 `num` | 负 `num` | 返回值
  --- | --- | ---
  0 |  | 0
  1 |  | 1
  2 |  | 10
  ... normal progression ...
  2147483646 |  | 1111111111111111111111111111110
  2147483647（最大有符号整数） |  | 1111111111111111111111111111111 (31 1's)
  2147483648 | -2147483648 | 10000000000000000000000000000000
  ... normal progression ...
  4294967294 | -2 | 11111111111111111111111111111110
  4294967295（最大无符号整数） | -1 | 11111111111111111111111111111111 (32 1's)

  64 位机器上的输入范围
  正 `num` | 负 `num` | 返回值
  --- | --- | ---
  0 |  | 0
  1 |  | 1
  2 |  | 10
  ... normal progression ...
  9223372036854775806 |  | 111111111111111111111111111111111111111111111111111111111111110
  9223372036854775807（最大有符号整数） |  | 111111111111111111111111111111111111111111111111111111111111111 (63 1's)
  | -9223372036854775808 | 1000000000000000000000000000000000000000000000000000000000000000
  ... normal progression ...
  | -2 | 1111111111111111111111111111111111111111111111111111111111111110
  | -1 | 1111111111111111111111111111111111111111111111111111111111111111 (64 1's)

### 返回值

`num` 的二进制字符串表示

### 示例

示例 #1 decbin() 示例

    <?php
    echo decbin(12) . "\n";
    echo decbin(26);
    ?>

以上示例会输出：

    1100
    11010

### 参见

- bindec() - 二进制转换为十进制
- decoct() - 十进制转换为八进制
- dechex() - 十进制转换为十六进制
- base_convert() - 在任意进制之间转换数字
- printf() - 输出格式化字符串，格式使用 `%b`、`%032b` 或 `%064b`
- sprintf() - 返回格式化字符串，格式使用 `%b`、`%032b` 或 `%064b`

# dechex

(PHP 4, PHP 5, PHP 7, PHP 8)

dechex — 十进制转换为十六进制

### 说明

function dechex(int `$num`): string

返回一字符串，包含有给定 `num` 参数的十六进制表示。

所能转换的最大数值为十进制的 `PHP_INT_MAX``* 2 + 1` (或 `-1`)：在 32 位平台上是十进制的 `4294967295`，其 dechex() 的结果为 `ffffffff`。

### 参数

`num`

  要转换的十进制值

  PHP 的 int 类型是有符号的，但 dechex() 处理无符号整数，负正数会以无符号处理。

### 返回值

`num` 的16进制表示

### 示例

示例 #1 dechex() 示例

    <?php
    echo dechex(10) . "\n";
    echo dechex(47);
    ?>

以上示例会输出：

    a
    2f

示例 #2 大整数的 dechex() 示例

    <?php
    // 下面的输出假设是 32 位平台。
    // 注意输出的所有值一样。
    echo dechex(-1)."\n";
    echo dechex(PHP_INT_MAX * 2 + 1)."\n";
    echo dechex(pow(2, 32) - 1)."\n";
    ?>

以上示例会输出：

    ffffffff
    ffffffff
    ffffffff

### 参见

- hexdec() - 十六进制转换为十进制
- decbin() - 十进制转换为二进制
- decoct() - 十进制转换为八进制
- base_convert() - 在任意进制之间转换数字

# decoct

(PHP 4, PHP 5, PHP 7, PHP 8)

decoct — 十进制转换为八进制

### 说明

function decoct(int `$num`): string

返回一字符串，包含有给定 `num` 参数的八进制表示。可以转换的最大数字取决于平台。对于 32 位平台通常是十进制的 `4294967295`，结果是 `37777777777`。对于 64 位平台通常是十进制的 `9223372036854775807`，结果是 `777777777777777777777`。

### 参数

`num`

  待转换的十进制值

### 返回值

`num` 参数八进制表示的字符串。

### 示例

示例 #1 decoct() 示例

    <?php
    echo decoct(15) . "\n";
    echo decoct(264);
    ?>

以上示例会输出：

    17
    410

### 参见

- octdec() - 八进制转换为十进制
- decbin() - 十进制转换为二进制
- dechex() - 十进制转换为十六进制
- base_convert() - 在任意进制之间转换数字

# deg2rad

(PHP 4, PHP 5, PHP 7, PHP 8)

deg2rad — 将角度转换为弧度

### 说明

function deg2rad(float `$num`): float

本函数把 `num` 从角度转换成弧度。

### 参数

`num`

  以角度为单位的值

### 返回值

`num` 等量的弧度值

### 示例

示例 #1 deg2rad() 示例

    <?php

    echo deg2rad(45), PHP_EOL; // 0.785398163397
    var_dump(deg2rad(45) === M_PI_4); // bool(true)

    ?>

### 参见

- rad2deg() - 将弧度数转换为相应的角度数

# exp

(PHP 4, PHP 5, PHP 7, PHP 8)

exp — 计算 `e` 的指数

### 说明

function exp(float `$num`): float

返回 `e` 的 `num` 次方值。

> 注意:

> 用“`e`”作为自然对数的底数，大约为 2.718282。

### 参数

`num`

  要处理的参数

### 返回值

'e' raised to the power of `num`

### 示例

示例 #1 exp() 示例

    <?php
    echo exp(12), PHP_EOL;
    echo exp(5.7);
    ?>

以上示例会输出：

    162754.791419
    298.86740096706

### 参见

- log() - 自然对数
- pow() - 指数表达式

# expm1

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

expm1 — 返回 `exp($num) - 1`，甚至当 number 的值接近零也能计算出准确结果

### 说明

function expm1(float `$num`): float

expm1() 返回 `exp($`num`) - 1`，甚至当 `num` 的值接近零也能计算出准确结果。但是当两个数值趋近于相等的时候，`exp($`num`) - 1`就会变得不太准确。

### 参数

`num`

  要处理的参数

### 返回值

`e` 的 `num` 次方减 1。

### 参见

- log1p() - 返回 log(1 + number)，甚至当 number 的值接近零也能计算出准确结果
- exp() - 计算 e 的指数

# fdiv

(PHP 8)

fdiv — Divides two numbers, according to IEEE 754

### 说明

function fdiv(float `$num1`, float `$num2`): float

Returns the floating point result of dividing the `num1` by the `num2`. If the `num2` is zero, then one of `INF`, -`INF`, or `NAN` will be returned.

Note that in comparisons, `NAN` will never be equal (`==`) or identical (`===`) to any value, including itself.

### 参数

`num1`

  The dividend (numerator)

`num2`

  The divisor

### 返回值

The floating point result of `num1`/`num2`

### 示例

示例 #1 Using 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)
    ?>

### 参见

- Division operator `/`
- intdiv() - 对除法结果取整 - Integer division
- fmod() - 返回除法的浮点数余数
- fpow() - Raise one number to the power of another, according to IEEE 754

# floor

(PHP 4, PHP 5, PHP 7, PHP 8)

floor — 舍去法取整

### 说明

function floor(int|float `$num`): float

如有必要，通过对 `num` 向下取整（作为浮点数）。

### 参数

`num`

  要取整的数字

### 返回值

对 `num` 向下取整。floor() 返回的类型仍然是 float。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | `num` 不再接受支持数字转换的内部对象。

### 示例

示例 #1 floor() 示例

    <?php
    echo floor(4.3), PHP_EOL;   // 4
    echo floor(9.999), PHP_EOL; // 9
    echo floor(-3.14), PHP_EOL; // -4
    ?>

### 参见

- ceil() - 进一法取整
- round() - 对浮点数进行四舍五入

# fmod

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

fmod — 返回除法的浮点数余数

### 说明

function fmod(float `$num1`, float `$num2`): float

返回被除数（`num1`）除以除数（`num2`）所得的浮点数余数。余数（r）的定义是：num1 = i * num2 + r，其中 i 是整数。如果 `num2` 是非零值，则 r 和 `num1` 的符号相同并且其数量值小于 `num2`。

### 参数

`num1`

  被除数

`num2`

  除数

### 返回值

`num1`/`num2` 的浮点数余数。 如果第二个参数为 0，`NAN` （float）。

### 示例

示例 #1 fmod() 的使用

    <?php
    $x = 5.7;
    $y = 1.3;
    $r = fmod($x, $y);
    // $r equals 0.5, because 4 * 1.3 + 0.5 = 5.7

    var_dump($x, $y, $r);
    ?>

### 参见

- `/`——浮点除法
- `%`——整数取模
- intdiv() - 对除法结果取整——整数除法

# fpow

(PHP 8 >= 8.4.0)

fpow — Raise one number to the power of another, according to IEEE 754

### 说明

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.

### 参数

`num`
  The base to use.
`exponent`
  The exponent.

### 返回值

Returns a float corresponding to `$num$exponent`.

### 示例

示例 #1 fpow() example

    <?php
    var_dump(fpow(10, 2));
    var_dump(fpow(0, -3));
    var_dump(fpow(-1, 5.5));
    ?>

以上示例会输出：

    float(100)
    float(INF)
    float(NAN)

### 参见

- Exponentiation operator `**`
- pow() - 指数表达式
- fdiv() - Divides two numbers, according to IEEE 754
- fmod() - 返回除法的浮点数余数

# hexdec

(PHP 4, PHP 5, PHP 7, PHP 8)

hexdec — 十六进制转换为十进制

### 说明

function hexdec(string `$hex_string`): int|float

返回与 `hex_string` 参数所表示的十六进制数等值的的十进制数。hexdec() 将一个十六进制字符串转换为十进制数。

hexdec() 会忽略它遇到的任意非十六进制的字符。自 PHP 7.4.0 起，弃用使用任何无效字符。

### 参数

`hex_string`

  要转换的十六进制的字符串

### 返回值

`hex_string` 十进制的表示

### 更新日志

版本 | 说明
--- | ---
7.4.0 | 传递任何无效字符现在将生成弃用通知。但仍会计算结果，就好像无效字符不存在一样。

### 示例

示例 #1 hexdec() 示例

    <?php
    var_dump(hexdec("ee")); // prints "int(238)"
    var_dump(hexdec("a0")); // prints "int(160)"
    ?>

示例 #2 hexdec() 包含无效字符

    <?php
    var_dump(hexdec("See"));  // print "int(238)"
    var_dump(hexdec("that")); // print "int(10)"
    ?>

### 注释

> 注意:

> 此函数可以将太大的数字转换为适应平台的 int 类型，在这种情况下，较大值将会作为 float 返回。

### 参见

- dechex() - 十进制转换为十六进制
- bindec() - 二进制转换为十进制
- octdec() - 八进制转换为十进制
- base_convert() - 在任意进制之间转换数字

# hypot

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

hypot — 计算直角三角形的斜边长度

### 说明

function hypot(float `$x`, float `$y`): float

hypot() 函数将会根据直角三角形的两直角边长度 `x` 和 `y` 计算其斜边的长度。或者是坐标点 （`x`, `y`）到原点的距离。该函数的算法等同于 `sqrt($x*$x + $y*$y)`。

### 参数

`x`

  第一条边的长度

`y`

  第二条边的长度

### 返回值

计算斜边的长度

# intdiv

(PHP 7, PHP 8)

intdiv — 对除法结果取整

### 说明

function intdiv(int `$num1`, int `$num2`): int

返回 `num1` 除以 `num2` 商数的整数部分。

### 参数

`num1`

  被除数。

`num2`

  除数。

### 返回值

`num1` 除以 `num2` 的商，对该商取整。

### 错误／异常

如果 `num2` 是 `0`，将抛出 DivisionByZeroError 异常。如果 `num1` 是 `PHP_INT_MIN` 并且 `num2` 是 `-1`，将抛出 ArithmeticError 异常.

### 示例

示例 #1 intdiv() 的一些示例

    <?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));
    ?>

以上示例会输出：

    int(1)
    int(-1)
    int(-1)
    int(1)
    int(1)
    int(1)

示例 #2 intdiv() 无效除数的示例

    <?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;
    }
    ?>

以上示例会输出：

    ArithmeticError: Division of PHP_INT_MIN by -1 is not an integer
    DivisionByZeroError: Division by zero

### 参见

- `/`——浮点除法
- `%`——整数取模
- fmod() - 返回除法的浮点数余数——浮点数取模

# is_finite

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_finite — 判断浮点数是否是有效的有限值

### 说明

function is_finite(float `$num`): bool

返回指定的 `num` 是否是有限浮点数。

有限浮点数既不是 `NAN`（is_nan()）也不是无限的（is_infinite()）。

### 参数

`num`

  要检查的 float

### 返回值

如果 `num` 不是 `NAN`、`INF` 或 -`INF`，那么为 `true`，否则为 `false`。

### 示例

示例 #1 is_finite() 示例

    <?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));
    ?>

以上示例会输出：

    float(1.2345)
    bool(true)
    float(NAN)
    bool(false)
    float(INF)
    bool(false)

### 参见

- is_infinite() - 判断浮点数是否为无限值
- is_nan() - 判断浮点数是否是否为 NAN

# is_infinite

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_infinite — 判断浮点数是否为无限值

### 说明

function is_infinite(float `$num`): bool

返回指定的 `num` 是否是 `INF` 或 -`INF`。

### 参数

`num`

  要检查的 float

### 返回值

如果 `num` 是 `INF` 或 -`INF`，返回 `true`，否则返回 `false`。

### 示例

示例 #1 is_infinite() 示例

    <?php
    $inf = 1e308 * 2;

    var_dump($inf, is_infinite($inf));

    $negative_inf = -$inf;

    var_dump($negative_inf, is_infinite($negative_inf));
    ?>

以上示例会输出：

    float(INF)
    bool(true)
    float(-INF)
    bool(true)

### 参见

- is_finite() - 判断浮点数是否是有效的有限值
- is_nan() - 判断浮点数是否是否为 NAN

# is_nan

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_nan — 判断浮点数是否是否为 NAN

### 说明

function is_nan(float `$num`): bool

返回指定的 `num` 是否是 `NAN`（非数值）。

`NAN` 是从未定义的数学运算中返回的，例如传递的参数在函数的输入域之外的时候。平方根（sqrt()）仅对正数定义，传递负数将导致 `NAN`。返回 `NAN` 的其它操作示例有 `INF` 除以 `INF` 以及涉及现有 `NAN` 值的任何操作。

> 注意:

> 尽管名字叫 Not A Number，但 `NAN` 是有效的 float 类型。

警告

`NAN` 不能与 `NAN` 进行比较。要检测浮点数是否是 `NAN`，必须使用 is_nan()。使用 `$float === NAN` 检测将不起作用。

### 参数

`num`

  要检查的 float

### 返回值

如果 `num` 是 `NAN`，返回 `true`，否则返回 `false`。

### 示例

示例 #1 is_nan() 示例

    <?php
    $nan = sqrt(-1);

    var_dump($nan, is_nan($nan));
    ?>

以上示例会输出：

    float(NAN)
    bool(true)

### 参见

- is_finite() - 判断浮点数是否是有效的有限值
- is_infinite() - 判断浮点数是否为无限值

# log

(PHP 4, PHP 5, PHP 7, PHP 8)

log — 自然对数

### 说明

function log(float `$num`, float `$base` = `M_E`): float

如果指定了可选的参数 `base`，log() 返回 logbase `num`，否则 log() 返回参数 `num` 的自然对数。

### 参数

`num`

  要计算对数的值

`base`

  可选的底数（默认是“e”，也可以说是自然对数）。

### 返回值

以 `base` 为底 `num` 的对数，如果未指定 `num` 则为自然对数。

### 参见

- log10() - 以 10 为底的对数
- exp() - 计算 e 的指数
- pow() - 指数表达式
- error_log() - 发送错误信息到某个地方

# log10

(PHP 4, PHP 5, PHP 7, PHP 8)

log10 — 以 10 为底的对数

### 说明

function log10(float `$num`): float

返回参数 `num` 以 10 为底的对数。

### 参数

`num`

  要处理的参数

### 返回值

`num` 以 10 为底的对数。

### 参见

- log() - 自然对数

# log1p

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

log1p — 返回 log(1 + number)，甚至当 number 的值接近零也能计算出准确结果

### 说明

function log1p(float `$num`): float

log1p() 返回 log(1 + `num`)，甚至当 `num` 的值接近零也能计算出准确结果。log() 在这种情况下，可能由于缺乏精度只返回 log(1)。

### 参数

`num`

  要处理的参数

### 返回值

log(1 + `num`)

### 参见

- expm1() - 返回 exp($num) - 1，甚至当 number 的值接近零也能计算出准确结果
- log() - 自然对数
- log10() - 以 10 为底的对数

# max

(PHP 4, PHP 5, PHP 7, PHP 8)

max — 找出最大值

### 说明

function max(mixed `$value`, mixed `...$values`): mixed

替代签名（不支持命名参数）：

function max(array `$value_array`): mixed

如果仅有一个参数且为数组，max() 返回该数组中最大的值。如果第一个参数是整数、字符串或浮点数，则至少需要两个参数而 max() 会返回这些值中最大的一个。可以比较无限多个值。

> 注意:

> 不同类型的值将使用标准比较规则进行比较。例如，一个非数字 string 与 int 比较时就当做是 `0`，但多个非数字 string 值将会按照字母数字比较。返回的实际值是未应用任何转换的原始类型。

警告

传递不同类型的参数时要小心，因为 max() 会产生不可预测的结果。

### 参数

`value`

  任何可比较的值。

`values`

  任何可比较的值。

`value_array`

  包含值的数组。

### 返回值

max() 根据标准比较返回认为是“最大”的参数值。如果不同类型的多个值认为相等（比如 `0` 与 `'abc'`），则将会返回提供给函数的第一个值。

### 错误／异常

如果传递空数组，max() 抛出 ValueError。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | max() 现在失败时会抛出 ValueError；之前会返回 `false` 并发出 `E_WARNING` 错误。
8.0.0 | 由于 字符串到数字的比较 已经改变，max() 在这些情况下不再根据参数的顺序返回不同的值。

### 示例

示例 #1 使用 max() 的示例

    <?php
    echo max(2, 3, 1, 6, 7), PHP_EOL;  // 7
    echo max(array(2, 4, 5)), PHP_EOL; // 5

    // 这里比较-1 < 0，所以 'hello' 是最大的值
    echo max('hello', -1), PHP_EOL;    // hello

    // 当有多个长度不同的数组时，max 返回最长的那个
    $val = max(array(2, 2, 2), array(1, 1, 1, 1)); // array(1, 1, 1, 1)
    var_dump($val);

    // 多个长度相同的数组将从左到右进行比较，所以在我们的例子中：2 == 2，但 5 > 4
    $val = max(array(2, 4, 8), array(2, 5, 1)); // array(2, 5, 1)
    var_dump($val);

    // 在比较中，数组被认为比任何其他值都大，所以如果同时给出数组和非数组，将返回数组
    $val = max('string', array(2, 5, 7), 42);   // array(2, 5, 7)
    var_dump($val);

    // 如果一个参数是 NULL 或布尔值，那么它将使用 FALSE < TRUE 的规则与其他值进行比较，而不考虑其他类型的值
    // 在下面的例子中，-10 在比较中被当做 TRUE 来处理
    $val = max(-10, FALSE); // -10
    var_dump($val);

    // 另一方面，0 被当做 FALSE 来处理，所以它“比” TRUE 小
    $val = max(0, TRUE); // TRUE
    var_dump($val);
    ?>

### 参见

- min() - 找出最小值
- count() - 统计数组、Countable 对象中所有元素的数量

# min

(PHP 4, PHP 5, PHP 7, PHP 8)

min — 找出最小值

### 说明

function min(mixed `$value`, mixed `...$values`): mixed

替代签名（不支持命名参数）：

function min(array `$value_array`): mixed

如果仅有一个参数且为数组，min() 返回该数组中最小的值。如果给出了两个或更多参数, min() 会返回这些值中最小的一个。

> 注意:

> 不同类型的值将使用标准比较规则进行比较。例如，一个非数字 string 与 int 比较时就当做是 `0`，但多个非数字 string 值将会按照字母数字比较。返回的实际值是未应用任何转换的原始类型。

警告

传递不同类型的参数时要小心，因为 min() 会产生不可预测的结果。

### 参数

`value`

  任何可比较的值。

`values`

  任何可比较的值。

`value_array`

  包含值的数组。

### 返回值

min() 根据标准比较返回认为是“最小”的参数值。如果不同类型的多个值认为相等（比如 `0` 与 `'abc'`），则将会返回提供给函数的第一个值。

### 错误／异常

如果传递空数组，min() 抛出 ValueError。

### 更新日志

版本 | 说明
--- | ---
8.0.0 | min() 现在失败时会抛出 ValueError；之前会返回 `false` 并发出 `E_WARNING` 错误。
8.0.0 | 由于 字符串到数字的比较 已经改变，min() 在这些情况下不再根据参数的顺序返回不同的值。

### 示例

示例 #1 min() 用法的示例

    <?php
    echo min(2, 3, 1, 6, 7), PHP_EOL;  // 1
    echo min(array(2, 4, 5)), PHP_EOL; // 2

    // Here we are comparing -1 < 0, so -1 is the lowest value
    echo min('hello', -1), PHP_EOL;    // -1

    // With multiple arrays of different lengths, min returns the shortest
    $val = min(array(2, 2, 2), array(1, 1, 1, 1)); // array(2, 2, 2)
    var_dump($val);

    // Multiple arrays of the same length are compared from left to right
    // so in our example: 2 == 2, but 4 < 5
    $val = min(array(2, 4, 8), array(2, 5, 1)); // array(2, 4, 8)
    var_dump($val);

    // 如果同时给出数组和非数组，则绝对不会返回数组
    // 因为比较认为数组大于任何值
    $val = min('string', array(2, 5, 7), 42);   // string
    var_dump($val);

    // If one argument is NULL or a boolean, it will be compared against
    // other values using the rules FALSE < TRUE and NULL == FALSE regardless of the
    // other types involved
    // In the below examples, both -10 and 10 are treated as TRUE in the comparison
    $val = min(-10, FALSE, 10); // FALSE
    var_dump($val);

    $val = min(-10, NULL, 10);  // NULL
    var_dump($val);

    // 0, on the other hand, is treated as FALSE, so is "lower than" TRUE
    $val = min(0, TRUE); // 0
    var_dump($val);
    ?>

### 参见

- max() - 找出最大值
- count() - 统计数组、Countable 对象中所有元素的数量

# octdec

(PHP 4, PHP 5, PHP 7, PHP 8)

octdec — 八进制转换为十进制

### 说明

function octdec(string `$octal_string`): int|float

返回 `octal_string` 参数所表示的八进制数的十进制等值。`octal_string` 中的任何无效字符都会默认忽略。自 PHP 7.4.0 起，弃用使用任何无效字符。

### 参数

`octal_string`

  要转换的八进制的字符串。

### 返回值

`octal_string` 的十进制的表示

### 更新日志

版本 | 说明
--- | ---
7.4.0 | 传递任何无效字符现在将生成弃用通知。但仍会计算结果，就好像无效字符不存在一样。

### 示例

示例 #1 octdec() 示例

    <?php
    echo octdec('77') . "\n";
    echo octdec(decoct(45));
    ?>

以上示例会输出：

    63
    45

### 注释

> 注意:

> 此函数可以将太大的数字转换为适应平台的 int 类型，在这种情况下，较大值将会作为 float 返回。

### 参见

- decoct() - 十进制转换为八进制
- bindec() - 二进制转换为十进制
- hexdec() - 十六进制转换为十进制
- base_convert() - 在任意进制之间转换数字

# pi

(PHP 4, PHP 5, PHP 7, PHP 8)

pi — 得到圆周率值

### 说明

function pi(): float

返回圆周率的近似值。也可以使用 `M_PI` 常量，该常量产生与 pi() 完全相同的结果。

### 参数

此函数没有参数。

### 返回值

圆周率（pi）的浮点近似值。

### 示例

示例 #1 pi() 示例

    <?php
    echo pi(), PHP_EOL; // 3.1415926535898
    echo M_PI, PHP_EOL; // 3.1415926535898
    ?>

# pow

(PHP 4, PHP 5, PHP 7, PHP 8)

pow — 指数表达式

### 说明

function pow(mixed `$num`, mixed `$exponent`): int|float|object

返回 `num` 的 `exponent` 次方的幂。

> 注意:

> 可以使用 ** 运算符代替。

### 参数

`num`

  底数

`exponent`

  指数

### 返回值

`num` 的 `exponent` 次方。如果两个参数都是非负整数且结果可以用整数表示，则返回 int 类型，否则返回 float。

PHP 扩展可能会覆盖此操作的行为，使其返回一个对象。

### 示例

示例 #1 pow() 的一些示例

    <?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
    ?>

示例 #2 Examples of pow() With GMP Extension Object

    <?php
    var_dump(pow(new GMP("3"), new GMP("2"))); // object(GMP)
    ?>

### 注释

> 注意:

> 本函数会转换所有输入为数字，甚至是非标量值，将会导致怪异的结果。

### 参见

- exp() - 计算 e 的指数
- sqrt() - 平方根
- bcpow() - 任意精度数字的乘方
- gmp_pow() - Raise number into power

# rad2deg

(PHP 4, PHP 5, PHP 7, PHP 8)

rad2deg — 将弧度数转换为相应的角度数

### 说明

function rad2deg(float `$num`): float

本函数将 `num` 从弧度转换为角度。

### 参数

`num`

  一个弧度值

### 返回值

`num` 相应的角度数

### 示例

示例 #1 rad2deg() 示例

    <?php

    echo rad2deg(M_PI_4); // 45

    ?>

### 参见

- deg2rad() - 将角度转换为弧度

# round

(PHP 4, PHP 5, PHP 7, PHP 8)

round — 对浮点数进行四舍五入

### 说明

function round(int|float `$num`, int `$precision` = 0, int|RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): float

返回将 `num` 根据指定精度 `precision`（十进制小数点后数字的数目）进行四舍五入的结果。`precision` 也可以是负数或零（默认值）。

### 参数

`num`

  要处理的值。

`precision`

  可选的十进制小数点后数字的数目。

  如果 `precision` 是正数，则 `num` 会四舍五入到小数点后 `precision` 位有效数字。

  如果 `precision` 是负数，则 `num` 四舍五入到小数点前 `precision` 位有效数字。即 `pow(10, -$precision)` 最接近的倍数，例如，`precision` 为 -1，`num` 可以四舍五入到十位，`precision` 为 -2，`num` 可以四舍五入到百位，等等。

`mode`

  使用 RoundingMode 或以下常量之一来指定舍入模式。 Use RoundingMode or one of the following constants to specify the mode in which rounding occurs.

  常量 | 说明
  --- | ---
  `PHP_ROUND_HALF_UP` | 当 `num` 恰好处于中间时，将其向远离零的方向舍入，使 1.5 变为 2，-1.5 变为 -2。
  `PHP_ROUND_HALF_DOWN` | 当 `num` 恰好处于中间时，将其向靠近零的方向舍入，使 1.5 变为 1，-1.5 变为 -1。
  `PHP_ROUND_HALF_EVEN` | 将 `num` 四舍五入到最接近的偶数值，1.5 和 2.5 都变为 2。
  `PHP_ROUND_HALF_ODD` | 将 `num` 四舍五入到最接近的奇数值，1.5 变为 1，2.5 变为 3。

  然而，请注意，某些新添加的模式仅存在于 RoundingMode 中。

### 返回值

值是四舍五入到指定 `precision` 精度的 float。

### 错误／异常

如果 `mode` 是无效的，此函数将抛出 ValueError 异常。 在 PHP 8.4.0 之前，无效的模式会默认为 `PHP_ROUND_HALF_UP`。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 新增了四种舍入模式。
8.4.0 | 如果 `mode` 是无效的，现在将抛出 ValueError 异常。
8.0.0 | `num` 不再接受支持数字转换的内部对象。

### 示例

示例 #1 round() 示例

    <?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));
    ?>

以上示例会输出：

    float(3)
    float(4)
    float(4)
    float(4)
    float(5.05)
    float(5.06)
    float(300)
    float(0)
    float(700)
    float(1000)

示例 #2 `precision` 如何影响 float

    <?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));
    ?>

以上示例会输出：

    float(135.79)
    float(135.79)
    float(135.8)
    float(136)
    float(140)
    float(100)
    float(0)

示例 #3 `mode` 示例

    <?php
    echo 'Rounding modes with 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 'Rounding modes with 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));
    ?>

以上示例会输出：

    Rounding modes with 9.5
    float(10)
    float(9)
    float(10)
    float(9)

    Rounding modes with 8.5
    float(9)
    float(8)
    float(8)
    float(9)

示例 #4 带 `precision` 的 `mode` 示例

    <?php
    echo 'Using PHP_ROUND_HALF_UP with 1 decimal digit precision' . 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 'Using PHP_ROUND_HALF_DOWN with 1 decimal digit precision' . 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 'Using PHP_ROUND_HALF_EVEN with 1 decimal digit precision' . 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 'Using PHP_ROUND_HALF_ODD with 1 decimal digit precision' . PHP_EOL;
    var_dump(round( 1.55, 1, PHP_ROUND_HALF_ODD));
    var_dump(round(-1.55, 1, PHP_ROUND_HALF_ODD));
    ?>

以上示例会输出：

    Using PHP_ROUND_HALF_UP with 1 decimal digit precision
    float(1.6)
    float(-1.6)

    Using PHP_ROUND_HALF_DOWN with 1 decimal digit precision
    float(1.5)
    float(-1.5)

    Using PHP_ROUND_HALF_EVEN with 1 decimal digit precision
    float(1.6)
    float(-1.6)

    Using PHP_ROUND_HALF_ODD with 1 decimal digit precision
    float(1.5)
    float(-1.5)

示例 #5 使用 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";
    }
    ?>

以上示例会输出：

    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

### 参见

- ceil() - 进一法取整
- floor() - 舍去法取整
- number_format() - 以千位分隔符方式格式化一个数字

# sin

(PHP 4, PHP 5, PHP 7, PHP 8)

sin — 正弦

### 说明

function sin(float `$num`): float

sin() 返回参数 `num` 的正弦值。参数 `num` 的单位为弧度。

### 参数

`num`

  单位是弧度的值。

### 返回值

`num` 的正弦值

### 示例

示例 #1 sin() 示例

    <?php
    // 返回值的精度由配置中的 precision 指示确定
    echo sin(deg2rad(60)), PHP_EOL;  //  0.866025403 ...
    echo sin(60), PHP_EOL;           // -0.304810621 ...

    ?>

### 参见

- asin() - 反正弦
- sinh() - 双曲正弦
- cos() - 余弦
- tan() - 正切
- deg2rad() - 将角度转换为弧度

# sinh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

sinh — 双曲正弦

### 说明

function sinh(float `$num`): float

返回 `num` 的双曲正弦值，定义为 `(exp($num) - exp(-$num))/2`。

### 参数

`num`

  要处理的参数

### 返回值

`num` 的双曲正弦值

### 参见

- sin() - 正弦
- asinh() - 反双曲正弦
- cosh() - 双曲余弦
- tanh() - 双曲正切

# sqrt

(PHP 4, PHP 5, PHP 7, PHP 8)

sqrt — 平方根

### 说明

function sqrt(float `$num`): float

返回 `num` 的平方根。

### 参数

`num`

  要处理的参数

### 返回值

返回 `num` 的平方根，负数时返回 `NAN`。

### 示例

示例 #1 sqrt() 示例

    <?php
    // 精度取决于精度指令
    echo sqrt(9), PHP_EOL; // 3
    echo sqrt(10), PHP_EOL; // 3.16227766 ...
    ?>

### 参见

- pow() - 指数表达式
- `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 — 正切

### 说明

function tan(float `$num`): float

tan() 返回参数 `num` 的正切值。参数 `num` 的单位为弧度。

### 参数

`num`

  要处理的以弧度为单位的参数

### 返回值

`num` 的正切值

### 示例

示例 #1 tan() 示例

    <?php

    echo tan(M_PI_4); // 1

    ?>

### 参见

- atan() - 反正切
- atan2() - 两个参数的反正切
- sin() - 正弦
- cos() - 余弦
- tanh() - 双曲正切
- deg2rad() - 将角度转换为弧度

# tanh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

tanh — 双曲正切

### 说明

function tanh(float `$num`): float

返回 `num` 的双曲正切值，定义为 `sinh($num)/cosh($num)`。

### 参数

`num`

  要处理的参数

### 返回值

`num` 的双曲正切值

### 参见

- tan() - 正切
- atanh() - 反双曲正切
- sinh() - 双曲正弦
- cosh() - 双曲余弦

## 目录

- abs — 绝对值
- acos — 反余弦
- acosh — 反双曲余弦
- asin — 反正弦
- asinh — 反双曲正弦
- atan — 反正切
- atan2 — 两个参数的反正切
- atanh — 反双曲正切
- base_convert — 在任意进制之间转换数字
- bindec — 二进制转换为十进制
- ceil — 进一法取整
- cos — 余弦
- cosh — 双曲余弦
- decbin — 十进制转换为二进制
- dechex — 十进制转换为十六进制
- decoct — 十进制转换为八进制
- deg2rad — 将角度转换为弧度
- exp — 计算 e 的指数
- expm1 — 返回 exp($num) - 1，甚至当 number 的值接近零也能计算出准确结果
- fdiv — Divides two numbers, according to IEEE 754
- floor — 舍去法取整
- fmod — 返回除法的浮点数余数
- fpow — Raise one number to the power of another, according to IEEE 754
- hexdec — 十六进制转换为十进制
- hypot — 计算直角三角形的斜边长度
- intdiv — 对除法结果取整
- is_finite — 判断浮点数是否是有效的有限值
- is_infinite — 判断浮点数是否为无限值
- is_nan — 判断浮点数是否是否为 NAN
- log — 自然对数
- log10 — 以 10 为底的对数
- log1p — 返回 log(1 + number)，甚至当 number 的值接近零也能计算出准确结果
- max — 找出最大值
- min — 找出最小值
- octdec — 八进制转换为十进制
- pi — 得到圆周率值
- pow — 指数表达式
- rad2deg — 将弧度数转换为相应的角度数
- round — 对浮点数进行四舍五入
- sin — 正弦
- sinh — 双曲正弦
- sqrt — 平方根
- tan — 正切
- tanh — 双曲正切

- 预定义常量
- RoundingMode — The RoundingMode Enum
- Math 函数
  - abs — 绝对值
  - acos — 反余弦
  - acosh — 反双曲余弦
  - asin — 反正弦
  - asinh — 反双曲正弦
  - atan — 反正切
  - atan2 — 两个参数的反正切
  - atanh — 反双曲正切
  - base_convert — 在任意进制之间转换数字
  - bindec — 二进制转换为十进制
  - ceil — 进一法取整
  - cos — 余弦
  - cosh — 双曲余弦
  - decbin — 十进制转换为二进制
  - dechex — 十进制转换为十六进制
  - decoct — 十进制转换为八进制
  - deg2rad — 将角度转换为弧度
  - exp — 计算 e 的指数
  - expm1 — 返回 exp($num) - 1，甚至当 number 的值接近零也能计算出准确结果
  - fdiv — Divides two numbers, according to IEEE 754
  - floor — 舍去法取整
  - fmod — 返回除法的浮点数余数
  - fpow — Raise one number to the power of another, according to IEEE 754
  - hexdec — 十六进制转换为十进制
  - hypot — 计算直角三角形的斜边长度
  - intdiv — 对除法结果取整
  - is_finite — 判断浮点数是否是有效的有限值
  - is_infinite — 判断浮点数是否为无限值
  - is_nan — 判断浮点数是否是否为 NAN
  - log — 自然对数
  - log10 — 以 10 为底的对数
  - log1p — 返回 log(1 + number)，甚至当 number 的值接近零也能计算出准确结果
  - max — 找出最大值
  - min — 找出最小值
  - octdec — 八进制转换为十进制
  - pi — 得到圆周率值
  - pow — 指数表达式
  - rad2deg — 将弧度数转换为相应的角度数
  - round — 对浮点数进行四舍五入
  - sin — 正弦
  - sinh — 双曲正弦
  - sqrt — 平方根
  - tan — 正切
  - tanh — 双曲正切

# Statistics

# 简介

警告

此扩展已无人维护。

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.

# 安装/配置

## 目录

- 需求
- 安装

## 需求

No external libraries are needed. The extension comes bundled with the libraries used.

## 安装

此 » PECL 扩展未与 PHP 捆绑。

此扩展被认为已无人维护及已消亡。然而，此扩展的源代码还可在 PECL SVN 找到： » https://pecl.php.net/package/stats.

此扩展在 Windows 平台的二进制扩展 (DLL 文件) PECL 可以在 PECL 官方网站上下载。

# Statistic 函数

# stats_absolute_deviation

(PECL stats >= 1.0.0)

stats_absolute_deviation — Returns the absolute deviation of an array of values

### 说明

function stats_absolute_deviation(array `$a`): float

Returns the absolute deviation of the values in `a`.

### 参数

`a`

  The input array

### 返回值

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

### 说明

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

### 参数

`par1`

  The first parameter

`par2`

  The second parameter

`par3`

  The third parameter

`which`

  The flag to determine what to be calculated

### 返回值

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

### 说明

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

### 参数

`par1`

  The first parameter

`par2`

  The second parameter

`par3`

  The third parameter

`which`

  The flag to determine what to be calculated

### 返回值

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

### 说明

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

### 参数

`par1`

  The first parameter

`par2`

  The second parameter

`par3`

  The third parameter

`which`

  The flag to determine what to be calculated

### 返回值

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

### 说明

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

### 参数

`par1`

  The first parameter

`par2`

  The second parameter

`which`

  The flag to determine what to be calculated

### 返回值

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

### 说明

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

### 参数

`par1`

  The first parameter

`par2`

  The second parameter

`which`

  The flag to determine what to be calculated

### 返回值

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

### 说明

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

### 参数

`par1`

  The first parameter

`par2`

  The second parameter

`par3`

  The third parameter

`which`

  The flag to determine what to be calculated

### 返回值

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

### 说明

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

### 参数

`par1`

  The first parameter

`par2`

  The second parameter

`par3`

  The third parameter

`which`

  The flag to determine what to be calculated

### 返回值

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

### 说明

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

### 参数

`par1`

  The first parameter

`par2`

  The second parameter

`par3`

  The third parameter

`which`

  The flag to determine what to be calculated

### 返回值

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

### 说明

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

### 参数

`par1`

  The first parameter

`par2`

  The second parameter

`par3`

  The third parameter

`which`

  The flag to determine what to be calculated

### 返回值

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

### 说明

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

### 参数

`par1`

  The first parameter

`par2`

  The second parameter

`par3`

  The third parameter

`which`

  The flag to determine what to be calculated

### 返回值

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

### 说明

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

### 参数

`par1`

  The first parameter

`par2`

  The second parameter

`par3`

  The third parameter

`which`

  The flag to determine what to be calculated

### 返回值

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

### 说明

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

### 参数

`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

### 返回值

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

### 说明

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

### 参数

`par1`

  The first parameter

`par2`

  The second parameter

`par3`

  The third parameter

`which`

  The flag to determine what to be calculated

### 返回值

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

### 说明

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

### 参数

`par1`

  The first parameter

`par2`

  The second parameter

`par3`

  The third parameter

`which`

  The flag to determine what to be calculated

### 返回值

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

### 说明

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

### 参数

`par1`

  The first parameter

`par2`

  The second parameter

`which`

  The flag to determine what to be calculated

### 返回值

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

### 说明

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

### 参数

`par1`

  The first parameter

`par2`

  The second parameter

`which`

  The flag to determine what to be calculated

### 返回值

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

### 说明

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

### 参数

`par1`

  The first parameter

`par2`

  The second parameter

`par3`

  The third parameter

`which`

  The flag to determine what to be calculated

### 返回值

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

### 说明

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

### 参数

`par1`

  The first parameter

`par2`

  The second parameter

`par3`

  The third parameter

`which`

  The flag to determine what to be calculated

### 返回值

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

### 说明

function stats_covariance(array `$a`, array `$b`): float

Returns the covariance of `a` and `b`.

### 参数

`a`

  The first array

`b`

  The second array

### 返回值

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

### 说明

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`.

### 参数

`x`

  The value at which the probability density is calculated

`a`

  The shape parameter of the distribution

`b`

  The shape parameter of the distribution

### 返回值

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

### 说明

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.

### 参数

`x`

  The value at which the probability density is calculated

`ave`

  The location parameter of the distribution

`stdev`

  The scale parameter of the distribution

### 返回值

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

### 说明

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`.

### 参数

`x`

  The value at which the probability density is calculated

`dfr`

  The degree of freedom of the distribution

### 返回值

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

### 说明

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`.

### 参数

`x`

  The value at which the probability density is calculated

`scale`

  The scale of the distribution

### 返回值

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

### 说明

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`.

### 参数

`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

### 返回值

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

### 说明

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`.

### 参数

`x`

  The value at which the probability density is calculated

`shape`

  The shape parameter of the distribution

`scale`

  The scale parameter of the distribution

### 返回值

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

### 说明

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`.

### 参数

`x`

  The value at which the probability density is calculated

`ave`

  The location parameter of the distribution

`stdev`

  The shape parameter of the distribution

### 返回值

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

### 说明

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`.

### 参数

`x`

  The value at which the probability density is calculated

`ave`

  The location parameter of the distribution

`stdev`

  The shape parameter of the distribution

### 返回值

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

### 说明

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`.

### 参数

`x`

  The value at which the probability density is calculated

`ave`

  The mean of the distribution

`stdev`

  The standard deviation of the distribution

### 返回值

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

### 说明

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`.

### 参数

`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

### 返回值

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

### 说明

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`.

### 参数

`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

### 返回值

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

### 说明

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`.

### 参数

`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

### 返回值

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

### 说明

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`.

### 参数

`x`

  The value at which the probability mass is calculated

`lb`

  The parameter of the Poisson distribution

### 返回值

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

### 说明

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`.

### 参数

`x`

  The value at which the probability density is calculated

`dfr`

  The degree of freedom of the distribution

### 返回值

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

### 说明

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`.

### 参数

`x`

  The value at which the probability density is calculated

`a`

  The lower bound of the distribution

`b`

  The upper bound of the distribution

### 返回值

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

### 说明

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`.

### 参数

`x`

  The value at which the probability density is calculated

`a`

  The shape parameter of the distribution

`b`

  The scale parameter of the distribution

### 返回值

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

### 说明

function stats_harmonic_mean(array `$a`): number

Returns the harmonic mean of the values in `a`.

### 参数

`a`

  The input array

### 返回值

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

### 说明

function stats_kurtosis(array `$a`): float

Returns the kurtosis of the values in `a`.

### 参数

`a`

  The input array

### 返回值

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

### 说明

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.

### 参数

`a`

  The shape parameter of the beta distribution

`b`

  The shape parameter of the beta distribution

### 返回值

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

### 说明

function stats_rand_gen_chisquare(float `$df`): float

Returns a random deviate from the chi-square distribution where the degrees of freedom is `df`.

### 参数

`df`

  The degrees of freedom

### 返回值

A random deviate

# stats_rand_gen_exponential

(PECL stats >= 1.0.0)

stats_rand_gen_exponential — Generates a random deviate from the exponential distribution

### 说明

function stats_rand_gen_exponential(float `$av`): float

Returns a random deviate from the exponential distribution of which the scale is `av`.

### 参数

`av`

  The scale parameter

### 返回值

A random deviate

# stats_rand_gen_f

(PECL stats >= 1.0.0)

stats_rand_gen_f — Generates a random deviate from the F distribution

### 说明

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.

### 参数

`dfn`

  The degrees of freedom in the numerator

`dfd`

  The degrees of freedom in the denominator

### 返回值

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)

### 说明

function stats_rand_gen_funiform(float `$low`, float `$high`): float

Returns a random deviate from the uniform distribution from `low` to `high`.

### 参数

`low`

  The lower bound (exclusive)

`high`

  The upper bound (exclusive)

### 返回值

A random deviate

# stats_rand_gen_gamma

(PECL stats >= 1.0.0)

stats_rand_gen_gamma — Generates a random deviate from the gamma distribution

### 说明

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).

### 参数

`a`

  location parameter of Gamma distribution (`a` > 0).

`r`

  shape parameter of Gamma distribution (`r` > 0).

### 返回值

A random deviate

# stats_rand_gen_ibinomial

(PECL stats >= 1.0.0)

stats_rand_gen_ibinomial — Generates a random deviate from the binomial distribution

### 说明

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`.

### 参数

`n`

  The number of trials

`pp`

  The probability of an event in each trial

### 返回值

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

### 说明

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`.

### 参数

`n`

  The number of success

`p`

  The success rate

### 返回值

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

### 说明

function stats_rand_gen_int(): int

Returns a random integer between 1 and 2147483562

### 参数

此函数没有参数。

### 返回值

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

### 说明

function stats_rand_gen_ipoisson(float `$mu`): int

Returns a random deviate from the Poisson distribution with parameter `mu`.

### 参数

`mu`

  The parameter of the Poisson distribution

### 返回值

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)

### 说明

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).

### 参数

`low`

  The lower bound

`high`

  The upper bound

### 返回值

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

### 说明

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`.

### 参数

`df`

  The degrees of freedom

`xnonc`

  The non-centrality parameter

### 返回值

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

### 说明

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`.

### 参数

`dfn`

  The degrees of freedom of the numerator

`dfd`

  The degrees of freedom of the denominator

`xnonc`

  The non-centrality parameter

### 返回值

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

### 说明

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`.

### 参数

`df`

  The degrees of freedom

`xnonc`

  The non-centrality parameter

### 返回值

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

### 说明

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`.

### 参数

`av`

  The mean of the normal distribution

`sd`

  The standard deviation of the normal distribution

### 返回值

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

### 说明

function stats_rand_gen_t(float `$df`): float

Returns a random deviate from the t-distribution with the degrees of freedom, `df`.

### 参数

`df`

  The degrees of freedom

### 返回值

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

### 说明

function stats_rand_get_seeds(): array

Returns the current seed values of the random number generator

### 参数

此函数没有参数。

### 返回值

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

### 说明

function stats_rand_phrase_to_seeds(string `$phrase`): array

Generate two seeds for the random number generator from a `phrase`.

### 参数

`phrase`

  The input phrase

### 返回值

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

### 说明

function stats_rand_ranf(): float

Returns a random floating point number from a uniform distribution between 0 (exclusive) and 1 (exclusive).

### 参数

此函数没有参数。

### 返回值

A random floating point number

# stats_rand_setall

(PECL stats >= 1.0.0)

stats_rand_setall — Set seed values to the random generator

### 说明

function stats_rand_setall(int `$iseed1`, int `$iseed2`): void

Set `iseed1` and `iseed2` as seed values to the random generator used in statistic functions.

### 参数

`iseed1`

  The value which is used as the random seed

`iseed2`

  The value which is used as the random seed

### 返回值

No values are returned.

# stats_skew

(PECL stats >= 1.0.0)

stats_skew — Computes the skewness of the data in the array

### 说明

function stats_skew(array `$a`): float

Returns the skewness of the values in `a`.

### 参数

`a`

  The input array

### 返回值

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

### 说明

function stats_standard_deviation(array `$a`, bool `$sample` = `false`): float

Returns the standard deviation of the values in `a`.

### 参数

`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`.

### 返回值

Returns the standard deviation on success; `false` on failure.

### 错误／异常

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

### 说明

function stats_stat_binomial_coef(int `$x`, int `$n`): float

Returns the binomial coefficient of `n` choose `x`.

### 参数

`x`

  The number of chooses from the set

`n`

  The number of elements in the set

### 返回值

Returns the binomial coefficient

# stats_stat_correlation

(PECL stats >= 1.0.0)

stats_stat_correlation — Returns the Pearson correlation coefficient of two data sets

### 说明

function stats_stat_correlation(array `$arr1`, array `$arr2`): float

Returns the Pearson correlation coefficient between `arr1` and `arr2`.

### 参数

`arr1`

  The first array

`arr2`

  The second array

### 返回值

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

### 说明

function stats_stat_factorial(int `$n`): float

Returns the factorial of an integer, `n`.

### 参数

`n`

  An integer

### 返回值

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

### 说明

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`.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`arr1`

  The first set of values

`arr2`

  The second set of values

### 返回值

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

### 说明

function stats_stat_innerproduct(array `$arr1`, array `$arr2`): float

Returns the inner product of `arr1` and `arr2`.

### 参数

`arr1`

  The first array

`arr2`

  The second array

### 返回值

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

### 说明

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`.

### 参数

`arr1`

  The first samples

`arr2`

  The second samples

### 返回值

Returns the t-value, or `false` if failure.

# stats_stat_percentile

(PECL stats >= 1.0.0)

stats_stat_percentile — Returns the percentile value

### 说明

function stats_stat_percentile(array `$arr`, float `$perc`): float

Returns the `perc`-th percentile value of the array `arr`.

### 参数

`arr`

  The input array

`perc`

  The percentile

### 返回值

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

### 说明

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`.

### 参数

`arr`

  The input array

`power`

  The power

### 返回值

Returns the power sum of the input array.

# stats_variance

(PECL stats >= 1.0.0)

stats_variance — Returns the variance

### 说明

function stats_variance(array `$a`, bool `$sample` = `false`): float

Returns the variance of the values in `a`.

### 参数

`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`.

### 返回值

Returns the variance on success; `false` on failure.

## 目录

- 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

- 安装/配置
  - 需求
  - 安装
- Statistic 函数
  - 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

# 简介

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/.

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置

## 需求

The trader extension is based on » TA-Lib. TA-Lib is fully integrated into the extension, therefore no external libraries are needed.

## 安装

此 » PECL 扩展未与 PHP 捆绑。

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/trader.

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

Trader 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
trader.real_precision | 3 | `INI_ALL` | Since trader 0.2.1
trader.real_round_mode | HALF_DOWN | `INI_ALL` | Since trader 0.3.0

这是配置指令的简短说明。

`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.

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`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 函数

# trader_acos

(PECL trader >= 0.2.0)

trader_acos — Vector Trigonometric ACos

### 说明

function trader_acos(array `$real`): array

Calculates the arc cosine for each value in `real` and returns the resulting array.

### 参数

`real`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_ad

(PECL trader >= 0.2.0)

trader_ad — Chaikin A/D Line

### 说明

function trader_ad(
array `$high`,
array `$low`,
array `$close`,
array `$volume`
): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`volume`

  成交量，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_add

(PECL trader >= 0.2.0)

trader_add — Vector Arithmetic Add

### 说明

function trader_add(array `$real0`, array `$real1`): array

Calculates the vector addition of `real0` to `real1` and returns the resulting vector.

### 参数

`real0`

  浮点数数组。

`real1`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_adosc

(PECL trader >= 0.2.0)

trader_adosc — Chaikin A/D Oscillator

### 说明

function trader_adosc(
array `$high`,
array `$low`,
array `$close`,
array `$volume`,
int `$fastPeriod` = ?,
int `$slowPeriod` = ?
): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`volume`

  成交量，浮点数数组。

`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.

### 返回值

Returns an array with calculated data or false on failure.

# trader_adx

(PECL trader >= 0.2.0)

trader_adx — Average Directional Movement Index

### 说明

function trader_adx(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_adxr

(PECL trader >= 0.2.0)

trader_adxr — Average Directional Movement Index Rating

### 说明

function trader_adxr(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_apo

(PECL trader >= 0.2.0)

trader_apo — Absolute Price Oscillator

### 说明

function trader_apo(
array `$real`,
int `$fastPeriod` = ?,
int `$slowPeriod` = ?,
int `$mAType` = ?
): array

### 参数

`real`

  浮点数数组。

`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.

### 返回值

Returns an array with calculated data or false on failure.

# trader_aroon

(PECL trader >= 0.2.0)

trader_aroon — Aroon

### 说明

function trader_aroon(array `$high`, array `$low`, int `$timePeriod` = ?): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_aroonosc

(PECL trader >= 0.2.0)

trader_aroonosc — Aroon Oscillator

### 说明

function trader_aroonosc(array `$high`, array `$low`, int `$timePeriod` = ?): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_asin

(PECL trader >= 0.2.0)

trader_asin — Vector Trigonometric ASin

### 说明

function trader_asin(array `$real`): array

Calculates the arc sine for each value in `real` and returns the resulting array.

### 参数

`real`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_atan

(PECL trader >= 0.2.0)

trader_atan — Vector Trigonometric ATan

### 说明

function trader_atan(array `$real`): array

Calculates the arc tangent for each value in `real` and returns the resulting array.

### 参数

`real`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_atr

(PECL trader >= 0.2.0)

trader_atr — Average True Range

### 说明

function trader_atr(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_avgprice

(PECL trader >= 0.2.0)

trader_avgprice — Average Price

### 说明

function trader_avgprice(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_bbands

(PECL trader >= 0.2.0)

trader_bbands — Bollinger Bands

### 说明

function trader_bbands(
array `$real`,
int `$timePeriod` = ?,
float `$nbDevUp` = ?,
float `$nbDevDn` = ?,
int `$mAType` = ?
): array

### 参数

`real`

  浮点数数组。

`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.

### 返回值

Returns an array with calculated data or false on failure.

# trader_beta

(PECL trader >= 0.2.0)

trader_beta — Beta

### 说明

function trader_beta(array `$real0`, array `$real1`, int `$timePeriod` = ?): array

### 参数

`real0`

  浮点数数组。

`real1`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_bop

(PECL trader >= 0.2.0)

trader_bop — Balance Of Power

### 说明

function trader_bop(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cci

(PECL trader >= 0.2.0)

trader_cci — Commodity Channel Index

### 说明

function trader_cci(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdl2crows

(PECL trader >= 0.2.0)

trader_cdl2crows — Two Crows

### 说明

function trader_cdl2crows(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdl3blackcrows

(PECL trader >= 0.2.0)

trader_cdl3blackcrows — Three Black Crows

### 说明

function trader_cdl3blackcrows(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdl3inside

(PECL trader >= 0.2.0)

trader_cdl3inside — Three Inside Up/Down

### 说明

function trader_cdl3inside(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdl3linestrike

(PECL trader >= 0.2.0)

trader_cdl3linestrike — Three-Line Strike

### 说明

function trader_cdl3linestrike(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdl3outside

(PECL trader >= 0.2.0)

trader_cdl3outside — Three Outside Up/Down

### 说明

function trader_cdl3outside(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdl3starsinsouth

(PECL trader >= 0.2.0)

trader_cdl3starsinsouth — Three Stars In The South

### 说明

function trader_cdl3starsinsouth(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdl3whitesoldiers

(PECL trader >= 0.2.0)

trader_cdl3whitesoldiers — Three Advancing White Soldiers

### 说明

function trader_cdl3whitesoldiers(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlabandonedbaby

(PECL trader >= 0.2.0)

trader_cdlabandonedbaby — Abandoned Baby

### 说明

function trader_cdlabandonedbaby(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`penetration`

  一个烛台渗入到另一个烛台的百分比。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdladvanceblock

(PECL trader >= 0.2.0)

trader_cdladvanceblock — Advance Block

### 说明

function trader_cdladvanceblock(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlbelthold

(PECL trader >= 0.2.0)

trader_cdlbelthold — Belt-hold

### 说明

function trader_cdlbelthold(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlbreakaway

(PECL trader >= 0.2.0)

trader_cdlbreakaway — Breakaway

### 说明

function trader_cdlbreakaway(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlclosingmarubozu

(PECL trader >= 0.2.0)

trader_cdlclosingmarubozu — Closing Marubozu

### 说明

function trader_cdlclosingmarubozu(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlconcealbabyswall

(PECL trader >= 0.2.0)

trader_cdlconcealbabyswall — Concealing Baby Swallow

### 说明

function trader_cdlconcealbabyswall(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlcounterattack

(PECL trader >= 0.2.0)

trader_cdlcounterattack — Counterattack

### 说明

function trader_cdlcounterattack(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdldarkcloudcover

(PECL trader >= 0.2.0)

trader_cdldarkcloudcover — Dark Cloud Cover

### 说明

function trader_cdldarkcloudcover(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`penetration`

  一个烛台渗入到另一个烛台的百分比。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdldoji

(PECL trader >= 0.2.0)

trader_cdldoji — Doji

### 说明

function trader_cdldoji(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdldojistar

(PECL trader >= 0.2.0)

trader_cdldojistar — Doji Star

### 说明

function trader_cdldojistar(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdldragonflydoji

(PECL trader >= 0.2.0)

trader_cdldragonflydoji — Dragonfly Doji

### 说明

function trader_cdldragonflydoji(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlengulfing

(PECL trader >= 0.2.0)

trader_cdlengulfing — Engulfing Pattern

### 说明

function trader_cdlengulfing(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdleveningdojistar

(PECL trader >= 0.2.0)

trader_cdleveningdojistar — Evening Doji Star

### 说明

function trader_cdleveningdojistar(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`penetration`

  一个烛台渗入到另一个烛台的百分比。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdleveningstar

(PECL trader >= 0.2.0)

trader_cdleveningstar — Evening Star

### 说明

function trader_cdleveningstar(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`penetration`

  一个烛台渗入到另一个烛台的百分比。

### 返回值

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

### 说明

function trader_cdlgapsidesidewhite(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlgravestonedoji

(PECL trader >= 0.2.0)

trader_cdlgravestonedoji — Gravestone Doji

### 说明

function trader_cdlgravestonedoji(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlhammer

(PECL trader >= 0.2.0)

trader_cdlhammer — Hammer

### 说明

function trader_cdlhammer(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlhangingman

(PECL trader >= 0.2.0)

trader_cdlhangingman — Hanging Man

### 说明

function trader_cdlhangingman(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlharami

(PECL trader >= 0.2.0)

trader_cdlharami — Harami Pattern

### 说明

function trader_cdlharami(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlharamicross

(PECL trader >= 0.2.0)

trader_cdlharamicross — Harami Cross Pattern

### 说明

function trader_cdlharamicross(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlhighwave

(PECL trader >= 0.2.0)

trader_cdlhighwave — High-Wave Candle

### 说明

function trader_cdlhighwave(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlhikkake

(PECL trader >= 0.2.0)

trader_cdlhikkake — Hikkake Pattern

### 说明

function trader_cdlhikkake(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlhikkakemod

(PECL trader >= 0.2.0)

trader_cdlhikkakemod — Modified Hikkake Pattern

### 说明

function trader_cdlhikkakemod(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlhomingpigeon

(PECL trader >= 0.2.0)

trader_cdlhomingpigeon — Homing Pigeon

### 说明

function trader_cdlhomingpigeon(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlidentical3crows

(PECL trader >= 0.2.0)

trader_cdlidentical3crows — Identical Three Crows

### 说明

function trader_cdlidentical3crows(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlinneck

(PECL trader >= 0.2.0)

trader_cdlinneck — In-Neck Pattern

### 说明

function trader_cdlinneck(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlinvertedhammer

(PECL trader >= 0.2.0)

trader_cdlinvertedhammer — Inverted Hammer

### 说明

function trader_cdlinvertedhammer(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlkicking

(PECL trader >= 0.2.0)

trader_cdlkicking — Kicking

### 说明

function trader_cdlkicking(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

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

### 说明

function trader_cdlkickingbylength(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlladderbottom

(PECL trader >= 0.2.0)

trader_cdlladderbottom — Ladder Bottom

### 说明

function trader_cdlladderbottom(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdllongleggeddoji

(PECL trader >= 0.2.0)

trader_cdllongleggeddoji — Long Legged Doji

### 说明

function trader_cdllongleggeddoji(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdllongline

(PECL trader >= 0.2.0)

trader_cdllongline — Long Line Candle

### 说明

function trader_cdllongline(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlmarubozu

(PECL trader >= 0.2.0)

trader_cdlmarubozu — Marubozu

### 说明

function trader_cdlmarubozu(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlmatchinglow

(PECL trader >= 0.2.0)

trader_cdlmatchinglow — Matching Low

### 说明

function trader_cdlmatchinglow(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlmathold

(PECL trader >= 0.2.0)

trader_cdlmathold — Mat Hold

### 说明

function trader_cdlmathold(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`penetration`

  一个烛台渗入到另一个烛台的百分比。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlmorningdojistar

(PECL trader >= 0.2.0)

trader_cdlmorningdojistar — Morning Doji Star

### 说明

function trader_cdlmorningdojistar(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`penetration`

  一个烛台渗入到另一个烛台的百分比。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlmorningstar

(PECL trader >= 0.2.0)

trader_cdlmorningstar — Morning Star

### 说明

function trader_cdlmorningstar(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`penetration`

  一个烛台渗入到另一个烛台的百分比。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlonneck

(PECL trader >= 0.2.0)

trader_cdlonneck — On-Neck Pattern

### 说明

function trader_cdlonneck(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlpiercing

(PECL trader >= 0.2.0)

trader_cdlpiercing — Piercing Pattern

### 说明

function trader_cdlpiercing(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlrickshawman

(PECL trader >= 0.2.0)

trader_cdlrickshawman — Rickshaw Man

### 说明

function trader_cdlrickshawman(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlrisefall3methods

(PECL trader >= 0.2.0)

trader_cdlrisefall3methods — Rising/Falling Three Methods

### 说明

function trader_cdlrisefall3methods(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlseparatinglines

(PECL trader >= 0.2.0)

trader_cdlseparatinglines — Separating Lines

### 说明

function trader_cdlseparatinglines(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlshootingstar

(PECL trader >= 0.2.0)

trader_cdlshootingstar — Shooting Star

### 说明

function trader_cdlshootingstar(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlshortline

(PECL trader >= 0.2.0)

trader_cdlshortline — Short Line Candle

### 说明

function trader_cdlshortline(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlspinningtop

(PECL trader >= 0.2.0)

trader_cdlspinningtop — Spinning Top

### 说明

function trader_cdlspinningtop(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlstalledpattern

(PECL trader >= 0.2.0)

trader_cdlstalledpattern — Stalled Pattern

### 说明

function trader_cdlstalledpattern(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlsticksandwich

(PECL trader >= 0.2.0)

trader_cdlsticksandwich — Stick Sandwich

### 说明

function trader_cdlsticksandwich(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

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)

### 说明

function trader_cdltakuri(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdltasukigap

(PECL trader >= 0.2.0)

trader_cdltasukigap — Tasuki Gap

### 说明

function trader_cdltasukigap(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlthrusting

(PECL trader >= 0.2.0)

trader_cdlthrusting — Thrusting Pattern

### 说明

function trader_cdlthrusting(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdltristar

(PECL trader >= 0.2.0)

trader_cdltristar — Tristar Pattern

### 说明

function trader_cdltristar(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlunique3river

(PECL trader >= 0.2.0)

trader_cdlunique3river — Unique 3 River

### 说明

function trader_cdlunique3river(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlupsidegap2crows

(PECL trader >= 0.2.0)

trader_cdlupsidegap2crows — Upside Gap Two Crows

### 说明

function trader_cdlupsidegap2crows(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cdlxsidegap3methods

(PECL trader >= 0.2.0)

trader_cdlxsidegap3methods — Upside/Downside Gap Three Methods

### 说明

function trader_cdlxsidegap3methods(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### 参数

`open`

  开盘价，浮点数数组。

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_ceil

(PECL trader >= 0.2.0)

trader_ceil — Vector Ceil

### 说明

function trader_ceil(array `$real`): array

Calculates the next highest integer for each value in `real` and returns the resulting array.

### 参数

`real`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cmo

(PECL trader >= 0.2.0)

trader_cmo — Chande Momentum Oscillator

### 说明

function trader_cmo(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_correl

(PECL trader >= 0.2.0)

trader_correl — Pearson's Correlation Coefficient (r)

### 说明

function trader_correl(array `$real0`, array `$real1`, int `$timePeriod` = ?): array

### 参数

`real0`

  浮点数数组。

`real1`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_cos

(PECL trader >= 0.2.0)

trader_cos — Vector Trigonometric Cos

### 说明

function trader_cos(array `$real`): array

Calculates the cosine for each value in `real` and returns the resulting array.

### 参数

`real`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_cosh

(PECL trader >= 0.2.0)

trader_cosh — Vector Trigonometric Cosh

### 说明

function trader_cosh(array `$real`): array

Calculates the hyperbolic cosine for each value in `real` and returns the resulting array.

### 参数

`real`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_dema

(PECL trader >= 0.2.0)

trader_dema — Double Exponential Moving Average

### 说明

function trader_dema(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_div

(PECL trader >= 0.2.0)

trader_div — Vector Arithmetic Div

### 说明

function trader_div(array `$real0`, array `$real1`): array

Divides each value from `real0` by the corresponding value from `real1` and returns the resulting array.

### 参数

`real0`

  浮点数数组。

`real1`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_dx

(PECL trader >= 0.2.0)

trader_dx — Directional Movement Index

### 说明

function trader_dx(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_ema

(PECL trader >= 0.2.0)

trader_ema — Exponential Moving Average

### 说明

function trader_ema(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_errno

(PECL trader >= 0.3.0)

trader_errno — Get error code

### 说明

function trader_errno(): int

Get error code of the last operation.

### 参数

此函数没有参数。

### 返回值

Returns the error code identified by one of the TRADER_ERR_* constants.

# trader_exp

(PECL trader >= 0.2.0)

trader_exp — Vector Arithmetic Exp

### 说明

function trader_exp(array `$real`): array

Calculates `e` raised to the power of each value in `real`. Returns an array with the calculated data.

### 参数

`real`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_floor

(PECL trader >= 0.2.0)

trader_floor — Vector Floor

### 说明

function trader_floor(array `$real`): array

Calculates the next lowest integer for each value in `real` and returns the resulting array.

### 参数

`real`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_get_compat

(PECL trader >= 0.2.2)

trader_get_compat — Get compatibility mode

### 说明

function trader_get_compat(): int

Get compatibility mode which affects the way calculations are done by all the extension functions.

### 参数

此函数没有参数。

### 返回值

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

### 说明

function trader_get_unstable_period(int `$functionId`): int

Get unstable period factor for a particular function.

### 参数

`functionId`

  Function ID the factor to be read for. TRADER_FUNC_UNST_* series of constants should be used.

### 返回值

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

### 说明

function trader_ht_dcperiod(array `$real`): array

### 参数

`real`

  浮点数数组。

### 返回值

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

### 说明

function trader_ht_dcphase(array `$real`): array

### 参数

`real`

  浮点数数组。

### 返回值

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

### 说明

function trader_ht_phasor(array `$real`): array

### 参数

`real`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_ht_sine

(PECL trader >= 0.2.0)

trader_ht_sine — Hilbert Transform - SineWave

### 说明

function trader_ht_sine(array `$real`): array

### 参数

`real`

  浮点数数组。

### 返回值

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

### 说明

function trader_ht_trendline(array `$real`): array

### 参数

`real`

  浮点数数组。

### 返回值

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

### 说明

function trader_ht_trendmode(array `$real`): array

### 参数

`real`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_kama

(PECL trader >= 0.2.0)

trader_kama — Kaufman Adaptive Moving Average

### 说明

function trader_kama(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_linearreg

(PECL trader >= 0.2.0)

trader_linearreg — Linear Regression

### 说明

function trader_linearreg(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_linearreg_angle

(PECL trader >= 0.2.0)

trader_linearreg_angle — Linear Regression Angle

### 说明

function trader_linearreg_angle(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_linearreg_intercept

(PECL trader >= 0.2.0)

trader_linearreg_intercept — Linear Regression Intercept

### 说明

function trader_linearreg_intercept(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_linearreg_slope

(PECL trader >= 0.2.0)

trader_linearreg_slope — Linear Regression Slope

### 说明

function trader_linearreg_slope(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_ln

(PECL trader >= 0.2.0)

trader_ln — Vector Log Natural

### 说明

function trader_ln(array `$real`): array

Calculates the natural logarithm for each value in `real` and returns the resulting array.

### 参数

`real`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_log10

(PECL trader >= 0.2.0)

trader_log10 — Vector Log10

### 说明

function trader_log10(array `$real`): array

Calculates the base-10 logarithm for each value in `real` and returns the resulting array.

### 参数

`real`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_ma

(PECL trader >= 0.2.0)

trader_ma — Moving average

### 说明

function trader_ma(array `$real`, int `$timePeriod` = ?, int `$mAType` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

`mAType`

  Type of Moving Average. TRADER_MA_TYPE_* series of constants should be used.

### 返回值

Returns an array with calculated data or false on failure.

# trader_macd

(PECL trader >= 0.2.0)

trader_macd — Moving Average Convergence/Divergence

### 说明

function trader_macd(
array `$real`,
int `$fastPeriod` = ?,
int `$slowPeriod` = ?,
int `$signalPeriod` = ?
): array

### 参数

`real`

  浮点数数组。

`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.

### 返回值

Returns an array with calculated data or false on failure.

# trader_macdext

(PECL trader >= 0.2.0)

trader_macdext — MACD with controllable MA type

### 说明

function trader_macdext(
array `$real`,
int `$fastPeriod` = ?,
int `$fastMAType` = ?,
int `$slowPeriod` = ?,
int `$slowMAType` = ?,
int `$signalPeriod` = ?,
int `$signalMAType` = ?
): array

### 参数

`real`

  浮点数数组。

`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.

### 返回值

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

### 说明

function trader_macdfix(array `$real`, int `$signalPeriod` = ?): array

### 参数

`real`

  浮点数数组。

`signalPeriod`

  Smoothing for the signal line (nb of period). Valid range from 1 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_mama

(PECL trader >= 0.2.0)

trader_mama — MESA Adaptive Moving Average

### 说明

function trader_mama(array `$real`, float `$fastLimit` = ?, float `$slowLimit` = ?): array

### 参数

`real`

  浮点数数组。

`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.

### 返回值

Returns an array with calculated data or false on failure.

# trader_mavp

(PECL trader >= 0.2.0)

trader_mavp — Moving average with variable period

### 说明

function trader_mavp(
array `$real`,
array `$periods`,
int `$minPeriod` = ?,
int `$maxPeriod` = ?,
int `$mAType` = ?
): array

### 参数

`real`

  浮点数数组。

`periods`

  浮点数数组。

`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.

### 返回值

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

### 说明

function trader_max(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

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

### 说明

function trader_maxindex(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_medprice

(PECL trader >= 0.2.0)

trader_medprice — Median Price

### 说明

function trader_medprice(array `$high`, array `$low`): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_mfi

(PECL trader >= 0.2.0)

trader_mfi — Money Flow Index

### 说明

function trader_mfi(
array `$high`,
array `$low`,
array `$close`,
array `$volume`,
int `$timePeriod` = ?
): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`volume`

  成交量，浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_midpoint

(PECL trader >= 0.2.0)

trader_midpoint — MidPoint over period

### 说明

function trader_midpoint(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_midprice

(PECL trader >= 0.2.0)

trader_midprice — Midpoint Price over period

### 说明

function trader_midprice(array `$high`, array `$low`, int `$timePeriod` = ?): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

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

### 说明

function trader_min(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

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

### 说明

function trader_minindex(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

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

### 说明

function trader_minmax(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

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

### 说明

function trader_minmaxindex(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_minus_di

(PECL trader >= 0.2.0)

trader_minus_di — Minus Directional Indicator

### 说明

function trader_minus_di(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_minus_dm

(PECL trader >= 0.2.0)

trader_minus_dm — Minus Directional Movement

### 说明

function trader_minus_dm(array `$high`, array `$low`, int `$timePeriod` = ?): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_mom

(PECL trader >= 0.2.0)

trader_mom — Momentum

### 说明

function trader_mom(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_mult

(PECL trader >= 0.2.0)

trader_mult — Vector Arithmetic Mult

### 说明

function trader_mult(array `$real0`, array `$real1`): array

Calculates the vector dot product of `real0` with `real1` and returns the resulting vector.

### 参数

`real0`

  浮点数数组。

`real1`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_natr

(PECL trader >= 0.2.0)

trader_natr — Normalized Average True Range

### 说明

function trader_natr(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_obv

(PECL trader >= 0.2.0)

trader_obv — On Balance Volume

### 说明

function trader_obv(array `$real`, array `$volume`): array

### 参数

`real`

  浮点数数组。

`volume`

  成交量，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_plus_di

(PECL trader >= 0.2.0)

trader_plus_di — Plus Directional Indicator

### 说明

function trader_plus_di(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_plus_dm

(PECL trader >= 0.2.0)

trader_plus_dm — Plus Directional Movement

### 说明

function trader_plus_dm(array `$high`, array `$low`, int `$timePeriod` = ?): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_ppo

(PECL trader >= 0.2.0)

trader_ppo — Percentage Price Oscillator

### 说明

function trader_ppo(
array `$real`,
int `$fastPeriod` = ?,
int `$slowPeriod` = ?,
int `$mAType` = ?
): array

### 参数

`real`

  浮点数数组。

`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.

### 返回值

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

### 说明

function trader_roc(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

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

### 说明

function trader_rocp(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

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)

### 说明

function trader_rocr(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

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

### 说明

function trader_rocr100(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_rsi

(PECL trader >= 0.2.0)

trader_rsi — Relative Strength Index

### 说明

function trader_rsi(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_sar

(PECL trader >= 0.2.0)

trader_sar — Parabolic SAR

### 说明

function trader_sar(
array `$high`,
array `$low`,
float `$acceleration` = ?,
float `$maximum` = ?
): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`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.

### 返回值

Returns an array with calculated data or false on failure.

# trader_sarext

(PECL trader >= 0.2.0)

trader_sarext — Parabolic SAR - Extended

### 说明

function trader_sarext(
array `$high`,
array `$low`,
float `$startValue` = ?,
float `$offsetOnReverse` = ?,
float `$accelerationInitLong` = ?,
float `$accelerationLong` = ?,
float `$accelerationMaxLong` = ?,
float `$accelerationInitShort` = ?,
float `$accelerationShort` = ?,
float `$accelerationMaxShort` = ?
): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`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.

### 返回值

Returns an array with calculated data or false on failure.

# trader_set_compat

(PECL trader >= 0.2.2)

trader_set_compat — Set compatibility mode

### 说明

function trader_set_compat(int `$compatId`): void

Set compatibility mode which will affect the way calculations are done by all the extension functions.

### 参数

`compatId`

  Compatibility Id. TRADER_COMPATIBILITY_* series of constants should be used.

### 返回值

没有返回值。

# trader_set_unstable_period

(PECL trader >= 0.2.2)

trader_set_unstable_period — Set unstable period

### 说明

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.

### 参数

`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.

### 返回值

没有返回值。

# trader_sin

(PECL trader >= 0.2.0)

trader_sin — Vector Trigonometric Sin

### 说明

function trader_sin(array `$real`): array

Calculates the sine for each value in `real` and returns the resulting array.

### 参数

`real`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_sinh

(PECL trader >= 0.2.0)

trader_sinh — Vector Trigonometric Sinh

### 说明

function trader_sinh(array `$real`): array

Calculates the hyperbolic sine for each value in `real` and returns the resulting array.

### 参数

`real`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_sma

(PECL trader >= 0.2.0)

trader_sma — Simple Moving Average

### 说明

function trader_sma(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_sqrt

(PECL trader >= 0.2.0)

trader_sqrt — Vector Square Root

### 说明

function trader_sqrt(array `$real`): array

Calculates the square root of each value in `real` and returns the resulting array.

### 参数

`real`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_stddev

(PECL trader >= 0.2.0)

trader_stddev — Standard Deviation

### 说明

function trader_stddev(array `$real`, int `$timePeriod` = ?, float `$nbDev` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

`nbDev`

### 返回值

Returns an array with calculated data or false on failure.

# trader_stoch

(PECL trader >= 0.2.0)

trader_stoch — Stochastic

### 说明

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

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`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.

### 返回值

Returns an array with calculated data or false on failure.

# trader_stochf

(PECL trader >= 0.2.0)

trader_stochf — Stochastic Fast

### 说明

function trader_stochf(
array `$high`,
array `$low`,
array `$close`,
int `$fastK_Period` = ?,
int `$fastD_Period` = ?,
int `$fastD_MAType` = ?
): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`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.

### 返回值

Returns an array with calculated data or false on failure.

# trader_stochrsi

(PECL trader >= 0.2.0)

trader_stochrsi — Stochastic Relative Strength Index

### 说明

function trader_stochrsi(
array `$real`,
int `$timePeriod` = ?,
int `$fastK_Period` = ?,
int `$fastD_Period` = ?,
int `$fastD_MAType` = ?
): array

### 参数

`real`

  浮点数数组。

`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.

### 返回值

Returns an array with calculated data or false on failure.

# trader_sub

(PECL trader >= 0.2.0)

trader_sub — Vector Arithmetic Subtraction

### 说明

function trader_sub(array `$real0`, array `$real1`): array

Calculates the vector subtraction of `real1` from `real0` and returns the resulting vector.

### 参数

`real0`

  浮点数数组。

`real1`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_sum

(PECL trader >= 0.2.0)

trader_sum — Summation

### 说明

function trader_sum(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_t3

(PECL trader >= 0.2.0)

trader_t3 — Triple Exponential Moving Average (T3)

### 说明

function trader_t3(array `$real`, int `$timePeriod` = ?, float `$vFactor` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

`vFactor`

  成交量因子。有效值从 0 到 1。

### 返回值

Returns an array with calculated data or false on failure.

# trader_tan

(PECL trader >= 0.2.0)

trader_tan — Vector Trigonometric Tan

### 说明

function trader_tan(array `$real`): array

Calculates the tangent for each value in `real` and returns the resulting array.

### 参数

`real`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_tanh

(PECL trader >= 0.2.0)

trader_tanh — Vector Trigonometric Tanh

### 说明

function trader_tanh(array `$real`): array

Calculates the hyperbolic tangent for each value in `real` and returns the resulting array.

### 参数

`real`

  浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_tema

(PECL trader >= 0.2.0)

trader_tema — Triple Exponential Moving Average

### 说明

function trader_tema(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_trange

(PECL trader >= 0.2.0)

trader_trange — True Range

### 说明

function trader_trange(array `$high`, array `$low`, array `$close`): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_trima

(PECL trader >= 0.2.0)

trader_trima — Triangular Moving Average

### 说明

function trader_trima(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

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

### 说明

function trader_trix(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_tsf

(PECL trader >= 0.2.0)

trader_tsf — Time Series Forecast

### 说明

function trader_tsf(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_typprice

(PECL trader >= 0.2.0)

trader_typprice — Typical Price

### 说明

function trader_typprice(array `$high`, array `$low`, array `$close`): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_ultosc

(PECL trader >= 0.2.0)

trader_ultosc — Ultimate Oscillator

### 说明

function trader_ultosc(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod1` = ?,
int `$timePeriod2` = ?,
int `$timePeriod3` = ?
): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`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.

### 返回值

Returns an array with calculated data or false on failure.

# trader_var

(PECL trader >= 0.2.0)

trader_var — Variance

### 说明

function trader_var(array `$real`, int `$timePeriod` = ?, float `$nbDev` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

`nbDev`

### 返回值

Returns an array with calculated data or false on failure.

# trader_wclprice

(PECL trader >= 0.2.0)

trader_wclprice — Weighted Close Price

### 说明

function trader_wclprice(array `$high`, array `$low`, array `$close`): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

### 返回值

Returns an array with calculated data or false on failure.

# trader_willr

(PECL trader >= 0.2.0)

trader_willr — Williams' %R

### 说明

function trader_willr(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### 参数

`high`

  高价，浮点数数组。

`low`

  低价，浮点数数组。

`close`

  收盘价，浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

# trader_wma

(PECL trader >= 0.2.0)

trader_wma — Weighted Moving Average

### 说明

function trader_wma(array `$real`, int `$timePeriod` = ?): array

### 参数

`real`

  浮点数数组。

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### 返回值

Returns an array with calculated data or false on failure.

## 目录

- 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

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
- 预定义常量
- Trader 函数
  - 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 任意精度数学
  - 安装/配置
  - BC 数学 函数
  - BcMath\Number — The BcMath\Number class
- GMP — GNU Multiple Precision
  - 安装/配置
  - 预定义常量
  - 示例
  - GMP 函数
  - GMP — The GMP class
- Math — 数学函数
  - 预定义常量
  - RoundingMode — The RoundingMode Enum
  - Math 函数
- Statistics
  - 安装/配置
  - Statistic 函数
- Trader — Technical Analysis for Traders
  - 安装/配置
  - 预定义常量
  - Trader 函数

# 非文本内容的 MIME 输出

# Forms Data Format

# 简介

Forms Data Format (FDF) is a format for handling forms within PDF documents. You should read the documentation at » http://www.adobe.com/devnet/acrobat/fdftoolkit.html for more information on what FDF is and how it is used in general.

The general idea of FDF is similar to HTML forms. The difference is basically the format how data is transmitted to the server when the submit button is pressed (this is actually the Form Data Format) and the format of the form itself (which is the Portable Document Format, PDF). Processing the FDF data is one of the features provided by the fdf functions. But there is more. One may as well take an existing PDF form and populated the input fields with data without modifying the form itself. In such a case one would create a FDF document (fdf_create()) set the values of each input field (fdf_set_value()) and associate it with a PDF form (fdf_set_file()). Finally it has to be sent to the browser with MimeType `application/vnd.fdf`. The Acrobat reader plugin of your browser recognizes the MimeType, reads the associated PDF form and fills in the data from the FDF document.

If you look at an FDF-document with a text editor you will find a catalogue object with the name `FDF`. Such an object may contain a number of entries like `Fields`, `F`, `Status` etc.. The most commonly used entries are `Fields` which points to a list of input fields, and `F` which contains the filename of the PDF-document this data belongs to. Those entries are referred to in the FDF documentation as /F-Key or /Status-Key. Modifying this entries is done by functions like fdf_set_file() and fdf_set_status(). Fields are modified with fdf_set_value(), fdf_set_opt() etc..

# 安装/配置

## 目录

- 需求
- 安装
- 资源类型

## 需求

You need the FDF toolkit SDK available from » http://www.adobe.com/devnet/acrobat/fdftoolkit.html. As of PHP 4.3.0 you need at least SDK version 5.0. The FDF toolkit library is available in binary form only, platforms supported by Adobe are Win32, Linux, Solaris and AIX.

## 安装

此扩展被认为已无人维护及已消亡。然而，此扩展的源代码还可在 PECL SVN 找到： » https://svn.php.net/viewvc/pecl/fdf.

This extension is no longer bundled with PHP.

> 注意: If you run into problems configuring PHP with fdftk support, check whether the header file fdftk.h and the library libfdftk.so are at the right place. The configure script supports both the directory structure of the FDF SDK distribution and the usual DIR/include / DIR/lib layout, so you can point it either directly to the unpacked distribution directory or put the header file and the appropriate library for your platform into e.g. /usr/local/include and /usr/local/lib and configure with --with-fdftk=/usr/local.

> 注意: Note to Win32 Users
> 为了使此扩展生效， DLL 文件必须能在 Windows 系统的 PATH 指示的路径下找到。如何操作的信息，请参见题为“如何在 Windows 中将 PHP 目录加到 PATH 中”的FAQ。虽然将 DLL 文件从 PHP 文件夹复制到 Windows 系统目录也行，但不建议这样做。 此扩展需要下列文件在 PATH 路径中： fdftk.dll

## 资源类型

Most fdf functions require a `fdf` resource as their first parameter. A `fdf` resource is a handle to an opened fdf file. `fdf` resources may be obtained using fdf_create(), fdf_open() and fdf_open_string().

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`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)

# 示例

The following examples shows just the evaluation of form data.

示例 #1 Evaluating a FDF document

    <?php
    // Open fdf from input string provided by the extension
    // The pdf form contained several input text fields with the names
    // volume, date, comment, publisher, preparer, and two checkboxes
    // show_publisher and show_preparer.
    $fdf = fdf_open_string($HTTP_FDF_DATA);
    $volume = fdf_get_value($fdf, "volume");
    echo "The volume field has the value '<b>$volume</b>'<br />";

    $date = fdf_get_value($fdf, "date");
    echo "The date field has the value '<b>$date</b>'<br />";

    $comment = fdf_get_value($fdf, "comment");
    echo "The comment field has the value '<b>$comment</b>'<br />";

    if (fdf_get_value($fdf, "show_publisher") == "On") {
      $publisher = fdf_get_value($fdf, "publisher");
      echo "The publisher field has the value '<b>$publisher</b>'<br />";
    } else
      echo "Publisher shall not be shown.<br />";

    if (fdf_get_value($fdf, "show_preparer") == "On") {
      $preparer = fdf_get_value($fdf, "preparer");
      echo "The preparer field has the value '<b>$preparer</b>'<br />";
    } else
      echo "Preparer shall not be shown.<br />";
    fdf_close($fdf);
    ?>

# FDF 函数

# fdf_add_doc_javascript

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_add_doc_javascript — Adds javascript code to the FDF document

### 说明

function fdf_add_doc_javascript(resource `$fdf_document`, string `$script_name`, string `$script_code`): bool

Adds a script to the FDF, which Acrobat then adds to the doc-level scripts of a document, once the FDF is imported into it.

### 参数

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
`script_name`
  The script name.
`script_code`
  The script code. It is strongly suggested to use `\r` for linebreaks within the script code.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Adding JavaScript code to a FDF

    <?php
    $fdf = fdf_create();
    fdf_add_doc_javascript($fdf, "PlusOne", "function PlusOne(x)\r{\r  return x+1;\r}\r");
    fdf_save($fdf);
    ?>

will create a FDF like this:

    %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 — Adds a template into the FDF document

### 说明

function fdf_add_template(
resource `$fdf_document`,
int `$newpage`,
string `$filename`,
string `$template`,
int `$rename`
): bool
警告

本函数还未编写文档，仅有参数列表。

# fdf_close

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_close — Close an FDF document

### 说明

function fdf_close(resource `$fdf_document`): void

Closes the FDF document.

### 参数

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().

### 返回值

没有返回值。

### 参见

- fdf_open() - Open a FDF document

# fdf_create

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_create — Create a new FDF document

### 说明

function fdf_create(): resource

Creates a new FDF document.

This function is needed if one would like to populate input fields in a PDF document with data.

### 参数

此函数没有参数。

### 返回值

Returns a FDF document handle, or `false` on error.

### 示例

示例 #1 Populating a PDF document

    <?php
    $outfdf = fdf_create();
    fdf_set_value($outfdf, "volume", $volume, 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");
    ?>

### 参见

- fdf_close() - Close an FDF document
- fdf_save() - Save a FDF document
- fdf_open() - Open a FDF document

# fdf_enum_values

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_enum_values — Call a user defined function for each document value

### 说明

function fdf_enum_values(resource `$fdf_document`, callable `$function`, mixed `$userdata` = ?): bool
警告

本函数还未编写文档，仅有参数列表。

# fdf_errno

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_errno — Return error code for last fdf operation

### 说明

function fdf_errno(): int

Gets the error code set by the last FDF function call.

A textual description of the error may be obtained using fdf_error().

### 参数

此函数没有参数。

### 返回值

Returns the error code as an integer, or zero if there was no errors.

### 参见

- fdf_error() - Return error description for FDF error code

# fdf_error

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_error — Return error description for FDF error code

### 说明

function fdf_error(int `$error_code` = -1): string

Gets a textual description for the FDF error code given in `error_code`.

### 参数

`error_code`
  An error code obtained with fdf_errno(). If not provided, this function uses the internal error code set by the last operation.

### 返回值

Returns the error message as a string, or the string `no error` if nothing went wrong.

### 参见

- fdf_errno() - Return error code for last fdf operation

# 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# 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

### 说明

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`.

### 参数

`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.

  > 注意: 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.

### 返回值

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

### 示例

示例 #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 — Get the value of the /Encoding key

### 说明

function fdf_get_encoding(resource `$fdf_document`): string

Gets the value of the `/Encoding` key.

### 参数

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().

### 返回值

Returns the encoding as a string. An empty string is returned if the default `PDFDocEncoding/Unicode` scheme is used.

### 参见

- fdf_set_encoding() - Sets FDF character encoding

# fdf_get_file

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_file — Get the value of the /F key

### 说明

function fdf_get_file(resource `$fdf_document`): string

Gets the value of the `/F` key.

### 参数

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().

### 返回值

Returns the key value, as a string.

### 参见

- fdf_set_file() - Set PDF document to display FDF data in

# fdf_get_flags

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_flags — Gets the flags of a field

### 说明

function fdf_get_flags(resource `$fdf_document`, string `$fieldname`, int `$whichflags`): int
警告

本函数还未编写文档，仅有参数列表。

# fdf_get_opt

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECLv)

fdf_get_opt — Gets a value from the opt array of a field

### 说明

function fdf_get_opt(resource `$fdf_document`, string `$fieldname`, int `$element` = -1): mixed
警告

本函数还未编写文档，仅有参数列表。

# fdf_get_status

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_status — Get the value of the /STATUS key

### 说明

function fdf_get_status(resource `$fdf_document`): string

Gets the value of the `/STATUS` key.

### 参数

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().

### 返回值

Returns the key value, as a string.

### 参见

- fdf_set_status() - Set the value of the /STATUS key

# fdf_get_value

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_value — Get the value of a field

### 说明

function fdf_get_value(resource `$fdf_document`, string `$fieldname`, int `$which` = -1): mixed

Gets the value for the requested field.

### 参数

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
`fieldname`
  Name of the FDF field, as a string.
`which`
  Elements of an array field can be retrieved by passing this optional parameter, starting at zero. For non-array fields, this parameter will be ignored.

### 返回值

Returns the field value.

### 参见

- fdf_set_value() - Set the value of a field

# fdf_get_version

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_version — Gets version number for FDF API or file

### 说明

function fdf_get_version(resource `$fdf_document` = ?): string

Return the FDF version for the given document, or the toolkit API version number if no parameter is given.

### 参数

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().

### 返回值

Returns the version as a string. For the current FDF toolkit 5.0 the API version number is `5.0` and the document version number is either `1.2`, `1.3` or `1.4`.

### 参见

- 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 — Sets FDF-specific output headers

### 说明

function fdf_header(): void

This is a convenience function to set appropriate HTTP headers for FDF output. It sets the `Content-type:` to `application/vnd.fdf`.

### 参数

此函数没有参数。

### 返回值

没有返回值。

# fdf_next_field_name

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_next_field_name — Get the next field name

### 说明

function fdf_next_field_name(resource `$fdf_document`, string `$fieldname` = ?): string

Gets the name of the field after the given field. This name can be used with several functions.

### 参数

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
`fieldname`
  Name of the FDF field, as a string. If not given, the first field will be assumed.

### 返回值

Returns the field name as a string.

### 示例

示例 #1 Detecting all fieldnames in a FDF

    <?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";
    }
    ?>

### 参见

- fdf_get_value() - Get the value of a field

# fdf_open

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_open — Open a FDF document

### 说明

function fdf_open(string `$filename`): resource

Opens a file with form data.

You can also use fdf_open_string() to process the results of a PDF form POST request.

### 参数

`filename`
  Path to the FDF file. This file must contain the data as returned from a PDF form or created using fdf_create() and fdf_save().

### 返回值

Returns a FDF document handle, or `false` on error.

### 示例

示例 #1 Accessing the form data

    <?php
    // Save the FDF data into a temp file
    $fdffp = fopen("test.fdf", "w");
    fwrite($fdffp, $HTTP_FDF_DATA, strlen($HTTP_FDF_DATA));
    fclose($fdffp);

    // Open temp file and evaluate data
    $fdf = fdf_open("test.fdf");
    /* ... */
    fdf_close($fdf);
    ?>

### 参见

- fdf_open_string() - Read a FDF document from a string
- fdf_close() - Close an FDF document
- fdf_create() - Create a new FDF document
- fdf_save() - Save a FDF document

# 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

### 说明

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.

### 参数

`fdf_data`
  The data as returned from a PDF form or created using fdf_create() and fdf_save_string().

### 返回值

Returns a FDF document handle, or `false` on error.

### 示例

示例 #1 Accessing the form data

    <?php
    $fdf = fdf_open_string($HTTP_FDF_DATA);
    /* ... */
    fdf_close($fdf);
    ?>

### 参见

- fdf_open() - Open a FDF document
- fdf_close() - Close an FDF document
- fdf_create() - Create a new FDF document
- 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 — Sets target frame for form

### 说明

function fdf_remove_item(resource `$fdf_document`, string `$fieldname`, int `$item`): bool
警告

本函数还未编写文档，仅有参数列表。

# fdf_save

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_save — Save a FDF document

### 说明

function fdf_save(resource `$fdf_document`, string `$filename` = ?): bool

Saves a FDF document.

### 参数

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
`filename`
  If provided, the resulting FDF will be written in this parameter. Otherwise, this function will write the FDF to the default PHP output stream.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- fdf_close() - Close an FDF document
- fdf_create() - Create a new FDF document
- 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

### 说明

function fdf_save_string(resource `$fdf_document`): string

Returns the FDF document as a string.

### 参数

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().

### 返回值

Returns the document as a string, or `false` on error.

### 示例

示例 #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;
    ?>

以上示例会输出：

    %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

### 参见

- fdf_open_string() - Read a FDF document from a string
- fdf_close() - Close an FDF document
- fdf_create() - Create a new FDF document
- fdf_save() - Save a FDF document

# fdf_set_ap

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_ap — Set the appearance of a field

### 说明

function fdf_set_ap(
resource `$fdf_document`,
string `$field_name`,
int `$face`,
string `$filename`,
int `$page_number`
): bool

Sets the appearance of a field (i.e. the value of the `/AP` key).

### 参数

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
`field_name`
`face`
  The possible values are `FDFNormalAP`, `FDFRolloverAP` and `FDFDownAP`.
`filename`
`page_number`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# fdf_set_encoding

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_encoding — Sets FDF character encoding

### 说明

function fdf_set_encoding(resource `$fdf_document`, string `$encoding`): bool

Sets the character encoding for the FDF document.

### 参数

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
`encoding`
  The encoding name. The following values are supported: "`Shift-JIS`", "`UHC`", "`GBK`" and "`BigFive`". An empty string resets the encoding to the default `PDFDocEncoding/Unicode` scheme.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# fdf_set_file

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_file — Set PDF document to display FDF data in

### 说明

function fdf_set_file(resource `$fdf_document`, string `$url`, string `$target_frame` = ?): bool

Selects a different PDF document to display the form results in than the form it originated from.

### 参数

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
`url`
  Should be given as an absolute URL.
`target_frame`
  Use this parameter to specify the frame in which the document will be displayed. You can also set the default value for this parameter using fdf_set_target_frame().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Passing FDF data to a second form

    <?php
      /* set content type for Adobe FDF */
      fdf_header();

      /* start new fdf */
      $fdf = fdf_create();

      /* set field "foo" to value "bar" */
      fdf_set_value($fdf, "foo", "bar");

      /* tell client to display FDF data using "fdf_form.pdf" */
      fdf_set_file($fdf, "http://www.example.com/fdf_form.pdf");

      /* output fdf */
      fdf_save($fdf);

      /* clean up */
      fdf_close($fdf);
    ?>

### 参见

- fdf_get_file() - Get the value of the /F key
- 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 — Sets a flag of a field

### 说明

function fdf_set_flags(
resource `$fdf_document`,
string `$fieldname`,
int `$whichFlags`,
int `$newFlags`
): bool

Sets certain flags of the given field.

### 参数

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
`fieldname`
  Name of the FDF field, as a string.
`whichFlags`
`newFlags`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- fdf_set_opt() - Sets an option of a field

# fdf_set_javascript_action

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_javascript_action — Sets an javascript action of a field

### 说明

function fdf_set_javascript_action(
resource `$fdf_document`,
string `$fieldname`,
int `$trigger`,
string `$script`
): bool

Sets a javascript action for the given field.

### 参数

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
`fieldname`
  Name of the FDF field, as a string.
`trigger`
`script`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- fdf_set_submit_form_action() - Sets a submit form action of a field

# 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

### 说明

function fdf_set_on_import_javascript(resource `$fdf_document`, string `$script`, bool `$before_data_import`): bool
警告

本函数还未编写文档，仅有参数列表。

### 参见

- fdf_add_doc_javascript() - Adds javascript code to the FDF document
- fdf_set_javascript_action() - Sets an javascript action of a field

# fdf_set_opt

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_opt — Sets an option of a field

### 说明

function fdf_set_opt(
resource `$fdf_document`,
string `$fieldname`,
int `$element`,
string `$str1`,
string `$str2`
): bool

Sets options of the given field.

### 参数

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
`fieldname`
  Name of the FDF field, as a string.
`element`
`str1`
`str2`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- fdf_set_flags() - Sets a flag of a field

# fdf_set_status

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_status — Set the value of the /STATUS key

### 说明

function fdf_set_status(resource `$fdf_document`, string `$status`): bool

Sets the value of the `/STATUS` key. When a client receives a FDF with a status set it will present the value in an alert box.

### 参数

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
`status`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- fdf_get_status() - Get the value of the /STATUS key

# fdf_set_submit_form_action

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_submit_form_action — Sets a submit form action of a field

### 说明

function fdf_set_submit_form_action(
resource `$fdf_document`,
string `$fieldname`,
int `$trigger`,
string `$script`,
int `$flags`
): bool

Sets a submit form action for the given field.

### 参数

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
`fieldname`
  Name of the FDF field, as a string.
`trigger`
`script`
`flags`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- fdf_set_javascript_action() - Sets an javascript action of a field

# 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

### 说明

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.

### 参数

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
`frame_name`
  The frame name, as a string.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- fdf_save_file()

# fdf_set_value

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_value — Set the value of a field

### 说明

function fdf_set_value(
resource `$fdf_document`,
string `$fieldname`,
mixed `$value`,
int `$isName` = ?
): bool

Sets the `value` for the given field.

### 参数

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
`fieldname`
  Name of the FDF field, as a string.
`value`
  This parameter will be stored as a string unless it is an array. In this case all array elements will be stored as a value array.
`isName`

  > 注意: In older versions of the FDF toolkit last parameter determined if the field value was to be converted to a PDF Name (= 1) or set to a PDF String (= 0). The value is no longer used in the current toolkit version 5.0. For compatibility reasons it is still supported as an optional parameter, but ignored internally.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- fdf_get_value() - Get the value of a field
- fdf_remove_item() - Sets target frame for form

# 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

### 说明

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.

### 参数

`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`.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- fdf_get_version() - Gets version number for FDF API or file

## 目录

- fdf_add_doc_javascript — Adds javascript code to the FDF document
- fdf_add_template — Adds a template into the FDF document
- fdf_close — Close an FDF document
- fdf_create — Create a new FDF document
- fdf_enum_values — Call a user defined function for each document value
- fdf_errno — Return error code for last fdf operation
- fdf_error — Return error description for FDF error code
- fdf_get_ap — Get the appearance of a field
- fdf_get_attachment — Extracts uploaded file embedded in the FDF
- fdf_get_encoding — Get the value of the /Encoding key
- fdf_get_file — Get the value of the /F key
- fdf_get_flags — Gets the flags of a field
- fdf_get_opt — Gets a value from the opt array of a field
- fdf_get_status — Get the value of the /STATUS key
- fdf_get_value — Get the value of a field
- fdf_get_version — Gets version number for FDF API or file
- fdf_header — Sets FDF-specific output headers
- fdf_next_field_name — Get the next field name
- fdf_open — Open a FDF document
- fdf_open_string — Read a FDF document from a string
- fdf_remove_item — Sets target frame for form
- fdf_save — Save a FDF document
- fdf_save_string — Returns the FDF document as a string
- fdf_set_ap — Set the appearance of a field
- fdf_set_encoding — Sets FDF character encoding
- fdf_set_file — Set PDF document to display FDF data in
- fdf_set_flags — Sets a flag of a field
- fdf_set_javascript_action — Sets an javascript action of a field
- fdf_set_on_import_javascript — Adds javascript code to be executed when Acrobat opens the FDF
- fdf_set_opt — Sets an option of a field
- fdf_set_status — Set the value of the /STATUS key
- fdf_set_submit_form_action — Sets a submit form action of a field
- fdf_set_target_frame — Set target frame for form display
- fdf_set_value — Set the value of a field
- fdf_set_version — Sets version number for a FDF file

- 安装/配置
  - 需求
  - 安装
  - 资源类型
- 预定义常量
- 示例
- FDF 函数
  - fdf_add_doc_javascript — Adds javascript code to the FDF document
  - fdf_add_template — Adds a template into the FDF document
  - fdf_close — Close an FDF document
  - fdf_create — Create a new FDF document
  - fdf_enum_values — Call a user defined function for each document value
  - fdf_errno — Return error code for last fdf operation
  - fdf_error — Return error description for FDF error code
  - fdf_get_ap — Get the appearance of a field
  - fdf_get_attachment — Extracts uploaded file embedded in the FDF
  - fdf_get_encoding — Get the value of the /Encoding key
  - fdf_get_file — Get the value of the /F key
  - fdf_get_flags — Gets the flags of a field
  - fdf_get_opt — Gets a value from the opt array of a field
  - fdf_get_status — Get the value of the /STATUS key
  - fdf_get_value — Get the value of a field
  - fdf_get_version — Gets version number for FDF API or file
  - fdf_header — Sets FDF-specific output headers
  - fdf_next_field_name — Get the next field name
  - fdf_open — Open a FDF document
  - fdf_open_string — Read a FDF document from a string
  - fdf_remove_item — Sets target frame for form
  - fdf_save — Save a FDF document
  - fdf_save_string — Returns the FDF document as a string
  - fdf_set_ap — Set the appearance of a field
  - fdf_set_encoding — Sets FDF character encoding
  - fdf_set_file — Set PDF document to display FDF data in
  - fdf_set_flags — Sets a flag of a field
  - fdf_set_javascript_action — Sets an javascript action of a field
  - fdf_set_on_import_javascript — Adds javascript code to be executed when Acrobat opens the FDF
  - fdf_set_opt — Sets an option of a field
  - fdf_set_status — Set the value of the /STATUS key
  - fdf_set_submit_form_action — Sets a submit form action of a field
  - fdf_set_target_frame — Set target frame for form display
  - fdf_set_value — Set the value of a field
  - fdf_set_version — Sets version number for a FDF file

# GNU Privacy Guard

# 简介

This module allows you to interact with » gnupg.

# 安装/配置

## 目录

- 需求
- 安装

## 需求

This extension requires the » gpgme library

## 安装

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/gnupg.

# 预定义常量

`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)

# 示例

## 目录

- Clearsign text

## Clearsign text

This example will clearsign a given text.

示例 #1 gnupg clearsign example (procedural)

    <?php
    // init gnupg
    $res = gnupg_init();
    // not really needed. Clearsign is default
    gnupg_setsignmode($res,GNUPG_SIG_MODE_CLEAR);
    // add key with passphrase 'test' for signing
    gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    // sign
    $signed = gnupg_sign($res,"just a test");
    echo $signed;
    ?>

示例 #2 gnupg clearsign example (OO)

    <?php
    // new class
    $gnupg = new gnupg();
    // not really needed. Clearsign is default
    $gnupg->setsignmode(gnupg::SIG_MODE_CLEAR);
    // add key with passphrase 'test' for signing
    $gnupg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    // sign
    $signed = $gnupg->sign("just a test");
    echo $signed;
    ?>

示例 #3 keylistiterator

This extension also comes with an Iterator for your keyring.

    <?php
    // create a new iterator for listing all public keys that matches 'example'
    $iterator = new gnupg_keylistiterator("example");
    foreach($iterator as $fingerprint => $userid){
        echo $fingerprint." -> ".$userid."\n";
    }
    ?>

# GnuPG 函数

# 注释

This extension makes use of the keyring of the current user. This keyring is normally located in ~/.gnupg/. To specify a custom location, store the path to the keyring in the environment variable GNUPGHOME. See putenv for more information how to do this.

Some functions require the specification of a key. This specification can be anything that refers to a unique key (userid, key-id, fingerprint, ...). This documentation uses the fingerprint in all examples.

> 注意: As alternative to the explicitly documented functions using resources, you can also use an object-oriented style using gnupg objects.

# gnupg_adddecryptkey

(PECL gnupg >= 0.5)

gnupg_adddecryptkey — Add a key for decryption

### 说明

function gnupg_adddecryptkey(resource `$identifier`, string `$fingerprint`, string `$passphrase`): bool

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。
`fingerprint`
  指纹键名。
`passphrase`
  The pass phrase.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Procedural gnupg_adddecryptkey() example

    <?php
    $res = gnupg_init();
    gnupg_adddecryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    ?>

示例 #2 OO gnupg_adddecryptkey() example

    <?php
    $gpg = new gnupg();
    $gpg->adddecryptkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    ?>

# gnupg_addencryptkey

(PECL gnupg >= 0.5)

gnupg_addencryptkey — Add a key for encryption

### 说明

function gnupg_addencryptkey(resource `$identifier`, string `$fingerprint`): bool

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。
`fingerprint`
  指纹键名。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Procedural gnupg_addencryptkey() example

    <?php
    $res = gnupg_init();
    gnupg_addencryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC");
    ?>

示例 #2 OO gnupg_addencryptkey() example

    <?php
    $gpg = new gnupg();
    $gpg->addencryptkey("8660281B6051D071D94B5B230549F9DC851566DC");
    ?>

# gnupg_addsignkey

(PECL gnupg >= 0.5)

gnupg_addsignkey — Add a key for signing

### 说明

function gnupg_addsignkey(resource `$identifier`, string `$fingerprint`, string `$passphrase` = ?): bool

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。
`fingerprint`
  指纹键名。
`passphrase`
  The pass phrase.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Procedural gnupg_addsignkey() example

    <?php
    $res = gnupg_init();
    gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    ?>

示例 #2 OO gnupg_addsignkey() example

    <?php
    $gpg = new gnupg();
    $gpg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    ?>

# gnupg_cleardecryptkeys

(PECL gnupg >= 0.5)

gnupg_cleardecryptkeys — Removes all keys which were set for decryption before

### 说明

function gnupg_cleardecryptkeys(resource `$identifier`): bool

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Procedural gnupg_cleardecryptkeys() example

    <?php
    $res = gnupg_init();
    gnupg_cleardecryptkeys($res);
    ?>

示例 #2 OO gnupg_cleardecryptkeys() example

    <?php
    $gpg = new gnupg();
    $gpg->cleardecryptkeys();
    ?>

# gnupg_clearencryptkeys

(PECL gnupg >= 0.5)

gnupg_clearencryptkeys — Removes all keys which were set for encryption before

### 说明

function gnupg_clearencryptkeys(resource `$identifier`): bool

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Procedural gnupg_clearencryptkeys() example

    <?php
    $res = gnupg_init();
    gnupg_clearencryptkeys($res);
    ?>

示例 #2 OO gnupg_clearencryptkeys() example

    <?php
    $gpg = new gnupg();
    $gpg->clearencryptkeys();
    ?>

# gnupg_clearsignkeys

(PECL gnupg >= 0.5)

gnupg_clearsignkeys — Removes all keys which were set for signing before

### 说明

function gnupg_clearsignkeys(resource `$identifier`): bool

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Procedural gnupg_clearsignkeys() example

    <?php
    $res = gnupg_init();
    gnupg_clearsignkeys($res);
    ?>

示例 #2 OO gnupg_clearsignkeys() example

    <?php
    $gpg = new gnupg();
    $gpg->clearsignkeys();
    ?>

# gnupg_decrypt

(PECL gnupg >= 0.1)

gnupg_decrypt — Decrypts a given text

### 说明

function gnupg_decrypt(resource `$identifier`, string `$text`): string|false

Decrypts the given text with the keys, which were set with gnupg_adddecryptkey before.

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。
`text`
  The text being decrypted.

### 返回值

On success, this function returns the decrypted text. On failure, this function returns `false`.

### 示例

示例 #1 Procedural gnupg_decrypt() example

    <?php
    $res = gnupg_init();
    gnupg_adddecryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    $plain = gnupg_decrypt($res,$encrypted_text);
    echo $plain;
    ?>

示例 #2 OO gnupg_decrypt() example

    <?php
    $gpg = new gnupg();
    $gpg->adddecryptkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    $plain = $gpg->decrypt($encrypted_text);
    echo $plain;
    ?>

# gnupg_decryptverify

(PECL gnupg >= 0.2)

gnupg_decryptverify — Decrypts and verifies a given text

### 说明

function gnupg_decryptverify(resource `$identifier`, string `$text`, string `&$plaintext`): array|false

Decrypts and verifies a given text and returns information about the signature.

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。
`text`
  The text being decrypted.
`plaintext`
  The parameter `plaintext` gets filled with the decrypted text.

### 返回值

On success, this function returns information about the signature and fills the `plaintext` parameter with the decrypted text. On failure, this function returns `false`.

### 示例

示例 #1 Procedural gnupg_decryptverify() example

    <?php
    $plaintext = "";
    $res = gnupg_init();
    gnupg_adddecryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    $info = gnupg_decryptverify($res,$text,$plaintext);
    print_r($info);
    ?>

示例 #2 OO gnupg_decryptverify() example

    <?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 — Delete a key from the keyring

### 说明

function gnupg_deletekey(resource `$identifier`, string `$key`, bool `$allow_secret`): bool

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。
`key`
  The key to delete.
`allow_secret`
  It specifies whether to delete secret keys as well.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Procedural gnupg_deletekey() example

    <?php
    $res = gnupg_init();
    gnupg_deletekey($res, "8660281B6051D071D94B5B230549F9DC851566DC");
    ?>

示例 #2 OO gnupg_deletekey() example

    <?php
    $gpg = new gnupg();
    $gpg->deletekey("8660281B6051D071D94B5B230549F9DC851566DC");
    ?>

# gnupg_encrypt

(PECL gnupg >= 0.1)

gnupg_encrypt — Encrypts a given text

### 说明

function gnupg_encrypt(resource `$identifier`, string `$plaintext`): string|false

Encrypts the given `plaintext` with the keys, which were set with gnupg_addencryptkey before and returns the encrypted text.

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。
`plaintext`
  The text being encrypted.

### 返回值

On success, this function returns the encrypted text. On failure, this function returns `false`.

### 示例

示例 #1 Procedural gnupg_encrypt() example

    <?php
    $res = gnupg_init();
    gnupg_addencryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC");
    $enc = gnupg_encrypt($res, "just a test");
    echo $enc;
    ?>

示例 #2 OO gnupg_encrypt() example

    <?php
    $gpg = new gnupg();
    $gpg->addencryptkey("8660281B6051D071D94B5B230549F9DC851566DC");
    $enc = $gpg->encrypt("just a test");
    echo $enc;
    ?>

# gnupg_encryptsign

(PECL gnupg >= 0.2)

gnupg_encryptsign — Encrypts and signs a given text

### 说明

function gnupg_encryptsign(resource `$identifier`, string `$plaintext`): string|false

Encrypts and signs the given `plaintext` with the keys, which were set with gnupg_addsignkey and gnupg_addencryptkey before and returns the encrypted and signed text.

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。
`plaintext`
  The text being encrypted.

### 返回值

On success, this function returns the encrypted and signed text. On failure, this function returns `false`.

### 示例

示例 #1 Procedural gnupg_encryptsign() example

    <?php
    $res = gnupg_init();
    gnupg_addencryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC");
    gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    $enc = gnupg_encryptsign($res, "just a test");
    echo $enc;
    ?>

示例 #2 OO gnupg_encryptsign() example

    <?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 — Exports a key

### 说明

function gnupg_export(resource `$identifier`, string `$fingerprint`): string|false

Exports the key `fingerprint`.

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。
`fingerprint`
  指纹键名。

### 返回值

On success, this function returns the keydata. On failure, this function returns `false`.

### 示例

示例 #1 Procedural gnupg_export() example

    <?php
    $res = gnupg_init();
    $export = gnupg_export($res,"8660281B6051D071D94B5B230549F9DC851566DC");
    echo $export;
    ?>

示例 #2 OO gnupg_export() example

    <?php
    $gpg = new gnupg();
    $export = $gpg->export("8660281B6051D071D94B5B230549F9DC851566DC");
    ?>

# gnupg_getengineinfo

(PECL gnupg >= 1.5)

gnupg_getengineinfo — Returns the engine info

### 说明

function gnupg_getengineinfo(resource `$identifier`): array

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。

### 返回值

Returns an array with engine info consisting of `protocol`, `file_name` and `home_dir`.

### 示例

示例 #1 Procedural gnupg_getengineinfo() example

    <?php
    $res = gnupg_init();
    print_r(gnupg_getengineinfo($res));
    ?>

以上示例会输出：

    array(3) {
      ["protocol"]=>
      int(0)
      ["file_name"]=>
      string(12) "/usr/bin/gpg"
      ["home_dir"]=>
      string(0) ""
    }

示例 #2 OO gnupg_getengineinfo() example

    <?php
    $gpg = new gnupg(["file_name" => "/usr/bin/gpg2", "home_dir" => "/var/www/.gnupg"]);
    print_r($gpg->getengineinfo());
    ?>

以上示例会输出：

    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 — Returns the errortext, if a function fails

### 说明

function gnupg_geterror(resource `$identifier`): string|false

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。

### 返回值

Returns an errortext, if an error has occurred, otherwise `false`.

### 示例

示例 #1 Procedural gnupg_geterror() example

    <?php
    $res = gnupg_init();
    echo gnupg_geterror($res);
    ?>

示例 #2 OO gnupg_geterror() example

    <?php
    $gpg = new gnupg();
    echo $gpg->geterror();
    ?>

# gnupg_geterrorinfo

(PECL gnupg >= 1.5)

gnupg_geterrorinfo — Returns the error info

### 说明

function gnupg_geterrorinfo(resource `$identifier`): array

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。

### 返回值

Returns an array with error info.

### 示例

示例 #1 Procedural gnupg_geterrorinfo() example

    <?php
    $res = gnupg_init();
    // this is called without any error
    print_r(gnupg_geterrorinfo($res));
    ?>

以上示例会输出：

    array(4) {
      ["generic_message"]=>
      bool(false)
      ["gpgme_code"]=>
      int(0)
      ["gpgme_source"]=>
      string(18) "Unspecified source"
      ["gpgme_message"]=>
      string(7) "Success"
    }

示例 #2 OO gnupg_geterrorinfo() example

    <?php
    $gpg = new gnupg();
    // error call
    $gpg->decrypt('abc');
    // error info should be displayed
    print_r($gpg->geterrorinfo());
    ?>

以上示例会输出：

    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 — Returns the currently active protocol for all operations

### 说明

function gnupg_getprotocol(resource `$identifier`): int

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。

### 返回值

Returns the currently active protocol, which can be one of `GNUPG_PROTOCOL_OpenPGP` or `GNUPG_PROTOCOL_CMS`.

### 示例

示例 #1 Procedural gnupg_getprotocol() example

    <?php
    $res = gnupg_init();
    echo gnupg_getprotocol($res);
    ?>

示例 #2 OO gnupg_getprotocol() example

    <?php
    $gpg = new gnupg();
    echo $gpg->getprotocol();
    ?>

# gnupg_gettrustlist

(PECL gnupg >= 0.5)

gnupg_gettrustlist — Search the trust items

### 说明

function gnupg_gettrustlist(resource `$identifier`, string `$pattern`): ?array

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。
`pattern`
  Expression to limit the list of trust items to only the ones matching the pattern.

### 返回值

On success, this function returns an array of trust items. On failure, this function returns `null`.

### 示例

示例 #1 Procedural gnupg_gettrustlist() example

    <?php
    $res = gnupg_init();
    $items = gnupg_gettrustlist($res);
    print_r($items);
    ?>

示例 #2 OO gnupg_gettrustlist() example

    <?php
    $gpg = new gnupg();
    $items = $gpg->gettrustlist();
    print_r($items);
    ?>

# gnupg_import

(PECL gnupg >= 0.3)

gnupg_import — Imports a key

### 说明

function gnupg_import(resource `$identifier`, string `$keydata`): array|false

Imports the key `keydata` and returns an array with information about the importprocess.

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。
`keydata`
  The data key that is being imported.

### 返回值

On success, this function returns and info-array about the importprocess. On failure, this function returns `false`.

### 示例

示例 #1 Procedural gnupg_import() example

    <?php
    $res = gnupg_init();
    $info = gnupg_import($res,$keydata);
    print_r($info);
    ?>

示例 #2 OO gnupg_import() example

    <?php
    $gpg = new gnupg();
    $info = $gpg->import($keydata);
    print_r($info);
    ?>

# gnupg_init

(PECL gnupg >= 0.4)

gnupg_init — Initialize a connection

### 说明

function gnupg_init(?array `$options` = `null`): resource

### 参数

`options`

  Must be an associative array. It is used to change the default configuration of the crypto engine.

  Configuration overrides
  key | type | description
  --- | --- | ---
  file_name | string | It is the file name of the executable program implementing this protocol which is usually path of the `gpg` executable.
  home_dir | string | It is the directory name of the configuration directory. It also overrides `GNUPGHOME` environment variable that is used for the same purpose.

### 返回值

A GnuPG resource connection used by other GnuPG functions.

### 更新日志

版本 | 说明
--- | ---
PECL gnupg 1.5.0 | The `options` parameter was added.

### 示例

示例 #1 Procedural gnupg_init() example with default setting

    <?php
    $res = gnupg_init();
    ?>

示例 #2 Procedural gnupg_init() example with overridden file name and home dir

    <?php
    $res = gnupg_init(["file_name" => "/usr/bin/gpg2", "home_dir" => "/var/www/.gnupg"]);
    ?>

示例 #3 OO gnupg initializer example with default setting

    <?php
    $gpg = new gnupg();
    ?>

示例 #4 OO gnupg initializer example with overridden file name and home dir

    <?php
    $gpg = new gnupg(["file_name" => "/usr/bin/gpg2", "home_dir" => "/var/www/.gnupg"]);
    ?>

# gnupg_keyinfo

(PECL gnupg >= 0.1)

gnupg_keyinfo — Returns an array with information about all keys that matches the given pattern

### 说明

function gnupg_keyinfo(resource `$identifier`, string `$pattern`): array|false

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。
`pattern`
  The pattern being checked against the keys.

### 返回值

Returns an array with information about all keys that matches the given pattern or `false`, if an error has occurred.

### 示例

示例 #1 Procedural gnupg_keyinfo() example

    <?php
    $res = gnupg_init();
    $info = gnupg_keyinfo($res, 'test');
    print_r($info);
    ?>

示例 #2 OO gnupg_keyinfo() example

    <?php
    $gpg = new gnupg();
    $info = $gpg->keyinfo("test");
    print_r($info);
    ?>

# gnupg_listsignatures

(PECL gnupg >= 0.5)

gnupg_listsignatures — List key signatures

### 说明

function gnupg_listsignatures(resource `$identifier`, string `$keyid`): ?array

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。
`keyid`
  The key ID to list signatures for.

### 返回值

On success, this function returns an array of key signatures. On failure, this function returns `null`.

### 示例

示例 #1 Procedural gnupg_listsignatures() example

    <?php
    $res = gnupg_init();
    $signatures = gnupg_listsignatures($res, "8660281B6051D071D94B5B230549F9DC851566DC");
    print_r($signatures);
    ?>

示例 #2 OO gnupg_listsignatures() example

    <?php
    $gpg = new gnupg();
    $signatures = $gpg->listsignatures("8660281B6051D071D94B5B230549F9DC851566DC");
    print_r($signatures);
    ?>

# gnupg_setarmor

(PECL gnupg >= 0.1)

gnupg_setarmor — Toggle armored output

### 说明

function gnupg_setarmor(resource `$identifier`, int `$armor`): bool

Toggle the armored output.

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。
`armor`
  Pass a non-zero integer-value to this function to enable armored-output (default). Pass 0 to disable armored output.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Procedural gnupg_setarmor() example

    <?php
    $res = gnupg_init();
    gnupg_setarmor($res,1); // enable armored output;
    gnupg_setarmor($res,0); // disable armored output;
    ?>

示例 #2 OO gnupg_setarmor() example

    <?php
    $gpg = new gnupg();
    $gpg->setarmor(1); // enable armored output;
    $gpg->setarmor(0); // disable armored output;
    ?>

# gnupg_seterrormode

(PECL gnupg >= 0.6)

gnupg_seterrormode — Sets the mode for error_reporting

### 说明

function gnupg_seterrormode(resource `$identifier`, int `$errormode`): void

Sets the mode for error_reporting.

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。
`errormode`
  The error mode. `errormode` takes a constant indicating what type of error_reporting should be used. The possible values are `GNUPG_ERROR_WARNING`, `GNUPG_ERROR_EXCEPTION` and `GNUPG_ERROR_SILENT`. By default `GNUPG_ERROR_SILENT` is used.

### 返回值

没有返回值。

### 示例

示例 #1 Procedural gnupg_seterrormode() example

    <?php
    $res = gnupg_init();
    gnupg_seterrormode($res,GNUPG_ERROR_WARNING); // raise a PHP-Warning in case of an error
    ?>

示例 #2 OO gnupg_seterrormode() example

    <?php
    $gpg = new gnupg();
    $gpg->seterrormode(gnupg::ERROR_EXCEPTION); // throw an exception in case of an error
    ?>

# gnupg_setsignmode

(PECL gnupg >= 0.1)

gnupg_setsignmode — Sets the mode for signing

### 说明

function gnupg_setsignmode(resource `$identifier`, int `$signmode`): bool

Sets the mode for signing.

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。
`sigmode`
  The mode for signing. `signmode` takes a constant indicating what type of signature should be produced. The possible values are `GNUPG_SIG_MODE_NORMAL`, `GNUPG_SIG_MODE_DETACH` and `GNUPG_SIG_MODE_CLEAR`. By default `GNUPG_SIG_MODE_CLEAR` is used.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #1 Procedural gnupg_setsignmode() example

    <?php
    $res = gnupg_init();
    gnupg_setsignmode($res,GNUPG_SIG_MODE_DETACH); // produce a detached signature
    ?>

示例 #2 OO gnupg_setsignmode() example

    <?php
    $gpg = new gnupg();
    $gpg->setsignmode(gnupg::SIG_MODE_DETACH); // produce a detached signature
    ?>

# gnupg_sign

(PECL gnupg >= 0.1)

gnupg_sign — Signs a given text

### 说明

function gnupg_sign(resource `$identifier`, string `$plaintext`): string|false

Signs the given `plaintext` with the keys, which were set with gnupg_addsignkey before and returns the signed text or the signature, depending on what was set with gnupg_setsignmode.

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。
`plaintext`
  The plain text being signed.

### 返回值

On success, this function returns the signed text or the signature. On failure, this function returns `false`.

### 示例

示例 #1 Procedural gnupg_sign() example

    <?php
    $res = gnupg_init();
    gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    $signed = gnupg_sign($res, "just a test");
    echo $signed;
    ?>

示例 #2 OO gnupg_sign() example

    <?php
    $gpg = new gnupg();
    $gpg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    $signed = $gpg->sign("just a test");
    echo $signed;
    ?>

# gnupg_verify

(PECL gnupg >= 0.1)

gnupg_verify — Verifies a signed text

### 说明

function gnupg_verify(
resource `$identifier`,
string `$signed_text`,
string `$signature`,
string `&$plaintext` = ?
): array|false

Verifies the given `signed_text` and returns information about the signature.

### 参数

`identifier`
  gnupg 标识符，由对 gnupg_init() 或 gnupg 的调用生成。
`signed_text`
  The signed text.
`signature`
  The signature. To verify a clearsigned text, set signature to `false`.
`plaintext`
  The plain text. If this optional parameter is passed, it is filled with the plain text.

### 返回值

On success, this function returns information about the signature. On failure, this function returns `false`.

### 示例

示例 #1 Procedural gnupg_verify() example

    <?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);
    ?>

示例 #2 OO gnupg_verify() example

    <?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);
    ?>

## 目录

- gnupg_adddecryptkey — Add a key for decryption
- gnupg_addencryptkey — Add a key for encryption
- gnupg_addsignkey — Add a key for signing
- gnupg_cleardecryptkeys — Removes all keys which were set for decryption before
- gnupg_clearencryptkeys — Removes all keys which were set for encryption before
- gnupg_clearsignkeys — Removes all keys which were set for signing before
- gnupg_decrypt — Decrypts a given text
- gnupg_decryptverify — Decrypts and verifies a given text
- gnupg_deletekey — Delete a key from the keyring
- gnupg_encrypt — Encrypts a given text
- gnupg_encryptsign — Encrypts and signs a given text
- gnupg_export — Exports a key
- gnupg_getengineinfo — Returns the engine info
- gnupg_geterror — Returns the errortext, if a function fails
- gnupg_geterrorinfo — Returns the error info
- gnupg_getprotocol — Returns the currently active protocol for all operations
- gnupg_gettrustlist — Search the trust items
- gnupg_import — Imports a key
- gnupg_init — Initialize a connection
- gnupg_keyinfo — Returns an array with information about all keys that matches the given pattern
- gnupg_listsignatures — List key signatures
- gnupg_setarmor — Toggle armored output
- gnupg_seterrormode — Sets the mode for error_reporting
- gnupg_setsignmode — Sets the mode for signing
- gnupg_sign — Signs a given text
- gnupg_verify — Verifies a signed text

- 安装/配置
  - 需求
  - 安装
- 预定义常量
- 示例
  - Clearsign text
- GnuPG 函数
  - gnupg_adddecryptkey — Add a key for decryption
  - gnupg_addencryptkey — Add a key for encryption
  - gnupg_addsignkey — Add a key for signing
  - gnupg_cleardecryptkeys — Removes all keys which were set for decryption before
  - gnupg_clearencryptkeys — Removes all keys which were set for encryption before
  - gnupg_clearsignkeys — Removes all keys which were set for signing before
  - gnupg_decrypt — Decrypts a given text
  - gnupg_decryptverify — Decrypts and verifies a given text
  - gnupg_deletekey — Delete a key from the keyring
  - gnupg_encrypt — Encrypts a given text
  - gnupg_encryptsign — Encrypts and signs a given text
  - gnupg_export — Exports a key
  - gnupg_getengineinfo — Returns the engine info
  - gnupg_geterror — Returns the errortext, if a function fails
  - gnupg_geterrorinfo — Returns the error info
  - gnupg_getprotocol — Returns the currently active protocol for all operations
  - gnupg_gettrustlist — Search the trust items
  - gnupg_import — Imports a key
  - gnupg_init — Initialize a connection
  - gnupg_keyinfo — Returns an array with information about all keys that matches the given pattern
  - gnupg_listsignatures — List key signatures
  - gnupg_setarmor — Toggle armored output
  - gnupg_seterrormode — Sets the mode for error_reporting
  - gnupg_setsignmode — Sets the mode for signing
  - gnupg_sign — Signs a given text
  - gnupg_verify — Verifies a signed text

# wkhtmltox

# 简介

libwkhtmltox is an open source LGPLv3 library for rendering HTML into PDF and various image formats using the QtWebKit rendering engine.

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置

## 需求

libwkhtmltox source and binary releases are distributed at » wkhtmltopdf.org.

警告

Windows users need to take the additional step of adding wkhtmltox.dll to their PATH.

## 安装

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

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

wkhtmltox 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
wkhtmltox.graphics | Off | `INI_SYSTEM`|`INI_PERDIR` | >= 0.3.2

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`wkhtmltox.graphics` bool

  Allow libwkhtmltox to use graphics.

# The wkhtmltox\PDF\Converter class

(wkhtmltox >= 0.1.0)

## 简介

Converts an HTML input, or set of HTML inputs, into PDF output

## 类摘要

class wkhtmltox\PDF\Converter {
/* Constructor */
public function __construct(array `$settings` = ?)
/* 方法 */
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

### 说明

public function wkhtmltox\PDF\Converter::add(wkhtmltox\PDF\Object `$object`): void

Adds the given object to conversion

### 参数

`object`

  The object to add

# wkhtmltox\PDF\Converter::__construct

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Converter::__construct — Create a new PDF converter

### 说明

public function wkhtmltox\PDF\Converter::__construct(array `$settings` = ?)

Creates a PDF converter, using optional configuration settings

### 参数

`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

### 说明

public function wkhtmltox\PDF\Converter::convert(): ?string

Performs conversion of all previously added Objects

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function wkhtmltox\PDF\Converter::getVersion(): string

Determines the version of Converter as reported by libwkhtmltox

### 参数

此函数没有参数。

### 返回值

Returns a version string

## 目录

- 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)

## 简介

Represents an HTML document, input to PDF converter

## 类摘要

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

### 说明

public function wkhtmltox\PDF\Object::__construct(string `$buffer`, array `$settings` = ?)

Creates a new PDF Object from the given buffer and optional configuration settings

### 参数

`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

## 目录

- wkhtmltox\PDF\Object::__construct — Create a new PDF Object

# The wkhtmltox\Image\Converter class

(wkhtmltox >= 0.1.0)

## 简介

Converts an HTML input into various image formats

## 类摘要

class wkhtmltox\Image\Converter {
/* Constructor */
public function __construct(string `$buffer` = ?, array `$settings` = ?)
/* 方法 */
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

### 说明

public function wkhtmltox\Image\Converter::__construct(string `$buffer` = ?, array `$settings` = ?)

Creates an Image converter, optionally taking an input buffer and configuration settings

### 参数

`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

### 说明

public function wkhtmltox\Image\Converter::convert(): ?string

Performs conversion of the input buffer

### 参数

此函数没有参数。

### 返回值

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

### 说明

public function wkhtmltox\Image\Converter::getVersion(): string

Determines the version of Converter as reported by libwkhtmltox

### 参数

此函数没有参数。

### 返回值

Returns a version string

警告

This is not yet implemented by libwkhtmltox

## 目录

- wkhtmltox\Image\Converter::__construct — Create a new Image converter
- wkhtmltox\Image\Converter::convert — Perform Image conversion
- wkhtmltox\Image\Converter::getVersion — Determine version of Converter

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
- 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

# 简介

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.

# 安装/配置

## 目录

- 需求
- 安装
- 资源类型

## 需求

You need at least pslib >= 0.1.12. The ps library (pslib) is available at » http://pslib.sourceforge.net/.

## 安装

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/ps.

## 资源类型

This extension defines a PostScript document resource returned by ps_new().

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

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 函数

## 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

### 说明

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.

此说明在文档被打印或显示时不可见，只在文档用 Acrobat Distiller 或 Ghostview 转换成 PDF 时显示。

### 参数

`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.

### 返回值

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.

### 参见

- 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

### 说明

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.

此说明在文档被打印或显示时不可见，只在文档用 Acrobat Distiller 或 Ghostview 转换成 PDF 时显示。

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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.

此说明在文档被打印或显示时不可见，只在文档用 Acrobat Distiller 或 Ghostview 转换成 PDF 时显示。

### 参数

`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`.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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.

此说明在文档被打印或显示时不可见，只在文档用 Acrobat Distiller 或 Ghostview 转换成 PDF 时显示。

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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.

此说明在文档被打印或显示时不可见，只在文档用 Acrobat Distiller 或 Ghostview 转换成 PDF 时显示。

### 参数

`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`.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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.

此说明在文档被打印或显示时不可见，只在文档用 Acrobat Distiller 或 Ghostview 转换成 PDF 时显示。

### 参数

`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`.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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`.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ps_arcn() - Draws an arc clockwise

# ps_arcn

(PECL ps >= 1.1.0)

ps_arcn — Draws an arc clockwise

### 说明

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`.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ps_arc() - Draws an arc counterclockwise

# ps_begin_page

(PECL ps >= 1.1.0)

ps_begin_page — Start a new page

### 说明

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.

> 注意:

> 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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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`.

### 参数

`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.

### 返回值

The identifier of the pattern 或者在失败时返回 `false`.

### 示例

示例 #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);
    ?>

### 参见

- 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

### 说明

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().

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

### 参见

- ps_end_template() - End a template

# ps_circle

(PECL ps >= 1.1.0)

ps_circle — Draws a circle

### 说明

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.

### 参数

`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

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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.

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ps_closepath() - Closes path

# ps_close

(PECL ps >= 1.1.0)

ps_close — Closes a PostScript document

### 说明

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.

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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.

### 参数

`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().

### 返回值

Returns `null` on success 或者在失败时返回 `false`.

### 参见

- 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

### 说明

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..

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function ps_closepath_stroke(resource `$psdoc`): bool

Connects the last point with first point of a path and draws the resulting closed line.

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ps_closepath() - Closes path

# ps_continue_text

(PECL ps >= 1.1.0)

ps_continue_text — Continue text in next line

### 说明

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()

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`text`

  The text to output.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ps_lineto() - Draws a line

# ps_delete

(PECL ps >= 1.1.0)

ps_delete — Deletes all resources of a PostScript document

### 说明

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.

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ps_close() - Closes a PostScript document

# ps_end_page

(PECL ps >= 1.1.0)

ps_end_page — End a page

### 说明

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.

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ps_begin_page() - Start a new page

# ps_end_pattern

(PECL ps >= 1.2.0)

ps_end_pattern — End a pattern

### 说明

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.

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ps_begin_pattern() - Start a new pattern

# ps_end_template

(PECL ps >= 1.2.0)

ps_end_template — End a template

### 说明

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.

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ps_begin_template() - Start a new template

# ps_fill

(PECL ps >= 1.1.0)

ps_fill — Fills the current path

### 说明

function ps_fill(resource `$psdoc`): bool

Fills the path constructed with previously called drawing functions like ps_lineto().

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function ps_fill_stroke(resource `$psdoc`): bool

Fills and draws the path constructed with previously called drawing functions like ps_lineto().

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ps_fill() - Fills the current path
- ps_stroke() - Draws the current path

# ps_findfont

(PECL ps >= 1.1.0)

ps_findfont — Loads a font

### 说明

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.

### 参数

`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.

### 返回值

Returns the identifier of the font or zero in case of an error. The identifier is a positive number.

### 参见

- 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

### 说明

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.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### 参见

- ps_open_file() - Opens a file for output

# ps_get_parameter

(PECL ps >= 1.1.0)

ps_get_parameter — Gets certain parameters

### 说明

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.

### 参数

`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.

### 返回值

Returns the value of the parameter 或者在失败时返回 `false`.

### 参见

- ps_set_parameter() - Sets certain parameters

# ps_get_value

(PECL ps >= 1.1.0)

ps_get_value — Gets certain values

### 说明

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.

### 参数

`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.

### 返回值

Returns the value of the parameter or `false`.

### 参见

- ps_set_value() - Sets certain values

# ps_hyphenate

(PECL ps >= 1.1.1)

ps_hyphenate — Hyphenates a word

### 说明

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.

### 参数

`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.

### 返回值

An array of integers indicating the position of possible breaks in the text 或者在失败时返回 `false`.

### 示例

示例 #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);
    ?>

以上示例会输出：

    Ko-ordi-na-ten-sys-tem

### 参见

- 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

### 说明

function ps_include_file(resource `$psdoc`, string `$file`): bool

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`file`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# ps_lineto

(PECL ps >= 1.1.0)

ps_lineto — Draws a line

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

### 参见

- ps_moveto() - Sets current point

# ps_makespotcolor

(PECL ps >= 1.1.0)

ps_makespotcolor — Create spot color

### 说明

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.

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`name`

  Name of the spot color, e.g. Pantone 5565.

### 返回值

The id of the new spot color or 0 in case of an error.

### 示例

示例 #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.

### 参见

- ps_setcolor() - Sets current color

# ps_moveto

(PECL ps >= 1.1.0)

ps_moveto — Sets current point

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ps_lineto() - Draws a line

# ps_new

(PECL ps >= 1.1.0)

ps_new — Creates a new PostScript document object

### 说明

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.

### 参数

此函数没有参数。

### 返回值

Resource of PostScript document 或者在失败时返回 `false`. The return value is passed to all other functions as the first argument.

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ps_close() - Closes a PostScript document

# ps_open_image

(PECL ps >= 1.1.0)

ps_open_image — Reads an image for later placement

### 说明

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.

### 参数

`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`

### 返回值

Returns identifier of image or zero in case of an error. The identifier is a positive number greater than 0.

### 参见

- 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

### 说明

function ps_open_image_file(
resource `$psdoc`,
string `$type`,
string `$filename`,
string `$stringparam` = ?,
int `$intparam` = 0
): int

Loads an image for later use.

### 参数

`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.

### 返回值

Returns identifier of image or zero in case of an error. The identifier is a positive number greater than 0.

### 参见

- 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

### 说明

function ps_open_memory_image(resource `$psdoc`, int `$gd`): int
警告

本函数还未编写文档，仅有参数列表。

### 参数

`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

### 说明

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().

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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().

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ps_save() - Save current context

# ps_rotate

(PECL ps >= 1.1.0)

ps_rotate — Sets rotation factor

### 说明

function ps_rotate(resource `$psdoc`, float `$rot`): bool

Sets the rotation of the coordinate system.

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`rot`

  Angle of rotation in degree.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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().

### 参见

- ps_scale() - Sets scaling factor
- ps_translate() - Sets translation

# ps_save

(PECL ps >= 1.1.0)

ps_save — Save current context

### 说明

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().

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ps_restore() - Restore previously save context

# ps_scale

(PECL ps >= 1.1.0)

ps_scale — Sets scaling factor

### 说明

function ps_scale(resource `$psdoc`, float `$x`, float `$y`): bool

Sets horizontal and vertical scaling of the coordinate system.

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`x`

  Scaling factor in horizontal direction.

`y`

  Scaling factor in vertical direction.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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().

### 参数

`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.

  > 注意:

  > 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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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().

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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);
    ?>

### 参见

- ps_set_value() - Sets certain values
- ps_show() - Output text

# ps_set_value

(PECL ps >= 1.1.0)

ps_set_value — Sets certain values

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ps_get_value() - Gets certain values
- ps_set_parameter() - Sets certain parameters

# ps_setcolor

(PECL ps >= 1.1.0)

ps_setcolor — Sets current color

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 注释

警告

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

### 说明

function ps_setdash(resource `$psdoc`, float `$on`, float `$off`): bool

Sets the length of the black and white portions of a dashed line.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ps_setpolydash() - Sets appearance of a dashed line

# ps_setflat

(PECL ps >= 1.1.0)

ps_setflat — Sets flatness

### 说明

function ps_setflat(resource `$psdoc`, float `$value`): bool

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`value`

  The `value` must be between 0.2 and 1.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# ps_setfont

(PECL ps >= 1.1.0)

ps_setfont — Sets font to use for following output

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function ps_setgray(resource `$psdoc`, float `$gray`): bool

Sets the gray value for all following drawing operations.

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`gray`

  The value must be between 0 (white) and 1 (black).

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- ps_setcolor() - Sets current color

# ps_setlinecap

(PECL ps >= 1.1.0)

ps_setlinecap — Sets appearance of line ends

### 说明

function ps_setlinecap(resource `$psdoc`, int `$type`): bool

Sets how line ends look like.

### 参数

`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`.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function ps_setlinejoin(resource `$psdoc`, int `$type`): bool

Sets how lines are joined.

### 参数

`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`.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function ps_setlinewidth(resource `$psdoc`, float `$width`): bool

Sets the line width for all following drawing operations.

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`width`

  The width of lines in points.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function ps_setoverprintmode(resource `$psdoc`, int `$mode`): bool

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`mode`

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# ps_setpolydash

(PECL ps >= 1.1.0)

ps_setpolydash — Sets appearance of a dashed line

### 说明

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.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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.

### 参见

- ps_setdash() - Sets appearance of a dashed line

# ps_shading

(PECL ps >= 1.3.0)

ps_shading — Creates a shading for later use

### 说明

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`.

### 参数

`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.

### 返回值

Returns the identifier of the pattern 或者在失败时返回 `false`.

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

The identifier of the pattern 或者在失败时返回 `false`.

### 参见

- 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

### 说明

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.

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`shadingid`

  The identifier of a shading previously created with ps_shading().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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.

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`text`

  The text to be output.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

Number of characters that could not be written.

### 参见

- ps_continue_text() - Continue text in next line

# ps_show_xy

(PECL ps >= 1.1.0)

ps_show_xy — Output text at given position

### 说明

function ps_show_xy(
resource `$psdoc`,
string `$text`,
float `$x`,
float `$y`
): bool

Output a text at the given text position.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function ps_show_xy2(
resource `$psdoc`,
string `$text`,
int `$len`,
float `$xcoor`,
float `$ycoor`
): bool
警告

本函数还未编写文档，仅有参数列表。

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# ps_show2

(PECL ps >= 1.1.0)

ps_show2 — Output a text at current position

### 说明

function ps_show2(resource `$psdoc`, string `$text`, int `$len`): bool

Output text at the current position. Do not print more than `len` characters.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

# ps_string_geometry

(PECL ps >= 1.2.0)

ps_string_geometry — Gets geometry of a string

### 说明

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.

### 参数

`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.

### 返回值

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.

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

Width of a string in points.

### 参见

- ps_string_geometry() - Gets geometry of a string

# ps_stroke

(PECL ps >= 1.1.0)

ps_stroke — Draws the current path

### 说明

function ps_stroke(resource `$psdoc`): bool

Draws the path constructed with previously called drawing functions like ps_lineto().

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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().

### 参数

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`ord`

  The position of the glyph in the font encoding vector.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

The name of a glyph in the given font.

### 参见

- 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

### 说明

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.

### 参数

`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.

### 返回值

The width of a glyph in points.

### 参见

- ps_symbol() - Output a glyph
- ps_symbol_name() - Gets name of a glyph

# ps_translate

(PECL ps >= 1.1.0)

ps_translate — Sets translation

### 说明

function ps_translate(resource `$psdoc`, float `$x`, float `$y`): bool

Sets a new initial point of the coordinate system.

### 参数

`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.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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.

### 参见

- ps_scale() - Sets scaling factor
- ps_rotate() - Sets rotation factor

## 目录

- 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

- 安装/配置
  - 需求
  - 安装
  - 资源类型
- 预定义常量
- PS 函数
  - 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

# 简介

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 via PECL

## 需求

This extension requires » librpm version 4.11.3 or higher.

## Installation via PECL

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/rpminfo.

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

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 函数

# rpmaddtag

(PECL rpminfo >= 0.5.0)

rpmaddtag — Add tag retrieved in query

### 说明

function rpmaddtag(int `$tag`): bool

Add an additional retrieved tag in subsequent queries.

### 参数

`tag`
  One of `RPMTAG_*` constant.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 参见

- 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

### 说明

function rpmdbinfo(string `$nevr`, bool `$full` = `false`): ?array

Retrieve information about an installed package, from the system RPM database.

### 参数

`nevr`
  Name with optional epoch, version and release.
`full`
  If `true` all information headers for the file are retrieved, else only a minimal set.

### 返回值

An array of array of information, or `null` on error.

### 示例

示例 #1 A rpmdbinfo() example

    <?php
    rpmaddtag(RPMTAG_INSTALLTIME);
    $info = rpmdbinfo("php-pecl-rpminfo");
    print_r($info);
    ?>

以上示例会输出：

    Array
    (
        [0] => Array
            (
                [Name] => php-pecl-rpminfo
                [Version] => 0.4.2
                [Release] => 1.fc31
                [Summary] => RPM information
                [Installtime] => 1586244687
                [Arch] => x86_64
            )
    )

### 参见

- rpmaddtag() - Add tag retrieved in query

# rpmdbsearch

(PECL rpminfo >= 0.3.0)

rpmdbsearch — Search RPM packages

### 说明

function rpmdbsearch(
string `$pattern`,
int `$rpmtag` = RPMTAG_NAME,
int `$rpmmire` = -1,
bool `$full` = `false`
): ?array

Search packages in the system RPM database.

### 参数

`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.

### 返回值

An array of array of information, or `null` on error.

### 示例

示例 #1 Searching for the package owning a file

    <?php
    $info = rpmdbsearch("/usr/bin/php", RPMTAG_INSTFILENAMES);
    print_r($info);
    ?>

以上示例会输出：

    Array
    (
        [0] => Array
            (
                [Name] => php-cli
                [Version] => 7.4.4
                [Release] => 1.fc32
                [Summary] => Command-line interface for PHP
                [Arch] => x86_64
            )

    )

### 参见

- rpmaddtag() - Add tag retrieved in query

# rpmdefine

(PECL rpminfo >= 1.2.0)

rpmdefine — Define or change a RPM macro value

### 说明

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.

### 参数

`text`
  Macro name, options, body.

### 返回值

成功时返回 `true`， 或者在失败时返回 `false`。

### 示例

示例 #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"]);
    ?>

以上示例会输出：

    AlmaLinux release file
    Fedora release files

### 参见

- 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

### 说明

function rpmexpand(string `$text`): string

Retrieve expanded value of a RPM macro.

### 参数

`text`
  Text with RPM macros to expand.

### 返回值

A string with concatenated macro expansions.

### 示例

示例 #1 A rpmexpand() example

    <?php
    $distro = rpmexpand("%{?fedora:Fedora %{fedora}}%{?rhel:Enterprise Linux %{rhel}}");
    print_r($distro);
    ?>

以上示例会输出：

    Fedora 41

### 参见

- rpmexpandnumeric() - Retrieve numerical value of a RPM macro

# rpmexpandnumeric

(PECL rpminfo >= 1.2.0)

rpmexpandnumeric — Retrieve numerical value of a RPM macro

### 说明

function rpmexpandnumeric(string `$text`): int

Retrieve numerical value of a RPM macro.

### 参数

`text`
  Text with RPM macros to expand.

### 返回值

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`.

### 示例

示例 #1 A rpmexpandnumeric() example

    <?php
    $bits = rpmexpandnumeric("%__isa_bits");
    print_r($bits);
    ?>

以上示例会输出：

    64

### 参见

- rpmexpand() - Retrieve expanded value of a RPM macro

# rpmgetsymlink

(PECL rpminfo >= 1.1.0)

rpmgetsymlink — Get target of a symlink

### 说明

function rpmgetsymlink(string `$path`, string `$name`): ?string

Get target of a symlink.

### 参数

`path`
  Path of the RPM file.
`name`
  Name of the symlink file.

### 返回值

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

### 说明

function rpminfo(string `$path`, bool `$full` = `false`, string `&$error` = ?): ?array

Retrieve information about a local file, a RPM package.

### 参数

`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.

### 返回值

An array of information, or `null` on error.

### 示例

示例 #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);
    ?>

以上示例会输出：

    Array
    (
        [Name] => php-pecl-rpminfo
        [Version] => 0.4.2
        [Release] => 1.el8
        [Summary] => RPM information
        [Buildtime] => 1586244821
        [Arch] => x86_64
    )

### 参见

- rpmaddtag() - Add tag retrieved in query

# rpmvercmp

(PECL rpminfo >= 0.1.0)

rpmvercmp — RPM version comparison

### 说明

function rpmvercmp(string `$evr1`, string `$evr2`, ?string `$operator` = `null`): int|bool

Compare two RPM package versions.

### 参数

`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.

### 返回值

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.

### 更新日志

版本 | 说明
--- | ---
PECL rpminfo 0.7.0 | Optional `operator` was added.

## 目录

- 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 via PECL
- 预定义常量
- RpmInfo 函数
  - 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

# 简介

An efficient and fast xlsx file export extension.

# 安装/配置

## 目录

- 需求
- 安装
- 资源类型

## 需求

XLSWriter requires PHP 7.0 and above.

## 安装

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/xlswriter

## 资源类型

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)

## 简介

Create xlsx files and set cells and output xlsx files

## 类摘要

class Vtiful\Kernel\Excel {
/* 方法 */
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

### 说明

public function Vtiful\Kernel\Excel::addSheet(string `$sheetName`)

Create a new worksheet in the xlsx file.

### 参数

`sheetName`

  Worksheet name

### 返回值

Vtiful\Kernel\Excel instance

### 示例

示例 #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

### 说明

public function Vtiful\Kernel\Excel::autoFilter(string `$scope`)

Add autofilter to a worksheet.

### 参数

`scope`

  Cell start and end coordinate string.

### 返回值

Vtiful\Kernel\Excel instance

### 示例

示例 #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

### 说明

public function Vtiful\Kernel\Excel::constMemory(string `$fileName`, string `$sheetName` = ?)

Write a large file with constant memory usage.

### 参数

`fileName`

  XLSX file name

`sheetName`

  Worksheet name

### 返回值

Vtiful\Kernel\Excel instance

### 示例

示例 #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

### 说明

public function Vtiful\Kernel\Excel::__construct(array `$config`)

Vtiful\Kernel\Excel constructor, create a class object.

### 参数

`config`

  XLSX file export configuration

### 示例

示例 #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

### 说明

public function Vtiful\Kernel\Excel::data(array `$data`)

Write a data in the worksheet.

### 参数

`data`

  worksheet data

### 返回值

Vtiful\Kernel\Excel instance

### 示例

示例 #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

### 说明

public function Vtiful\Kernel\Excel::fileName(string `$fileName`, string `$sheetName` = ?)

Create a brand new xlsx file and create a worksheet.

### 参数

`fileName`

  XLSX file name

`sheetName`

  Worksheet name

### 返回值

Vtiful\Kernel\Excel instance

### 示例

示例 #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

### 说明

public function Vtiful\Kernel\Excel::getHandle()

Get the xlsx text resource handle.

### 参数

此函数没有参数。

### 返回值

Resource

### 示例

示例 #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

### 说明

public function Vtiful\Kernel\Excel::header(array `$headerData`)

Write a header in the worksheet.

### 参数

`headerData`

  worksheet header data

### 返回值

Vtiful\Kernel\Excel instance

### 示例

示例 #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

### 说明

public function Vtiful\Kernel\Excel::insertFormula(int `$row`, int `$column`, string `$formula`)

Insert calculation formula.

### 参数

`row`

  cell row

`column`

  cell column

`formula`

  formula string

### 返回值

Vtiful\Kernel\Excel instance

### 示例

示例 #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

### 说明

public function Vtiful\Kernel\Excel::insertImage(int `$row`, int `$column`, string `$localImagePath`)

Insert a local image into the cell.

### 参数

`row`

  cell row

`column`

  cell column

`localImagePath`

  local image path

### 返回值

Vtiful\Kernel\Excel instance

### 示例

示例 #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

### 说明

public function Vtiful\Kernel\Excel::insertText(
int `$row`,
int `$column`,
int|float|string `$data`,
string `$format` = ?
)

Write text in a cell.

### 参数

`row`

  cell row

`column`

  cell column

`data`

  data to be written

`format`

  String format

### 返回值

Vtiful\Kernel\Excel instance

### 示例

示例 #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

### 说明

public function Vtiful\Kernel\Excel::mergeCells(string `$scope`, string `$data`)

Merge Cells.

### 参数

`scope`

  cell start and end coordinate strings

`data`

  string data

### 返回值

Vtiful\Kernel\Excel instance

### 示例

示例 #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

### 说明

public function Vtiful\Kernel\Excel::output()

Output xlsx file to disk.

### 参数

此函数没有参数。

### 返回值

XLSX file path;

### 示例

示例 #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

### 说明

public function Vtiful\Kernel\Excel::setColumn(string `$range`, float `$width`, resource `$format` = ?)

Set the format of the column.

### 参数

`range`

  cell start and end coordinate strings

`width`

  column width

`format`

  cell format resource

### 返回值

Vtiful\Kernel\Excel instance

### 示例

示例 #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

### 说明

public function Vtiful\Kernel\Excel::setRow(string `$range`, float `$height`, resource `$format` = ?)

Set the format of the row.

### 参数

`range`

  cell start and end coordinate strings

`height`

  row height

`format`

  cell format resource

### 返回值

Vtiful\Kernel\Excel instance

### 示例

示例 #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();

## 目录

- 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)

## 简介

Create a cell format object

## 类摘要

class Vtiful\Kernel\Format {
/* 常量 */
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;
/* 方法 */
public function align(resource `$handle`, int `$style`)
public function bold(resource `$handle`)
public function italic(resource `$handle`)
public function underline(resource `$handle`, int `$style`)
}

## 预定义常量

`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`

`Vtiful\Kernel\Format::UNDERLINE_DOUBLE_ACCOUNTING`

# Vtiful\Kernel\Format::align

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Format::align — Vtiful\Kernel\Format align

### 说明

public function Vtiful\Kernel\Format::align(resource `$handle`, int `$style`)

set cell align

### 参数

`handle`

  xlsx file handle

`style`

  Vtiful\Kernel\Format constant

### 返回值

Resource

### 示例

示例 #1 Align style example

    <?php
    $config = [
        'path' => './tests'
    ];

    $excel = new \Vtiful\Kernel\Excel($config);
    $excel->fileName('tutorial01.xlsx');

    $format = new \Vtiful\Kernel\Format($excel->getHandle());
    $alignStyle = $format->align(\Vtiful\Kernel\Format::FORMAT_ALIGN_LEFT)->toResource();

    $excel->header(['name', 'age'])
        ->data([['viest', 21]])
        ->setColumn('A:A', 200, $alignStyle)
        ->output();
    ?>

# Vtiful\Kernel\Format::bold

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Format::bold — Vtiful\Kernel\Format bold

### 说明

public function Vtiful\Kernel\Format::bold(resource `$handle`)

Vtiful\Kernel\Format bold format

### 参数

`handle`

  xlsx file handle

### 返回值

Resource

### 示例

示例 #1 Bold style 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\Format::italic

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Format::italic — Vtiful\Kernel\Format italic

### 说明

public function Vtiful\Kernel\Format::italic(resource `$handle`)

Vtiful\Kernel\Format italic format

### 参数

`handle`

  xlsx file handle

### 返回值

Resource

### 示例

示例 #1 Italic style example

    <?php
    $config = [
        'path' => './tests'
    ];

    $excel = new \Vtiful\Kernel\Excel($config);
    $excel->fileName('tutorial01.xlsx');

    $format = new \Vtiful\Kernel\Format($excel->getHandle());
    $italicStyle = $format->italic()->toResource();

    $excel->header(['name', 'age'])
        ->data([['viest', 21]])
        ->setColumn('A:A', 200, $italicStyle)
        ->output();
    ?>

# Vtiful\Kernel\Format::underline

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Format::underline — Vtiful\Kernel\Format underline

### 说明

public function Vtiful\Kernel\Format::underline(resource `$handle`, int `$style`)

Vtiful\Kernel\Format underline format

### 参数

`handle`

  xlsx file handle

`style`

  Vtiful\Kernel\Format constant

### 返回值

Resource

### 示例

示例 #1 Underline style example

    <?php
    $config = [
        'path' => './tests'
    ];

    $excel = new \Vtiful\Kernel\Excel($config);
    $excel->fileName('tutorial01.xlsx');

    $format = new \Vtiful\Kernel\Format($excel->getHandle());
    $underlineStyle = $format->underline(\Vtiful\Kernel\Format::UNDERLINE_SINGLE)->toResource();

    $excel->header(['name', 'age'])
        ->data([['viest', 21]])
        ->setColumn('A:A', 200, $underlineStyle)
        ->output();
    ?>

## 目录

- Vtiful\Kernel\Format::align — Vtiful\Kernel\Format align
- Vtiful\Kernel\Format::bold — Vtiful\Kernel\Format bold
- Vtiful\Kernel\Format::italic — Vtiful\Kernel\Format italic
- Vtiful\Kernel\Format::underline — Vtiful\Kernel\Format underline

- 安装/配置
  - 需求
  - 安装
  - 资源类型
- Vtiful\Kernel\Excel — The Vtiful\Kernel\Excel class
  - 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
- Vtiful\Kernel\Format — The Vtiful\Kernel\Format class
  - Vtiful\Kernel\Format::align — Vtiful\Kernel\Format align
  - Vtiful\Kernel\Format::bold — Vtiful\Kernel\Format bold
  - Vtiful\Kernel\Format::italic — Vtiful\Kernel\Format italic
  - Vtiful\Kernel\Format::underline — Vtiful\Kernel\Format underline

- FDF — Forms Data Format
  - 安装/配置
  - 预定义常量
  - 示例
  - FDF 函数
- GnuPG — GNU Privacy Guard
  - 安装/配置
  - 预定义常量
  - 示例
  - GnuPG 函数
- wkhtmltox
  - 安装/配置
  - wkhtmltox\PDF\Converter — The wkhtmltox\PDF\Converter class
  - wkhtmltox\PDF\Object — The wkhtmltox\PDF\Object class
  - wkhtmltox\Image\Converter — The wkhtmltox\Image\Converter class
- PS — PostScript document creation
  - 安装/配置
  - 预定义常量
  - PS 函数
- RpmInfo
  - 安装/配置
  - 预定义常量
  - RpmInfo 函数
- XLSWriter
  - 安装/配置
  - Vtiful\Kernel\Excel — The Vtiful\Kernel\Excel class
  - Vtiful\Kernel\Format — The Vtiful\Kernel\Format class

# 进程控制扩展

# Eio

# 简介

This extension provides asynchronous POSIX I/O by means of » libeio C library written by Marc Lehmann.

> 注意: 此扩展在 Windows 平台上不可用。

警告

It is important to be aware that each request is executed in a thread, and the order of execution of continuously queued requests basically is unpredictable. For instance, the following piece of code is incorrect.

示例 #1 Incorrect requests

    <?php
    // Request to create symlink of $filename to $link
    eio_symlink($filename, $link);

    // Request to move $filename to $new_filename
    eio_rename($filename, $new_filename);

    // Process requests
    eio_event_loop();
    ?>

In the example above eio_rename() request may finish before eio_symlink(). To fix it you might call eio_rename() in the callback of eio_symlink():

示例 #2 Calling request from a request callback

    <?php
    function my_symlink_done($filename, $result) {
     // Request to move $filename to $new_filename
     eio_rename($filename, "/path/to/new-name");

     // Process requests
     eio_event_loop();
    }

    // Request to create symlink of $filename to $link
    eio_symlink($filename, $link, EIO_PRI_DEFAULT, "my_symlink_done", $filename);

    // Process requests
    eio_event_loop();
    ?>

Alternatively, you might want to create a request group:

示例 #3 Calling request from a request callback

    <?php
    /* Is called when the group requests are done */
    function my_grp_done($data, $result) {
     // ...
    }

    function my_symlink_done($filename, $result) {
     // Create eio_rename request and add it to the group
     $req = eio_rename($filename, "/path/to/new-name");
     eio_grp_add($grp, $req);
     // You might want to add more requests...
    }

    // Create a request group
    $grp = eio_grp("my_grp_done", "my_grp_data");

    // Create eio_symlink request and add it to the group
    // Pass $filename to the callback
    $req = eio_symlink($filename, $link,
      EIO_PRI_DEFAULT, "my_symlink_done", $filename);
    eio_grp_add($grp, $req);

    // Process requests
    eio_event_loop();
    ?>

Group is a special kind of request that could accumulate a set of regular eio requests. This could be used to create a complex request that opens, reads and closes a file.

Since version 0.3.0 alpha, a variable used in communications with libeio internally, could be retrieved with eio_get_event_stream(). The variable could be used to bind to an event loop supported by some other extension. You might organize a simple event loop where eio and libevent work together:

示例 #4 Using eio with libevent

    <?php
    function my_eio_poll($fd, $events, $arg) {
        /* Some libevent regulation might go here .. */
        if (eio_nreqs()) {
            eio_poll();
        }
        /* .. and here */
    }

    function my_res_cb($d, $r) {
        var_dump($r); var_dump($d);
    }

    $base = event_base_new();
    $event = event_new();

    // This stream is used to bind with libevent
    $fd = eio_get_event_stream();

    eio_nop(EIO_PRI_DEFAULT, "my_res_cb", "nop data");
    eio_mkdir("/tmp/abc-eio-temp", 0750, EIO_PRI_DEFAULT, "my_res_cb", "mkdir data");
    /* some other eio_* calls here ... */

    // set event flags
    event_set($event, $fd, EV_READ /*| EV_PERSIST*/, "my_eio_poll", array($event, $base));

    // set event base
    event_base_set($event, $base);

    // enable event
    event_add($event);

    // start event loop
    event_base_loop($base);

    /* The same will be available via buffered libevent interface */
    ?>

# 安装/配置

## 目录

- 需求
- 安装
- 资源类型

## 需求

This extension has » libeio library embedded. So you do NOT need to install libeio separately.

## 安装

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/eio.

For information about manual installation, please read the file INSTALL included in the package.

## 资源类型

There are two resource types in this extension: request and request group.

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

Request priority constants:

`EIO_PRI_MIN` (int)
  Request minimal priority.
`EIO_PRI_DEFAULT` (int)
  Request default priority.
`EIO_PRI_MAX` (int)
  Request maximal priority.

eio_seek() `whence` argument:

`EIO_SEEK_SET` (int)
  The offset is set to specified number of bytes (`offset`).
`EIO_SEEK_CUR` (int)
  The offset is set to its current location plus `offset` bytes.
`EIO_SEEK_END` (int)
  The offset is set to the size of the file plus `offset` bytes.

Flags used with eio_readdir():

`EIO_READDIR_DENTS` (int)
  eio_readdir() flag. If specified, the result argument of the callback becomes an array with the following keys: `'names'` - array of directory names `'dents'` - array of `struct eio_dirent`-like arrays having the following keys each: `'name'` - the directory name; `'type'` - one of EIO_DT_* constants; `'inode'` - the inode number, if available, otherwise unspecified.
`EIO_READDIR_DIRS_FIRST` (int)
  When this flag is specified, the names will be returned in an order where likely directories come first, in optimal stat order.
`EIO_READDIR_STAT_ORDER` (int)
  When this flag is specified, then the names will be returned in an order suitable for `stat`'ing each one. When planning to stat() all files in the given directory, the returned order will likely be fastest.
`EIO_READDIR_FOUND_UNKNOWN` (int)
`EIO_DT_UNKNOWN` (int)
  Unknown node type (very common). Further stat() needed.
`EIO_DT_FIFO` (int)
  FIFO node type.
`EIO_DT_CHR` (int)
  Node type.
`EIO_DT_MPC` (int)
  Multiplexed char device (v7+coherent) node type.
`EIO_DT_DIR` (int)
  Directory node type.
`EIO_DT_NAM` (int)
  Xenix special named file node type.
`EIO_DT_BLK` (int)
  Node type.
`EIO_DT_MPB` (int)
  Multiplexed block device (v7+coherent).
`EIO_DT_REG` (int)
  Node type.
`EIO_DT_NWK` (int)
`EIO_DT_CMP` (int)
  HP-UX network special node type.
`EIO_DT_LNK` (int)
  Link node type.
`EIO_DT_SOCK` (int)
  Socket node type.
`EIO_DT_DOOR` (int)
  Solaris door node type.
`EIO_DT_WHT` (int)
  Node type.
`EIO_DT_MAX` (int)
  Highest node type value.

Access modes for eio_open() `flags` argument:

`EIO_O_RDONLY` (int)
`EIO_O_WRONLY` (int)
`EIO_O_RDWR` (int)
`EIO_O_NONBLOCK` (int)
`EIO_O_APPEND` (int)
`EIO_O_CREAT` (int)
`EIO_O_TRUNC` (int)
`EIO_O_EXCL` (int)
`EIO_O_FSYNC` (int)

`mode` argument flags for eio_open():

`EIO_S_IRUSR` (int)
`EIO_S_IWUSR` (int)
`EIO_S_IXUSR` (int)
`EIO_S_IRGRP` (int)
`EIO_S_IWGRP` (int)
`EIO_S_IXGRP` (int)
`EIO_S_IROTH` (int)
`EIO_S_IWOTH` (int)
`EIO_S_IXOTH` (int)
`EIO_S_IFREG` (int)
`EIO_S_IFCHR` (int)
`EIO_S_IFBLK` (int)
`EIO_S_IFIFO` (int)
`EIO_S_IFSOCK` (int)

eio_sync_file_range() flags:

`EIO_SYNC_FILE_RANGE_WAIT_BEFORE` (int)
`EIO_SYNC_FILE_RANGE_WRITE` (int)
`EIO_SYNC_FILE_RANGE_WAIT_AFTER` (int)

eio_fallocate() flags:

`EIO_FALLOC_FL_KEEP_SIZE` (int)

> 注意: EIO_S_I* constants have the same meaning as their S_I* POSIX counterparts.

> 注意: EIO_SYNC_FILE_* constants have the same meaning as their SYNC_FILE_** counterparts.

> 注意: EIO_O_* constants have the same meaning as their O_* POSIX counterparts.

# 示例

示例 #1 Cancelling a request

    <?php
     /* Is called when eio_nop() finished */
     function my_nop_cb($data, $result) {
      echo "my_nop ", $data, "\n";
     }

    // This eio_nop() call will be cancelled
    $req = eio_nop(EIO_PRI_DEFAULT, "my_nop_cb", "1");
    var_dump($req);
    eio_cancel($req);

    // This time eio_nop() will be processed
    eio_nop(EIO_PRI_DEFAULT, "my_nop_cb", "2");

    // Process requests
    eio_event_loop();
    ?>

以上示例的输出类似于：

    resource(4) of type (EIO Request Descriptor)
    my_nop 2

示例 #2 Calling eio_chmod()

    <?php
    $temp_filename = dirname(__FILE__) ."/eio-temp-file.tmp";
    touch($temp_filename);

    /* Is called when eio_chmod() finished */
    function my_chmod_callback($data, $result) {
        global $temp_filename;

        if ($result == 0 && !is_readable($temp_filename) && is_writable($temp_filename)) {
            echo "eio_chmod_ok";
        }

        @unlink($temp_filename);
    }

    eio_chmod($temp_filename, 0200, EIO_PRI_DEFAULT, "my_chmod_callback");
    eio_event_loop();
    ?>

以上示例的输出类似于：

    eio_chmod_ok

示例 #3 Making a custom request

    <?php
    /* Callback for the custom callback */
    function my_custom_callback($data, $result) {
        var_dump($data);
        var_dump(count($result));
        var_dump($result['data_modified']);
        var_dump($result['result']);
    }

    /* The custom request */
    function my_custom($data) {
        var_dump($data);

        $result  = array(
            'result'        => 1001,
            'data_modified' => "my custom data",
        );

        return $result;
    }

    $data = "my_custom_data";
    $req = eio_custom("my_custom", EIO_PRI_DEFAULT, "my_custom_callback", $data);
    var_dump($req);
    eio_event_loop();
    ?>

以上示例的输出类似于：

    resource(4) of type (EIO Request Descriptor)
    string(14) "my_custom_data"
    string(14) "my_custom_data"
    int(2)
    string(14) "my custom data"
    int(1001)

示例 #4 Grouping requests

    <?php
    /*
     * Create a group request to open, read and close a file
     */

    $temp_filename = dirname(__FILE__) ."/eio-file.tmp";
    $fp = fopen($temp_filename, "w");
    fwrite($fp, "some data");
    fclose($fp);

    /* Is called when the group requests are done */
    function my_grp_done($data, $result) {
     global $temp_filename;
     var_dump($result == 0);
     @unlink($temp_filename);
    }

    /* Is called when eio_open() done */
    function my_grp_file_opened_callback($data, $result) {
     global $my_file_fd, $grp;

     $my_file_fd = $result;

     var_dump($result > 0);

     // Create eio_read() request and add it to the group
     $req = eio_read($my_file_fd, 4, 0, EIO_PRI_DEFAULT, "my_grp_file_read_callback");
     eio_grp_add($grp, $req);
    }

    /* Is called when eio_read() done */
    function my_grp_file_read_callback($data, $result) {
     global $my_file_fd, $grp;

     var_dump($result);

     // Create eio_close() request and add it to the group
     $req = eio_close($my_file_fd);
     eio_grp_add($grp, $req);
    }

    $grp = eio_grp("my_grp_done", "my_grp_data");

    // Create eio_open() request and add it to the group
    $req = eio_open($temp_filename, EIO_O_RDWR | EIO_O_APPEND , NULL,
      EIO_PRI_DEFAULT, "my_grp_file_opened_callback", NULL);
    eio_grp_add($grp, $req);
    var_dump($grp);

    eio_event_loop();
    ?>

以上示例的输出类似于：

    resource(6) of type (EIO Group Descriptor)
    bool(true)
    string(4) "some"
    bool(true)

示例 #5 Using eio with libevent extension

    <?php
    function my_eio_poll($fd, $events, $arg) {
        /* Some libevent regulation might go here .. */
        if (eio_nreqs()) {
            eio_poll();
        }
        /* .. and here */
    }

    function my_nop_cb($d, $r) {
        var_dump($r); var_dump($d);
    }

    $base = event_base_new();
    $event = event_new();

    $fd = eio_get_event_stream();
    var_dump($fd);

    eio_nop(EIO_PRI_DEFAULT, "my_nop_cb", "nop data");
    eio_mkdir("/tmp/abc-eio-temp", 0750, EIO_PRI_DEFAULT, "my_nop_cb", "nop data");
    /* some other eio_* calls here ... */

    // set event flags
    event_set($event, $fd, EV_READ /*| EV_PERSIST*/, "my_eio_poll", array($event, $base));

    // set event base
    event_base_set($event, $base);

    // enable event
    event_add($event);

    // start event loop
    event_base_loop($base);

    /* The same will be available via buffered libevent interface */
    ?>

以上示例的输出类似于：

    int(3)
    int(0)
    string(8) "nop data"
    int(0)
    string(10) "mkdir data"

示例 #6 Using eio with event extension

    <?php
    $base = new EventBase();

    // Retrieve eio polling stream.
    // Note, this variable should be alive as long as the event loop is running.
    $eio_stream = eio_get_event_stream();

    // Bind eio polling stream to the event loop.
    $poll_event = new Event($base, $eio_stream, Event::READ, function () {
      if (eio_nreqs()) {
        eio_poll();
      }
    });
    $poll_event->add();

    // Add eio jobs
    eio_nop(EIO_PRI_DEFAULT, function () {
      echo "eio_nop\n";
    });

    // Add events
    $timer = Event::timer($base, function () {
      echo "2 seconds elapsed\n";
    });
    $timer->add(2);

    // Dispatch events.
    $base->dispatch();
    ?>

以上示例的输出类似于：

    eio_nop
    2 seconds elapsed

# Eio 函数

# eio_busy

(PECL eio >= 0.0.1dev)

eio_busy — Artificially increase load. Could be useful in tests, benchmarking

### 说明

function eio_busy(
int `$delay`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_busy() artificially increases load taking `delay` seconds to execute. May be used for debugging, or benchmarking.

### 参数

`delay`
  Delay in seconds
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`
  This callback is called when all the group requests are done.
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_busy() returns request resource on success, 或者在失败时返回 `false`.

### 参见

- eio_nop() - Does nothing, except go through the whole request cycle

# eio_cancel

(PECL eio >= 0.0.1dev)

eio_cancel — Cancels a request

### 说明

function eio_cancel(resource `$req`): void

eio_cancel() cancels a request specified by `req`

### 参数

`req`
  The request resource
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

没有返回值。

### 示例

示例 #1 eio_cancel() example

    <?php
     /* Is called when eio_nop() finished */
     function my_nop_cb($data, $result) {
      echo "my_nop ", $data, "\n";
     }

    // This eio_nop() call will be cancelled
    $req = eio_nop(EIO_PRI_DEFAULT, "my_nop_cb", "1");
    var_dump($req);
    eio_cancel($req);

    // This time eio_nop() will be processed
    eio_nop(EIO_PRI_DEFAULT, "my_nop_cb", "2");

    // Process requests
    eio_event_loop();
    ?>

以上示例的输出类似于：

    resource(4) of type (EIO Request Descriptor)
    my_nop 2

### 参见

- eio_grp_cancel() - Cancels a request group

# eio_chmod

(PECL eio >= 0.0.1dev)

eio_chmod — Change file/directory permissions

### 说明

function eio_chmod(
string `$path`,
int `$mode`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_chmod() changes file, or directory permissions. The new permissions are specified by `mode`.

### 参数

`path`
  Path to the target file or directory
  警告

  避免相对路径。

`mode`
  The new permissions. E.g. `0644`.
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_chmod() returns request resource on success, 或者在失败时返回 `false`.

### 参见

- eio_chown() - Change file/directory ownership

# eio_chown

(PECL eio >= 0.0.1dev)

eio_chown — Change file/directory ownership

### 说明

function eio_chown(
string `$path`,
int `$uid`,
int `$gid` = -1,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_chown() changes ownership of a file, or directory. The new owner is specified by `uid`, and the group by `gid`.

### 参数

`path`
  Path to file or directory.
  警告

  避免相对路径。

`uid`
  User ID. Is ignored when equal to -1.
`gid`
  Group ID. Is ignored when equal to -1.
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_chown() returns request resource on success, 或者在失败时返回 `false`.

### 参见

- eio_chmod() - Change file/directory permissions

# eio_close

(PECL eio >= 0.0.1dev)

eio_close — Close file

### 说明

function eio_close(
mixed `$fd`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_close() closes file specified by `fd`.

### 参数

`fd`
  Stream, Socket resource, or numeric file descriptor
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_close() returns request resource on success, 或者在失败时返回 `false`.

### 参见

- eio_open() - Opens a file

# eio_custom

(PECL eio >= 0.0.1dev)

eio_custom — Execute custom request like any other eio_* call

### 说明

function eio_custom(
callable `$execute`,
int `$pri`,
callable `$callback`,
mixed `$data` = NULL
): resource

eio_custom() executes custom function specified by `execute` processing it just like any other eio_* call.

### 参数

`execute`

  Specifies the request function that should match the following prototype:

            mixed execute(mixed data);

  `callback` is event completion callback that should match the following prototype:

            void callback(mixed data, mixed result);

  `data` is the data passed to `execute` via `data` argument without modifications `result` value returned by `execute`
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_custom() returns request resource on success, 或者在失败时返回 `false`.

### 示例

示例 #1 eio_custom() example

    <?php
    /* Callback for the custom callback */
    function my_custom_callback($data, $result) {
        var_dump($data);
        var_dump(count($result));
        var_dump($result['data_modified']);
        var_dump($result['result']);
    }

    /* The custom request */
    function my_custom($data) {
        var_dump($data);

        $result  = array(
            'result'        => 1001,
            'data_modified' => "my custom data",
        );

        return $result;
    }

    $data = "my_custom_data";
    $req = eio_custom("my_custom", EIO_PRI_DEFAULT, "my_custom_callback", $data);
    var_dump($req);
    eio_event_loop();
    ?>

以上示例的输出类似于：

    resource(4) of type (EIO Request Descriptor)
    string(14) "my_custom_data"
    string(14) "my_custom_data"
    int(2)
    string(14) "my custom data"
    int(1001)

# eio_dup2

(PECL eio >= 0.0.1dev)

eio_dup2 — Duplicate a file descriptor

### 说明

function eio_dup2(
mixed `$fd`,
mixed `$fd2`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_dup2() duplicates file descriptor.

### 参数

`fd`
  Source stream, Socket resource, or numeric file descriptor
`fd2`
  Target stream, Socket resource, or numeric file descriptor
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_dup2() returns request resource on success, 或者在失败时返回 `false`.

# eio_event_loop

(PECL eio >= 0.0.1dev)

eio_event_loop — Polls libeio until all requests proceeded

### 说明

function eio_event_loop(): bool

eio_event_loop() polls libeio until all requests proceeded.

### 参数

此函数没有参数。

### 返回值

eio_event_loop() returns `true` on success, 或者在失败时返回 `false`.

### 示例

示例 #1 eio_event_loop() example

    <?php
    $temp_filename = "eio-temp-file.tmp";
    touch($temp_filename);

    /* Is called when eio_chmod() finished */
    function my_chmod_callback($data, $result) {
        global $temp_filename;

        if ($result == 0 && !is_readable($temp_filename) && is_writable($temp_filename)) {
            echo "eio_chmod_ok";
        }

        @unlink($temp_filename);
    }

    eio_chmod($temp_filename, 0200, EIO_PRI_DEFAULT, "my_chmod_callback");
    eio_event_loop();
    ?>

以上示例的输出类似于：

    eio_chmod_ok

### 参见

- eio_poll() - Can be called whenever there are pending requests that need finishing

# eio_fallocate

(PECL eio >= 0.0.1dev)

eio_fallocate — Allows the caller to directly manipulate the allocated disk space for a file

### 说明

function eio_fallocate(
mixed `$fd`,
int `$mode`,
int `$offset`,
int `$length`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_fallocate() allows the caller to directly manipulate the allocated disk space for the file specified by `fd` file descriptor for the byte range starting at `offset` and continuing for `length` bytes.

> 注意: File should be opened for writing
> `EIO_O_CREAT` should be logically OR'd with `EIO_O_WRONLY`, or `EIO_O_RDWR`

### 参数

`fd`
  Stream, Socket resource, or numeric file descriptor, e.g. returned by eio_open().
`mode`
  Currently only one flag is supported for mode: `EIO_FALLOC_FL_KEEP_SIZE` (the same as POSIX constant `FALLOC_FL_KEEP_SIZE`).
`offset`
  Specifies start of the byte range.
`length`
  Specifies length of the byte range.
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_fallocate() returns request resource on success, 或者在失败时返回 `false`.

# eio_fchmod

(PECL eio >= 0.0.1dev)

eio_fchmod — Change file permissions

### 说明

function eio_fchmod(
mixed `$fd`,
int `$mode`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_fchmod() changes permissions for the file specified by `fd` file descriptor.

### 参数

`fd`
  Stream, Socket resource, or numeric file descriptor, e.g. returned by eio_open().
`mode`
  The new permissions. E.g. 0644.
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_fchmod() returns request resource on success, 或者在失败时返回 `false`.

### 参见

- eio_fchown() - Change file ownership

# eio_fchown

(PECL eio >= 0.0.1dev)

eio_fchown — Change file ownership

### 说明

function eio_fchown(
mixed `$fd`,
int `$uid`,
int `$gid` = -1,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_fchown() changes ownership of the file specified by `fd` file descriptor.

### 参数

`fd`
  Stream, Socket resource, or numeric file descriptor.
`uid`
  User ID. Is ignored when equal to -1.
`gid`
  Group ID. Is ignored when equal to -1.
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_fchown() returns request resource on success, 或者在失败时返回 `false`.

### 参见

- eio_fchmod() - Change file permissions

# eio_fdatasync

(PECL eio >= 0.0.1dev)

eio_fdatasync — Synchronize a file's in-core state with storage device

### 说明

function eio_fdatasync(
mixed `$fd`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_fdatasync() synchronizes a file's in-core state with storage device.

### 参数

`fd`
  Stream, Socket resource, or numeric file descriptor, e.g. returned by eio_open().
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_fdatasync() returns request resource on success, 或者在失败时返回 `false`.

# eio_fstat

(PECL eio >= 0.0.1dev)

eio_fstat — Get file status

### 说明

function eio_fstat(
mixed `$fd`,
int `$pri`,
callable `$callback`,
mixed `$data` = ?
): resource

eio_fstat() returns file status information in `result` argument of `callback`

### 参数

`fd`
  Stream, Socket resource, or numeric file descriptor.
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_fstat() returns request resource on success, 或者在失败时返回 `false`.

### 示例

示例 #1 eio_fstat() example

    <?php
    // Create temporary file
    $tmp_filename = dirname(__FILE__) ."/eio-file.tmp";
    touch($tmp_filename);

    /* Is called when eio_fstat() done */
    function my_res_cb($data, $result) {
     // Should output array with stat info
     var_dump($result);

     if ($data['fd']) {
      // Close temporary file
      eio_close($data['fd']);
      eio_event_loop();
     }
     // Remove temporary file
     @unlink($data['file']);
    }

    /* Is called when eio_open() done */
    function my_open_cb($data, $result) {
     // Prepare data for callback
     $d = array(
      'fd'  => $result,
      'file'=> $data
     );
     // Request stat info
     eio_fstat($result, EIO_PRI_DEFAULT, "my_res_cb", $d);
     // Process request(s)
     eio_event_loop();
    }

    // Open temporary file
    eio_open($tmp_filename, EIO_O_RDONLY, NULL, EIO_PRI_DEFAULT,
      "my_open_cb", $tmp_filename);
    eio_event_loop();
    ?>

以上示例的输出类似于：

    array(12) {
     ["st_dev"]=>
      int(2050)
      ["st_ino"]=>
      int(2489159)
      ["st_mode"]=>
      int(33188)
      ["st_nlink"]=>
      int(1)
      ["st_uid"]=>
      int(1000)
      ["st_gid"]=>
      int(100)
      ["st_rdev"]=>
      int(0)
      ["st_blksize"]=>
      int(4096)
      ["st_blocks"]=>
      int(0)
      ["st_atime"]=>
      int(1318239506)
      ["st_mtime"]=>
      int(1318239506)
      ["st_ctime"]=>
      int(1318239506)
    }

### 参见

- eio_lstat() - Get file status
- eio_stat() - Get file status

# eio_fstatvfs

(PECL eio >= 0.0.1dev)

eio_fstatvfs — Get file system statistics

### 说明

function eio_fstatvfs(
mixed `$fd`,
int `$pri`,
callable `$callback`,
mixed `$data` = ?
): resource

eio_fstatvfs() returns file system statistics in `result` of `callback`.

### 参数

`fd`
  A file descriptor of a file within the mounted file system.
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_fstatvfs() returns request resource on success, 或者在失败时返回 `false`.

### 参见

- eio_statvfs() - Get file system statistics

# eio_fsync

(PECL eio >= 0.0.1dev)

eio_fsync — Synchronize a file's in-core state with storage device

### 说明

function eio_fsync(
mixed `$fd`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

Synchronize a file's in-core state with storage device

### 参数

`fd`
  Stream, Socket resource, or numeric file descriptor.
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_fsync() returns request resource on success, 或者在失败时返回 `false`.

### 参见

- eio_sync() - Commit buffer cache to disk

# eio_ftruncate

(PECL eio >= 0.0.1dev)

eio_ftruncate — Truncate a file

### 说明

function eio_ftruncate(
mixed `$fd`,
int `$offset` = 0,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_ftruncate() causes a regular file referenced by `fd` file descriptor to be truncated to precisely `length` bytes.

### 参数

`fd`
  Stream, Socket resource, or numeric file descriptor.
`offset`
  Offset from beginning of the file
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_ftruncate() returns request resource on success, 或者在失败时返回 `false`.

### 参见

- eio_truncate() - Truncate a file

# eio_futime

(PECL eio >= 0.0.1dev)

eio_futime — Change file last access and modification times

### 说明

function eio_futime(
mixed `$fd`,
float `$atime`,
float `$mtime`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_futime() changes file last access and modification times.

### 参数

`fd`
  Stream, Socket resource, or numeric file descriptor, e.g. returned by eio_open()
`atime`
  Access time
`mtime`
  Modification time
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_futime() returns request resource on success, 或者在失败时返回 `false`.

### 参见

- eio_utime() - Change file last access and modification times

# eio_get_event_stream

(PECL eio >= 0.3.1b)

eio_get_event_stream — Get stream representing a variable used in internal communications with libeio

### 说明

function eio_get_event_stream(): mixed

eio_get_event_stream() acquires stream representing a variable used in internal communications with libeio. Could be used to bind with some event loop provided by other PECL extension, for example libevent.

### 参数

此函数没有参数。

### 返回值

eio_get_event_stream() returns stream on success; otherwise, `null`

### 示例

示例 #1 Using eio with libevent

    <?php
    function my_eio_poll($fd, $events, $arg) {
        /* Some libevent regulation might go here .. */
        if (eio_nreqs()) {
            eio_poll();
        }
        /* .. and here */
    }

    function my_res_cb($d, $r) {
        var_dump($r); var_dump($d);
    }

    $base = event_base_new();
    $event = event_new();

    $fd = eio_get_event_stream();
    var_dump($fd);

    eio_nop(EIO_PRI_DEFAULT, "my_res_cb", "nop data");
    eio_mkdir("/tmp/abc-eio-temp", 0750, EIO_PRI_DEFAULT, "my_res_cb", "mkdir data");
    /* some other eio_* calls here ... */

    // set event flags
    event_set($event, $fd, EV_READ /*| EV_PERSIST*/, "my_eio_poll", array($event, $base));

    // set event base
    event_base_set($event, $base);

    // enable event
    event_add($event);

    // start event loop
    event_base_loop($base);

    /* The same will be available via buffered libevent interface */
    ?>

以上示例的输出类似于：

    int(3)
    int(0)
    string(8) "nop data"
    int(0)
    string(10) "mkdir data"

# eio_get_last_error

(PECL eio >= 1.0.0)

eio_get_last_error — Returns string describing the last error associated with a request resource

### 说明

function eio_get_last_error(resource `$req`): string

eio_get_last_error() returns string describing the last error associated with `req`.

### 参数

`req`
  The request resource.

### 返回值

eio_get_last_error() returns string describing the last error associated with the request resource specified by `req`.

警告

此函数是实验性的。此函数的表象，包括名称及其相关文档都可能在未来的 PHP 发布版本中未通知就被修改。使用本函数风险自担。

# eio_grp

(PECL eio >= 0.0.1dev)

eio_grp — Creates a request group

### 说明

function eio_grp(callable `$callback`, string `$data` = NULL): resource

eio_grp() creates a request group.

### 参数

`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_grp() returns request group resource on success, 或者在失败时返回 `false`.

### 示例

示例 #1 eio_grp() example

    <?php
    $temp_filename = dirname(__FILE__) ."/eio-file.tmp";
    $fp = fopen($temp_filename, "w");
    fwrite($fp, "some data");
    fclose($fp);
    $my_file_fd = NULL;

    /* Is called when the group requests are done */
    function my_grp_done($data, $result) {
     // Remove the file, if it still exists
     @unlink($data);
    }

    /* Is called when the temporary file is opened */
    function my_grp_file_opened_callback($data, $result) {
     global $my_file_fd, $grp;

     $my_file_fd = $result;

     $req = eio_read($my_file_fd, 4, 0,
       EIO_PRI_DEFAULT, "my_grp_file_read_callback");
     eio_grp_add($grp, $req);
    }

    /* Is called when the file is read */
    function my_grp_file_read_callback($data, $result) {
     global $my_file_fd, $grp;

     var_dump($result);

     // Create request to close the file
     $req = eio_close($my_file_fd);

     // Add request to the group
     eio_grp_add($grp, $req);
    }

    // Create request group
    $grp = eio_grp("my_grp_done", $temp_filename);

    // Create request
    $req = eio_open($temp_filename, EIO_O_RDWR | EIO_O_APPEND , NULL,
      EIO_PRI_DEFAULT, "my_grp_file_opened_callback", NULL);

    // Add request to the group
    eio_grp_add($grp, $req);

    // Process requests
    eio_event_loop();
    ?>

以上示例的输出类似于：

    string(4) "some"

### 参见

- eio_grp_cancel() - Cancels a request group
- eio_grp_add() - Adds a request to the request group

# eio_grp_add

(PECL eio >= 0.0.1dev)

eio_grp_add — Adds a request to the request group

### 说明

function eio_grp_add(resource `$grp`, resource `$req`): void

eio_grp_add() adds a request to the request group.

### 参数

`grp`
  The request group resource returned by eio_grp()
`req`
  The request resource

### 返回值

没有返回值。

### 示例

示例 #1 Grouping requests

    <?php
    /*
     * Create a group request to open, read and close a file
     */

    // Create temporary file and write some bytes to it
    $temp_filename = dirname(__FILE__) ."/eio-file.tmp";
    $fp = fopen($temp_filename, "w");
    fwrite($fp, "some data");
    fclose($fp);

    /* Is called when the group requests are done */
    function my_grp_done($data, $result) {
     var_dump($result == 0);
     @unlink($data);
    }

    /* Is called when eio_open() done */
    function my_grp_file_opened_callback($data, $result) {
     global $grp;

     // $result should contain the file descriptor
     var_dump($result > 0);

     // Create eio_read() request and add it to the group
     // Pass file descriptor to the callback
     $req = eio_read($result, 4, 0,
       EIO_PRI_DEFAULT, "my_grp_file_read_callback", $result);
     eio_grp_add($grp, $req);
    }

    /* Is called when eio_read() done */
    function my_grp_file_read_callback($data, $result) {
     global $grp;

     // Read bytes
     var_dump($result);

     // Create eio_close() request and add it to the group
     // $data should contain the file descriptor
     $req = eio_close($data);
     eio_grp_add($grp, $req);
    }

    // Create request group
    $grp = eio_grp("my_grp_done", $temp_filename);
    var_dump($grp);

    // Create eio_open() request and add it to the group
    $req = eio_open($temp_filename, EIO_O_RDWR | EIO_O_APPEND , NULL,
      EIO_PRI_DEFAULT, "my_grp_file_opened_callback", NULL);
    eio_grp_add($grp, $req);

    // Process requests
    eio_event_loop();
    ?>

以上示例的输出类似于：

    resource(6) of type (EIO Group Descriptor)
    bool(true)
    string(4) "some"
    bool(true)

### 参见

- eio_grp() - Creates a request group
- eio_grp_cancel() - Cancels a request group
- eio_grp_limit() - Set group limit

# eio_grp_cancel

(PECL eio >= 0.0.1dev)

eio_grp_cancel — Cancels a request group

### 说明

function eio_grp_cancel(resource `$grp`): void

eio_grp_cancel() cancels a group request specified by `grp` request group resource.

### 参数

`grp`
  The request group resource returned by eio_grp().

### 返回值

没有返回值。

### 参见

- eio_grp() - Creates a request group
- eio_grp_add() - Adds a request to the request group

# eio_grp_limit

(PECL eio >= 0.0.1dev)

eio_grp_limit — Set group limit

### 说明

function eio_grp_limit(resource `$grp`, int `$limit`): void

Limit number of requests in the request group.

### 参数

`grp`
  The request group resource.
`limit`
  Number of requests in the group.

### 返回值

没有返回值。

### 参见

- eio_grp_add() - Adds a request to the request group

# eio_init

(PECL eio = 1.0.0)

eio_init — (Re-)initialize Eio

### 说明

function eio_init(): void

eio_init() (re-)initializes Eio. It allocates memory for internal structures of libeio and Eio itself. You may call eio_init() before using Eio functions. Otherwise it will be called internally first time you invoke an Eio function in a process.

> 注意: This function was removed in version 3.0.0RC1 of the eio extension for PHP version 8 and higher.

### 参数

此函数没有参数。

### 返回值

没有返回值。

# eio_link

(PECL eio >= 0.0.1dev)

eio_link — Create a hardlink for file

### 说明

function eio_link(
string `$path`,
string `$new_path`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_link() creates a hardlink `new_path` for a file specified by `path`.

### 参数

`path`
  Source file path.
`new_path`
  Target file path.
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

### 示例

示例 #1 eio_link() example

    <?php
    $filename = dirname(__FILE__)."/symlink.dat";
    touch($filename);
    $link = dirname(__FILE__)."/symlink.link";
    $hardlink = dirname(__FILE__)."/hardlink.link";

    function my_hardlink_cb($data, $result) {
        global $link, $filename;
        var_dump(file_exists($data) && !is_link($data));
        @unlink($data);

        eio_symlink($filename, $link, EIO_PRI_DEFAULT, "my_symlink_cb", $link);
    }

    function my_symlink_cb($data, $result) {
        global $link, $filename;
        var_dump(file_exists($data) && is_link($data));

        if (!eio_readlink($data, EIO_PRI_DEFAULT, "my_readlink_cb", NULL)) {
            @unlink($link);
            @unlink($filename);
        }
    }

    function my_readlink_cb($data, $result) {
        global $filename, $link;
        var_dump($result);

        @unlink($link);
        @unlink($filename);
    }

    eio_link($filename, $hardlink, EIO_PRI_DEFAULT, "my_hardlink_cb", $hardlink);
    eio_event_loop();
    ?>

以上示例的输出类似于：

    bool(true)
    bool(true)
    string(%d) "%ssymlink.dat"

### 参见

- eio_symlink() - Create a symbolic link

# eio_lstat

(PECL eio >= 0.0.1dev)

eio_lstat — Get file status

### 说明

function eio_lstat(
string `$path`,
int `$pri`,
callable `$callback`,
mixed `$data` = NULL
): resource

eio_lstat() returns file status information in `result` argument of `callback`

### 参数

`path`
  The file path
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_lstat() returns request resource on success or `false` on error.

### 示例

示例 #1 eio_lstat() example

    <?php
    $tmp_filename = dirname(__FILE__). "/eio-file.tmp";
    touch($tmp_filename);

    function my_res_cb($data, $result) {
        var_dump($data);
        var_dump($result);
    }

    function my_open_cb($data, $result) {
        eio_close($result);
        eio_event_loop();

        @unlink($data);
    }

    eio_lstat($tmp_filename, EIO_PRI_DEFAULT, "my_res_cb", "eio_lstat");
    eio_open($tmp_filename, EIO_O_RDONLY, NULL,
     EIO_PRI_DEFAULT, "my_open_cb", $tmp_filename);
    eio_event_loop();
    ?>

以上示例的输出类似于：

    string(9) "eio_lstat"
    array(12) {
     ["st_dev"]=>
      int(2050)
      ["st_ino"]=>
      int(2099197)
      ["st_mode"]=>
      int(33188)
      ["st_nlink"]=>
      int(1)
      ["st_uid"]=>
      int(1000)
      ["st_gid"]=>
      int(100)
      ["st_rdev"]=>
      int(0)
      ["st_blksize"]=>
      int(4096)
      ["st_blocks"]=>
      int(0)
      ["st_atime"]=>
      int(1318235777)
      ["st_mtime"]=>
      int(1318235777)
      ["st_ctime"]=>
      int(1318235777)
    }

### 参见

- eio_stat() - Get file status
- eio_fstat() - Get file status

# eio_mkdir

(PECL eio >= 0.0.1dev)

eio_mkdir — Create directory

### 说明

function eio_mkdir(
string `$path`,
int `$mode`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_mkdir() creates directory with specified access `mode`.

### 参数

`path`
  Path for the new directory.
`mode`
  Access mode, e.g. 0755
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_mkdir() returns request resource on success, 或者在失败时返回 `false`.

### 示例

示例 #1 eio_mkdir() example

    <?php
    $temp_dirname = "eio-temp-dir";

    /* Is called when eio_mkdir() finishes */
    function my_mkdir_callback($data, $result) {
     if ($result == 0 && is_dir($temp_dirname)
       && !is_readable($temp_dirname)
       && is_writable($temp_dirname)) {
      echo "eio_mkdir_ok";
     }

     // Remove directory
        if (file_exists($data))
            rmdir($temp_dirname);
    }

    // Create directory with access mode 0300
    eio_mkdir($temp_dirname, 0300, EIO_PRI_DEFAULT, "my_mkdir_callback", $temp_dirname);
    eio_event_loop();
    ?>

以上示例的输出类似于：

    eio_mkdir_ok

### 参见

- eio_rmdir() - Remove a directory

# eio_mknod

(PECL eio >= 0.0.1dev)

eio_mknod — Create a special or ordinary file

### 说明

function eio_mknod(
string `$path`,
int `$mode`,
int `$dev`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_mknod() creates ordinary or special(often) file.

警告

本函数还未编写文档，仅有参数列表。

### 参数

`path`
  Path for the new node(file).
`mode`
  Specifies both the permissions to use and the type of node to be created. It should be a combination (using bitwise OR) of one of the file types listed below and the permissions for the new node(e.g. 0640). Possible file types are: `EIO_S_IFREG`(regular file), `EIO_S_IFCHR`(character file), `EIO_S_IFBLK`(block special file), `EIO_S_IFIFO`(FIFO - named pipe) and `EIO_S_IFSOCK`(UNIX domain socket). To specify permissions EIO_S_I* constants could be used.
`dev`
  If the file type is `EIO_S_IFCHR` or `EIO_S_IFBLK` then dev specifies the major and minor numbers of the newly created device special file. Otherwise `dev` ignored. See mknod(2) man page for details.
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_mknod() returns request resource on success, 或者在失败时返回 `false`.

### 示例

示例 #1 eio_mknod() example

    <?php
    // FIFO name
    $temp_filename = "/tmp/eio-temp-fifo";

    /* Is called when eio_mknod() finishes */
    function my_mknod_callback($data, $result) {
        $s = stat($data);
        var_dump($s);

        if ($result == 0) {
            echo "eio_mknod_ok";
        }

        @unlink($data);
    }

    eio_mknod($temp_filename, EIO_S_IFIFO, 0,
        EIO_PRI_DEFAULT, "my_mknod_callback", $temp_filename);
    eio_event_loop();
    ?>

以上示例的输出类似于：

    array(26) {
      [0]=>
      int(17)
      [1]=>
      int(2337608)
      [2]=>
      int(4096)
      [3]=>
      int(1)
      [4]=>
      int(1000)
      [5]=>
      int(100)
      [6]=>
      int(0)
      [7]=>
      int(0)
      [8]=>
      int(1318241261)
      [9]=>
      int(1318241261)
      [10]=>
      int(1318241261)
      [11]=>
      int(4096)
      [12]=>
      int(0)
      ["dev"]=>
      int(17)
      ["ino"]=>
      int(2337608)
      ["mode"]=>
      int(4096)
      ["nlink"]=>
      int(1)
      ["uid"]=>
      int(1000)
      ["gid"]=>
      int(100)
      ["rdev"]=>
      int(0)
      ["size"]=>
      int(0)
      ["atime"]=>
      int(1318241261)
      ["mtime"]=>
      int(1318241261)
      ["ctime"]=>
      int(1318241261)
      ["blksize"]=>
      int(4096)
      ["blocks"]=>
      int(0)
    }
    eio_mknod_ok

### 参见

- eio_open() - Opens a file

# eio_nop

(PECL eio >= 0.0.1dev)

eio_nop — Does nothing, except go through the whole request cycle

### 说明

function eio_nop(int `$pri` = EIO_PRI_DEFAULT, callable `$callback` = NULL, mixed `$data` = NULL): resource

eio_nop() does nothing, except go through the whole request cycle. Could be useful in debugging.

### 参数

`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_nop() returns request resource on success, 或者在失败时返回 `false`.

### 参见

- eio_busy() - Artificially increase load. Could be useful in tests, benchmarking

# eio_npending

(PECL eio >= 0.0.1dev)

eio_npending — Returns number of finished, but unhandled requests

### 说明

function eio_npending(): int

eio_npending() returns number of finished, but unhandled requests

### 参数

此函数没有参数。

### 返回值

eio_npending() returns number of finished, but unhandled requests.

### 参见

- eio_nreqs() - Returns number of requests to be processed
- eio_nready() - Returns number of not-yet handled requests
- eio_nthreads() - Returns number of threads currently in use

# eio_nready

(PECL eio >= 0.0.1dev)

eio_nready — Returns number of not-yet handled requests

### 说明

function eio_nready(): int

### 参数

此函数没有参数。

### 返回值

eio_nready() returns number of not-yet handled requests

### 参见

- eio_nreqs() - Returns number of requests to be processed
- eio_nthreads() - Returns number of threads currently in use

# eio_nreqs

(PECL eio >= 0.0.1dev)

eio_nreqs — Returns number of requests to be processed

### 说明

function eio_nreqs(): int

eio_nreqs() could be called in a custom loop calling eio_poll().

### 参数

此函数没有参数。

### 返回值

eio_nreqs() returns number of requests to be processed.

### 示例

示例 #1 eio_nreqs() example

    <?php
    function res_cb($data, $result) {
        var_dump($data);
        var_dump($result);
    }

    eio_nop(EIO_PRI_DEFAULT, "res_cb", "1");
    eio_nop(EIO_PRI_DEFAULT, "res_cb", "2");
    eio_nop(EIO_PRI_DEFAULT, "res_cb", "3");

    while (eio_nreqs()) {
        eio_poll();
    }
    ?>

以上示例的输出类似于：

    string(1) "1"
    int(0)
    string(1) "3"
    int(0)
    string(1) "2"
    int(0)

### 参见

- eio_poll() - Can be called whenever there are pending requests that need finishing
- eio_nready() - Returns number of not-yet handled requests

# eio_nthreads

(PECL eio >= 0.0.1dev)

eio_nthreads — Returns number of threads currently in use

### 说明

function eio_nthreads(): int

### 参数

此函数没有参数。

### 返回值

eio_nthreads() returns number of threads currently in use.

### 参见

- eio_npending() - Returns number of finished, but unhandled requests
- eio_nready() - Returns number of not-yet handled requests
- eio_nreqs() - Returns number of requests to be processed
- eio_set_max_idle() - Set maximum number of idle threads
- eio_set_max_parallel() - Set maximum parallel threads
- eio_set_min_parallel() - Set minimum parallel thread number

# eio_open

(PECL eio >= 0.0.1dev)

eio_open — Opens a file

### 说明

function eio_open(
string `$path`,
int `$flags`,
int `$mode`,
int `$pri`,
callable `$callback`,
mixed `$data` = NULL
): resource

eio_open() opens file specified by `path` in access mode `mode` with the given `flags`.

### 参数

`path`

  Path of the file to be opened.

  警告

  In some SAPIs(e.g. PHP-FPM) it could fail, if you don't specify full path.

`flags`
  One of EIO_O_* constants, or their combinations. EIO_O_* constants have the same meaning, as their corresponding O_* counterparts defined in `fnctl.h` C header file. Default is `EIO_O_RDWR`.
`mode`
  One of EIO_S_I* constants, or their combination (via bitwise OR operator). The constants have the same meaning as their S_I* counterparts defined in » sys/stat.h C header file. Required, if a file is created. Otherwise ignored.
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_open() returns file descriptor in `result` argument of `callback` on success; otherwise, `result` is equal to `-1`.

### 示例

示例 #1 eio_open() example

    <?php
    $temp_filename = "eio-temp-file.tmp";

    /* Is called when eio_close() finishes */
    function my_close_cb($data, $result) {
     // Zero indicates success
        var_dump($result == 0);
     @unlink($data);
    }

    /* Is called when eio_open() finishes */
    function my_file_opened_callback($data, $result) {
     // $result should contain the file descriptor
        var_dump($result > 0);

        if ($result > 0) {
      // Close the file
            eio_close($result, EIO_PRI_DEFAULT, "my_close_cb", $data);
            eio_event_loop();
        }
    }

    // Create new file for reading and writing
    // Deny group and others to do anything with that file
    eio_open($temp_filename, EIO_O_CREAT | EIO_O_RDWR, EIO_S_IRUSR | EIO_S_IWUSR,
      EIO_PRI_DEFAULT, "my_file_opened_callback", $temp_filename);
    eio_event_loop();
    ?>

以上示例的输出类似于：

    bool(true)
    bool(true)

### 参见

- eio_mknod() - Create a special or ordinary file

# eio_poll

(PECL eio >= 0.0.1dev)

eio_poll — Can be called whenever there are pending requests that need finishing

### 说明

function eio_poll(): int

eio_poll() can be used to implement special event loop. For this eio_nreqs() could be used to test if there are unprocessed requests.

> 注意: Applicable only when implementing userspace event loop.

### 参数

此函数没有参数。

### 返回值

If any request invocation returns a non-zero value, returns that value. Otherwise, it returns `0`.

### 示例

示例 #1 eio_poll() example

    <?php
    function res_cb($data, $result) {
        var_dump($data);
        var_dump($result);
    }

    eio_nop(EIO_PRI_DEFAULT, "res_cb", "1");
    eio_nop(EIO_PRI_DEFAULT, "res_cb", "2");
    eio_nop(EIO_PRI_DEFAULT, "res_cb", "3");

    while (eio_nreqs()) {
        // Some specific IPC or so
        eio_poll();
    }
    ?>

以上示例的输出类似于：

    string(1) "1"
    int(0)
    string(1) "3"
    int(0)
    string(1) "2"
    int(0)

### 参见

- eio_nreqs() - Returns number of requests to be processed

# eio_read

(PECL eio >= 0.0.1dev)

eio_read — Read from a file descriptor at given offset

### 说明

function eio_read(
mixed `$fd`,
int `$length`,
int `$offset`,
int `$pri`,
callable `$callback`,
mixed `$data` = NULL
): resource

eio_read() reads up to `length` bytes from `fd` file descriptor at `offset`. The read bytes are stored in `result` argument of `callback`.

### 参数

`fd`
  Stream, Socket resource, or numeric file descriptor
`length`
  Maximum number of bytes to read.
`offset`
  Offset within the file.
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_read() stores read bytes in `result` argument of `callback` function.

### 示例

示例 #1 eio_read() example

    <?php
    // Open a temporary file and write some bytes there
    $temp_filename = "eio-temp-file.tmp";
    $fp = fopen($temp_filename, "w");
    fwrite($fp, "1234567890");
    fclose($fp);

    /* Is called when eio_read() is done */
    function my_read_cb($data, $result) {
        global $temp_filename;

     // Output read bytes
        var_dump($result);

     // Close file
        eio_close($data);
        eio_event_loop();

     // Remove temporary file
        @unlink($temp_filename);
    }

    /* Is called when eio_open() is done */
    function my_file_opened_callback($data, $result) {
     // $result should contain the file descriptor
        if ($result > 0) {
      // Read 5 bytes starting from third
            eio_read($result, 5, 2, EIO_PRI_DEFAULT, "my_read_cb", $result);
            eio_event_loop();
        } else {
      // eio_open() failed
            unlink($data);
        }
    }

    // Open the file for reading and writing
    eio_open($temp_filename, EIO_O_RDWR, NULL,
        EIO_PRI_DEFAULT, "my_file_opened_callback", $temp_filename);
    eio_event_loop();
    ?>

以上示例的输出类似于：

    string(5) "34567"

### 参见

- eio_open() - Opens a file
- eio_write() - Write to file
- eio_close() - Close file
- eio_event_loop() - Polls libeio until all requests proceeded

# eio_readahead

(PECL eio >= 0.0.1dev)

eio_readahead — Perform file readahead into page cache

### 说明

function eio_readahead(
mixed `$fd`,
int `$offset`,
int `$length`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_readahead() populates the page cache with data from a file so that subsequent reads from that file will not block on disk I/O. See `READAHEAD(2)` man page for details.

### 参数

`fd`
  Stream, Socket resource, or numeric file descriptor
`offset`
  Starting point from which data is to be read.
`length`
  Number of bytes to be read.
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_readahead() returns request resource on success, 或者在失败时返回 `false`.

# eio_readdir

(PECL eio >= 0.0.1dev)

eio_readdir — Reads through a whole directory

### 说明

function eio_readdir(
string `$path`,
int `$flags`,
int `$pri`,
callable `$callback`,
string `$data` = NULL
): resource

Reads through a whole directory(via the `opendir`, `readdir` and `closedir` system calls) and returns either the names or an array in `result` argument of `callback` function, depending on the `flags` argument.

### 参数

`path`
  Directory path.
`flags`
  Combination of EIO_READDIR_* constants.
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_readdir() returns request resource on success, 或者在失败时返回 `false`. Sets `result` argument of `callback` function according to `flags`:

`EIO_READDIR_DENTS` (int)
  eio_readdir() flag. If specified, the result argument of the callback becomes an array with the following keys: `'names'` - array of directory names `'dents'` - array of `struct eio_dirent`-like arrays having the following keys each: `'name'` - the directory name; `'type'` - one of EIO_DT_* constants; `'inode'` - the inode number, if available, otherwise unspecified;
`EIO_READDIR_DIRS_FIRST` (int)
  When this flag is specified, the names will be returned in an order where likely directories come first, in optimal stat order.
`EIO_READDIR_STAT_ORDER` (int)
  When this flag is specified, then the names will be returned in an order suitable for `stat`'ing each one. When planning to stat() all files in the given directory, the returned order will likely be fastest.
`EIO_READDIR_FOUND_UNKNOWN` (int)

Node types:

`EIO_DT_UNKNOWN` (int)
  Unknown node type(very common). Further stat() needed.
`EIO_DT_FIFO` (int)
  FIFO node type
`EIO_DT_CHR` (int)
  Node type
`EIO_DT_MPC` (int)
  Multiplexed char device (v7+coherent) node type
`EIO_DT_DIR` (int)
  Directory node type
`EIO_DT_NAM` (int)
  Xenix special named file node type
`EIO_DT_BLK` (int)
  Node type
`EIO_DT_MPB` (int)
  Multiplexed block device (v7+coherent)
`EIO_DT_REG` (int)
  Node type
`EIO_DT_NWK` (int)
`EIO_DT_CMP` (int)
  HP-UX network special node type
`EIO_DT_LNK` (int)
  Link node type
`EIO_DT_SOCK` (int)
  Socket node type
`EIO_DT_DOOR` (int)
  Solaris door node type
`EIO_DT_WHT` (int)
  Node type
`EIO_DT_MAX` (int)
  Highest node type value

### 示例

示例 #1 eio_readdir() example

    <?php
    /* Is called when eio_readdir() finishes */
    function my_readdir_callback($data, $result) {
        echo __FUNCTION__, " called\n";
        echo "data: "; var_dump($data);
        echo "result: "; var_dump($result);
        echo "\n";
    }

    eio_readdir("/var/spool/news", EIO_READDIR_STAT_ORDER | EIO_READDIR_DIRS_FIRST,
      EIO_PRI_DEFAULT, "my_readdir_callback");
    eio_event_loop();
    ?>

以上示例的输出类似于：

    my_readdir_callback called
    data: NULL
    result: array(2) {
     ["names"]=>
      array(7) {
       [0]=>
        string(7) "archive"
        [1]=>
        string(8) "articles"
        [2]=>
        string(8) "incoming"
        [3]=>
        string(7) "innfeed"
        [4]=>
        string(8) "outgoing"
        [5]=>
        string(8) "overview"
        [6]=>
        string(3) "tmp"
      }
     ["dents"]=>
      array(7) {
       [0]=>
        array(3)
        {
         ["name"]=>
          string(7)
          "archive"
          ["type"]=>
          int(4)
          ["inode"]=>
          int(393265)
        }
       [1]=>
        array(3)
        {
         ["name"]=>
          string(8)
          "articles"
          ["type"]=>
          int(4)
          ["inode"]=>
          int(393266)
        }
       [2]=>
        array(3)
        {
         ["name"]=>
          string(8)
          "incoming"
          ["type"]=>
          int(4)
          ["inode"]=>
          int(393267)
        }
       [3]=>
        array(3)
        {
         ["name"]=>
          string(7)
          "innfeed"
          ["type"]=>
          int(4)
          ["inode"]=>
          int(393269)
        }
       [4]=>
        array(3)
        {
         ["name"]=>
          string(8)
          "outgoing"
          ["type"]=>
          int(4)
          ["inode"]=>
          int(393270)
        }
       [5]=>
        array(3)
        {
         ["name"]=>
          string(8)
          "overview"
          ["type"]=>
          int(4)
          ["inode"]=>
          int(393271)
        }
       [6]=>
        array(3)
        {
         ["name"]=>
          string(3)
          "tmp"
          ["type"]=>
          int(4)
          ["inode"]=>
          int(393272)
        }
      }
    }

# eio_readlink

(PECL eio >= 0.0.1dev)

eio_readlink — Read value of a symbolic link

### 说明

function eio_readlink(
string `$path`,
int `$pri`,
callable `$callback`,
mixed `$data` = NULL
): resource

### 参数

`path`
  Source symbolic link path
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_readlink() returns request resource on success, 或者在失败时返回 `false`.

### 示例

示例 #1 eio_readlink() example

    <?php
    $filename = dirname(__FILE__)."/symlink.dat";
    touch($filename);
    $link = dirname(__FILE__)."/symlink.link";
    $hardlink = dirname(__FILE__)."/hardlink.link";

    function my_hardlink_cb($data, $result) {
        global $link, $filename;
        var_dump(file_exists($data) && !is_link($data));
        @unlink($data);

        eio_symlink($filename, $link, EIO_PRI_DEFAULT, "my_symlink_cb", $link);
    }

    function my_symlink_cb($data, $result) {
        global $link, $filename;
        var_dump(file_exists($data) && is_link($data));

        if (!eio_readlink($data, EIO_PRI_DEFAULT, "my_readlink_cb", NULL)) {
            @unlink($link);
            @unlink($filename);
        }
    }

    function my_readlink_cb($data, $result) {
        global $filename, $link;
        var_dump($result);

        @unlink($link);
        @unlink($filename);
    }

    eio_link($filename, $hardlink, EIO_PRI_DEFAULT, "my_hardlink_cb", $hardlink);
    eio_event_loop();
    ?>

以上示例的输出类似于：

    bool(true)
    bool(true)
    string(16) "/tmp/symlink.dat"

### 参见

- eio_symlink() - Create a symbolic link

# eio_realpath

(PECL eio >= 0.0.1dev)

eio_realpath — Get the canonicalized absolute pathname

### 说明

function eio_realpath(
string `$path`,
int `$pri`,
callable `$callback`,
string `$data` = NULL
): resource

eio_realpath() returns the canonicalized absolute pathname in `result` argument of `callback` function.

### 参数

`path`
  Short pathname
`pri`
`callback`
`data`

### 返回值

### 示例

示例 #1 eio_realpath() example

    <?php
    var_dump(getcwd());

    function my_realpath_callback($data, $result) {
        var_dump($result);
    }

    eio_realpath("../", EIO_PRI_DEFAULT, "my_realpath_callback");
    eio_event_loop();
    ?>

以上示例的输出类似于：

    string(12) "/home/ruslan"
    string(5) "/home"

# eio_rename

(PECL eio >= 0.0.1dev)

eio_rename — Change the name or location of a file

### 说明

function eio_rename(
string `$path`,
string `$new_path`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_rename() renames or moves a file to new location.

### 参数

`path`
  Source path
`new_path`
  Target path
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_rename() returns request resource on success, 或者在失败时返回 `false`.

### 示例

示例 #1 eio_rename() example

    <?php
    $filename = dirname(__FILE__)."/eio-temp-file.dat";
    touch($filename);
    $new_filename = dirname(__FILE__)."/eio-temp-file-new.dat";

    function my_rename_cb($data, $result) {
        global $filename, $new_filename;

        if ($result == 0 && !file_exists($filename) && file_exists($new_filename)) {
            @unlink($new_filename);
            echo "eio_rename_ok";
        } else {
            @unlink($filename);
        }
    }

    eio_rename($filename, $new_filename, EIO_PRI_DEFAULT, "my_rename_cb", $filename);
    eio_event_loop();
    ?>

以上示例的输出类似于：

    eio_rename_ok

# eio_rmdir

(PECL eio >= 0.0.1dev)

eio_rmdir — Remove a directory

### 说明

function eio_rmdir(
string `$path`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_rmdir() removes a directory.

### 参数

`path`
  Directory path
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_rmdir() returns request resource on success, 或者在失败时返回 `false`.

### 示例

示例 #1 eio_rmdir() example

    <?php
    $temp_dirname = "eio-temp-dir";
    mkdir($temp_dirname);

    function my_rmdir_callback($data, $result) {
        if ($result == 0 && !file_exists($data)) {
            echo "eio_rmdir_ok";
        } else if (file_exists($data)) {
            rmdir($data);
        }
    }

    eio_rmdir($temp_dirname, EIO_PRI_DEFAULT, "my_rmdir_callback", $temp_dirname);
    eio_event_loop();
    ?>

以上示例的输出类似于：

    eio_rmdir_ok

### 参见

- eio_mkdir() - Create directory

# eio_seek

(PECL eio >= 0.5.0b)

eio_seek — Seek to a position

### 说明

function eio_seek(
mixed `$fd`,
int `$offset`,
int `$whence`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_seek() repositions the offset of the open file associated with stream, Socket instance, or file descriptor specified by `fd` to the argument `offset` according to the directive `whence`.

### 参数

`fd`
  Stream, Socket instance, or numeric file descriptor.
`offset`
  Starting point from which data is to be read.
`whence`

  `whence` values are:

  - `EIO_SEEK_SET` - Set position equal to `offset` bytes.
  - `EIO_SEEK_CUR` - Set position to current location plus `offset`.
  - `EIO_SEEK_END` - Set position to end-of-file plus `offset`.
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_seek() returns request resource on success, 或者在失败时返回 `false`.

# eio_sendfile

(PECL eio >= 0.0.1dev)

eio_sendfile — Transfer data between file descriptors

### 说明

function eio_sendfile(
mixed `$out_fd`,
mixed `$in_fd`,
int `$offset`,
int `$length`,
int `$pri` = ?,
callable `$callback` = ?,
string `$data` = ?
): resource

eio_sendfile() copies data between one file descriptor and another. See `SENDFILE(2)` man page for details.

### 参数

`out_fd`
  Output stream, Socket resource, or file descriptor. Should be opened for writing.
`in_fd`
  Input stream, Socket resource, or file descriptor. Should be opened for reading.
`offset`
  Offset within the source file.
`length`
  Number of bytes to copy.
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_sendfile() returns request resource on success, 或者在失败时返回 `false`.

# eio_set_max_idle

(PECL eio >= 0.0.1dev)

eio_set_max_idle — Set maximum number of idle threads

### 说明

function eio_set_max_idle(int `$nthreads`): void

### 参数

`nthreads`
  Number of idle threads.

### 返回值

没有返回值。

### 参见

- eio_nthreads() - Returns number of threads currently in use
- eio_set_min_parallel() - Set minimum parallel thread number
- eio_set_max_parallel() - Set maximum parallel threads

# eio_set_max_parallel

(PECL eio >= 0.0.1dev)

eio_set_max_parallel — Set maximum parallel threads

### 说明

function eio_set_max_parallel(int `$nthreads`): void

### 参数

`nthreads`
  Number of parallel threads

### 返回值

没有返回值。

### 参见

- eio_nthreads() - Returns number of threads currently in use
- eio_set_max_idle() - Set maximum number of idle threads
- eio_set_min_parallel() - Set minimum parallel thread number

# eio_set_max_poll_reqs

(PECL eio >= 0.0.1dev)

eio_set_max_poll_reqs — Set maximum number of requests processed in a poll

### 说明

function eio_set_max_poll_reqs(int `$nreqs`): void

### 参数

`nreqs`
  Number of requests

### 返回值

没有返回值。

# eio_set_max_poll_time

(PECL eio >= 0.0.1dev)

eio_set_max_poll_time — Set maximum poll time

### 说明

function eio_set_max_poll_time(float `$nseconds`): void

Polling stops, if poll took longer than `nseconds` seconds.

### 参数

`nseconds`
  Number of seconds

### 返回值

没有返回值。

# eio_set_min_parallel

(PECL eio >= 0.0.1dev)

eio_set_min_parallel — Set minimum parallel thread number

### 说明

function eio_set_min_parallel(string `$nthreads`): void

### 参数

`nthreads`
  Number of parallel threads.

### 返回值

没有返回值。

### 参见

- eio_nthreads() - Returns number of threads currently in use
- eio_set_max_idle() - Set maximum number of idle threads
- eio_set_max_parallel() - Set maximum parallel threads

# eio_stat

(PECL eio >= 0.0.1dev)

eio_stat — Get file status

### 说明

function eio_stat(
string `$path`,
int `$pri`,
callable `$callback`,
mixed `$data` = NULL
): resource

eio_stat() returns file status information in `result` argument of `callback`

### 参数

`path`
  The file path
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_stat() returns request resource on success or `false` on error. On success assigns `result` argument of `callback` to an array.

### 示例

示例 #1 eio_stat() example

    <?php
    $tmp_filename = "eio-file.tmp";
    touch($tmp_filename);

    function my_res_cb($data, $result) {
        var_dump($data);
        var_dump($result);
    }

    function my_open_cb($data, $result) {
        eio_close($result);
        eio_event_loop();

        @unlink($data);
    }

    eio_stat($tmp_filename, EIO_PRI_DEFAULT, "my_res_cb", "eio_stat");
    eio_open($tmp_filename, EIO_O_RDONLY, NULL,
     EIO_PRI_DEFAULT, "my_open_cb", $tmp_filename);
    eio_event_loop();
    ?>

以上示例的输出类似于：

    string(8) "eio_stat"
    array(12) {
      ["st_dev"]=>
      int(2050)
      ["st_ino"]=>
      int(2489173)
      ["st_mode"]=>
      int(33188)
      ["st_nlink"]=>
      int(1)
      ["st_uid"]=>
      int(1000)
      ["st_gid"]=>
      int(100)
      ["st_rdev"]=>
      int(0)
      ["st_blksize"]=>
      int(4096)
      ["st_blocks"]=>
      int(0)
      ["st_atime"]=>
      int(1318250380)
      ["st_mtime"]=>
      int(1318250380)
      ["st_ctime"]=>
      int(1318250380)
    }

### 参见

- eio_lstat() - Get file status
- eio_fstat() - Get file status

# eio_statvfs

(PECL eio >= 0.0.1dev)

eio_statvfs — Get file system statistics

### 说明

function eio_statvfs(
string `$path`,
int `$pri`,
callable `$callback`,
mixed `$data` = ?
): resource

eio_statvfs() returns file system statistics information in `result` argument of `callback`

### 参数

`path`
  Pathname of any file within the mounted file system
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_statvfs() returns request resource on success, 或者在失败时返回 `false`. On success assigns `result` argument of `callback` to an array.

### 示例

示例 #1 eio_statvfs() example

    <?php
    $tmp_filename = '/tmp/eio-file.tmp';
    touch($tmp_filename);

    function my_statvfs_callback($data, $result) {
        var_dump($data);
        var_dump($result);

     @unlink($data);
    }

    eio_statvfs($tmp_filename, EIO_PRI_DEFAULT, "my_statvfs_callback", $tmp_filename);
    eio_event_loop();
    ?>

以上示例的输出类似于：

    string(17) "/tmp/eio-file.tmp"
    array(11) {
      ["f_bsize"]=>
      int(4096)
      ["f_frsize"]=>
      int(4096)
      ["f_blocks"]=>
      int(262144)
      ["f_bfree"]=>
      int(262111)
      ["f_bavail"]=>
      int(262111)
      ["f_files"]=>
      int(1540815)
      ["f_ffree"]=>
      int(1540743)
      ["f_favail"]=>
      int(1540743)
      ["f_fsid"]=>
      int(0)
      ["f_flag"]=>
      int(4102)
      ["f_namemax"]=>
      int(255)
    }

# eio_symlink

(PECL eio >= 0.0.1dev)

eio_symlink — Create a symbolic link

### 说明

function eio_symlink(
string `$path`,
string `$new_path`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_symlink() creates a symbolic link `new_path` to `path`.

### 参数

`path`
  Source path
`new_path`
  Target path
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_symlink() returns request resource on success, 或者在失败时返回 `false`.

### 示例

示例 #1 eio_symlink() example

    <?php
    $filename = dirname(__FILE__)."/symlink.dat";
    touch($filename);
    $link = dirname(__FILE__)."/symlink.link";

    function my_symlink_cb($data, $result) {
        global $link, $filename;
        var_dump(file_exists($data) && is_link($data));

        if (!eio_readlink($data, EIO_PRI_DEFAULT, "my_readlink_cb", NULL)) {
            @unlink($link);
            @unlink($filename);
        }
    }

    function my_readlink_cb($data, $result) {
        global $filename, $link;
        var_dump($result);

        @unlink($link);
        @unlink($filename);
    }

    eio_symlink($filename, $link, EIO_PRI_DEFAULT, "my_symlink_cb", $link);
    eio_event_loop();
    ?>

以上示例的输出类似于：

    bool(true)
    string(16) "/tmp/symlink.dat"

### 参见

- eio_link() - Create a hardlink for file

# eio_sync

(PECL eio >= 0.0.1dev)

eio_sync — Commit buffer cache to disk

### 说明

function eio_sync(int `$pri` = EIO_PRI_DEFAULT, callable `$callback` = NULL, mixed `$data` = NULL): resource

### 参数

此函数没有参数。

### 返回值

eio_sync() returns request resource on success, 或者在失败时返回 `false`.

# eio_sync_file_range

(PECL eio >= 0.0.1dev)

eio_sync_file_range — Sync a file segment with disk

### 说明

function eio_sync_file_range(
mixed `$fd`,
int `$offset`,
int `$nbytes`,
int `$flags`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_sync_file_range() permits fine control when synchronizing the open file referred to by the file descriptor `fd` with disk.

### 参数

`fd`
  File descriptor
`offset`
  The starting byte of the file range to be synchronized
`nbytes`
  Specifies the length of the range to be synchronized, in bytes. If `nbytes` is zero, then all bytes from `offset` through to the end of file are synchronized.
`flags`
  A bit-mask. Can include any of the following values: `EIO_SYNC_FILE_RANGE_WAIT_BEFORE`, `EIO_SYNC_FILE_RANGE_WRITE`, `EIO_SYNC_FILE_RANGE_WAIT_AFTER`. These flags have the same meaning as their SYNC_FILE_RANGE_* counterparts(see `SYNC_FILE_RANGE(2)` man page).
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_sync_file_range() returns request resource on success, 或者在失败时返回 `false`.

# eio_syncfs

(PECL eio >= 0.0.1dev)

eio_syncfs — Calls Linux' syncfs syscall, if available

### 说明

function eio_syncfs(
mixed `$fd`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

### 参数

`fd`
  File descriptor
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_syncfs() returns request resource on success, 或者在失败时返回 `false`.

# eio_truncate

(PECL eio >= 0.0.1dev)

eio_truncate — Truncate a file

### 说明

function eio_truncate(
string `$path`,
int `$offset` = 0,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_truncate() causes the regular file named by `path` to be truncated to a size of precisely `length` bytes

### 参数

`path`
  File path
`offset`
  Offset from beginning of the file.
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_truncate() returns request resource on success, 或者在失败时返回 `false`.

### 参见

- eio_ftruncate() - Truncate a file

# eio_unlink

(PECL eio >= 0.0.1dev)

eio_unlink — Delete a name and possibly the file it refers to

### 说明

function eio_unlink(
string `$path`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_unlink() deletes a name from the file system.

### 参数

`path`
  Path to file
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_unlink() returns request resource on success, 或者在失败时返回 `false`.

# eio_utime

(PECL eio >= 0.0.1dev)

eio_utime — Change file last access and modification times

### 说明

function eio_utime(
string `$path`,
float `$atime`,
float `$mtime`,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

### 参数

`path`
  Path to the file.
`atime`
  Access time
`mtime`
  Modification time
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_utime() returns request resource on success, 或者在失败时返回 `false`.

### 参见

- eio_futime() - Change file last access and modification times

# eio_write

(PECL eio >= 0.0.1dev)

eio_write — Write to file

### 说明

function eio_write(
mixed `$fd`,
string `$str`,
int `$length` = 0,
int `$offset` = 0,
int `$pri` = EIO_PRI_DEFAULT,
callable `$callback` = NULL,
mixed `$data` = NULL
): resource

eio_write() writes up to `length` bytes from `str` at `offset` offset from the beginning of the file.

### 参数

`fd`
  Stream, Socket resource, or numeric file descriptor, e.g. returned by eio_open()
`str`
  Source string
`length`
  Maximum number of bytes to write.
`offset`
  Offset from the beginning of file.
`pri`
  请求的优先级：`EIO_PRI_DEFAULT`，`EIO_PRI_MIN`，`EIO_PRI_MAX` 或 `null`。如果是 `null`，`pri` 将设为 `EIO_PRI_DEFAULT`。
`callback`

  `callback` 函数在请求完成时被调用。其应匹配一下原型：

      void callback(mixed $data, int $result[, resource $req]);

  `data`
    传递给请求的用户数据。
  `result`
    针对请求的结果的值。通常是相应的系统调用返回的值。
  `req`
    可选的请求资源，可被 eio_get_last_error() 之类的函数使用。
`data`
  Arbitrary variable passed to `callback`.

### 返回值

eio_write() returns request resource on success, 或者在失败时返回 `false`.

### 参见

- eio_open() - Opens a file

## 目录

- eio_busy — Artificially increase load. Could be useful in tests, benchmarking
- eio_cancel — Cancels a request
- eio_chmod — Change file/directory permissions
- eio_chown — Change file/directory ownership
- eio_close — Close file
- eio_custom — Execute custom request like any other eio_* call
- eio_dup2 — Duplicate a file descriptor
- eio_event_loop — Polls libeio until all requests proceeded
- eio_fallocate — Allows the caller to directly manipulate the allocated disk space for a file
- eio_fchmod — Change file permissions
- eio_fchown — Change file ownership
- eio_fdatasync — Synchronize a file's in-core state with storage device
- eio_fstat — Get file status
- eio_fstatvfs — Get file system statistics
- eio_fsync — Synchronize a file's in-core state with storage device
- eio_ftruncate — Truncate a file
- eio_futime — Change file last access and modification times
- eio_get_event_stream — Get stream representing a variable used in internal communications with libeio
- eio_get_last_error — Returns string describing the last error associated with a request resource
- eio_grp — Creates a request group
- eio_grp_add — Adds a request to the request group
- eio_grp_cancel — Cancels a request group
- eio_grp_limit — Set group limit
- eio_init — (Re-)initialize Eio
- eio_link — Create a hardlink for file
- eio_lstat — Get file status
- eio_mkdir — Create directory
- eio_mknod — Create a special or ordinary file
- eio_nop — Does nothing, except go through the whole request cycle
- eio_npending — Returns number of finished, but unhandled requests
- eio_nready — Returns number of not-yet handled requests
- eio_nreqs — Returns number of requests to be processed
- eio_nthreads — Returns number of threads currently in use
- eio_open — Opens a file
- eio_poll — Can be called whenever there are pending requests that need finishing
- eio_read — Read from a file descriptor at given offset
- eio_readahead — Perform file readahead into page cache
- eio_readdir — Reads through a whole directory
- eio_readlink — Read value of a symbolic link
- eio_realpath — Get the canonicalized absolute pathname
- eio_rename — Change the name or location of a file
- eio_rmdir — Remove a directory
- eio_seek — Seek to a position
- eio_sendfile — Transfer data between file descriptors
- eio_set_max_idle — Set maximum number of idle threads
- eio_set_max_parallel — Set maximum parallel threads
- eio_set_max_poll_reqs — Set maximum number of requests processed in a poll
- eio_set_max_poll_time — Set maximum poll time
- eio_set_min_parallel — Set minimum parallel thread number
- eio_stat — Get file status
- eio_statvfs — Get file system statistics
- eio_symlink — Create a symbolic link
- eio_sync — Commit buffer cache to disk
- eio_sync_file_range — Sync a file segment with disk
- eio_syncfs — Calls Linux' syncfs syscall, if available
- eio_truncate — Truncate a file
- eio_unlink — Delete a name and possibly the file it refers to
- eio_utime — Change file last access and modification times
- eio_write — Write to file

- 安装/配置
  - 需求
  - 安装
  - 资源类型
- 预定义常量
- 示例
- Eio 函数
  - eio_busy — Artificially increase load. Could be useful in tests, benchmarking
  - eio_cancel — Cancels a request
  - eio_chmod — Change file/directory permissions
  - eio_chown — Change file/directory ownership
  - eio_close — Close file
  - eio_custom — Execute custom request like any other eio_* call
  - eio_dup2 — Duplicate a file descriptor
  - eio_event_loop — Polls libeio until all requests proceeded
  - eio_fallocate — Allows the caller to directly manipulate the allocated disk space for a file
  - eio_fchmod — Change file permissions
  - eio_fchown — Change file ownership
  - eio_fdatasync — Synchronize a file's in-core state with storage device
  - eio_fstat — Get file status
  - eio_fstatvfs — Get file system statistics
  - eio_fsync — Synchronize a file's in-core state with storage device
  - eio_ftruncate — Truncate a file
  - eio_futime — Change file last access and modification times
  - eio_get_event_stream — Get stream representing a variable used in internal communications with libeio
  - eio_get_last_error — Returns string describing the last error associated with a request resource
  - eio_grp — Creates a request group
  - eio_grp_add — Adds a request to the request group
  - eio_grp_cancel — Cancels a request group
  - eio_grp_limit — Set group limit
  - eio_init — (Re-)initialize Eio
  - eio_link — Create a hardlink for file
  - eio_lstat — Get file status
  - eio_mkdir — Create directory
  - eio_mknod — Create a special or ordinary file
  - eio_nop — Does nothing, except go through the whole request cycle
  - eio_npending — Returns number of finished, but unhandled requests
  - eio_nready — Returns number of not-yet handled requests
  - eio_nreqs — Returns number of requests to be processed
  - eio_nthreads — Returns number of threads currently in use
  - eio_open — Opens a file
  - eio_poll — Can be called whenever there are pending requests that need finishing
  - eio_read — Read from a file descriptor at given offset
  - eio_readahead — Perform file readahead into page cache
  - eio_readdir — Reads through a whole directory
  - eio_readlink — Read value of a symbolic link
  - eio_realpath — Get the canonicalized absolute pathname
  - eio_rename — Change the name or location of a file
  - eio_rmdir — Remove a directory
  - eio_seek — Seek to a position
  - eio_sendfile — Transfer data between file descriptors
  - eio_set_max_idle — Set maximum number of idle threads
  - eio_set_max_parallel — Set maximum parallel threads
  - eio_set_max_poll_reqs — Set maximum number of requests processed in a poll
  - eio_set_max_poll_time — Set maximum poll time
  - eio_set_min_parallel — Set minimum parallel thread number
  - eio_stat — Get file status
  - eio_statvfs — Get file system statistics
  - eio_symlink — Create a symbolic link
  - eio_sync — Commit buffer cache to disk
  - eio_sync_file_range — Sync a file segment with disk
  - eio_syncfs — Calls Linux' syncfs syscall, if available
  - eio_truncate — Truncate a file
  - eio_unlink — Delete a name and possibly the file it refers to
  - eio_utime — Change file last access and modification times
  - eio_write — Write to file

# Ev

# 简介

This extension provides interface to » libev library - a high performance full-featured event loop written in C.

> 注意: 此扩展在 Windows 平台上不可用。

Libev is an event loop: one registers interest in certain events (such as a file descriptor being readable or a timeout occurring), and it will manage these event sources and provide the program with events.

To do this, it must take more or less complete control over the process (or thread) by executing the event loop handler, and will then communicate events via a callback mechanism.

You register interest in certain events by registering so-called event watchers, and then hand it over to libev by starting the watcher.

For details refer to the » documentation of libev.

# 安装/配置

## 目录

- 需求
- 安装

## 需求

`libev` library is embedded into this extension. You don't need to install it separately.

## 安装

此 » PECL 扩展未与 PHP 捆绑。

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/ev.

# 示例

示例 #1 Simple timers

    <?php
    // Create and start timer firing after 2 seconds
    $w1 = new EvTimer(2, 0, function () {
        echo "2 seconds elapsed\n";
    });

    // Create and launch timer firing after 2 seconds repeating each second
    // until we manually stop it
    $w2 = new EvTimer(2, 1, function ($w) {
        echo "is called every second, is launched after 2 seconds\n";
        echo "iteration = ", Ev::iteration(), PHP_EOL;

        // Stop the watcher after 5 iterations
        Ev::iteration() == 5 and $w->stop();
        // Stop the watcher if further calls cause more than 10 iterations
        Ev::iteration() >= 10 and $w->stop();
    });

    // Create stopped timer. It will be inactive until we start it ourselves
    $w_stopped = EvTimer::createStopped(10, 5, function($w) {
        echo "Callback of a timer created as stopped\n";

        // Stop the watcher after 2 iterations
        Ev::iteration() >= 2 and $w->stop();
    });

    // Loop until Ev::stop() is called or all of watchers stop
    Ev::run();

    // Start and look if it works
    $w_stopped->start();
    echo "Run single iteration\n";
    Ev::run(Ev::RUN_ONCE);

    echo "Restart the second watcher and try to handle the same events, but don't block\n";
    $w2->again();
    Ev::run(Ev::RUN_NOWAIT);

    $w = new EvTimer(10, 0, function() {});
    echo "Running a blocking loop\n";
    Ev::run();
    echo "END\n";
    ?>

以上示例的输出类似于：

    2 seconds elapsed
    is called every second, is launched after 2 seconds
    iteration = 1
    is called every second, is launched after 2 seconds
    iteration = 2
    is called every second, is launched after 2 seconds
    iteration = 3
    is called every second, is launched after 2 seconds
    iteration = 4
    is called every second, is launched after 2 seconds
    iteration = 5
    Run single iteration
    Callback of a timer created as stopped
    Restart the second watcher and try to handle the same events, but don't block
    Running a blocking loop
    is called every second, is launched after 2 seconds
    iteration = 8
    is called every second, is launched after 2 seconds
    iteration = 9
    is called every second, is launched after 2 seconds
    iteration = 10
    END

示例 #2 Periodic timer. Tick each 10.5 seconds

    <?php
    $w = new EvPeriodic(0., 10.5, NULL, function ($w, $revents) {
        echo time(), PHP_EOL;
    });

    Ev::run();
    ?>

示例 #3 Periodic timer. Use reschedule callback

    <?php
    // Tick each 10.5 seconds

    function reschedule_cb ($watcher, $now) {
        return $now + (10.5. - fmod($now, 10.5));
    }

    $w = new EvPeriodic(0., 0., "reschedule_cb", function ($w, $revents) {
        echo time(), PHP_EOL;
    });

    Ev::run();
    ?>

示例 #4 Periodic timer. Tick every 10.5 seconds starting at now

    <?php
    // Tick every 10.5 seconds starting at now
    $w = new EvPeriodic(fmod(Ev::now(), 10.5), 10.5, NULL, function ($w, $revents) {
        echo time(), PHP_EOL;
    });

    Ev::run();
    ?>

示例 #5 Wait until STDIN is readable

    <?php
    // Wait until STDIN is readable
    $w = new EvIo(STDIN, Ev::READ, function ($watcher, $revents) {
        echo "STDIN is readable\n";
    });

    Ev::run(Ev::RUN_ONCE);
    ?>

示例 #6 Use some async I/O to access a socket

    <?php
    /* Use some async I/O to access a socket */

    // `sockets' extension still logs warnings
    // for EINPROGRESS, EAGAIN/EWOULDBLOCK etc.
    error_reporting(E_ERROR);

    $e_nonblocking = array (/*EAGAIN or EWOULDBLOCK*/11, /*EINPROGRESS*/115);

    // Get the port for the WWW service
    $service_port = getservbyname('www', 'tcp');

    // Get the IP address for the target host
    $address = gethostbyname('google.co.uk');

    // Create a TCP/IP socket
    $socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
    if ($socket === FALSE) {
        echo "socket_create() failed: reason: "
            .socket_strerror(socket_last_error()) . "\n";
    }

    // Set O_NONBLOCK flag
    socket_set_nonblock($socket);

    // Abort on timeout
    $timeout_watcher = new EvTimer(10.0, 0., function () use ($socket) {
        socket_close($socket);
        Ev::stop(Ev::BREAK_ALL);
    });

    // Make HEAD request when the socket is writable
    $write_watcher = new EvIo($socket, Ev::WRITE, function ($w)
        use ($socket, $timeout_watcher, $e_nonblocking)
    {
        // Stop timeout watcher
        $timeout_watcher->stop();
        // Stop write watcher
        $w->stop();

        $in = "HEAD / HTTP/1.1\r\n";
        $in .= "Host: google.co.uk\r\n";
        $in .= "Connection: Close\r\n\r\n";

        if (!socket_write($socket, $in, strlen($in))) {
            trigger_error("Failed writing $in to socket", E_USER_ERROR);
        }

        $read_watcher = new EvIo($socket, Ev::READ, function ($w, $re)
            use ($socket, $e_nonblocking)
        {
            // Socket is readable. recv() 20 bytes using non-blocking mode
            $ret = socket_recv($socket, $out, 20, MSG_DONTWAIT);

            if ($ret) {
                echo $out;
            } elseif ($ret === 0) {
                // All read
                $w->stop();
                socket_close($socket);
                return;
            }

            // Caught EINPROGRESS, EAGAIN, or EWOULDBLOCK
            if (in_array(socket_last_error(), $e_nonblocking)) {
                return;
            }

            $w->stop();
            socket_close($socket);
        });

        Ev::run();
    });

    $result = socket_connect($socket, $address, $service_port);

    Ev::run();
    ?>

以上示例的输出类似于：

    HTTP/1.1 301 Moved Permanently
    Location: http://www.google.co.uk/
    Content-Type: text/html; charset=UTF-8
    Date: Sun, 23 Dec 2012 16:08:27 GMT
    Expires: Tue, 22 Jan 2013 16:08:27 GMT
    Cache-Control: public, max-age=2592000
    Server: gws
    Content-Length: 221
    X-XSS-Protection: 1; mode=block
    X-Frame-Options: SAMEORIGIN
    Connection: close

示例 #7 Embedding one loop into another

    <?php
    /*
    * Try to get an embeddable event loop and embed it into the default event loop.
    * If it is impossible, use the default
    * loop. The default loop is stored in $loop_hi, while the embeddable loop is
    * stored in $loop_lo(which is $loop_hi in the case no embeddable loop can be
    * used).
    *
    * Sample translated to PHP
    * http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#Examples_CONTENT-9
    */
    $loop_hi = EvLoop::defaultLoop();
    $loop_lo = NULL;
    $embed   = NULL;

    /*
    * See if there is a chance of getting one that works
    * (flags' value of 0 means autodetection)
    */
    $loop_lo = Ev::embeddableBackends() & Ev::recommendedBackends()
        ? new EvLoop(Ev::embeddableBackends() & Ev::recommendedBackends())
        : 0;

    if ($loop_lo) {
        $embed = new EvEmbed($loop_lo, function () {});
    } else {
        $loop_lo = $loop_hi;
    }
    ?>

示例 #8 Embedding loop created with kqueue backend into the default loop

    <?php
    /*
    * Check if kqueue is available but not recommended and create a kqueue backend
    * for use with sockets (which usually work with any kqueue implementation).
    * Store the kqueue/socket-only event loop in loop_socket. (One might optionally
    * use EVFLAG_NOENV, too)
    *
    * Example borrowed from
    * http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#Examples_CONTENT-9
    */
    $loop        = EvLoop::defaultLoop();
    $socket_loop = NULL;
    $embed       = NULL;

    if (Ev::supportedBackends() & ~Ev::recommendedBackends() & Ev::BACKEND_KQUEUE) {
        if (($socket_loop = new EvLoop(Ev::BACKEND_KQUEUE))) {
            $embed = new EvEmbed($loop);
        }
    }

    if (!$socket_loop) {
        $socket_loop = $loop;
    }

    // Now use $socket_loop for all sockets, and $loop for anything else
    ?>

示例 #9 Handle SIGTERM signal

    <?php
    $w = new EvSignal(SIGTERM, function ($watcher) {
        echo "SIGTERM received\n";
        $watcher->stop();
    });

    Ev::run();
    ?>

示例 #10 Monitor changes of /var/log/messages

    <?php
    // Use 10 second update interval.
    $w = new EvStat("/var/log/messages", 8, function ($w) {
        echo "/var/log/messages changed\n";

        $attr = $w->attr();

        if ($attr['nlink']) {
            printf("Current size: %ld\n", $attr['size']);
            printf("Current atime: %ld\n", $attr['atime']);
            printf("Current mtime: %ld\n", $attr['mtime']);
        } else {
            fprintf(STDERR, "`messages` file is not there!");
            $w->stop();
        }
    });

    Ev::run();
    ?>

示例 #11 Monitor changes of /var/log/messages. Avoid missing updates by means of one second delay

    <?php
    $timer = EvTimer::createStopped(0., 1.02, function ($w) {
        $w->stop();

        $stat = $w->data;

        // 1 second after the most recent change of the file
        printf("Current size: %ld\n", $stat->attr()['size']);
    });

    $stat = new EvStat("/var/log/messages", 0., function () use ($timer) {
        // Reset timer watcher
        $timer->again();
    });

    $timer->data = $stat;

    Ev::run();
    ?>

示例 #12 Process status changes

    <?php
    $pid = pcntl_fork();

    if ($pid == -1) {
        fprintf(STDERR, "pcntl_fork failed\n");
    } elseif ($pid) {
        $w = new EvChild($pid, FALSE, function ($w, $revents) {
            $w->stop();

            printf("Process %d exited with status %d\n", $w->rpid, $w->rstatus);
        });

        Ev::run();

        // Protect against Zombies
        pcntl_wait($status);
    } else {
        //Forked child
        exit(2);
    }
    ?>

# Watchers

A watcher is an object that gets created to record interest in some event. For instance, the following code waits for `STDIN` to become readable:

    <?php
    // Wait until STDIN is readable
    $w = new EvIo(STDIN, Ev::READ, function ($watcher, $revents) {
     echo "STDIN is readable\n";
    });
    Ev::run(Ev::RUN_ONCE);
    ?>

All the watcher constructors automatically start the watchers. `createStopped` methods create stopped watchers(e.g. EvIo::createStopped())

Note that a watcher will automatically be stopped when the watcher object is destroyed. Therefore, the watcher objects returned by the constructors or factory methods should be kept.

Note also that all methods changing some watcher property( set, priority etc.) automatically stop and start it again if it is active, which means pending events get lost.

See also: Watcher callbacks.

# Watcher callbacks

All watchers can be active(waiting for events) or inactive(paused). Only active watchers will have their callbacks invoked. All callbacks will be called with at least two arguments: `watcher` - the watcher, and `revents` a bitmask of received events.

Watcher callbacks are passed to the watcher constructors (the classes derived from EvWatcher - EvCheck::__construct(), EvChild::__construct() etc.). A watcher callback should match the following prototype:

function callback( object `$watcher` = NULL , int `$revents` = NULL ): void

`watcher`
  The watcher instance(of a class extending EvWatcher ).
`revents`
  Watcher received events.

Each watcher type has its associated bit in `revents`, so one can use the same callback for multiple watchers. The event mask is named after the type, i.e. EvChild (or EvLoop::child()) sets `Ev::CHILD`, EvPrepare (or EvLoop::prepare()) sets `Ev::PREPARE`, EvPeriodic (or EvLoop::periodic()) sets `Ev::PERIODIC` and so on, with the exception of I/O events (which can set both `Ev::READ` and `Ev::WRITE` bits).

# Periodic watcher operation modes

EvPeriodic watcher works in different modes depending on the `offset`, `interval` and `reschedule_cb` parameters.

1. Absolute timer. In this mode `interval` = `0`, `reschedule_cb` = `null`. This time simply fires at the wallclock time `offset` and doesn't repeat. It will not adjust when a time jump occurs, that is, if it is to be run at January 1st 2014 then it will run when the system time reaches or surpasses this time.
2. Repeating interval timer. In this mode `interval` > `0`, `reschedule_cb` = `null`; the watcher will always be scheduled to timeout at the next `offset` + `N` * `interval` time(for some integer `N`) and then repeat, regardless of any time jumps.

   This can be used to create timers that do not drift with respect to system time:

       <?php
       $hourly = EvPeriodic(0, 3600, NULL, function () {
         echo "once per hour\n";
       });
       ?>

   That doesn't mean there will always be `3600` seconds in between triggers, but only that the callback will be called when the system time shows a full hour( UTC ). EvPeriodic will try to run the callback in this mode at the next possible time where time = `offset` ( `mod` `interval` ), regardless of any time jumps.
3. Manual reschedule mode. In this mode `reschedule_cb` is a callable. `interval` and `offset` are both being ignored. Instead, each time the periodic watcher gets scheduled, the reschedule callback ( `reschedule_cb`) will be called with the watcher as first, and the current time as second argument. This callback must not stop or destroy this or any other periodic watchers, ever, and must not call any event loop functions or methods. To stop it return `1e30` and stop it afterwards. An EvPrepare watcher may be used for this task. It must return the next time to trigger, based on the passed time value (that is, the lowest time value larger than or equal to the second argument). It will usually be called just before the callback will be triggered, but might be called at other times, too.

   示例 #1 Using reschedule callback

       <?php
       // Tick each 10.5 seconds

       function reschedule_cb ($watcher, $now) {
          return $now + (10.5. - fmod($now, 10.5));
       }

       $w = new EvPeriodic(0., 0., "reschedule_cb", function ($w, $revents) {
          echo time(), PHP_EOL;
       });

       Ev::run();
       ?>

# The Ev class

(PECL ev >= 0.2.0)

## 简介

Ev is a static class providing access to the default loop and to some common operations.

## 类摘要

final class Ev {
/* 常量 */
const int FLAG_AUTO = 0;
const int FLAG_NOENV = 16777216;
const int FLAG_FORKCHECK = 33554432;
const int FLAG_NOINOTIFY = 1048576;
const int FLAG_SIGNALFD = 2097152;
const int FLAG_NOSIGMASK = 4194304;
const int RUN_NOWAIT = 1;
const int RUN_ONCE = 2;
const int BREAK_CANCEL = 0;
const int BREAK_ONE = 1;
const int BREAK_ALL = 2;
const int MINPRI = -2;
const int MAXPRI = 2;
const int READ = 1;
const int WRITE = 2;
const int TIMER = 256;
const int PERIODIC = 512;
const int SIGNAL = 1024;
const int CHILD = 2048;
const int STAT = 4096;
const int IDLE = 8192;
const int PREPARE = 16384;
const int CHECK = 32768;
const int EMBED = 65536;
const int CUSTOM = 16777216;
const int ERROR = 2147483648;
const int BACKEND_SELECT = 1;
const int BACKEND_POLL = 2;
const int BACKEND_EPOLL = 4;
const int BACKEND_KQUEUE = 8;
const int BACKEND_DEVPOLL = 16;
const int BACKEND_PORT = 32;
const int BACKEND_ALL = 63;
const int BACKEND_MASK = 65535;
/* 方法 */
final public static function backend(): int
final public static function depth(): int
final public static function embeddableBackends(): int
final public static function feedSignal( int `$signum` ): void
final public static function feedSignalEvent( int `$signum` ): void
final public static function iteration(): int
final public static function now(): float
final public static function nowUpdate(): void
final public static function recommendedBackends(): int
final public static function resume(): void
final public static function run( int `$flags` = ?): void
final public static function sleep( float `$seconds` ): void
final public static function stop( int `$how` = ?): void
final public static function supportedBackends(): int
final public static function suspend(): void
final public static function time(): float
final public static function verify(): void
}

## 预定义常量

Flags passed to create a loop:

`Ev::FLAG_AUTO`
  The default flags value
`Ev::FLAG_NOENV`
  If this flag used(or the program runs setuid or setgid), `libev` won't look at the environment variable LIBEV_FLAGS. Otherwise(by default), LIBEV_FLAGS will override the flags completely if it is found. Useful for performance tests and searching for bugs.
`Ev::FLAG_FORKCHECK`
  Makes libev check for a fork in each iteration, instead of calling EvLoop::fork() manually. This works by calling `getpid()` on every iteration of the loop, and thus this might slow down the event loop with lots of loop iterations, but usually is not noticeable. This flag setting cannot be overridden or specified in the LIBEV_FLAGS environment variable.
`Ev::FLAG_NOINOTIFY`
  When this flag is specified, `libev` won't attempt to use the `inotify` API for its » ev_stat watchers. The flag can be useful to conserve inotify file descriptors, as otherwise each loop using `ev_stat` watchers consumes one `inotify` handle.
`Ev::FLAG_SIGNALFD`
  When this flag is specified, `libev` will attempt to use the `signalfd` API for its » ev_signal (and » ev_child) watchers. This API delivers signals synchronously, which makes it both faster and might make it possible to get the queued signal data. It can also simplify signal handling with threads, as long as signals are properly blocked in threads. `Signalfd` will not be used by default.
`Ev::FLAG_NOSIGMASK`
  When this flag is specified, `libev` will avoid to modify the signal mask. Specifically, this means having to make sure signals are unblocked before receiving them. This behaviour is useful for custom signal handling, or handling signals only in specific threads.

Flags passed to Ev::run(), or EvLoop::run()

`Ev::RUN_NOWAIT`
  Means that event loop will look for new events, will handle those events and any already outstanding ones, but will not wait and block the process in case there are no events and will return after one iteration of the loop. This is sometimes useful to poll and handle new events while doing lengthy calculations, to keep the program responsive.
`Ev::RUN_ONCE`
  Means that event loop will look for new events (waiting if necessary) and will handle those and any already outstanding ones. It will block the process until at least one new event arrives (which could be an event internal to libev itself, so there is no guarantee that a user-registered callback will be called), and will return after one iteration of the loop.

Flags passed to Ev::stop(), or EvLoop::stop()

`Ev::BREAK_CANCEL`
  Cancel the break operation.
`Ev::BREAK_ONE`
  Makes the innermost Ev::run() (or EvLoop::run()) call return.
`Ev::BREAK_ALL`
  Makes all nested Ev::run() (or EvLoop::run()) calls return.

Watcher priorities:

`Ev::MINPRI`
  Minimum allowed watcher priority.
`Ev::MAXPRI`
  Maximum allowed watcher priority.

Bit masks of (received) events:

`Ev::READ`
  The file descriptor in the EvIo watcher has become readable.
`Ev::WRITE`
  The file descriptor in the EvIo watcher has become writable.
`Ev::TIMER`
  EvTimer watcher has been timed out.
`Ev::PERIODIC`
  EvPeriodic watcher has been timed out.
`Ev::SIGNAL`
  A signal specified in EvSignal::__construct() has been received.
`Ev::CHILD`
  The `pid` specified in EvChild::__construct() has received a status change.
`Ev::STAT`
  The path specified in EvStat watcher changed its attributes.
`Ev::IDLE`
  EvIdle watcher works when there is nothing to do with other watchers.
`Ev::PREPARE`
  All EvPrepare watchers are invoked just before Ev::run() starts. Thus, EvPrepare watchers are the last watchers invoked before the event loop sleeps or polls for new events.
`Ev::CHECK`
  All EvCheck watchers are queued just after Ev::run() has gathered the new events, but before it queues any callbacks for any received events. Thus, EvCheck watchers will be invoked before any other watchers of the same or lower priority within an event loop iteration.
`Ev::EMBED`
  The embedded event loop specified in the EvEmbed watcher needs attention.
`Ev::CUSTOM`
  Not ever sent(or otherwise used) by `libev` itself, but can be freely used by `libev` users to signal watchers (e.g. via EvWatcher::feed() ).
`Ev::ERROR`
  An unspecified error has occurred, the watcher has been stopped. This might happen because the watcher could not be properly started because `libev` ran out of memory, a file descriptor was found to be closed or any other problem. `Libev` considers these application bugs. See also » ANATOMY OF A WATCHER

Backend flags:

`Ev::BACKEND_SELECT`
  `select(2) backend`
`Ev::BACKEND_POLL`
  `poll(2) backend`
`Ev::BACKEND_EPOLL`
  Linux-specific `epoll(7)` backend for both pre- and post-2.6.9 kernels
`Ev::BACKEND_KQUEUE`
  `kqueue` backend used on most BSD systems. EvEmbed watcher could be used to embed one loop(with kqueue backend) into another. For instance, one can try to create an event loop with `kqueue` backend and use it for sockets only.
`Ev::BACKEND_DEVPOLL`
  Solaris 8 backend. This is not implemented yet.
`Ev::BACKEND_PORT`
  Solaris 10 event port mechanism with a good scaling.
`Ev::BACKEND_ALL`
  Try all backends(even corrupted ones). It's not recommended to use it explicitly. Bitwise operators should be applied here(e.g. `Ev::BACKEND_ALL` & ~ `Ev::BACKEND_KQUEUE`) Use Ev::recommendedBackends(), or don't specify any backends at all.
`Ev::BACKEND_MASK`
  Not a backend, but a mask to select all backend bits from `flags` value to mask out any backends(e.g. when modifying the LIBEV_FLAGS environment variable).

> 注意: For the default loop during module initialization phase `Ev` registers » ev_loop_fork call by means of `pthread_atfork` (if available).

> 注意: There are methods providing access to the default event loop in Ev class(e.g. Ev::iteration(), Ev::depth() etc.) For custom loops (created with EvLoop::__construct()) these values may be accessed via corresponding properties and methods of the EvLoop class. The instance of the default event loop itself can be fetched by means of EvLoop::defaultLoop() method.

# Ev::backend

(PECL ev >= 0.2.0)

Ev::backend — Returns an integer describing the backend used by libev

### 说明

final public static function Ev::backend(): int

Returns an integer describing the backend used by libev. See Backend flags

### 参数

此函数没有参数。

### 返回值

Returns an integer(bit mask) describing the backend used by libev.

### 参见

- EvEmbed
- Ev::embeddableBackends() - Returns the set of backends that are embeddable in other event loops
- Ev::recommendedBackends() - Returns a bit mask of recommended backends for current platform
- Ev::supportedBackends() - Returns the set of backends supported by current libev configuration
- Backend flags

# Ev::depth

(PECL ev >= 0.2.0)

Ev::depth — Returns recursion depth

### 说明

final public static function Ev::depth(): int

The number of times Ev::run() was entered minus the number of times Ev::run() was exited normally, in other words, the recursion depth. Outside Ev::run(), this number is `0`. In a callback, this number is `1`, unless Ev::run() was invoked recursively (or from another thread), in which case it is higher.

### 参数

此函数没有参数。

### 返回值

ev_depth() returns recursion depth of the default loop.

### 参见

- Ev::iteration() - Return the number of times the default event loop has polled for new events

# Ev::embeddableBackends

(PECL ev >= 0.2.0)

Ev::embeddableBackends — Returns the set of backends that are embeddable in other event loops

### 说明

final public static function Ev::embeddableBackends(): int

Returns the set of backends that are embeddable in other event loops.

### 参数

此函数没有参数。

### 返回值

Returns a bit mask which can containing backend flags combined using bitwise OR operator.

### 示例

示例 #1 Embedding loop created with kqueue backend into the default loop

    <?php
    /*
    * Check if kqueue is available but not recommended and create a kqueue backend
    * for use with sockets (which usually work with any kqueue implementation).
    * Store the kqueue/socket-only event loop in loop_socket. (One might optionally
    * use EVFLAG_NOENV, too)
    *
    * Example borrowed from
    * http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#Examples_CONTENT-9
    */
    $loop        = EvLoop::defaultLoop();
    $socket_loop = NULL;
    $embed       = NULL;

    if (Ev::supportedBackends() & ~Ev::recommendedBackends() & Ev::BACKEND_KQUEUE) {
     if (($socket_loop = new EvLoop(Ev::BACKEND_KQUEUE))) {
      $embed = new EvEmbed($loop);
     }
    }

    if (!$socket_loop) {
     $socket_loop = $loop;
    }

    // Now use $socket_loop for all sockets, and $loop for anything else
    ?>

### 参见

- EvEmbed
- Ev::recommendedBackends() - Returns a bit mask of recommended backends for current platform
- Ev::supportedBackends() - Returns the set of backends supported by current libev configuration
- Backend flags
- Examples

# Ev::feedSignal

(PECL ev >= 0.2.0)

Ev::feedSignal — Feed a signal event into Ev

### 说明

final public static function Ev::feedSignal( int `$signum` ): void

Simulates a signal receive. It is safe to call this function at any time, from any context, including signal handlers or random threads. Its main use is to customise signal handling in the process.

Unlike Ev::feedSignalEvent(), this works regardless of which loop has registered the signal.

### 参数

`signum`
  Signal number. See `signal(7)` man page for details. You can use constants exported by `pcntl` extension.

### 返回值

没有返回值。

### 参见

- Ev::feedSignalEvent() - Feed signal event into the default loop

# Ev::feedSignalEvent

(No version information available, might only be in Git)

Ev::feedSignalEvent — Feed signal event into the default loop

### 说明

final public static function Ev::feedSignalEvent( int `$signum` ): void

Feed signal event into the default loop. Ev will react to this call as if the signal specified by `signal` had occurred.

### 参数

`signum`
  Signal number. See `signal(7)` man page for details. See also constants exported by `pcntl` extension.

### 返回值

没有返回值。

### 参见

- Ev::feedSignal() - Feed a signal event into Ev

# Ev::iteration

(PECL ev >= 0.2.0)

Ev::iteration — Return the number of times the default event loop has polled for new events

### 说明

final public static function Ev::iteration(): int

Return the number of times the event loop has polled for new events. Sometimes useful as a generation counter.

### 参数

此函数没有参数。

### 返回值

Returns number of polls of the default event loop.

### 参见

- Ev::depth() - Returns recursion depth

# Ev::now

(PECL ev >= 0.2.0)

Ev::now — Returns the time when the last iteration of the default event loop has started

### 说明

final public static function Ev::now(): float

Returns the time when the last iteration of the default event loop has started. This is the time that timers( EvTimer and EvPeriodic) are based on, and referring to it is usually faster than calling Ev::time().

### 参数

此函数没有参数。

### 返回值

Returns number of seconds(fractional) representing the time when the last iteration of the default event loop has started.

### 参见

- Ev::nowUpdate() - Establishes the current time by querying the kernel, updating the time returned by Ev::now in the progress

# Ev::nowUpdate

(PECL ev >= 0.2.0)

Ev::nowUpdate — Establishes the current time by querying the kernel, updating the time returned by Ev::now in the progress

### 说明

final public static function Ev::nowUpdate(): void

Establishes the current time by querying the kernel, updating the time returned by Ev::now() in the progress. This is a costly operation and is usually done automatically within Ev::run().

This method is rarely useful, but when some event callback runs for a very long time without entering the event loop, updating libev 's consideration of the current time is a good idea.

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 参见

- Ev::now() - Returns the time when the last iteration of the default event loop has started

# Ev::recommendedBackends

(PECL ev >= 0.2.0)

Ev::recommendedBackends — Returns a bit mask of recommended backends for current platform

### 说明

final public static function Ev::recommendedBackends(): int

Returns the set of all backends compiled into this binary of `libev` and also recommended for this platform, meaning it will work for most file descriptor types. This set is often smaller than the one returned by ev_supported_backends(), as for example `kqueue` is broken on most `BSD` systems and will not be auto-detected unless it is requested explicitly. This is the set of backends that `libev` will probe when no backends are specified explicitly.

### 参数

此函数没有参数。

### 返回值

Returns a bit mask which can containing backend flags combined using bitwise OR operator.

### 示例

示例 #1 Embedding one loop into another

    <?php
    /*
    * Try to get an embeddable event loop and embed it into the default event loop.
    * If it is impossible, use the default
    * loop. The default loop is stored in $loop_hi, while the embeddable loop is
    * stored in $loop_lo(which is $loop_hi in the case no embeddable loop can be
    * used).
    *
    * Sample translated to PHP
    * http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#Examples_CONTENT-9
    */
    $loop_hi = EvLoop::defaultLoop();
    $loop_lo = NULL;
    $embed   = NULL;

    /*
    * See if there is a chance of getting one that works
    * (flags' value of 0 means autodetection)
    */
    $loop_lo = Ev::embeddableBackends() & Ev::recommendedBackends()
     ? new EvLoop(Ev::embeddableBackends() & Ev::recommendedBackends())
     : 0;

    if ($loop_lo) {
     $embed = new EvEmbed($loop_lo, function () {});
    } else {
     $loop_lo = $loop_hi;
    }
    ?>

### 参见

- EvEmbed
- Ev::embeddableBackends() - Returns the set of backends that are embeddable in other event loops
- Ev::supportedBackends() - Returns the set of backends supported by current libev configuration
- Backend flags
- Examples

# Ev::resume

(PECL ev >= 0.2.0)

Ev::resume — Resume previously suspended default event loop

### 说明

final public static function Ev::resume(): void

Ev::suspend() and Ev::resume() methods suspend and resume a loop correspondingly.

All timer watchers will be delayed by the time spent between suspend and resume, and all periodic watchers will be rescheduled(that is, they will lose any events that would have occurred while suspended).

After calling Ev::suspend() it is not allowed to call any function on the given loop other than Ev::resume(). Also it is not allowed to call Ev::resume() without a previous call to Ev::suspend().

Calling suspend / resume has the side effect of updating the event loop time(see Ev::nowUpdate() ).

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 参见

- Ev::suspend() - Suspend the default event loop

# Ev::run

(PECL ev >= 0.2.0)

Ev::run — Begin checking for events and calling callbacks for the default loop

### 说明

final public static function Ev::run( int `$flags` = ?): void

Begin checking for events and calling callbacks for the default loop. Returns when a callback calls Ev::stop() method, or the flags are nonzero(in which case the return value is true) or when there are no active watchers which reference the loop( EvWatcher::keepalive() is `true`), in which case the return value will be `false`. The return value can generally be interpreted as if `true`, there is more work left to do.

### 参数

`flags`

  Optional parameter `flags` can be one of the following:

  List for possible values of `flags`
  `flags` | Description
  --- | ---
  `0` | The default behavior described above
  `Ev::RUN_ONCE` | Block at most one(wait, but don't loop)
  `Ev::RUN_NOWAIT` | Don't block at all(fetch/handle events, but don't wait)

  See the run flag constants.

### 返回值

没有返回值。

### 参见

- Ev::stop() - Stops the default event loop
- EvLoop::run() - Begin checking for events and calling callbacks for the loop

# Ev::sleep

(PECL ev >= 0.2.0)

Ev::sleep — Block the process for the given number of seconds

### 说明

final public static function Ev::sleep( float `$seconds` ): void

Block the process for the given number of seconds.

### 参数

`seconds`
  Fractional number of seconds

### 返回值

没有返回值。

# Ev::stop

(PECL ev >= 0.2.0)

Ev::stop — Stops the default event loop

### 说明

final public static function Ev::stop( int `$how` = ?): void

Stops the default event loop

### 参数

`how`
  One of Ev::BREAK_* constants.

### 返回值

没有返回值。

### 参见

- Ev::run() - Begin checking for events and calling callbacks for the default loop

# Ev::supportedBackends

(PECL ev >= 0.2.0)

Ev::supportedBackends — Returns the set of backends supported by current libev configuration

### 说明

final public static function Ev::supportedBackends(): int

Returns the set of backends supported by current libev configuration.

### 参数

此函数没有参数。

### 返回值

Returns a bit mask which can containing backend flags combined using bitwise OR operator.

### 示例

示例 #1 Embedding loop created with kqueue backend into the default loop

    <?php
    /*
    * Check if kqueue is available but not recommended and create a kqueue backend
    * for use with sockets (which usually work with any kqueue implementation).
    * Store the kqueue/socket-only event loop in loop_socket. (One might optionally
    * use EVFLAG_NOENV, too)
    *
    * Example borrowed from
    * http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#Examples_CONTENT-9
    */
    $loop        = EvLoop::defaultLoop();
    $socket_loop = NULL;
    $embed       = NULL;

    if (Ev::supportedBackends() & ~Ev::recommendedBackends() & Ev::BACKEND_KQUEUE) {
     if (($socket_loop = new EvLoop(Ev::BACKEND_KQUEUE))) {
      $embed = new EvEmbed($loop);
     }
    }

    if (!$socket_loop) {
     $socket_loop = $loop;
    }

    // Now use $socket_loop for all sockets, and $loop for anything else
    ?>

### 参见

- EvEmbed
- Ev::recommendedBackends() - Returns a bit mask of recommended backends for current platform
- Ev::embeddableBackends() - Returns the set of backends that are embeddable in other event loops
- Backend flags
- Examples

# Ev::suspend

(PECL ev >= 0.2.0)

Ev::suspend — Suspend the default event loop

### 说明

final public static function Ev::suspend(): void

Ev::suspend() and Ev::resume() methods suspend and resume the default loop correspondingly.

All timer watchers will be delayed by the time spent between suspend and resume, and all periodic watchers will be rescheduled(that is, they will lose any events that would have occurred while suspended).

After calling Ev::suspend() it is not allowed to call any function on the given loop other than Ev::resume(). Also it is not allowed to call Ev::resume() without a previous call to Ev::suspend().

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 参见

- Ev::resume() - Resume previously suspended default event loop

# Ev::time

(PECL ev >= 0.2.0)

Ev::time — Returns the current time in fractional seconds since the epoch

### 说明

final public static function Ev::time(): float

Returns the current time in fractional seconds since the epoch. Consider using Ev::now()

### 参数

此函数没有参数。

### 返回值

Returns the current time in fractional seconds since the epoch.

### 参见

- Ev::now() - Returns the time when the last iteration of the default event loop has started

# Ev::verify

(PECL ev >= 0.2.0)

Ev::verify — Performs internal consistency checks(for debugging)

### 说明

final public static function Ev::verify(): void

Performs internal consistency checks(for debugging libev) and abort the program if any data structures were found to be corrupted.

### 参数

此函数没有参数。

### 返回值

没有返回值。

## 目录

- Ev::backend — Returns an integer describing the backend used by libev
- Ev::depth — Returns recursion depth
- Ev::embeddableBackends — Returns the set of backends that are embeddable in other event loops
- Ev::feedSignal — Feed a signal event into Ev
- Ev::feedSignalEvent — Feed signal event into the default loop
- Ev::iteration — Return the number of times the default event loop has polled for new events
- Ev::now — Returns the time when the last iteration of the default event loop has started
- Ev::nowUpdate — Establishes the current time by querying the kernel, updating the time returned by Ev::now in the progress
- Ev::recommendedBackends — Returns a bit mask of recommended backends for current platform
- Ev::resume — Resume previously suspended default event loop
- Ev::run — Begin checking for events and calling callbacks for the default loop
- Ev::sleep — Block the process for the given number of seconds
- Ev::stop — Stops the default event loop
- Ev::supportedBackends — Returns the set of backends supported by current libev configuration
- Ev::suspend — Suspend the default event loop
- Ev::time — Returns the current time in fractional seconds since the epoch
- Ev::verify — Performs internal consistency checks(for debugging)

# The EvCheck class

(PECL ev >= 0.2.0)

## 简介

EvPrepare and EvCheck watchers are usually used in pairs. EvPrepare watchers get invoked before the process blocks, EvCheck afterwards.

It is not allowed to call EvLoop::run() or similar methods or functions that enter the current event loop from either EvPrepare or EvCheck watchers. Other loops than the current one are fine, however. The rationale behind this is that one don't need to check for recursion in those watchers, i.e. the sequence will always be: EvPrepare -> blocking -> EvCheck, so having a watcher of each kind they will always be called in pairs bracketing the blocking call.

The main purpose is to integrate other event mechanisms into libev and their use is somewhat advanced. They could be used, for example, to track variable changes, implement custom watchers, integrate net-snmp or a coroutine library and lots more. They are also occasionally useful to cache some data and want to flush it before blocking.

It is recommended to give EvCheck watchers highest( `Ev::MAXPRI`) priority, to ensure that they are being run before any other watchers after the poll (this doesn’t matter for EvPrepare watchers).

Also, EvCheck watchers should not activate/feed events. While libev fully supports this, they might get executed before other EvCheck watchers did their job.

## 类摘要

class EvCheck extends EvWatcher {
/* 继承的属性 */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* 方法 */
public function __construct( callable `$callback` , mixed `$data` = ?, int `$priority` = ?)
final public static function createStopped( string `$callback` , string `$data` = ?, string `$priority` = ?): object
/* 继承的方法 */
public function EvWatcher::clear(): int
public function EvWatcher::feed( int `$revents` ): void
public function EvWatcher::getLoop(): EvLoop
public function EvWatcher::invoke( int `$revents` ): void
public function EvWatcher::keepalive( bool `$value` = ?): bool
public function EvWatcher::setCallback( callable `$callback` ): void
public function EvWatcher::start(): void
public function EvWatcher::stop(): void
}

# EvCheck::__construct

(PECL ev >= 0.2.0)

EvCheck::__construct — Constructs the EvCheck watcher object

### 说明

public function EvCheck::__construct( callable `$callback` , mixed `$data` = ?, int `$priority` = ?)

Constructs the EvCheck watcher object.

### 参数

`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 参见

- EvPrepare
- EvLoop::check() - Creates EvCheck object associated with the current event loop instance

# EvCheck::createStopped

(PECL ev >= 0.2.0)

EvCheck::createStopped — Create instance of a stopped EvCheck watcher

### 说明

final public static function EvCheck::createStopped( string `$callback` , string `$data` = ?, string `$priority` = ?): object

Create instance of a stopped EvCheck watcher

### 参数

`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 返回值

Returns EvCheck object on success.

### 参见

- EvPrepare

## 目录

- EvCheck::__construct — Constructs the EvCheck watcher object
- EvCheck::createStopped — Create instance of a stopped EvCheck watcher

# The EvChild class

(PECL ev >= 0.2.0)

## 简介

EvChild watchers trigger when the process receives a `SIGCHLD` in response to some child status changes (most typically when a child dies or exits). It is permissible to install an `EvChild` watcher after the child has been forked(which implies it might have already exited), as long as the event loop isn't entered(or is continued from a watcher), i.e. forking and then immediately registering a watcher for the child is fine, but forking and registering a watcher a few event loop iterations later or in the next callback invocation is not.

It is allowed to register EvChild watchers in the default loop only.

## 类摘要

class EvChild extends EvWatcher {
/* 属性 */
public $pid;
public $rpid;
public $rstatus;
/* 继承的属性 */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* 方法 */
public function __construct(
int `$pid` ,
bool `$trace` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
)
final public static function createStopped(
int `$pid` ,
bool `$trace` ,
callable `$callback` ,
mixed `$data` = ?,
int `$priority` = ?
): object
public function set( int `$pid` , bool `$trace` ): void
/* 继承的方法 */
public function EvWatcher::clear(): int
public function EvWatcher::feed( int `$revents` ): void
public function EvWatcher::getLoop(): EvLoop
public function EvWatcher::invoke( int `$revents` ): void
public function EvWatcher::keepalive( bool `$value` = ?): bool
public function EvWatcher::setCallback( callable `$callback` ): void
public function EvWatcher::start(): void
public function EvWatcher::stop(): void
}

## 属性

pid
  Readonly. The process ID this watcher watches out for, or `0`, meaning any process ID.
rpid
  Readonly .The process ID that detected a status change.
rstatus
  Readonly. The process exit status caused by rpid.

# EvChild::__construct

(PECL ev >= 0.2.0)

EvChild::__construct — Constructs the EvChild watcher object

### 说明

public function EvChild::__construct(
int `$pid` ,
bool `$trace` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
)

Constructs the EvChild watcher object.

Call the callback when a status change for process ID `pid` (or any PID if `pid` is `0`) has been received(a status change happens when the process terminates or is killed, or, when `trace` is `true`, additionally when it is stopped or continued). In other words, when the process receives a `SIGCHLD`, Ev will fetch the outstanding exit/wait status for all changed/zombie children and call the callback.

It is valid to install a child watcher after an EvChild has exited but before the event loop has started its next iteration. For example, first one calls `fork`, then the new child process might exit, and only then an EvChild watcher is installed in the parent for the new PID.

You can access both exit/tracing status and `pid` by using the rstatus and rpid properties of the watcher object.

The number of PID watchers per PID is unlimited. All of them will be called.

The EvChild::createStopped() method doesn't start(activate) the newly created watcher.

### 参数

`pid`
  Wait for status changes of process PID(or any process if PID is specified as `0` ).
`trace`
  If `false`, only activate the watcher when the process terminates. Otherwise(`true`) additionally activate the watcher when the process is stopped or continued.
`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 参见

- EvLoop::child() - Creates EvChild object associated with the current event loop

# EvChild::createStopped

(PECL ev >= 0.2.0)

EvChild::createStopped — Create instance of a stopped EvChild watcher

### 说明

final public static function EvChild::createStopped(
int `$pid` ,
bool `$trace` ,
callable `$callback` ,
mixed `$data` = ?,
int `$priority` = ?
): object

The same as EvChild::__construct(), but doesn't start the watcher automatically.

### 参数

`pid`
  The same as for EvChild::__construct()
`trace`
  The same as for EvChild::__construct()
`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 返回值

### 参见

- EvChild::__construct() - Constructs the EvChild watcher object
- EvLoop::child() - Creates EvChild object associated with the current event loop

# EvChild::set

(PECL ev >= 0.2.0)

EvChild::set — Configures the watcher

### 说明

public function EvChild::set( int `$pid` , bool `$trace` ): void

### 参数

`pid`
  The same as for EvChild::__construct()
`trace`
  The same as for EvChild::__construct()

### 返回值

没有返回值。

### 参见

- EvChild::__construct() - Constructs the EvChild watcher object

## 目录

- EvChild::__construct — Constructs the EvChild watcher object
- EvChild::createStopped — Create instance of a stopped EvChild watcher
- EvChild::set — Configures the watcher

# The EvEmbed class

(PECL ev >= 0.2.0)

## 简介

Used to embed one event loop into another.

## 类摘要

class EvEmbed extends EvWatcher {
/* 属性 */
public $embed;
/* 方法 */
public function __construct(
object `$other` ,
callable `$callback` = ?,
mixed `$data` = ?,
int `$priority` = ?
)
final public static function createStopped(
object `$other` ,
callable `$callback` = ?,
mixed `$data` = ?,
int `$priority` = ?
): void
public function set( object `$other` ): void
public function sweep(): void
/* 继承的方法 */
public function EvWatcher::clear(): int
public function EvWatcher::feed( int `$revents` ): void
public function EvWatcher::getLoop(): EvLoop
public function EvWatcher::invoke( int `$revents` ): void
public function EvWatcher::keepalive( bool `$value` = ?): bool
public function EvWatcher::setCallback( callable `$callback` ): void
public function EvWatcher::start(): void
public function EvWatcher::stop(): void
}

## 属性

is_active
data
is_pending
priority
embed

# EvEmbed::__construct

(PECL ev >= 0.2.0)

EvEmbed::__construct — Constructs the EvEmbed object

### 说明

public function EvEmbed::__construct(
object `$other` ,
callable `$callback` = ?,
mixed `$data` = ?,
int `$priority` = ?
)

This is a rather advanced watcher type that lets to embed one event loop into another(currently only IO events are supported in the embedded loop, other types of watchers might be handled in a delayed or incorrect fashion and must not be used).

See » the libev documentation for details.

This watcher is most useful on BSD systems without working `kqueue` to still be able to handle a large number of sockets. See example below.

### 参数

`other`
  Instance of EvLoop. The loop to embed, this loop must be embeddable(see Ev::embeddableBackends() ).
`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 示例

示例 #1 Embedding loop created with kqueue backend into the default loop

    <?php
    /*
     * Check if kqueue is available but not recommended and create a kqueue backend
     * for use with sockets (which usually work with any kqueue implementation).
     * Store the kqueue/socket-only event loop in loop_socket. (One might optionally
     * use EVFLAG_NOENV, too)
     *
     * Example borrowed from
     * http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#Examples_CONTENT-9
     */
    $loop        = EvLoop::defaultLoop();
    $socket_loop = NULL;
    $embed       = NULL;

    if (Ev::supportedBackends() & ~Ev::recommendedBackends() & Ev::BACKEND_KQUEUE) {
        if (($socket_loop = new EvLoop(Ev::BACKEND_KQUEUE))) {
            $embed = new EvEmbed($loop);
        }
    }

    if (!$socket_loop) {
        $socket_loop = $loop;
    }

    // Now use $socket_loop for all sockets, and $loop for anything else
    ?>

### 参见

- Ev::embeddableBackends() - Returns the set of backends that are embeddable in other event loops

# EvEmbed::createStopped

(PECL ev >= 0.2.0)

EvEmbed::createStopped — Create stopped EvEmbed watcher object

### 说明

final public static function EvEmbed::createStopped(
object `$other` ,
callable `$callback` = ?,
mixed `$data` = ?,
int `$priority` = ?
): void

The same as EvEmbed::__construct(), but doesn't start the watcher automatically.

### 参数

`other`
  The same as for EvEmbed::__construct()
`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 返回值

Returns stopped EvEmbed object on success.

### 参见

- EvEmbed::__construct() - Constructs the EvEmbed object
- Ev::embeddableBackends() - Returns the set of backends that are embeddable in other event loops

# EvEmbed::set

(PECL ev >= 0.2.0)

EvEmbed::set — Configures the watcher

### 说明

public function EvEmbed::set( object `$other` ): void

Configures the watcher to use `other` event loop object.

### 参数

`other`
  The same as for EvEmbed::__construct()

### 返回值

没有返回值。

# EvEmbed::sweep

(PECL ev >= 0.2.0)

EvEmbed::sweep — Make a single, non-blocking sweep over the embedded loop

### 说明

public function EvEmbed::sweep(): void

Make a single, non-blocking sweep over the embedded loop. Works similarly to the following, but in the most appropriate way for embedded loops:

    <?php
    $other->start(Ev::RUN_NOWAIT);
    ?>

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 参见

- EvWatcher::start() - Starts the watcher

## 目录

- EvEmbed::__construct — Constructs the EvEmbed object
- EvEmbed::createStopped — Create stopped EvEmbed watcher object
- EvEmbed::set — Configures the watcher
- EvEmbed::sweep — Make a single, non-blocking sweep over the embedded loop

# The EvFork class

(PECL ev >= 0.2.0)

## 简介

Fork watchers are called when a `fork()` was detected (usually because whoever signalled libev about it by calling EvLoop::fork() ). The invocation is done before the event loop blocks next and before EvCheck watchers are being called, and only in the child after the fork. Note, that if whoever calling EvLoop::fork() calls it in the wrong process, the fork handlers will be invoked, too.

## 类摘要

class EvFork extends EvWatcher {
/* 继承的属性 */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* 方法 */
public function __construct( callable `$callback` , mixed `$data` = `null` , int `$priority` = 0 )
final public static function createStopped( string `$callback` , string `$data` = ?, string `$priority` = ?): object
/* 继承的方法 */
public function EvWatcher::clear(): int
public function EvWatcher::feed( int `$revents` ): void
public function EvWatcher::getLoop(): EvLoop
public function EvWatcher::invoke( int `$revents` ): void
public function EvWatcher::keepalive( bool `$value` = ?): bool
public function EvWatcher::setCallback( callable `$callback` ): void
public function EvWatcher::start(): void
public function EvWatcher::stop(): void
}

# EvFork::__construct

(PECL ev >= 0.2.0)

EvFork::__construct — Constructs the EvFork watcher object

### 说明

public function EvFork::__construct( callable `$callback` , mixed `$data` = `null` , int `$priority` = 0 )

Constructs the EvFork watcher object and starts the watcher automatically.

### 参数

`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 参见

- EvLoop::fork() - Creates EvFork watcher object associated with the current event loop instance
- EvCheck

# EvFork::createStopped

(PECL ev >= 0.2.0)

EvFork::createStopped — Creates a stopped instance of EvFork watcher class

### 说明

final public static function EvFork::createStopped( string `$callback` , string `$data` = ?, string `$priority` = ?): object

The same as EvFork::__construct(), but doesn't start the watcher automatically.

### 参数

`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 返回值

Returns EvFork(stopped) object on success.

### 参见

- EvFork::__construct() - Constructs the EvFork watcher object

## 目录

- EvFork::__construct — Constructs the EvFork watcher object
- EvFork::createStopped — Creates a stopped instance of EvFork watcher class

# The EvIdle class

(PECL ev >= 0.2.0)

## 简介

EvIdle watchers trigger events when no other events of the same or higher priority are pending ( EvPrepare, EvCheck and other EvIdle watchers do not count as receiving events ).

Thus, as long as the process is busy handling sockets or timeouts(or even signals) of the same or higher priority it will not be triggered. But when the process is in idle(or only lower-priority watchers are pending), the EvIdle watchers are being called once per event loop iteration - until stopped, that is, or the process receives more events and becomes busy again with higher priority stuff.

Apart from keeping the process non-blocking(which is a useful on its own sometimes), EvIdle watchers are a good place to do "pseudo-background processing", or delay processing stuff to after the event loop has handled all outstanding events.

The most noticeable effect is that as long as any idle watchers are active, the process will not block when waiting for new events.

## 类摘要

class EvIdle extends EvWatcher {
/* 继承的属性 */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* 方法 */
public function __construct( callable `$callback` , mixed `$data` = ?, int `$priority` = ?)
final public static function createStopped( string `$callback` , mixed `$data` = ?, int `$priority` = ?): object
/* 继承的方法 */
public function EvWatcher::clear(): int
public function EvWatcher::feed( int `$revents` ): void
public function EvWatcher::getLoop(): EvLoop
public function EvWatcher::invoke( int `$revents` ): void
public function EvWatcher::keepalive( bool `$value` = ?): bool
public function EvWatcher::setCallback( callable `$callback` ): void
public function EvWatcher::start(): void
public function EvWatcher::stop(): void
}

# EvIdle::__construct

(PECL ev >= 0.2.0)

EvIdle::__construct — Constructs the EvIdle watcher object

### 说明

public function EvIdle::__construct( callable `$callback` , mixed `$data` = ?, int `$priority` = ?)

Constructs the EvIdle watcher object and starts the watcher automatically.

### 参数

`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 参见

- EvIdle::createStopped() - Creates instance of a stopped EvIdle watcher object
- EvLoop::idle() - Creates EvIdle watcher object associated with the current event loop instance

# EvIdle::createStopped

(PECL ev >= 0.2.0)

EvIdle::createStopped — Creates instance of a stopped EvIdle watcher object

### 说明

final public static function EvIdle::createStopped( string `$callback` , mixed `$data` = ?, int `$priority` = ?): object

The same as EvIdle::__construct(), but doesn't start the watcher automatically.

### 参数

`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 返回值

Returns EvIdle object on success.

### 参见

- EvIdle::__construct() - Constructs the EvIdle watcher object
- EvLoop::idle() - Creates EvIdle watcher object associated with the current event loop instance

## 目录

- EvIdle::__construct — Constructs the EvIdle watcher object
- EvIdle::createStopped — Creates instance of a stopped EvIdle watcher object

# The EvIo class

(PECL ev >= 0.2.0)

## 简介

EvIo watchers check whether a file descriptor(or socket, or a stream castable to numeric file descriptor) is readable or writable in each iteration of the event loop, or, more precisely, when reading would not block the process and writing would at least be able to write some data. This behaviour is called level-triggering because events are kept receiving as long as the condition persists. To stop receiving events just stop the watcher.

The number of read and/or write event watchers per `fd` is unlimited. Setting all file descriptors to non-blocking mode is also usually a good idea(but not required).

Another thing to watch out for is that it is quite easy to receive false readiness notifications, i.e. the callback might be called with `Ev::READ` but a subsequent read() will actually block because there is no data. It is very easy to get into this situation. Thus it is best to always use non-blocking I/O: An extra read() returning `EAGAIN` (or similar) is far preferable to a program hanging until some data arrives.

If for some reason it is impossible to run the `fd` in non-blocking mode, then separately re-test whether a file descriptor is really ready. Some people additionally use `SIGALRM` and an interval timer, just to be sure they won't block infinitely.

Always consider using non-blocking mode.

## 类摘要

class EvIo extends EvWatcher {
/* 属性 */
public $fd;
public $events;
/* 继承的属性 */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* 方法 */
public function __construct(
mixed `$fd` ,
int `$events` ,
callable `$callback` ,
mixed `$data` = ?,
int `$priority` = ?
)
final public static function createStopped(
mixed `$fd` ,
int `$events` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
): EvIo
public function set( mixed `$fd` , int `$events` ): void
/* 继承的方法 */
public function EvWatcher::clear(): int
public function EvWatcher::feed( int `$revents` ): void
public function EvWatcher::getLoop(): EvLoop
public function EvWatcher::invoke( int `$revents` ): void
public function EvWatcher::keepalive( bool `$value` = ?): bool
public function EvWatcher::setCallback( callable `$callback` ): void
public function EvWatcher::start(): void
public function EvWatcher::stop(): void
}

## 属性

fd
events

# EvIo::__construct

(PECL ev >= 0.2.0)

EvIo::__construct — Constructs EvIo watcher object

### 说明

public function EvIo::__construct(
mixed `$fd` ,
int `$events` ,
callable `$callback` ,
mixed `$data` = ?,
int `$priority` = ?
)

Constructs EvIo watcher object and starts the watcher automatically.

### 参数

`fd`
  Can be a stream opened with fopen() or similar functions, numeric file descriptor, or socket.
`events`
  `Ev::READ` and/or `Ev::WRITE`. See the bit masks.
`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 参见

- EvIo::createStopped() - Create stopped EvIo watcher object
- EvLoop::io() - Create EvIo watcher object associated with the current event loop instance

# EvIo::createStopped

(PECL ev >= 0.2.0)

EvIo::createStopped — Create stopped EvIo watcher object

### 说明

final public static function EvIo::createStopped(
mixed `$fd` ,
int `$events` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
): EvIo

The same as EvIo::__construct(), but doesn't start the watcher automatically.

### 参数

`fd`
  The same as for EvIo::__construct()
`events`
  The same as for EvIo::__construct()
`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 返回值

Returns EvIo object on success.

### 参见

- EvIo::__construct() - Constructs EvIo watcher object
- EvLoop::io() - Create EvIo watcher object associated with the current event loop instance

# EvIo::set

(PECL ev >= 0.2.0)

EvIo::set — Configures the watcher

### 说明

public function EvIo::set( mixed `$fd` , int `$events` ): void

Configures the EvIo watcher

### 参数

`fd`
  The same as for EvIo::__construct()
`events`
  The same as for EvIo::__construct()

### 返回值

没有返回值。

## 目录

- EvIo::__construct — Constructs EvIo watcher object
- EvIo::createStopped — Create stopped EvIo watcher object
- EvIo::set — Configures the watcher

# The EvLoop class

(PECL ev >= 0.2.0)

## 简介

Represents an event loop that is always distinct from the default loop. Unlike the default loop, it cannot handle EvChild watchers.

Having threads we have to create a loop per thread, and use the default loop in the parent thread.

The default event loop is initialized automatically by Ev. It is accessible via methods of the Ev class, or via EvLoop::defaultLoop() method.

## 类摘要

final class EvLoop {
/* 属性 */
public $data;
public $backend;
public $is_default_loop;
public $iteration;
public $pending;
public $io_interval;
public $timeout_interval;
public $depth;
/* 方法 */
public function __construct(
int `$flags` = ?,
mixed `$data` = NULL ,
float `$io_interval` = 0.0 ,
float `$timeout_interval` = 0.0
)
public function backend(): int
final public function check( string `$callback` , string `$data` = ?, string `$priority` = ?): EvCheck
final public function child(
string `$pid` ,
string `$trace` ,
string `$callback` ,
string `$data` = ?,
string `$priority` = ?
): EvChild
public static function defaultLoop(
int `$flags` = Ev::FLAG_AUTO ,
mixed `$data` = NULL ,
float `$io_interval` = 0. ,
float `$timeout_interval` = 0.
): EvLoop
final public function embed(
string `$other` ,
string `$callback` = ?,
string `$data` = ?,
string `$priority` = ?
): EvEmbed
final public function fork( callable `$callback` , mixed `$data` = `null` , int `$priority` = 0 ): EvFork
final public function idle( callable `$callback` , mixed `$data` = `null` , int `$priority` = 0 ): EvIdle
public function invokePending(): void
final public function io(
mixed `$fd` ,
int `$events` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
): EvIo
public function loopFork(): void
public function now(): float
public function nowUpdate(): void
final public function periodic(
float `$offset` ,
float `$interval` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
): EvPeriodic
final public function prepare( callable `$callback` , mixed `$data` = `null` , int `$priority` = 0 ): EvPrepare
public function resume(): void
public function run( int `$flags` = 0 ): void
final public function signal(
int `$signum` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
): EvSignal
final public function stat(
string `$path` ,
float `$interval` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
): EvStat
public function stop( int `$how` = ?): void
public function suspend(): void
final public function timer(
float `$after` ,
float `$repeat` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
): EvTimer
public function verify(): void
}

## 属性

data
  Custom data attached to loop
backend
  Readonly. The backend flags indicating the event backend in use.
is_default_loop
  Readonly. `true` if it is the default event loop.
iteration
  The current iteration count of the loop. See Ev::iteration()
pending
  The number of pending watchers. `0` indicates that there are no watchers pending.
io_interval
  Higher io_interval allows libev to spend more time collecting EvIo events, so more events can be handled per iteration, at the cost of increasing latency. Timeouts (both EvPeriodic and EvTimer) will not be affected. Setting this to a non-zero value will introduce an additional `sleep()` call into most loop iterations. The sleep time ensures that libev will not poll for EvIo events more often than once per this interval, on average. Many programs can usually benefit by setting the io_interval to a value near `0.1`, which is often enough for interactive servers(not for games). It usually doesn't make much sense to set it to a lower value than `0.01`, as this approaches the timing granularity of most systems. See also » FUNCTIONS CONTROLLING EVENT LOOPS.
timeout_interval
  Higher timeout_interval allows libev to spend more time collecting timeouts, at the expense of increased latency/jitter/inexactness(the watcher callback will be called later). EvIo watchers will not be affected. Setting this to a non-null value will not introduce any overhead in libev. See also » FUNCTIONS CONTROLLING EVENT LOOPS.
depth
  The recursion depth. See Ev::depth().

# EvLoop::backend

(PECL ev >= 0.2.0)

EvLoop::backend — Returns an integer describing the backend used by libev

### 说明

public function EvLoop::backend(): int

The same as Ev::backend(), but for the loop instance.

### 参数

此函数没有参数。

### 返回值

Returns an integer describing the backend used by libev. See Ev::backend().

### 参见

- Ev::backend() - Returns an integer describing the backend used by libev

# EvLoop::check

(PECL ev >= 0.2.0)

EvLoop::check — Creates EvCheck object associated with the current event loop instance

### 说明

final public function EvLoop::check( string `$callback` , string `$data` = ?, string `$priority` = ?): EvCheck

Creates EvCheck object associated with the current event loop instance.

### 参数

All parameters have the same meaning as for EvCheck::__construct()

### 返回值

Returns EvCheck object on success.

### 参见

- EvCheck::__construct() - Constructs the EvCheck watcher object

# EvLoop::child

(PECL ev >= 0.2.0)

EvLoop::child — Creates EvChild object associated with the current event loop

### 说明

final public function EvLoop::child(
string `$pid` ,
string `$trace` ,
string `$callback` ,
string `$data` = ?,
string `$priority` = ?
): EvChild

Creates EvChild object associated with the current event loop.

### 参数

All parameters have the same meaning as for EvChild::__construct()

### 返回值

Returns EvChild object on success.

### 参见

- EvChild::__construct() - Constructs the EvChild watcher object

# EvLoop::__construct

(PECL ev >= 0.2.0)

EvLoop::__construct — Constructs the event loop object

### 说明

public function EvLoop::__construct(
int `$flags` = ?,
mixed `$data` = NULL ,
float `$io_interval` = 0.0 ,
float `$timeout_interval` = 0.0
)

Constructs the event loop object.

### 参数

`flags`
  One of the event loop flags
`data`
  Custom data associated with the loop.
`io_interval`
  See io_interval
`timeout_interval`
  See timeout_interval

### 参见

- EvLoop::defaultLoop() - Returns or creates the default event loop

# EvLoop::defaultLoop

(PECL ev >= 0.2.0)

EvLoop::defaultLoop — Returns or creates the default event loop

### 说明

public static function EvLoop::defaultLoop(
int `$flags` = Ev::FLAG_AUTO ,
mixed `$data` = NULL ,
float `$io_interval` = 0. ,
float `$timeout_interval` = 0.
): EvLoop

If the default event loop is not created, EvLoop::defaultLoop() creates it with the specified parameters. Otherwise, it just returns the object representing previously created instance ignoring all the parameters.

### 参数

`flags`
  One of the event loop flags
`data`
  Custom data to associate with the loop.
`io_collect_interval`
  See io_interval
`timeout_collect_interval`
  See timeout_interval

### 返回值

Returns EvLoop object on success.

### 参见

- EvLoop::__construct() - Constructs the event loop object

# EvLoop::embed

(PECL ev >= 0.2.0)

EvLoop::embed — Creates an instance of EvEmbed watcher associated with the current EvLoop object

### 说明

final public function EvLoop::embed(
string `$other` ,
string `$callback` = ?,
string `$data` = ?,
string `$priority` = ?
): EvEmbed

Creates an instance of EvEmbed watcher associated with the current EvLoop object.

### 参数

All parameters have the same meaning as for EvEmbed::__construct().

### 返回值

Returns EvEmbed object on success.

### 参见

- EvEmbed::__construct() - Constructs the EvEmbed object

# EvLoop::fork

(PECL ev >= 0.2.0)

EvLoop::fork — Creates EvFork watcher object associated with the current event loop instance

### 说明

final public function EvLoop::fork( callable `$callback` , mixed `$data` = `null` , int `$priority` = 0 ): EvFork

Creates EvFork watcher object associated with the current event loop instance

### 参数

All parameters have the same meaning as for EvFork::__construct()

### 返回值

Returns EvFork object on success.

### 参见

- EvFork::__construct() - Constructs the EvFork watcher object

# EvLoop::idle

(PECL ev >= 0.2.0)

EvLoop::idle — Creates EvIdle watcher object associated with the current event loop instance

### 说明

final public function EvLoop::idle( callable `$callback` , mixed `$data` = `null` , int `$priority` = 0 ): EvIdle

Creates EvIdle watcher object associated with the current event loop instance

### 参数

All the parameters have the same meaning as for EvIdle::__construct()

### 返回值

Returns EvIdle object on success.

### 参见

- EvIdle::__construct() - Constructs the EvIdle watcher object

# EvLoop::invokePending

(PECL ev >= 0.2.0)

EvLoop::invokePending — Invoke all pending watchers while resetting their pending state

### 说明

public function EvLoop::invokePending(): void

Invoke all pending watchers while resetting their pending state.

### 参数

此函数没有参数。

### 返回值

没有返回值。

# EvLoop::io

(PECL ev >= 0.2.0)

EvLoop::io — Create EvIo watcher object associated with the current event loop instance

### 说明

final public function EvLoop::io(
mixed `$fd` ,
int `$events` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
): EvIo

Create EvIo watcher object associated with the current event loop instance.

### 参数

All parameters have the same meaning as for EvIo::__construct()

### 返回值

Returns EvIo object on success.

### 参见

- EvIo::__construct() - Constructs EvIo watcher object

# EvLoop::loopFork

(PECL ev >= 0.2.0)

EvLoop::loopFork — Must be called after a fork

### 说明

public function EvLoop::loopFork(): void

Must be called after a fork in the child, before entering or continuing the event loop. An alternative is to use `Ev::FLAG_FORKCHECK` which calls this function automatically, at some performance loss (refer to the » libev documentation ).

### 参数

此函数没有参数。

### 返回值

没有返回值。

# EvLoop::now

(PECL ev >= 0.2.0)

EvLoop::now — Returns the current "event loop time"

### 说明

public function EvLoop::now(): float

Returns the current "event loop time", which is the time the event loop received events and started processing them. This timestamp does not change as long as callbacks are being processed, and this is also the base time used for relative timers. You can treat it as the timestamp of the event occurring(or more correctly, libev finding out about it).

### 参数

此函数没有参数。

### 返回值

Returns time of the event loop in (fractional) seconds.

### 参见

- Ev::now() - Returns the time when the last iteration of the default event loop has started

# EvLoop::nowUpdate

(PECL ev >= 0.2.0)

EvLoop::nowUpdate — Establishes the current time by querying the kernel, updating the time returned by EvLoop::now in the progress

### 说明

public function EvLoop::nowUpdate(): void

Establishes the current time by querying the kernel, updating the time returned by EvLoop::now() in the progress. This is a costly operation and is usually done automatically within EvLoop::run().

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 参见

- EvLoop::now() - Returns the current "event loop time"
- Ev::nowUpdate() - Establishes the current time by querying the kernel, updating the time returned by Ev::now in the progress

# EvLoop::periodic

(PECL ev >= 0.2.0)

EvLoop::periodic — Creates EvPeriodic watcher object associated with the current event loop instance

### 说明

final public function EvLoop::periodic(
float `$offset` ,
float `$interval` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
): EvPeriodic

Creates EvPeriodic watcher object associated with the current event loop instance

### 参数

All parameters have the same meaning as for EvPeriodic::__construct()

### 返回值

Returns EvPeriodic object on success.

### 参见

- EvPeriodic::__construct() - Constructs EvPeriodic watcher object

# EvLoop::prepare

(PECL ev >= 0.2.0)

EvLoop::prepare — Creates EvPrepare watcher object associated with the current event loop instance

### 说明

final public function EvLoop::prepare( callable `$callback` , mixed `$data` = `null` , int `$priority` = 0 ): EvPrepare

Creates EvPrepare watcher object associated with the current event loop instance

### 参数

All parameters have the same meaning as for EvPrepare()

### 返回值

Returns EvPrepare object on success

### 参见

- EvPrepare::__construct() - Constructs EvPrepare watcher object

# EvLoop::resume

(PECL ev >= 0.2.0)

EvLoop::resume — Resume previously suspended default event loop

### 说明

public function EvLoop::resume(): void

EvLoop::suspend() and EvLoop::resume() methods suspend and resume a loop correspondingly.

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 参见

- EvLoop::suspend() - Suspend the loop
- Ev::resume() - Resume previously suspended default event loop

# EvLoop::run

(PECL ev >= 0.2.0)

EvLoop::run — Begin checking for events and calling callbacks for the loop

### 说明

public function EvLoop::run( int `$flags` = 0 ): void

Begin checking for events and calling callbacks for the current event loop. Returns when a callback calls Ev::stop() method, or the flags are nonzero(in which case the return value is true) or when there are no active watchers which reference the loop( EvWatcher::keepalive() is `true`), in which case the return value will be `false`. The return value can generally be interpreted as if `true`, there is more work left to do.

### 参数

`flags`

  Optional parameter `flags` can be one of the following:

  List for possible values of `flags`
  `flags` | Description
  --- | ---
  `0` | The default behavior described above
  `Ev::RUN_ONCE` | Block at most one(wait, but don't loop)
  `Ev::RUN_NOWAIT` | Don't block at all(fetch/handle events, but don't wait)

  See the run flag constants.

### 返回值

没有返回值。

### 参见

- EvLoop::stop() - Stops the event loop
- Ev::run() - Begin checking for events and calling callbacks for the default loop

# EvLoop::signal

(PECL ev >= 0.2.0)

EvLoop::signal — Creates EvSignal watcher object associated with the current event loop instance

### 说明

final public function EvLoop::signal(
int `$signum` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
): EvSignal

Creates EvSignal watcher object associated with the current event loop instance

### 参数

All parameters have the same meaning as for EvSignal::__construct()

### 返回值

Returns EvSignal object on success

### 参见

- EvSignal::__construct() - Constructs EvSignal watcher object

# EvLoop::stat

(PECL ev >= 0.2.0)

EvLoop::stat — Creates EvStat watcher object associated with the current event loop instance

### 说明

final public function EvLoop::stat(
string `$path` ,
float `$interval` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
): EvStat

Creates EvStat watcher object associated with the current event loop instance

### 参数

All parameters have the same meaning as for EvSignal::__construct()

### 返回值

Returns EvStat object on success

### 参见

- EvSignal::__construct() - Constructs EvSignal watcher object

# EvLoop::stop

(PECL ev >= 0.2.0)

EvLoop::stop — Stops the event loop

### 说明

public function EvLoop::stop( int `$how` = ?): void

Stops the event loop

### 参数

`how`
  One of Ev::BREAK_* constants.

### 返回值

没有返回值。

### 参见

- EvLoop::run() - Begin checking for events and calling callbacks for the loop
- Ev::stop() - Stops the default event loop

# EvLoop::suspend

(PECL ev >= 0.2.0)

EvLoop::suspend — Suspend the loop

### 说明

public function EvLoop::suspend(): void

EvLoop::suspend() and EvLoop::resume() methods suspend and resume a loop correspondingly.

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 参见

- EvLoop::resume() - Resume previously suspended default event loop
- Ev::suspend() - Suspend the default event loop

# EvLoop::timer

(PECL ev >= 0.2.0)

EvLoop::timer — Creates EvTimer watcher object associated with the current event loop instance

### 说明

final public function EvLoop::timer(
float `$after` ,
float `$repeat` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
): EvTimer

Creates EvTimer watcher object associated with the current event loop instance

### 参数

All parameters have the same meaning as for EvTimer::__construct()

### 返回值

Returns EvTimer object on success

### 参见

- EvTimer::__construct() - Constructs an EvTimer watcher object

# EvLoop::verify

(PECL ev >= 0.2.0)

EvLoop::verify — Performs internal consistency checks(for debugging)

### 说明

public function EvLoop::verify(): void

Performs internal consistency checks(for debugging libev) and abort the program if any data structures were found to be corrupted.

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 参见

- Ev::verify() - Performs internal consistency checks(for debugging)

## 目录

- EvLoop::backend — Returns an integer describing the backend used by libev
- EvLoop::check — Creates EvCheck object associated with the current event loop instance
- EvLoop::child — Creates EvChild object associated with the current event loop
- EvLoop::__construct — Constructs the event loop object
- EvLoop::defaultLoop — Returns or creates the default event loop
- EvLoop::embed — Creates an instance of EvEmbed watcher associated with the current EvLoop object
- EvLoop::fork — Creates EvFork watcher object associated with the current event loop instance
- EvLoop::idle — Creates EvIdle watcher object associated with the current event loop instance
- EvLoop::invokePending — Invoke all pending watchers while resetting their pending state
- EvLoop::io — Create EvIo watcher object associated with the current event loop instance
- EvLoop::loopFork — Must be called after a fork
- EvLoop::now — Returns the current "event loop time"
- EvLoop::nowUpdate — Establishes the current time by querying the kernel, updating the time returned by EvLoop::now in the progress
- EvLoop::periodic — Creates EvPeriodic watcher object associated with the current event loop instance
- EvLoop::prepare — Creates EvPrepare watcher object associated with the current event loop instance
- EvLoop::resume — Resume previously suspended default event loop
- EvLoop::run — Begin checking for events and calling callbacks for the loop
- EvLoop::signal — Creates EvSignal watcher object associated with the current event loop instance
- EvLoop::stat — Creates EvStat watcher object associated with the current event loop instance
- EvLoop::stop — Stops the event loop
- EvLoop::suspend — Suspend the loop
- EvLoop::timer — Creates EvTimer watcher object associated with the current event loop instance
- EvLoop::verify — Performs internal consistency checks(for debugging)

# The EvPeriodic class

(PECL ev >= 0.2.0)

## 简介

Periodic watchers are also timers of a kind, but they are very versatile.

Unlike EvTimer, EvPeriodic watchers are not based on real time(or relative time, the physical time that passes) but on wall clock time(absolute time, calendar or clock). The difference is that wall clock time can run faster or slower than real time, and time jumps are not uncommon(e.g. when adjusting it).

EvPeriodic watcher can be configured to trigger after some specific point in time. For example, if an EvPeriodic watcher is configured to trigger "in 10 seconds" (e.g. EvLoop::now() + `10.0`, i.e. an absolute time, not a delay), and the system clock is reset to January of the previous year, then it will take a year or more to trigger the event (unlike an EvTimer, which would still trigger roughly `10` seconds after starting it as it uses a relative timeout).

As with timers, the callback is guaranteed to be invoked only when the point in time where it is supposed to trigger has passed. If multiple timers become ready during the same loop iteration then the ones with earlier time-out values are invoked before ones with later time-out values (but this is no longer true when a callback calls EvLoop::run() recursively).

## 类摘要

class EvPeriodic extends EvWatcher {
/* 属性 */
public $offset;
public $interval;
/* 继承的属性 */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* 方法 */
public function __construct(
float `$offset` ,
string `$interval` ,
callable `$reschedule_cb` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
)
public function again(): void
public function at(): float
final public static function createStopped(
float `$offset` ,
float `$interval` ,
callable `$reschedule_cb` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
): EvPeriodic
public function set( float `$offset` , float `$interval` ): void
/* 继承的方法 */
public function EvWatcher::clear(): int
public function EvWatcher::feed( int `$revents` ): void
public function EvWatcher::getLoop(): EvLoop
public function EvWatcher::invoke( int `$revents` ): void
public function EvWatcher::keepalive( bool `$value` = ?): bool
public function EvWatcher::setCallback( callable `$callback` ): void
public function EvWatcher::start(): void
public function EvWatcher::stop(): void
}

## 属性

offset
  When repeating, this contains the offset value, otherwise this is the absolute point in time(the offset value passed to EvPeriodic::set(), although libev might modify this value for better numerical stability).
interval
  The current interval value. Can be modified any time, but changes only take effect when the periodic timer fires or EvPeriodic::again() is being called.

# EvPeriodic::again

(PECL ev >= 0.2.0)

EvPeriodic::again — Simply stops and restarts the periodic watcher again

### 说明

public function EvPeriodic::again(): void

Simply stops and restarts the periodic watcher again. This is only useful when attributes are changed.

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 参见

- EvTimer::again() - Restarts the timer watcher

# EvPeriodic::at

(PECL ev >= 0.2.0)

EvPeriodic::at — Returns the absolute time that this watcher is supposed to trigger next

### 说明

public function EvPeriodic::at(): float

When the watcher is active, returns the absolute time that this watcher is supposed to trigger next. This is not the same as the offset argument to EvPeriodic::set() or EvPeriodic::__construct(), but indeed works even in interval mode.

### 参数

此函数没有参数。

### 返回值

Returns the absolute time this watcher is supposed to trigger next in seconds.

# EvPeriodic::__construct

(PECL ev >= 0.2.0)

EvPeriodic::__construct — Constructs EvPeriodic watcher object

### 说明

public function EvPeriodic::__construct(
float `$offset` ,
string `$interval` ,
callable `$reschedule_cb` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
)

Constructs EvPeriodic watcher object and starts it automatically. EvPeriodic::createStopped() method creates stopped periodic watcher.

### 参数

`offset`
  See Periodic watcher operation modes
`interval`
  See Periodic watcher operation modes
`reschedule_cb`
  Reschedule callback. You can pass `null`. See Periodic watcher operation modes
`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 示例

示例 #1 Periodic timer. Use reschedule callback

    <?php
    // Tick each 10.5 seconds

    function reschedule_cb ($watcher, $now) {
     return $now + (10.5 - fmod($now, 10.5));
    }

    $w = new EvPeriodic(0., 0., "reschedule_cb", function ($w, $revents) {
     echo time(), PHP_EOL;
    });
    Ev::run();
    ?>

示例 #2 Periodic timer. Tick every 10.5 seconds starting at now

    <?php
    // Tick every 10.5 seconds starting at now
    $w = new EvPeriodic(fmod(Ev::now(), 10.5), 10.5, NULL, function ($w, $revents) {
     echo time(), PHP_EOL;
    });
    Ev::run();
    ?>

示例 #3 Hourly watcher

    <?php
    $hourly = EvPeriodic(0, 3600, NULL, function () {
     echo "once per hour\n";
    });
    ?>

### 参见

- Periodic watcher operation modes
- EvTimer
- EvPeriodic::createStopped() - Create a stopped EvPeriodic watcher

# EvPeriodic::createStopped

(PECL ev >= 0.2.0)

EvPeriodic::createStopped — Create a stopped EvPeriodic watcher

### 说明

final public static function EvPeriodic::createStopped(
float `$offset` ,
float `$interval` ,
callable `$reschedule_cb` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
): EvPeriodic

Create EvPeriodic object. Unlike EvPeriodic::__construct() this method doesn't start the watcher automatically.

### 参数

`offset`
  See Periodic watcher operation modes
`interval`
  See Periodic watcher operation modes
`reschedule_cb`
  Reschedule callback. You can pass `null`. See Periodic watcher operation modes
`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 返回值

Returns EvPeriodic watcher object on success.

### 参见

- EvPeriodic::__construct() - Constructs EvPeriodic watcher object
- EvTimer::createStopped() - Creates EvTimer stopped watcher object

# EvPeriodic::set

(PECL ev >= 0.2.0)

EvPeriodic::set — Configures the watcher

### 说明

public function EvPeriodic::set( float `$offset` , float `$interval` ): void

(Re-)Configures EvPeriodic watcher

### 参数

`offset`
  The same meaning as for EvPeriodic::__construct(). See Periodic watcher operation modes
`interval`
  The same meaning as for EvPeriodic::__construct(). See Periodic watcher operation modes

### 返回值

没有返回值。

## 目录

- EvPeriodic::again — Simply stops and restarts the periodic watcher again
- EvPeriodic::at — Returns the absolute time that this watcher is supposed to trigger next
- EvPeriodic::__construct — Constructs EvPeriodic watcher object
- EvPeriodic::createStopped — Create a stopped EvPeriodic watcher
- EvPeriodic::set — Configures the watcher

# The EvPrepare class

(PECL ev >= 0.2.0)

## 简介

EvPrepare and EvCheck watchers are usually used in pairs. EvPrepare watchers get invoked before the process blocks, EvCheck afterwards.

It is not allowed to call EvLoop::run() or similar methods or functions that enter the current event loop from either EvPrepare or EvCheck watchers. Other loops than the current one are fine, however. The rationale behind this is that one don't need to check for recursion in those watchers, i.e. the sequence will always be: EvPrepare -> blocking -> EvCheck, so having a watcher of each kind they will always be called in pairs bracketing the blocking call.

The main purpose is to integrate other event mechanisms into libev and their use is somewhat advanced. They could be used, for example, to track variable changes, implement custom watchers, integrate net-snmp or a coroutine library and lots more. They are also occasionally useful to cache some data and want to flush it before blocking.

It is recommended to give EvCheck watchers highest( `Ev::MAXPRI`) priority, to ensure that they are being run before any other watchers after the poll (this doesn’t matter for EvPrepare watchers).

Also, EvCheck watchers should not activate/feed events. While libev fully supports this, they might get executed before other EvCheck watchers did their job.

## 类摘要

class EvPrepare extends EvWatcher {
/* 继承的属性 */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* 方法 */
public function __construct( string `$callback` , string `$data` = ?, string `$priority` = ?)
final public static function createStopped( callable `$callback` , mixed `$data` = `null` , int `$priority` = 0 ): EvPrepare
/* 继承的方法 */
public function EvWatcher::clear(): int
public function EvWatcher::feed( int `$revents` ): void
public function EvWatcher::getLoop(): EvLoop
public function EvWatcher::invoke( int `$revents` ): void
public function EvWatcher::keepalive( bool `$value` = ?): bool
public function EvWatcher::setCallback( callable `$callback` ): void
public function EvWatcher::start(): void
public function EvWatcher::stop(): void
}

# EvPrepare::__construct

(PECL ev >= 0.2.0)

EvPrepare::__construct — Constructs EvPrepare watcher object

### 说明

public function EvPrepare::__construct( string `$callback` , string `$data` = ?, string `$priority` = ?)

Constructs EvPrepare watcher object. And starts the watcher automatically. If a stopped watcher is needed, consider using EvPrepare::createStopped()

### 参数

`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 参见

- EvCheck

# EvPrepare::createStopped

(PECL ev >= 0.2.0)

EvPrepare::createStopped — Creates a stopped instance of EvPrepare watcher

### 说明

final public static function EvPrepare::createStopped( callable `$callback` , mixed `$data` = `null` , int `$priority` = 0 ): EvPrepare

Creates a stopped instance of EvPrepare watcher. Unlike EvPrepare::__construct(), this method doesn't start the watcher automatically.

### 参数

`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 返回值

Returns EvPrepare object on success.

### 参见

- EvPrepare::__construct() - Constructs EvPrepare watcher object
- EvWatcher::start() - Starts the watcher

## 目录

- EvPrepare::__construct — Constructs EvPrepare watcher object
- EvPrepare::createStopped — Creates a stopped instance of EvPrepare watcher

# The EvSignal class

(PECL ev >= 0.2.0)

## 简介

EvSignal watchers will trigger an event when the process receives a specific signal one or more times. Even though signals are very asynchronous, libev will try its best to deliver signals synchronously, i.e. as part of the normal event processing, like any other event.

There is no limit for the number of watchers for the same signal, but only within the same loop, i.e. one can watch for `SIGINT` in the default loop and for `SIGIO` in another loop, but it is not allowed to watch for `SIGINT` in both the default loop and another loop at the same time. At the moment, `SIGCHLD` is permanently tied to the default loop.

If possible and supported, libev will install its handlers with `SA_RESTART` (or equivalent) behaviour enabled, so system calls should not be unduly interrupted. In case of a problem with system calls getting interrupted by signals, all the signals can be blocked in an EvCheck watcher and unblocked in a EvPrepare watcher.

## 类摘要

class EvSignal extends EvWatcher {
/* 属性 */
public $signum;
/* 继承的属性 */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* 方法 */
public function __construct(
int `$signum` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
)
final public static function createStopped(
int `$signum` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
): EvSignal
public function set( int `$signum` ): void
/* 继承的方法 */
public function EvWatcher::clear(): int
public function EvWatcher::feed( int `$revents` ): void
public function EvWatcher::getLoop(): EvLoop
public function EvWatcher::invoke( int `$revents` ): void
public function EvWatcher::keepalive( bool `$value` = ?): bool
public function EvWatcher::setCallback( callable `$callback` ): void
public function EvWatcher::start(): void
public function EvWatcher::stop(): void
}

## 属性

signum
  Signal number. See the constants exported by pcntl extension. See also `signal(7)` man page.

# EvSignal::__construct

(PECL ev >= 0.2.0)

EvSignal::__construct — Constructs EvSignal watcher object

### 说明

public function EvSignal::__construct(
int `$signum` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
)

Constructs EvSignal watcher object and starts it automatically. For a stopped signal watcher consider using EvSignal::createStopped() method.

### 参数

`signum`
  Signal number. See constants exported by pcntl extension. See also `signal(7)` man page.
`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 示例

示例 #1 Handle SIGTERM signal

    <?php
    $w = new EvSignal(SIGTERM, function ($watcher) {
        echo "SIGTERM received\n";
        $watcher->stop();
    });

    Ev::run();
    ?>

### 参见

- EvSignal::createStopped() - Create stopped EvSignal watcher object

# EvSignal::createStopped

(PECL ev >= 0.2.0)

EvSignal::createStopped — Create stopped EvSignal watcher object

### 说明

final public static function EvSignal::createStopped(
int `$signum` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
): EvSignal

Create stopped EvSignal watcher object. Unlike EvSignal::__construct(), this method doesn't start the watcher automatically.

### 参数

`signum`
  Signal number. See constants exported by pcntl extension. See also `signal(7)` man page.
`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 返回值

Returns EvSignal object on success.

### 参见

- EvWatcher::start() - Starts the watcher
- EvSignal::__construct() - Constructs EvSignal watcher object

# EvSignal::set

(PECL ev >= 0.2.0)

EvSignal::set — Configures the watcher

### 说明

public function EvSignal::set( int `$signum` ): void

Configures the watcher.

### 参数

`signum`
  Signal number. The same as for EvSignal::__construct()

### 返回值

没有返回值。

## 目录

- EvSignal::__construct — Constructs EvSignal watcher object
- EvSignal::createStopped — Create stopped EvSignal watcher object
- EvSignal::set — Configures the watcher

# The EvStat class

(PECL ev >= 0.2.0)

## 简介

EvStat monitors a file system path for attribute changes. It calls stat() on that path in regular intervals (or when the OS signals it changed) and sees if it changed compared to the last time, invoking the callback if it did.

The path does not need to exist: changing from "path exists" to "path does not exist" is a status change like any other. The condition "path does not exist" is signified by the `'nlink'` item being 0(returned by EvStat::attr() method).

The path must not end in a slash or contain special components such as `'.'` or `..`. The path should be absolute: if it is relative and the working directory changes, then the behaviour is undefined.

Since there is no portable change notification interface available, the portable implementation simply calls stat() regularly on the path to see if it changed somehow. For this case a recommended polling interval can be specified. If one specifies a polling interval of `0.0` (highly recommended) then a suitable, unspecified default value will be used(which could be expected to be around 5 seconds, although this might change dynamically). libev will also impose a minimum interval which is currently around `0.1`, but that’s usually overkill.

This watcher type is not meant for massive numbers of EvStat watchers, as even with OS-supported change notifications, this can be resource-intensive.

## 类摘要

class EvStat extends EvWatcher {
/* 属性 */
public $path;
public $interval;
/* 继承的属性 */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* 方法 */
public function __construct(
string `$path` ,
float `$interval` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
)
public function attr(): array
final public static function createStopped(
string `$path` ,
float `$interval` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
): void
public function prev(): void
public function set( string `$path` , float `$interval` ): void
public function stat(): bool
/* 继承的方法 */
public function EvWatcher::clear(): int
public function EvWatcher::feed( int `$revents` ): void
public function EvWatcher::getLoop(): EvLoop
public function EvWatcher::invoke( int `$revents` ): void
public function EvWatcher::keepalive( bool `$value` = ?): bool
public function EvWatcher::setCallback( callable `$callback` ): void
public function EvWatcher::start(): void
public function EvWatcher::stop(): void
}

## 属性

interval
  Readonly. Hint on how quickly a change is expected to be detected and should normally be specified as `0.0` to let libev choose a suitable value.
path
  Readonly. The path to wait for status changes on.

# EvStat::attr

(PECL ev >= 0.2.0)

EvStat::attr — Returns the values most recently detected by Ev

### 说明

public function EvStat::attr(): array

Returns array of the values most recently detected by Ev

### 参数

此函数没有参数。

### 返回值

Returns array with the values most recently detect by Ev(without actual `stat` 'ing):

List for item keys of the array returned by EvStat::attr()
Key | Description
--- | ---
`'dev'` | ID of device containing file
`'ino'` | inode number
`'mode'` | protection
`'nlink'` | number of hard links
`'uid'` | user ID of owner
`'size'` | total size, in bytes
`'gid'` | group ID of owner
`'rdev'` | device ID (if special file)
`'blksize'` | blocksize for file system I/O
`'blocks'` | number of 512B blocks allocated
`'atime'` | time of last access
`'ctime'` | time of last status change
`'mtime'` | time of last modification

See `stat(2)` man page for details.

### 示例

示例 #1 Monitor changes of /var/log/messages

    <?php
    // Use 10 second update interval.
    $w = new EvStat("/var/log/messages", 8, function ($w) {
        echo "/var/log/messages changed\n";

        $attr = $w->attr();

        if ($attr['nlink']) {
            printf("Current size: %ld\n", $attr['size']);
            printf("Current atime: %ld\n", $attr['atime']);
            printf("Current mtime: %ld\n", $attr['mtime']);
        } else {
            fprintf(STDERR, "`messages` file is not there!");
            $w->stop();
        }
    });

    Ev::run();
    ?>

### 参见

- EvStat::prev() - Returns the previous set of values returned by EvStat::attr
- EvStat::stat() - Initiates the stat call

# EvStat::__construct

(PECL ev >= 0.2.0)

EvStat::__construct — Constructs EvStat watcher object

### 说明

public function EvStat::__construct(
string `$path` ,
float `$interval` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
)

Constructs EvStat watcher object and starts the watcher automatically.

### 参数

`path`
  The path to wait for status changes on.
`interval`
  Hint on how quickly a change is expected to be detected and should normally be specified as `0.0` to let libev choose a suitable value.
`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 示例

示例 #1 Monitor changes of /var/log/messages

    <?php

    // Use 10 second update interval.
    $w = new EvStat("/var/log/messages", 10, function ($w) {
        echo "/var/log/messages changed\n";

        $attr = $w->attr();

        if ($attr['nlink']) {
            printf("Current size: %ld\n", $attr['size']);
            printf("Current atime: %ld\n", $attr['atime']);
            printf("Current mtime: %ld\n", $attr['mtime']);
        } else {
            fprintf(STDERR, "`messages` file is not there!");
            $w->stop();
        }
    });

    ?>

# EvStat::createStopped

(PECL ev >= 0.2.0)

EvStat::createStopped — Create a stopped EvStat watcher object

### 说明

final public static function EvStat::createStopped(
string `$path` ,
float `$interval` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
): void

Creates EvStat watcher object, but doesn't start it automatically(unlike EvStat::__construct() ).

### 参数

`path`
  The path to wait for status changes on.
`interval`
  Hint on how quickly a change is expected to be detected and should normally be specified as `0.0` to let libev choose a suitable value.
`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 返回值

Returns a stopped EvStat watcher object on success.

### 参见

- EvStat::__construct() - Constructs EvStat watcher object
- EvWatcher::start() - Starts the watcher

# EvStat::prev

(PECL ev >= 0.2.0)

EvStat::prev — Returns the previous set of values returned by EvStat::attr

### 说明

public function EvStat::prev(): void

Just like EvStat::attr(), but returns the previous set of values.

### 参数

此函数没有参数。

### 返回值

Returns an array with the same structure as the array returned by EvStat::attr(). The array contains previously detected values.

### 参见

- EvStat::attr() - Returns the values most recently detected by Ev
- EvStat::stat() - Initiates the stat call

# EvStat::set

(PECL ev >= 0.2.0)

EvStat::set — Configures the watcher

### 说明

public function EvStat::set( string `$path` , float `$interval` ): void

Configures the watcher.

### 参数

`path`
  The path to wait for status changes on.
`interval`
  Hint on how quickly a change is expected to be detected and should normally be specified as `0.0` to let libev choose a suitable value.

### 返回值

没有返回值。

# EvStat::stat

(PECL ev >= 0.2.0)

EvStat::stat — Initiates the stat call

### 说明

public function EvStat::stat(): bool

Initiates the stat call(updates internal cache). It stats(using `lstat`) the path specified in the watcher and sets to the values found.

### 参数

此函数没有参数。

### 返回值

Returns `true` if path exists. Otherwise `false`.

### 参见

- EvStat::attr() - Returns the values most recently detected by Ev
- EvStat::prev() - Returns the previous set of values returned by EvStat::attr

## 目录

- EvStat::attr — Returns the values most recently detected by Ev
- EvStat::__construct — Constructs EvStat watcher object
- EvStat::createStopped — Create a stopped EvStat watcher object
- EvStat::prev — Returns the previous set of values returned by EvStat::attr
- EvStat::set — Configures the watcher
- EvStat::stat — Initiates the stat call

# The EvTimer class

(PECL ev >= 0.2.0)

## 简介

EvTimer watchers are simple relative timers that generate an event after a given time, and optionally repeating in regular intervals after that.

The timers are based on real time, that is, if one registers an event that times out after an hour and resets the system clock to January last year, it will still time out after(roughly) one hour. "Roughly" because detecting time jumps is hard, and some inaccuracies are unavoidable.

The callback is guaranteed to be invoked only after its timeout has passed (not at, so on systems with very low-resolution clocks this might introduce a small delay). If multiple timers become ready during the same loop iteration then the ones with earlier time-out values are invoked before ones of the same priority with later time-out values (but this is no longer true when a callback calls EvLoop::run() recursively).

The timer itself will do a best-effort at avoiding drift, that is, if a timer is configured to trigger every `10` seconds, then it will normally trigger at exactly `10` second intervals. If, however, the script cannot keep up with the timer because it takes longer than those `10` seconds to do) the timer will not fire more than once per event loop iteration.

## 类摘要

class EvTimer extends EvWatcher {
/* 属性 */
public $repeat;
public $remaining;
/* 继承的属性 */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* 方法 */
public function __construct(
float `$after` ,
float `$repeat` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
)
public function again(): void
final public static function createStopped(
float `$after` ,
float `$repeat` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
): EvTimer
public function set( float `$after` , float `$repeat` ): void
/* 继承的方法 */
public function EvWatcher::clear(): int
public function EvWatcher::feed( int `$revents` ): void
public function EvWatcher::getLoop(): EvLoop
public function EvWatcher::invoke( int `$revents` ): void
public function EvWatcher::keepalive( bool `$value` = ?): bool
public function EvWatcher::setCallback( callable `$callback` ): void
public function EvWatcher::start(): void
public function EvWatcher::stop(): void
}

## 属性

repeat
  If repeat is `0.0`, then it will automatically be stopped once the timeout is reached. If it is positive, then the timer will automatically be configured to trigger again every repeat seconds later, until stopped manually.
remaining
  Returns the remaining time until a timer fires. If the timer is active, then this time is relative to the current event loop time, otherwise it's the timeout value currently configured. That is, after instantiating an EvTimer with an `after` value of `5.0` and `repeat` value of `7.0`, remaining returns `5.0`. When the timer is started and one second passes, remaining will return `4.0`. When the timer expires and is restarted, it will return roughly `7.0` (likely slightly less as callback invocation takes some time too), and so on.

# EvTimer::again

(PECL ev >= 0.2.0)

EvTimer::again — Restarts the timer watcher

### 说明

public function EvTimer::again(): void

This will act as if the timer timed out and restart it again if it is repeating. The exact semantics are:

1. if the timer is pending, its pending status is cleared.
2. if the timer is started but non-repeating, stop it (as if it timed out).
3. if the timer is repeating, either start it if necessary (with the repeat value), or reset the running timer to the repeat value.

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 参见

- EvWatcher::stop() - Stops the watcher

# EvTimer::__construct

(PECL ev >= 0.2.0)

EvTimer::__construct — Constructs an EvTimer watcher object

### 说明

public function EvTimer::__construct(
float `$after` ,
float `$repeat` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
)

Constructs an EvTimer watcher object.

### 参数

`after`
  Configures the timer to trigger after `after` seconds.
`repeat`
  If repeat is `0.0`, then it will automatically be stopped once the timeout is reached. If it is positive, then the timer will automatically be configured to trigger again every repeat seconds later, until stopped manually.
`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 示例

示例 #1 Simple timers

    <?php
    // Create and start timer firing after 2 seconds
    $w1 = new EvTimer(2, 0, function () {
        echo "2 seconds elapsed\n";
    });

    // Create and launch timer firing after 2 seconds repeating each second
    // until we manually stop it
    $w2 = new EvTimer(2, 1, function ($w) {
        echo "is called every second, is launched after 2 seconds\n";
        echo "iteration = ", Ev::iteration(), PHP_EOL;

        // Stop the watcher after 5 iterations
        Ev::iteration() == 5 and $w->stop();
        // Stop the watcher if further calls cause more than 10 iterations
        Ev::iteration() >= 10 and $w->stop();
    });

    // Create stopped timer. It will be inactive until we start it ourselves
    $w_stopped = EvTimer::createStopped(10, 5, function($w) {
        echo "Callback of a timer created as stopped\n";

        // Stop the watcher after 2 iterations
        Ev::iteration() >= 2 and $w->stop();
    });

    // Loop until Ev::stop() is called or all of watchers stop
    Ev::run();

    // Start and look if it works
    $w_stopped->start();
    echo "Run single iteration\n";
    Ev::run(Ev::RUN_ONCE);

    echo "Restart the second watcher and try to handle the same events, but don't block\n";
    $w2->again();
    Ev::run(Ev::RUN_NOWAIT);

    $w = new EvTimer(10, 0, function() {});
    echo "Running a blocking loop\n";
    Ev::run();
    echo "END\n";
    ?>

以上示例的输出类似于：

    2 seconds elapsed
    is called every second, is launched after 2 seconds
    iteration = 1
    is called every second, is launched after 2 seconds
    iteration = 2
    is called every second, is launched after 2 seconds
    iteration = 3
    is called every second, is launched after 2 seconds
    iteration = 4
    is called every second, is launched after 2 seconds
    iteration = 5
    Run single iteration
    Callback of a timer created as stopped
    Restart the second watcher and try to handle the same events, but don't block
    Running a blocking loop
    is called every second, is launched after 2 seconds
    iteration = 8
    is called every second, is launched after 2 seconds
    iteration = 9
    is called every second, is launched after 2 seconds
    iteration = 10
    END

### 参见

- EvTimer::createStopped() - Creates EvTimer stopped watcher object
- EvPeriodic
- » ev_timer - relative and optionally repeating timeouts
- » Be smart about timeouts

# EvTimer::createStopped

(PECL ev >= 0.2.0)

EvTimer::createStopped — Creates EvTimer stopped watcher object

### 说明

final public static function EvTimer::createStopped(
float `$after` ,
float `$repeat` ,
callable `$callback` ,
mixed `$data` = `null` ,
int `$priority` = 0
): EvTimer

Creates EvTimer stopped watcher object. Unlike EvTimer::__construct(), this method doesn't start the watcher automatically.

### 参数

`after`
  Configures the timer to trigger after `after` seconds.
`repeat`
  If repeat is `0.0`, then it will automatically be stopped once the timeout is reached. If it is positive, then the timer will automatically be configured to trigger again every repeat seconds later, until stopped manually.
`callback`
  See Watcher callbacks.
`data`
  Custom data associated with the watcher.
`priority`
  Watcher priority

### 返回值

Returns EvTimer watcher object on success.

### 示例

示例 #1 Monitor changes of /var/log/messages. Avoid missing updates by means of one second delay

    <?php
    $timer = EvTimer::createStopped(0., 1.02, function ($w) {
        $w->stop();

        $stat = $w->data;

        // 1 second after the most recent change of the file
        printf("Current size: %ld\n", $stat->attr()['size']);
    });

    $stat = new EvStat("/var/log/messages", 0., function () use ($timer) {
        // Reset timer watcher
        $timer->again();
    });

    $timer->data = $stat;

    Ev::run();
    ?>

### 参见

- EvTimer::__construct() - Constructs an EvTimer watcher object
- EvPeriodic

# EvTimer::set

(PECL ev >= 0.2.0)

EvTimer::set — Configures the watcher

### 说明

public function EvTimer::set( float `$after` , float `$repeat` ): void

Configures the watcher

### 参数

`after`
  Configures the timer to trigger after `after` seconds.
`repeat`
  If repeat is `0.0`, then it will automatically be stopped once the timeout is reached. If it is positive, then the timer will automatically be configured to trigger again every repeat seconds later, until stopped manually.

### 返回值

没有返回值。

## 目录

- EvTimer::again — Restarts the timer watcher
- EvTimer::__construct — Constructs an EvTimer watcher object
- EvTimer::createStopped — Creates EvTimer stopped watcher object
- EvTimer::set — Configures the watcher

# The EvWatcher class

(PECL ev >= 0.2.0)

## 简介

EvWatcher is a base class for all watchers( EvCheck, EvChild etc.). Since EvWatcher 's constructor is abstract, one can't(and don't need to) create EvWatcher objects directly.

## 类摘要

abstract class EvWatcher {
/* 属性 */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* 方法 */
abstract public function __construct()
public function clear(): int
public function feed( int `$revents` ): void
public function getLoop(): EvLoop
public function invoke( int `$revents` ): void
public function keepalive( bool `$value` = ?): bool
public function setCallback( callable `$callback` ): void
public function start(): void
public function stop(): void
}

## 属性

is_active
  Readonly. `true` if the watcher is active. `false` otherwise.
data
  User custom data associated with the watcher
is_pending
  Readonly .`true` if the watcher is pending, i.e. it has outstanding events, but its callback has not yet been invoked. `false` otherwise. As long, as a watcher is pending(but not active), one must not change its priority.
priority
  int between `Ev::MINPRI` and `Ev::MAXPRI`. Pending watchers with higher priority will be invoked before watchers with lower priority, but priority will not keep watchers from being executed(except for EvIdle watchers). EvIdle watchers provide functionality to suppress invocation when higher priority events are pending.

# EvWatcher::clear

(PECL ev >= 0.2.0)

EvWatcher::clear — Clear watcher pending status

### 说明

public function EvWatcher::clear(): int

If the watcher is pending, this method clears its pending status and returns its revents bitset(as if its callback was invoked). If the watcher isn't pending it does nothing and returns `0`.

Sometimes it can be useful to "poll" a watcher instead of waiting for its callback to be invoked, which can be accomplished with this function.

### 参数

此函数没有参数。

### 返回值

In case if the watcher is pending, returns revents bitset as if the watcher callback had been invoked. Otherwise returns `0`.

# EvWatcher::__construct

(PECL ev >= 0.2.0)

EvWatcher::__construct — Abstract constructor of a watcher object

### 说明

abstract public function EvWatcher::__construct()

EvWatcher::__construct() is an abstract constructor of a watcher object implemented in the derived classes.

### 参数

此函数没有参数。

# EvWatcher::feed

(PECL ev >= 0.2.0)

EvWatcher::feed — Feeds the given revents set into the event loop

### 说明

public function EvWatcher::feed( int `$revents` ): void

Feeds the given revents set into the event loop, as if the specified event had happened for the watcher.

### 参数

`revents`
  Bit mask of watcher received events.

### 返回值

没有返回值。

# EvWatcher::getLoop

(PECL ev >= 0.2.0)

EvWatcher::getLoop — Returns the loop responsible for the watcher

### 说明

public function EvWatcher::getLoop(): EvLoop

Returns the loop responsible for the watcher

### 参数

此函数没有参数。

### 返回值

Returns EvLoop event loop object responsible for the watcher.

# EvWatcher::invoke

(PECL ev >= 0.2.0)

EvWatcher::invoke — Invokes the watcher callback with the given received events bit mask

### 说明

public function EvWatcher::invoke( int `$revents` ): void

Invokes the watcher callback with the given received events bit mask.

### 参数

`revents`
  Bit mask of watcher received events.

### 返回值

没有返回值。

# EvWatcher::keepalive

(PECL ev >= 0.2.0)

EvWatcher::keepalive — Configures whether to keep the loop from returning

### 说明

public function EvWatcher::keepalive( bool `$value` = ?): bool

Configures whether to keep the loop from returning. With keepalive `value` set to `false` the watcher won't keep Ev::run() / EvLoop::run() from returning even though the watcher is active.

Watchers have keepalive `value` `true` by default.

Clearing keepalive status is useful when returning from Ev::run() / EvLoop::run() just because of the watcher is undesirable. It could be a long running UDP socket watcher or so.

### 参数

`value`
  With keepalive `value` set to `false` the watcher won't keep Ev::run() / EvLoop::run() from returning even though the watcher is active.

### 返回值

Returns the previous state.

### 示例

示例 #1 Register an I/O watcher for some UDP socket but do not keep the event loop from running just because of that watcher.

    <?php
    $udp_socket = ...
    $udp_watcher = new EvIo($udp_socket, Ev::READ, function () { /* ... */ });
    $udp_watcher->keepalive(FALSE);
    ?>

# EvWatcher::setCallback

(PECL ev >= 0.2.0)

EvWatcher::setCallback — Sets new callback for the watcher

### 说明

public function EvWatcher::setCallback( callable `$callback` ): void

Sets new callback for the watcher

### 参数

`callback`
  See Watcher callbacks.

### 返回值

没有返回值。

# EvWatcher::start

(PECL ev >= 0.2.0)

EvWatcher::start — Starts the watcher

### 说明

public function EvWatcher::start(): void

Marks the watcher as active. Note that only active watchers will receive events.

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 参见

- EvWatcher::stop() - Stops the watcher

# EvWatcher::stop

(PECL ev >= 0.2.0)

EvWatcher::stop — Stops the watcher

### 说明

public function EvWatcher::stop(): void

Marks the watcher as inactive. Note that only active watchers will receive events.

### 参数

此函数没有参数。

### 返回值

没有返回值。

### 参见

- EvWatcher::start() - Starts the watcher

## 目录

- EvWatcher::clear — Clear watcher pending status
- EvWatcher::__construct — Abstract constructor of a watcher object
- EvWatcher::feed — Feeds the given revents set into the event loop
- EvWatcher::getLoop — Returns the loop responsible for the watcher
- EvWatcher::invoke — Invokes the watcher callback with the given received events bit mask
- EvWatcher::keepalive — Configures whether to keep the loop from returning
- EvWatcher::setCallback — Sets new callback for the watcher
- EvWatcher::start — Starts the watcher
- EvWatcher::stop — Stops the watcher

- 安装/配置
  - 需求
  - 安装
- 示例
- Watchers
- Watcher callbacks
- Periodic watcher operation modes
- Ev — The Ev class
  - Ev::backend — Returns an integer describing the backend used by libev
  - Ev::depth — Returns recursion depth
  - Ev::embeddableBackends — Returns the set of backends that are embeddable in other event loops
  - Ev::feedSignal — Feed a signal event into Ev
  - Ev::feedSignalEvent — Feed signal event into the default loop
  - Ev::iteration — Return the number of times the default event loop has polled for new events
  - Ev::now — Returns the time when the last iteration of the default event loop has started
  - Ev::nowUpdate — Establishes the current time by querying the kernel, updating the time returned by Ev::now in the progress
  - Ev::recommendedBackends — Returns a bit mask of recommended backends for current platform
  - Ev::resume — Resume previously suspended default event loop
  - Ev::run — Begin checking for events and calling callbacks for the default loop
  - Ev::sleep — Block the process for the given number of seconds
  - Ev::stop — Stops the default event loop
  - Ev::supportedBackends — Returns the set of backends supported by current libev configuration
  - Ev::suspend — Suspend the default event loop
  - Ev::time — Returns the current time in fractional seconds since the epoch
  - Ev::verify — Performs internal consistency checks(for debugging)
- EvCheck — The EvCheck class
  - EvCheck::__construct — Constructs the EvCheck watcher object
  - EvCheck::createStopped — Create instance of a stopped EvCheck watcher
- EvChild — The EvChild class
  - EvChild::__construct — Constructs the EvChild watcher object
  - EvChild::createStopped — Create instance of a stopped EvChild watcher
  - EvChild::set — Configures the watcher
- EvEmbed — The EvEmbed class
  - EvEmbed::__construct — Constructs the EvEmbed object
  - EvEmbed::createStopped — Create stopped EvEmbed watcher object
  - EvEmbed::set — Configures the watcher
  - EvEmbed::sweep — Make a single, non-blocking sweep over the embedded loop
- EvFork — The EvFork class
  - EvFork::__construct — Constructs the EvFork watcher object
  - EvFork::createStopped — Creates a stopped instance of EvFork watcher class
- EvIdle — The EvIdle class
  - EvIdle::__construct — Constructs the EvIdle watcher object
  - EvIdle::createStopped — Creates instance of a stopped EvIdle watcher object
- EvIo — The EvIo class
  - EvIo::__construct — Constructs EvIo watcher object
  - EvIo::createStopped — Create stopped EvIo watcher object
  - EvIo::set — Configures the watcher
- EvLoop — The EvLoop class
  - EvLoop::backend — Returns an integer describing the backend used by libev
  - EvLoop::check — Creates EvCheck object associated with the current event loop instance
  - EvLoop::child — Creates EvChild object associated with the current event loop
  - EvLoop::__construct — Constructs the event loop object
  - EvLoop::defaultLoop — Returns or creates the default event loop
  - EvLoop::embed — Creates an instance of EvEmbed watcher associated with the current EvLoop object
  - EvLoop::fork — Creates EvFork watcher object associated with the current event loop instance
  - EvLoop::idle — Creates EvIdle watcher object associated with the current event loop instance
  - EvLoop::invokePending — Invoke all pending watchers while resetting their pending state
  - EvLoop::io — Create EvIo watcher object associated with the current event loop instance
  - EvLoop::loopFork — Must be called after a fork
  - EvLoop::now — Returns the current "event loop time"
  - EvLoop::nowUpdate — Establishes the current time by querying the kernel, updating the time returned by EvLoop::now in the progress
  - EvLoop::periodic — Creates EvPeriodic watcher object associated with the current event loop instance
  - EvLoop::prepare — Creates EvPrepare watcher object associated with the current event loop instance
  - EvLoop::resume — Resume previously suspended default event loop
  - EvLoop::run — Begin checking for events and calling callbacks for the loop
  - EvLoop::signal — Creates EvSignal watcher object associated with the current event loop instance
  - EvLoop::stat — Creates EvStat watcher object associated with the current event loop instance
  - EvLoop::stop — Stops the event loop
  - EvLoop::suspend — Suspend the loop
  - EvLoop::timer — Creates EvTimer watcher object associated with the current event loop instance
  - EvLoop::verify — Performs internal consistency checks(for debugging)
- EvPeriodic — The EvPeriodic class
  - EvPeriodic::again — Simply stops and restarts the periodic watcher again
  - EvPeriodic::at — Returns the absolute time that this watcher is supposed to trigger next
  - EvPeriodic::__construct — Constructs EvPeriodic watcher object
  - EvPeriodic::createStopped — Create a stopped EvPeriodic watcher
  - EvPeriodic::set — Configures the watcher
- EvPrepare — The EvPrepare class
  - EvPrepare::__construct — Constructs EvPrepare watcher object
  - EvPrepare::createStopped — Creates a stopped instance of EvPrepare watcher
- EvSignal — The EvSignal class
  - EvSignal::__construct — Constructs EvSignal watcher object
  - EvSignal::createStopped — Create stopped EvSignal watcher object
  - EvSignal::set — Configures the watcher
- EvStat — The EvStat class
  - EvStat::attr — Returns the values most recently detected by Ev
  - EvStat::__construct — Constructs EvStat watcher object
  - EvStat::createStopped — Create a stopped EvStat watcher object
  - EvStat::prev — Returns the previous set of values returned by EvStat::attr
  - EvStat::set — Configures the watcher
  - EvStat::stat — Initiates the stat call
- EvTimer — The EvTimer class
  - EvTimer::again — Restarts the timer watcher
  - EvTimer::__construct — Constructs an EvTimer watcher object
  - EvTimer::createStopped — Creates EvTimer stopped watcher object
  - EvTimer::set — Configures the watcher
- EvWatcher — The EvWatcher class
  - EvWatcher::clear — Clear watcher pending status
  - EvWatcher::__construct — Abstract constructor of a watcher object
  - EvWatcher::feed — Feeds the given revents set into the event loop
  - EvWatcher::getLoop — Returns the loop responsible for the watcher
  - EvWatcher::invoke — Invokes the watcher callback with the given received events bit mask
  - EvWatcher::keepalive — Configures whether to keep the loop from returning
  - EvWatcher::setCallback — Sets new callback for the watcher
  - EvWatcher::start — Starts the watcher
  - EvWatcher::stop — Stops the watcher

# Expect

# 简介

This extension allows to interact with processes through PTY. You may consider using the `expect://` wrapper with the filesystem functions which provide a simpler and more intuitive interface.

# 安装/配置

## 目录

- 需求
- 安装
- 运行时配置
- 资源类型

## 需求

This module uses the functions of the » expect library. You need libexpect version >= 5.43.0.

## 安装

此 » PECL 扩展未与 PHP 捆绑。 安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等，都在此处： » https://pecl.php.net/package/expect.

In order to use these functions you must compile PHP with expect support by using the --with-expect[=DIR] configure option.

Windows users will enable php_expect.dll inside of php.ini in order to use these functions. PECL 扩展的 DLL 当前不可用。参见 在 Windows 上构建章节。

## 运行时配置

这些函数的行为受 php.ini 中的设置影响。

In order to configure expect extension, there are configuration options in the configuration file php.ini.

Expect 配置选项
名字 | 默认 | 可修改范围 | 更新日志
--- | --- | --- | ---
expect.timeout | "10" | `INI_ALL` |
expect.loguser | "1" | `INI_ALL` |
expect.logfile | "" | `INI_ALL` |
expect.match_max | "" | `INI_ALL` |

有关 INI_* 样式的更多详情与定义，见 配置可被设定范围。

这是配置指令的简短说明。

`expect.timeout` int
  The timeout period for waiting for the data, when using the expect_expectl() function. A value of "-1" disables a timeout from occurring.

  > 注意: A value of "0" causes the expect_expectl() function to return immediately.

`expect.loguser` bool
  Whether expect should send any output from the spawned process to stdout. Since interactive programs typically echo their input, this usually suffices to show both sides of the conversation.
`expect.logfile` string
  Name of the file, where the output from the spawned process will be written. If this file doesn't exist, it will be created.

  > 注意: If this configuration is not empty, the output is written regardless of the value of expect.loguser.

`expect.match_max` int
  Changes default size (2000 bytes) of the buffer used to match asterisks in patterns.

## 资源类型

expect_popen() returns an open PTY stream used by expect_expectl().

# 预定义常量

下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

`EXP_GLOB` (int)
  Indicates that the pattern is a glob-style string pattern.
`EXP_EXACT` (int)
  Indicates that the pattern is an exact string.
`EXP_REGEXP` (int)
  Indicates that the pattern is a regexp-style string pattern.
`EXP_EOF` (int)
  Value, returned by expect_expectl(), when EOF is reached.
`EXP_TIMEOUT` (int)
  Value, returned by expect_expectl() upon timeout of seconds, specified in value of expect.timeout
`EXP_FULLBUFFER` (int)
  Value, returned by expect_expectl() if no pattern have been matched.

# 示例

## 目录

- Expect Usage Examples

## Expect Usage Examples

示例 #1 Expect Usage Example

This example connects to the remote host via SSH, and prints the remote uptime.

    <?php
    ini_set("expect.loguser", "Off");

    $stream = fopen("expect://ssh root@remotehost uptime", "r");

    $cases = array (
        array (0 => "password:", 1 => PASSWORD)
    );

    switch (expect_expectl ($stream, $cases)) {
        case PASSWORD:
            fwrite ($stream, "password\n");
            break;

        default:
            die ("Error was occurred while connecting to the remote host!\n");
    }

    while ($line = fgets($stream)) {
          print $line;
    }
    fclose ($stream);
    ?>

The following example connects to the remote host, determines whether installed OS is for 32 or 64 bit, then runs update for specific package.

示例 #2 Another Expect Usage Example

    <?php
    ini_set("expect.timeout", -1);
    ini_set("expect.loguser", "Off");

    $stream = expect_popen("ssh root@remotehost");

    while (true) {
        switch (expect_expectl ($stream, array (
                array ("password:", PASSWORD), // SSH is asking for password
                array ("yes/no)?", YESNO), // SSH is asking whether to store the host entry
                array ("~$ ", SHELL, EXP_EXACT), // We've got the shell!
        ))) {
            case PASSWORD:
                fwrite ($stream, "secret\n");
                break;

            case YESNO:
                fwrite ($stream, "yes\n");
                break;

            case SHELL:
                fwrite ($stream, "uname -a\n");
                while (true) {
                        switch (expect_expectl ($stream, array (
                                array ("~$ ", SHELL, EXP_EXACT), // We've got the shell!
                                array ("^Linux.*$", UNAME, EXP_REGEXP), // uname -a output
                        ), $match)) {
                            case UNAME:
                                $uname .= $match[0];
                                break;

                            case SHELL:
                                // Run update:
                                if (strstr ($uname, "x86_64")) {
                                        fwrite ($stream, "rpm -Uhv http://mirrorsite/somepath/some_64bit.rpm\n");
                                } else {
                                        fwrite ($stream, "rpm -Uhv http://mirrorsite/somepath/some_32bit.rpm\n");
                                }
                                fwrite ($stream, "exit\n");
                                break 2;

                            case EXP_TIMEOUT:
                            case EXP_EOF:
                                break 2;

                            default:
                                die ("Error has occurred!\n");
                        }
                }
                break 2;

            case EXP_TIMEOUT:
            case EXP_EOF:
                break 2;

            default:
                die ("Error has occurred!\n");
        }
    }

    fclose ($stream);
    ?>

# Expect 函数

# expect_expectl

(PECL expect >= 0.1.0)

expect_expectl — Waits until the output from a process matches one of the patterns, a specified time period has passed, or an EOF is seen

### 说明

function expect_expectl(resource `$expect`, array `$cases`, array `&$match` = ?): int

Waits until the output from a process matches one of the patterns, a specified time period has passed, or an EOF is seen.

If `match` is provided, then it is filled with the result of search. The matched string can be found in `match[0]`. The match substrings (according to the parentheses) in the original pattern can be found in `match[1]`, `match[2]`, and so on, up to `match[9]` (the limitation of libexpect).

### 参数

`expect`
  An Expect stream, previously opened with expect_popen().
`cases`

  An array of expect cases. Each expect case is an indexed array, as described in the following table:

  Expect Case Array
  Index Key | Value Type | Description | Is Mandatory | Default Value
  --- | --- | --- | --- | ---
  0 | string | pattern, that will be matched against the output from the stream | yes |
  1 | mixed | value, that will be returned by this function, if the pattern matches | yes |
  2 | integer | pattern type, one of: `EXP_GLOB`, `EXP_EXACT` or `EXP_REGEXP` | no | `EXP_GLOB`

### 返回值

Returns value associated with the pattern that was matched.

On failure this function returns: `EXP_EOF`, `EXP_TIMEOUT` or `EXP_FULLBUFFER`

### 更新日志

版本 | 说明
--- | ---
PECL expect 0.2.1 | Prior to version 0.2.1, in `match` parameter a match string was returned, not an array of match substrings.

### 示例

示例 #1 expect_expectl() example

    <?php
    // Copies file from remote host:
    ini_set("expect.timeout", 30);

    $stream = fopen("expect://scp user@remotehost:/var/log/messages /home/user/messages.txt", "r");

    $cases = array(
        // array(pattern, value to return if pattern matched)
        array("password:", "asked for password"),
        array("yes/no)?",  "asked for yes/no")
    );

    while (true) {
        switch (expect_expectl($stream, $cases)) {
            case "asked for password":
                fwrite($stream, "my password\n");
                break;
            case "asked for yes/no":
                fwrite($stream, "yes\n");
                break;
            case EXP_TIMEOUT:
            case EXP_EOF:
                break 2; // break both the switch statement and the while loop
            default:
                die("Error has occurred!");
        }
    }

    fclose($stream);
    ?>

### 参见

- expect_popen() - Execute command via Bourne shell, and open the PTY stream to the process

# expect_popen

(PECL expect >= 0.1.0)

expect_popen — Execute command via Bourne shell, and open the PTY stream to the process

### 说明

function expect_popen(string `$command`): resource

Execute command via Bourne shell, and open the PTY stream to the process.

### 参数

`command`
  Command to execute.

### 返回值

Returns an open PTY stream to the processes `stdio`, `stdout`, and `stderr`.

On failure this function returns `false`.

### 示例

示例 #1 expect_popen() example

    <?php
    // Login to the PHP.net CVS repository:
    $stream = expect_popen ("cvs -d :pserver:anonymous@cvs.php.net:/repository login");
    sleep (3);
    fwrite ($stream, "phpfi\n");
    fclose ($stream);
    ?>

### 参见

- popen() - 打开进程文件指针

## 目录

- expect_expectl — Waits until the output from a process matches one of the patterns, a specified time period has passed, or an EOF is seen
- expect_popen — Execute command via Bourne shell, and open the PTY stream to the process

- 安装/配置
  - 需求
  - 安装
  - 运行时配置
  - 资源类型
- 预定义常量
- 示例
  - Expect Usage Examples
- Expect 函数
  - expect_expectl — Waits until the output from a process matches one of the patterns, a specified time period has passed, or an EOF is seen
  - expect_popen — Execute command via Bourne shell, and open the PTY stream to the process

# 进程控制

# 简介<
[file cut: first 33554432 bytes kept]
