Ref/outcontrol-Phpdoc专题

See also header and setcookie.

flush

刷新输出缓冲

说明

void flush ( void )

刷新PHP程序的缓冲，而不论PHP执行在何种情况下（CGI ，web服务器等等）。该函数将当前为止程序的所有输出发送到用户的浏览器。

flush 函数不会对服务器或客户端浏览器的缓存模式产生影响。因此，必须同时使用 ob_flush 和flush 函数来刷新输出缓冲。

个别web服务器程序，特别是Win32下的web服务器程序，在发送结果到浏览器之前，仍然会缓存脚本的输出，直到程序结束为止。

有些Apache的模块，比如mod_gzip，可能自己进行输出缓存，这将导致flush函数产生的结果不会立即被发送到客户端浏览器。

甚至浏览器也会在显示之前，缓存接收到的内容。例如 Netscape 浏览器会在接受到换行或 html 标记的开头之前缓存内容，并且在接受到 \</table> 标记之前，不会显示出整个表格。

一些版本的 Microsoft Internet Explorer 只有当接受到的256个字节以后才开始显示该页面，所以必须发送一些额外的空格来让这些浏览器显示页面内容。

ob_clean

清空（擦掉）输出缓冲区

说明

void ob_clean ( void )

此函数用来丢弃输出缓冲区中的内容。

此函数不会像 ob_end_clean 函数那样销毁输出缓冲区。

输出缓冲必须已被 ob_start 以 PHP_OUTPUT_HANDLER_CLEANABLE 标记启动。否则 ob_clean 不会有效果。

返回值

没有返回值。

参见

ob_flush
ob_end_flush
ob_end_clean

ob_end_clean

清空（擦除）缓冲区并关闭输出缓冲

说明

bool ob_end_clean ( void )

此函数丢弃最顶层输出缓冲区的内容并关闭这个缓冲区。如果想要进一步处理缓冲区的内容，必须在ob_end_clean之前调用ob_get_contents，因为当调用ob_end_clean时缓冲区内容将被丢弃。

返回值

成功时返回 true，或者在失败时返回 false。错误的原因首先是，在调用时没有一个起作用的缓冲区，或者是因为某些原因缓冲区不能被删除（可能对特殊缓冲区而言）。

错误／异常

如果函数失败了，将引发一个E_NOTICE异常。

更新日志

版本	说明
4.2.0	添加了布尔返回值。

范例

下面的例子给出了一种去除所有输出缓冲区的方法：

示例 #1 ob_end_clean example

<?php
ob_start();
echo 'Text that won\'t get displayed.';
ob_end_clean();
?>

参见

ob_start
ob_get_contents
ob_flush

ob_end_flush

冲刷出（送出）输出缓冲区内容并关闭缓冲

说明

bool ob_end_flush ( void )

这个函数将送出最顶层缓冲区的内容（如果里边有内容的话），并关闭缓冲区。如果想进一步处理缓冲区中的内容，必须在ob_end_flush之前调用 ob_get_contents，因为在调用ob_end_flush后缓冲区内容被丢弃。

Note: 这个函数与ob_get_flush相似，不同的是ob_get_flush会把缓冲区中的内容作为字符串返回。

返回值

错误／异常

如果函数失败了，将引发一个E_NOTICE异常。

更新日志

版本	说明
4.2.0	添加了布尔返回值。

范例

示例 #1 ob_end_flush example

下面的例子给出了一种送出缓冲区内容并关闭所有输出缓冲区的容易的方法：

<?php
  while (@ob_end_flush());
?>

参见

ob_start
ob_get_contents
ob_get_flush
ob_flush
ob_end_clean

ob_flush

冲刷出（送出）输出缓冲区中的内容

说明

void ob_flush ( void )

这个函数将送出缓冲区的内容（如果里边有内容的话）。如果想进一步处理缓冲区中的内容，必须在ob_flush之前调用ob_get_contents ，因为在调用ob_flush之后缓冲区内容将被丢弃。

此函数不会销毁输出缓冲区，而像ob_end_flush 函数会销毁缓冲区。

返回值

没有返回值。

参见

ob_get_contents
ob_clean
ob_end_flush
ob_end_clean

ob_get_clean

得到当前缓冲区的内容并删除当前输出缓。

说明

string ob_get_clean ( void )

得到当前缓冲区的内容并删除当前输出缓冲区。

ob_get_clean 实质上是一起执行了 ob_get_contents 和 ob_end_clean。

返回值

返回输出缓冲区的内容，并结束输出缓冲区。如果输出缓冲区不是活跃的，即返回 false 。

范例

示例 #1 A simple ob_get_clean example

<?php

ob_start();

echo "Hello World";

$out = ob_get_clean();
$out = strtolower($out);

var_dump($out);
?>

以上例程会输出：

string(11) "hello world"

参见

ob_get_contents
ob_start

ob_get_contents

返回输出缓冲区的内容

说明

string ob_get_contents ( void )

只是得到输出缓冲区的内容，但不清除它。

返回值

此函数返回输出缓冲区的内容，或者如果输出缓冲区无效将返回false 。

范例

示例 #1 A simple ob_get_contents example

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

刷出（送出）缓冲区内容，以字符串形式返回内容，并关闭输出缓冲区。

说明

string ob_get_flush ( void )

ob_get_flush 刷出（送出）缓冲区内容，以字符串形式返回内容，并关闭输出缓冲区。

Note: 这个函数与ob_end_flush相似，不同的是本函数还会以字符串形式返回缓冲区内容。

返回值

返回输出缓冲区的内容；或者是，如果没有起作用的输出缓冲区，返回false 。

范例

示例 #1 ob_get_flush example

<?php
//using output_buffering=On
print_r(ob_list_handlers());

//save buffer in a file
$buffer = ob_get_flush();
file_put_contents('buffer.txt', $buffer);

print_r(ob_list_handlers());
?>

以上例程会输出：

Array
(
    [0] => default output handler
)
Array
(
)

参见

ob_end_clean
ob_end_flush
ob_list_handlers

ob_get_length

返回输出缓冲区内容的长度

说明

int ob_get_length ( void )

此函数将返回输出缓中冲区内容的长度。

返回值

返回输出缓冲区内容的长度；或者返回false——如果没有起作用的缓冲区。

范例

示例 #1 A simple ob_get_length example

<?php

ob_start();

echo "Hello ";

$len1 = ob_get_length();

echo "World";

$len2 = ob_get_length();

ob_end_clean();

echo $len1 . ", ." . $len2;
?>

以上例程会输出：

6, 11

参见

ob_start
ob_get_contents

ob_get_level

返回输出缓冲机制的嵌套级别

说明

int ob_get_level ( void )

返回输出缓冲机制的嵌套级别。

返回值

返回嵌套的输出缓冲处理程序的级别；或者是，如果输出缓冲区不起作用，返回零。

参见

ob_start
ob_get_contents

ob_get_status

得到所有输出缓冲区的状态

说明

array ob_get_status ([ bool $full_status = FALSE ] )

ob_get_status返回最顶层输出缓冲区的状态信息；或者如果full_status设为true，返回所有有效的输出缓冲级别。

参数

full_status
设为true 返回所有有效的输出缓冲区级别的状态信息。如果设为 false 或者没有设置，仅返回最顶层输出缓冲区的状态信息。

返回值

如果调用时没有full_status参数，或者full_status = false 将返回一个包含下面元素的简单数组：

Array
(
    [level] => 2
    [type] => 0
    [status] => 0
    [name] => URL-Rewriter
    [del] => 1
)

Key	Value
level	输出嵌套级别
type	PHP_OUTPUT_HANDLER_INTERNAL (0) 或者 PHP_OUTPUT_HANDLER_USER (1)
status	PHP_OUTPUT_HANDLER_START (0), PHP_OUTPUT_HANDLER_CONT (1) or PHP_OUTPUT_HANDLER_END (2) 三个之一
name	起作用的输出处理程序的名字，或者是默认的输出处理程序的名字（如果没有设置的话）
del	由ob_start设置的删除标签（Erase-flag）

如果调用时full_status = true，将返回一个数组，该数组的每个元素包含有效的输出缓冲区级别的状态信息。缓冲区的级别数用来当作数组的第一维数；每个元素自身是另一个数组，它持有该有效输出级别的状态信息。

Array
(
    [0] => Array
        (
            [chunk_size] => 0
            [size] => 40960
            [block_size] => 10240
            [type] => 1
            [status] => 0
            [name] => default output handler
            [del] => 1
        )

    [1] => Array
        (
            [chunk_size] => 0
            [size] => 40960
            [block_size] => 10240
            [type] => 0
            [buffer_size] => 0
            [status] => 0
            [name] => URL-Rewriter
            [del] => 1
        )

)

完整的输出包含以下附加元素：

Key	Value
chunk_size	由 ob_start设置的Chunk size值
size	...
blocksize	...

参见

ob_get_level
ob_list_handlers

ob_gzhandler

在ob_start中使用的用来压缩输出缓冲区中内容的回调函数。ob_start callback function to gzip output buffer

说明

string ob_gzhandler ( string $buffer , int $mode )

ob_gzhandler目的是用在ob_start中作回调函数，以方便将gz 编码的数据发送到支持压缩页面的浏览器。在ob_gzhandler真正发送压缩过的数据之前，该函数会确定（判定）浏览器可以接受哪种类型内容编码（"gzip","deflate",或者根本什么都不支持），然后返回相应的输出。所有可以发送正确头信息表明他自己可以接受压缩的网页的浏览器，都可以支持。 All browsers are supported since it's up to the browser to send the correct header saying that it accepts compressed web pages. 如果一个浏览器不支持压缩过的页面，此函数返回false。

参数

buffer

mode

返回值

更新日志

版本	说明
4.0.5	填加了 `mode` 参数。

范例

示例 #1 ob_gzhandler example

<?php

ob_start("ob_gzhandler");

?>
<html>
<body>
<p>This should be a compressed page.</p>
</html>
<body>

注释

Note:

ob_gzhandler 需要 zlib 扩展。

Note:

不能同时使用ob_gzhandler 和 zlib.output_compression。也要注意使用 zlib.output_compression 要优于 ob_gzhandler。

参见

ob_start
ob_end_flush

ob_implicit_flush

打开/关闭绝对刷送

说明

void ob_implicit_flush ([ int $flag = true ] )

ob_implicit_flush将打开或关闭绝对（隐式）刷送。绝对（隐式）刷送将导致在每次输出调用后有一次刷送操作，以便不再需要对 flush 的显式调用。

参数

flag
设为true 打开绝对刷送，反之是 false 。

返回值

没有返回值。

参见

flush
ob_start
ob_end_flush

ob_list_handlers

列出所有使用中的输出处理程序。

说明

array ob_list_handlers ( void )

列出所有使用中的输出处理程序。

返回值

此函数将返回一个数组，数组元素是正在使用中输出处理程序名（如果存在的输出处理程序的话）。如果启用了output_buffering 或者在 ob_start 中创建了一个匿名函数，ob_list_handlers 将返回 "default output handler"。

范例

示例 #1 ob_list_handlers example

<?php
//using output_buffering=On
print_r(ob_list_handlers());
ob_end_flush();

ob_start("ob_gzhandler");
print_r(ob_list_handlers());
ob_end_flush();

// anonymous functions
ob_start(create_function('$string', 'return $string;'));
print_r(ob_list_handlers());
ob_end_flush();
?>

以上例程会输出：

Array
(
    [0] => default output handler
)

Array
(
    [0] => ob_gzhandler
)

Array
(
    [0] => default output handler
)

参见

ob_end_clean
ob_end_flush
ob_get_flush
ob_start

ob_start

打开输出控制缓冲

说明

bool ob_start ([ callable $output_callback = null [, int $chunk_size = 0 [, int $flags = PHP_OUTPUT_HANDLER_STDFLAGS ]]] )

此函数将打开输出缓冲。当输出缓冲激活后，脚本将不会输出内容（除http标头外），相反需要输出的内容被存储在内部缓冲区中。

内部缓冲区的内容可以用 ob_get_contents 函数复制到一个字符串变量中。想要输出存储在内部缓冲区中的内容，可以使用 ob_end_flush 函数。另外，使用 ob_end_clean 函数会静默丢弃掉缓冲区的内容。

Warning

当有正在调用的回调函数时，一些网络服务器（例如Apache）会改变一个脚本的工作目录。你可以在回调函数中再把它改回来，例如 chdir(dirname($_SERVER['SCRIPT_FILENAME'])) 。

输出缓冲区是可堆叠的，这即意谓着，当有一个 ob_start 是活跃的时，你可以调用另一个 ob_start 。只要确保又正确调用了 ob_end_flush 恰当的次数即可。如果有多重输出回调函数是活跃的，输出内容会一直按嵌套的顺序依次通过它们而被过滤。

参数

output_callback
可选参数 output_callback 函数可以被指定。此函数把一个字符串当作参数并返回一个字符串。当输出缓冲区被( ob_flush, ob_clean 或者相似的函数)冲刷（送出）或者被清洗的时候；或者在请求结束之际输出缓冲区内容被冲刷到浏览器的时候该函数将会被调用。当调用 output_callback 时，它将收到输出缓冲区的内容作为参数并预期返回一个新的输出缓冲区作为结果，这个新返回的输出缓冲区内容将被送到浏览器。如果这个 output_callback 不是一个可以调用的函数，此函数会返回 false。以下是回调签名：

string handler ( string $buffer [, int $phase ] )

buffer
输出缓冲区中的内容。

phase
比特掩码 PHP_OUTPUTHANDLER* 常量。

如果 output_callback 返回 false ，其原来的输入内容被直接送到浏览器。

这个参数 output_callback 可以通过直接给一个 null 值而避开。

ob_end_clean, ob_end_flush, ob_clean, ob_flush 和 ob_start 不能从一个回调函数中调用。如果从回调函数中调用了它们，产生的行为是不明确的。如果想要删除缓冲区的内容，从回调函数中返回一个"" (空字符串)。更不能从一个回调函数中使用像print_r($expression, true) 或highlight_file($filename, true) 一样的输出缓冲函数。

Note:

ob_gzhandler function exists to facilitate sending gz-encoded data to web browsers that support compressed web pages. ob_gzhandler determines what type of content encoding the browser will accept and will return its output accordingly.

chunk_size
如果可选参数 chunk_size 被赋值了，在任何一个能引起缓冲区的长度等于或超过 chunk_size 的输出操作后，缓冲区都会被刷送。默认值 0 意味着函数仅在最后被调用。

PHP 5.4.0 之前，1 是一个特殊情况下的值，代表将 chunk_size 设置为 4096 字节。

flags
flags 参数代表了一个掩码位，用来控制对缓冲区的操作。 The default is to allow output buffers to be cleaned, flushed and removed, which can be set explicitly via PHP_OUTPUT_HANDLER_CLEANABLE | PHP_OUTPUT_HANDLER_FLUSHABLE | PHP_OUTPUT_HANDLER_REMOVABLE, or PHP_OUTPUT_HANDLER_STDFLAGS as shorthand.

每个标志都控制着对一组功能的访问，详细介绍如下：

Constant	Functions
`PHP_OUTPUT_HANDLER_CLEANABLE`	ob_clean, ob_end_clean 和 ob_get_clean。
`PHP_OUTPUT_HANDLER_FLUSHABLE`	ob_end_flush, ob_flush 和 ob_get_flush。
`PHP_OUTPUT_HANDLER_REMOVABLE`	ob_end_clean, ob_end_flush 和 ob_get_flush。

返回值

成功时返回 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 5.3 和 5.4 的方式创建一个不可擦除的输出缓冲区

<?php

if (version_compare(PHP_VERSION, '5.4.0', '>=')) {
  ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^
    PHP_OUTPUT_HANDLER_REMOVABLE);
} else {
  ob_start(null, 0, false);
}

?>

参见

ob_get_contents
ob_end_clean
ob_end_flush
ob_implicit_flush
ob_gzhandler
ob_iconv_handler
mb_output_handler
ob_tidyhandler

output_add_rewrite_var

添加URL重写器的值（Add URL rewriter values）

说明

bool output_add_rewrite_var ( string $name , string $value )

此函数给URL重写机制添加名/值对。这种名值对将被添加到URL（以GET参数的形式）和表单（以input隐藏域的形式），当透明URL重写用 session.use_trans_sid 开启时同样可以添加到session ID。要注意，绝对URL(http://example.com/..)不能被重写。

此函数的行为由url_rewriter.tags php.ini 参数控制。

Note: 如果还没有活跃的输出缓冲区，调用此函数将隐式地开启它。

参数

name
变量名。

value
变量值。

返回值

成功时返回 true，或者在失败时返回 false。

范例

示例 #1 output_add_rewrite_var example

<?php
output_add_rewrite_var('var', 'value');

// some links
echo '<a href="file.php">link</a>
<a href="http://example.com">link2</a>';

// a form
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
ob_flush
ob_list_handlers

output_reset_rewrite_vars

重设URL重写器的值（Reset URL rewriter values）

说明

bool output_reset_rewrite_vars ( void )

此函数重置URL重写器，移除所有的先前由 output_add_rewrite_var 函数设置的重写变量，或者移除会话机制（如果session.use_trans_sid 在 session_start上进行了设置）。

返回值

成功时返回 true，或者在失败时返回 false。

范例

示例 #1 output_reset_rewrite_vars example

<?php
session_start();
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?PHPSESSID=xxx&var=value">link</a>
<a href="file.php">link</a>

参见

output_add_rewrite_var
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_gzhandler — 在ob_start中使用的用来压缩输出缓冲区中内容的回调函数。ob_start callback function to gzip output buffer
ob_implicit_flush — 打开/关闭绝对刷送
ob_list_handlers — 列出所有使用中的输出处理程序。
ob_start — 打开输出控制缓冲
output_add_rewrite_var — 添加URL重写器的值（Add URL rewriter values）
output_reset_rewrite_vars — 重设URL重写器的值（Reset URL rewriter values）