How to customize printf function in PHP

大家都知道 libc 的 printf() 及其家族。本章节将详细介绍 PHP 声明和使用的许多克隆，它们的目标是什么，为什么使用它们，以及何时使用它们。

相关学习推荐：PHP编程从入门到精通

注意

Libc 中关于 printf() 及其朋友的文档位于此处。

你知道这些函数很有用，但有时无法提供足够的功能。另外，你知道向 printf()添加格式字符串并非易事，没有便携性和有安全风险。

PHP 添加了自己的类似于 printf 的函数，取代了 libc 的，并且由内部开发者使用。他们主要添加新的格式，并使用 zend_string代替 char *等等，让我们一起来看看。

警告

你必须掌握 libc 默认printf() 格式。请阅读它们的文档。

注意

添加了这些函数以 取代 libc 函数，意味着如果你使用了sprintf()，不会使用到 libc 的sprintf()，而是 PHP 取代了。除了传统的 printf()外，其他内容均被替换。

传统用途

首先，你不应该使用 sprintf()，因为该函数不执行任何检查，并且导致许多缓冲区溢出错误。请避免使用它。

警告

尽可能避免使用 sprintf()。

然后，你有一些选择。

你知道结果缓冲区的大小

如果你知道缓冲区大小，snprintf() 或者 slprintf() 都可以使用。这些函数虽然在返回上不同，但是它们的功能是一样的。

这两个都是根据传递的格式来打印，并且无论发生什么，都会通过一个NUL 字节 ‘\0’来终止你的缓冲区。 但是，snprintf() 返回可以使用的字符数，而slprintf()返回可以有效使用的字符数，因此可以检测过小的缓冲区和字符串截断。这个不会计算最后的‘\0’。

这里有个例子，以便你完全明白：

char foo[8]; /* 8字符大小的缓冲区 */
const char str[] = "Hello world"; /* 12个字符，包含 \0 */
int r;

r = snprintf(foo, sizeof(foo), "%s", str);
/* r = 11 ，即使这里只有7个可打印的字符可写入 foo */

/* foo 的值现在是 'H' 'e' 'l' 'l' 'o' ' ' 'w' '\0' */

snprintf() 不是一个好用的函数，因为它不允许检查最后的字符串截断。就像上面例子你看到的，显然“Hello world\0”不适合8字节的缓冲区，但是 snprintf() 仍然返回11给你，这是 strlen("Hello world\0") 的值。你没有办法检查字符串被截断了。

这是 slprintf()：

char foo[8]; /* 8字符大的缓冲区 */
const char str[] = "Hello world"; /* 12个字符，包含 \0 */
int r;

r = slprintf(foo, sizeof(foo), "%s", str);
/* r = 7 ，因为7个可打印的字符被写入 foo */

/* foo 现在的值是 'H' 'e' 'l' 'l' 'o' ' ' 'w' '\0' */

使用 slprintf()，结果缓冲区 foo 包含完全相同的字符串，但是如今返回值为7。7少于 “Hello world” 字符串的11个字符，所以你可以检查它被截断了：

if (slprintf(foo, sizeof(foo), "%s", str) < strlen(str)) {
    /* 发生字符串截断 */
}

记住：

• 这两个函数总是以NUL终止字符串，不管是否截断。最终的字符串是安全的 C 字符串。
• 只有 slprintf()会检查字符串截断。 

这两个函数在 main/snprintf.c 中有详细介绍。

你不知道缓冲区大小

现在如果你不知道结果缓冲区大小，则需要动态分配一个，并且使用spprintf()。记住，你必须自己释放缓冲区。

这是例子：

#include <time.h>

char *result;
int r;

time_t timestamp = time(NULL);

r = spprintf(&result, 0, "Here is the date: %s", asctime(localtime(&timestamp)));

/* 现在结果类似："Here is the date: Thu Jun 15 19:12:51 2017\n" */

efree(result);

spprintf() 返回被打印到结果缓冲区的字符数，不包括最后的‘\0’， 因此，你知道分配给你的字节数（减一）是多少。

请注意，是使用 ZendMM（请求分配）分配的，因此应作为请求的一部分使用，并使用 efree() 而不是free()释放。

注意

Zend 内存管理章节 (ZendMM) 详细介绍如何通过 PHP 分配动态内存。

如果你想要限制缓冲区大小，则将限制传递给第二个参数，如果你传递 0，意味着无限制：

#include <time.h>

char *result;
int r;

time_t timestamp = time(NULL);

/* 打印不超过 10 个字节 ||分配超过 11 个字节 */
r = spprintf(&result, 10, "Here is the date: %s", asctime(localtime(&timestamp)));

/* r == 10，并且给结果分配 11 个字节 */

efree(result);

注意

尽可能不要使用动态内存分配。这会影响执性能。如果有选择，则选静态堆栈分配缓冲区。

spprintf()写在 main/spprintf.c 中。

那么 printf() 呢？

如果你需要 printf()，即打印格式化到输出流，则使用php_printf()。该函数在内部使用 spprintf()，因此执行动态分配，以便将其发送到 SAPI 输出（在 CLI 的情况下又称为 stdout），或输出缓冲区（CGI 缓冲区）后将其释放，用于其他 SAPI。

特殊的 PHP printf 格式

记住，PHP 通过自己设计，取代了很多 libc 的 printf() 函数。你可以从阅读源代码中查看易于理解的参数解析 API。

这意味着解析算法的参数已完全被重写，并且可能与你在 libc 使用的不同。即，在大多数情况下，不会关注 libc 环境。

可能会使用特殊的格式，就像 “%I64” 打印64位 int，或者“%I32”。你也可以使用 “%Z” 去打印 zval（根据 PHP 规则转换为字符串），这是一个不错的补充。

该格式化程序也认识无穷数，并打印 “INF”，或者将非数字打印为  “NAN”。

如果你错误的请求格式化程序打印一个 NULL 指针，libc 肯定会崩溃，而 PHP 会将 “(null)” 作为结果字符串返回。

注意

如果在打印中你看到神奇的 “(null)” 出现，意味着你将 NULL 指针传递给了 PHP printf 系列函数之一。

Printf() 到 zend_strings

zend_string 作为 PHP 源代码里非常常见的结构，你可能需要 printf() 到 zend_string，而不是传统的 char *。为此，请使用strpprintf()。

该 API 是 zend_string *strpprintf(size_t max_len, const char *format, ...) ，意味着返回zend_string 给你，而不是你期望的可打印字符数。不过你可以限制使用第一个参数来限制该数（传递 0 表示无穷大）；并且你一定要记住将使用 Zend 内存管理分配 zend_string，并因此绑定当前请求。

显然，该格式 API 与上面看到的共享。

这有个例子：

zend_string *result;

result = strpprintf(0, "You are using PHP %s", PHP_VERSION);

/* 对结果做些什么 */

zend_string_release(result);

关于 zend_ API 的注释

您可能会遇到 zend_spprintf() 或 zend_strpprintf() 函数。这些与上面看到的完全相同。

这只是 Zend 引擎和 PHP 核心之间分离的一部分，这个细节对我们并不重要，因为在源码中，所有内容都是混合在一起的。

The above is the detailed content of How to customize printf function in PHP. For more information, please follow other related articles on the PHP Chinese website!