Skip to content

Commit

Permalink
translated part of output buffering documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@mumumu
mumumu committed May 12, 2024
1 parent dd3d6f4 commit 972fdb3
Show file tree
Hide file tree
Showing 2 changed files with 116 additions and 111 deletions.
130 changes: 66 additions & 64 deletions reference/outcontrol/flushing-system-buffers.xml
View file
Original file line number Diff line number Diff line change
@@ -1,136 +1,138 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 7ad99aeafea66a1562f668aa3cb11dcc9d9cb951 Maintainer: mumumu Status: working -->
<!-- EN-Revision: 7ad99aeafea66a1562f668aa3cb11dcc9d9cb951 Maintainer: mumumu Status: ready -->
<chapter xml:id="outcontrol.flushing-system-buffers" xmlns="http://docbook.org/ns/docbook">
<title>Flushing System Buffers</title>
<title>システムバッファのフラッシュ</title>
<para>
PHP provides two related ways
to flush (send and discard the contents of) system buffers:
through calling <function>flush</function>
and through enabling implicit flushing
with <function>ob_implicit_flush</function>
or the <link linkend="ini.implicit-flush">implicit_flush</link>
&php.ini; setting.
PHP は、システムバッファをフラッシュ(内容を送信して破棄)
する方法をふたつ提供します:
<function>flush</function> と、
<function>ob_implicit_flush</function> や
&php.ini; 設定 <link linkend="ini.implicit-flush">implicit_flush</link>
経由で暗黙のフラッシュを有効にする方法です。
</para>

<section>
<title>Output Flushing Behaviour</title>
<title>出力をフラッシュする動作</title>
<para>
With implicit flushing disabled, PHP will flush output only
when <function>flush</function> is called or when the script ends.
暗黙のフラッシュを無効にすると、
PHP は <function>flush</function> をコールしたときか、
スクリプトが終了したときにだけ出力をフラッシュします。
</para>
<para>
With implicit flushing enabled, PHP will attempt to flush
after every block of code resulting in output.
Output in this context is non-zero length data that is:
暗黙のフラッシュを有効にすると、
PHP は出力を生成するコードブロックが終了するたびに、
フラッシュを実行しようとします。
このコンテクストにおける出力は、以下に示す長さが 0 より大きなデータです:
<itemizedlist xml:id="outputcontrol.what-is-output">
<listitem>
<simpara>
outside of the <literal>&#60;?php ?&#62;</literal> tags
<literal>&#60;?php ?&#62;</literal> タグの外側
</simpara>
</listitem>
<listitem>
<simpara>
printed by language constructs and functions
whose explicit purpose is to output user provided variables or strings such as
ユーザが提供した変数や文字列を出力することを明確な目的とした言語構造や関数による出力。
これにあてはまる言語構造や関数は、
<function>echo</function>, <function>print</function>,
<function>printf</function>, <function>var_dump</function>,
<function>var_export</function>, <function>vprintf</function>
です。
</simpara>
</listitem>
<listitem>
<simpara>
printed by functions whose purpose is to collect and output
data/information on the running script or PHP such as
実行中のスクリプトや PHP に関するデータ/情報を収集し、
出力することを目的とした関数による出力。
これにあてはまる関数は、
<function>debug_print_backtrace</function>, <function>phpcredits</function>,
<function>phpinfo</function>,
<methodname>ReflectionExtension::info</methodname>
<methodname>ReflectionExtension::info</methodname> です。
</simpara>
</listitem>
<listitem>
<simpara>
printed by PHP on an uncaught exception or an unhandled error
(subject to the settings of
<link linkend="ini.display-errors">display_errors</link>
and <link linkend="ini.error-reporting">error_reporting</link>)
捕捉されなかった例外や、処理されなかったエラーが発生したときに
PHP が行う出力。
(出力されるかどうかは、
<link linkend="ini.display-errors">display_errors</link> と
<link linkend="ini.error-reporting">error_reporting</link> の設定次第です)
</simpara>
</listitem>
<listitem>
<simpara>
anything written to <literal>php://output</literal>
<literal>php://output</literal> に書き込まれたあらゆるデータ
</simpara>
</listitem>
</itemizedlist>
</para>
<note>
<simpara>
Printing empty strings or sending headers is not considered output
and will not result in a flush operation.
空文字列やヘッダの送信は、出力とはみなされないので、
フラッシュ操作は発生しません。
</simpara>
</note>
<warning>
<simpara>
If implicit flushing is enabled, control characters
(e.g. <literal>"\n"</literal>, <literal>"\r"</literal>,
<literal>"\0"</literal>)
will trigger flushing as well.
暗黙のフラッシュが有効な場合、制御文字
(例: <literal>"\n"</literal>, <literal>"\r"</literal>,
<literal>"\0"</literal>) もフラッシュを発生させます。
</simpara>
</warning>
</section>

<section>
<title>Limitations</title>
<title>制限</title>
<para>
This functionality cannot flush user-level output buffers.
To use these together, user-level output buffers must be flushed
before flushing system buffers in order for PHP to produce any output.
この機能は、ユーザレベルの出力バッファをフラッシュできません。
ユーザレベルの出力バッファを一緒にフラッシュするには、
PHP が何らかの出力を生成するためにシステムバッファをフラッシュする前に、
ユーザレベルの出力バッファをフラッシュしなければなりません。
</para>
<warning>
<simpara>
Calling <function>flush</function> or implicit flushing being enabled
can interfere with output handlers of user-level output buffers
that set and send headers in a web context
(e.g. <function>ob_gzhandler</function>)
by sending headers before these handlers can do so.
<function>flush</function> をコールしたり、
暗黙のフラッシュを有効にすると、
Web のコンテキスト中でヘッダを設定して送信するユーザレベルの出力バッファのハンドラ(例: <function>ob_gzhandler</function>) を邪魔する可能性があります。
これは、これらのハンドラがヘッダをそうしんする前に、フラッシュの動作がヘッダを送信することが原因です。
</simpara>
</warning>
<para>
Buffering implemented by the underlying software/hardware
cannot be overridden by PHP and should be taken into account
when working with PHP's buffer control functions.
Checking the web servers/browsers/consoles buffering settings
and working with these can alleviate possible issues.
Working in a web context, either the web server's buffering settings
or the script's buffering could be adjusted to work in tandem
whereas working around the buffering strategies of various browsers
can be achieved by adjusting buffering in the PHP script.
On consoles that implement line buffering,
newline characters could be inserted in the appropriate places
before flushing output.
基礎となる ソフトウェア/ハードウェアによって実装されたバッファリングは
PHP によって上書きできません。
よって、PHP のバッファ制御関数を使う際にはこの点を考慮する必要があります。
ウェブサーバー/ブラウザ/コンソールのバッファリング設定をチェックして使うことで、
起こりうる問題を軽減することができます。
Web のコンテキストで作業する場合、ウェブサーバーのバッファリング設定や
スクリプトのバッファリングを一緒に調整することができます。
PHP スクリプトのバッファリングを調整することで、
さまざまなブラウザのバッファリング戦略を回避できます。
行バッファリングを実装しているコンソールでは、
改行文字を適切な場所に挿入してから出力をフラッシュします。
</para>
</section>

<section>
<title><acronym>SAPI</acronym> Differences In Flushing</title>
<title><acronym>SAPI</acronym> ごとのフラッシュの動作の違い</title>
<para>
Although flushing is implemented by each <acronym>SAPI</acronym>
in a slightly different way,
these implementations fall in one of two categories:
フラッシュの機能は、<acronym>SAPI</acronym>
ごとに少し違ったやり方で実装されていますが、
以下の2つのカテゴリに分類できます:
<itemizedlist>
<listitem>
<simpara>
<acronym>SAPI</acronym>s used in a web context will flush headers first
followed by the output.
Web のコンテキストで使われる <acronym>SAPI</acronym> は、
ヘッダをまずフラッシュし、その後に出力を続けます。
<literal>Apache2Handler</literal>, <literal>CGI</literal>,
<literal>FastCGI</literal> and <literal>FPM</literal>
are such <acronym>SAPI</acronym>s
<literal>FastCGI</literal>, <literal>FPM</literal>
がこうした <acronym>SAPI</acronym> に該当します。
</simpara>
</listitem>
<listitem>
<simpara>
other <acronym>SAPI</acronym>s
such as <literal>CLI</literal> and <literal>embed</literal>
will flush output only
出力をフラッシュするだけの
<literal>CLI</literal> と <literal>embed</literal>
のようなその他の <acronym>SAPI</acronym>
</simpara>
</listitem>
</itemizedlist>
Expand Down
97 changes: 50 additions & 47 deletions reference/outcontrol/output-buffering.xml
View file
Original file line number Diff line number Diff line change
@@ -1,91 +1,94 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 7ad99aeafea66a1562f668aa3cb11dcc9d9cb951 Maintainer: mumumu Status: working -->
<!-- EN-Revision: 7ad99aeafea66a1562f668aa3cb11dcc9d9cb951 Maintainer: mumumu Status: ready -->
<chapter xml:id="outcontrol.output-buffering" xmlns="http://docbook.org/ns/docbook">
<title>Output Buffering</title>
<title>出力バッファリング</title>
<para>
Output buffering is the buffering (temporary storage) of output
before it is flushed (sent and discarded) to the browser (in a web context)
or to the shell (on the command line).
While output buffering is active no output is sent from the script,
instead the output is stored in an internal buffer.
出力バッファリングとは、ブラウザ(Web の場合) や
シェル(コマンドラインの場合) に出力をフラッシュ(送信して破棄)する前に、
バッファリング(一時的に保存) することです。
出力バッファリングが有効な間は、スクリプトから出力は送信されず、
代わりに内部バッファに保存されます。
</para>

<section>
<title>Buffering Affecting PHP</title>
<title>PHPに影響するバッファリング</title>
<para>
PHP relies on the underlying software/hardware infrastructure
when flushing output.
Buffering implemented by consoles on the command line (e.g. line buffered)
or web servers and browser in a web context (e.g. fully buffered)
do affect when output is displayed to the end-user.
Some of these effects can be eliminated by fine-tuning server settings
and/or aligning buffer sizes of the various layers.
PHP は、出力をフラッシュする際に、
基礎となる ソフトウェア/ハードウェア のインフラストラクチャに依存します。
コマンドライン上のコンソールで実装されているバッファリング
(例: 行バッファリング) や Web のコンテキストにおける ウェブサーバー
やブラウザが実装するバッファリング(例: 完全バッファリング) は、
エンドユーザーに出力を表示するタイミングに影響を与えます。
サーバの設定を微調整したり、
さまざまなレイヤーのバッファサイズを揃えたりすることで、これらの影響のいくつかを取り除くことができます。
</para>
</section>

<section>
<title>Output Buffering Control In PHP</title>
<title>PHPにおける出力バッファリングの制御</title>
<para>
PHP provides a fully buffered user-level output buffer
with functions to start, manipulate and turn off the buffer
(most <link linkend="ref.outcontrol">ob_<replaceable>*</replaceable></link> functions),
and two functions to flush the underlying system buffers
(<function>flush</function> and <function>ob_implicit_flush</function>).
Some of this functionality can be set and/or configured
using the appropriate &php.ini; settings as well.
PHP は、ユーザレベルの出力バッファを提供しており、
バッファリングを開始したり、管理したり、無効にしたりする関数を提供しています。
(これらの関数のほとんどは、<link linkend="ref.outcontrol">ob_<replaceable>*</replaceable></link> 関数にあります)
そして、既存のシステムバッファをフラッシュするための関数をふたつ
(<function>flush</function>と <function>ob_implicit_flush</function>)
提供しています。
これらの機能の中には、&php.ini; を適切に設定することで、
設定や構成できるものがあります。
</para>
</section>

<section>
<title>Use Cases</title>
<title>バッファリングの用途</title>
<para>
Output buffering is generally useful in situations when the buffered output
is modified or inspected, or it is used more than once in a request;
or when the controlled flushing of output is desired.
Specific use cases include:
出力バッファリングは一般的に、
バッファリングされた出力を修正したり、検査したり、
リクエストの中で出力を複数回使う場合に有用です。
あるいは、出力をフラッシュするタイミングを制御したい場合にも有用です。
具体的な使用例として、以下が挙げられます:
<itemizedlist>
<listitem>
<simpara>
caching the result of compute/time intensive scripts
for example by generating static <literal>HTML</literal> pages
計算/時間のかかるスクリプトの実行結果をキャッシュする場合。
たとえば、静的な<literal>HTML</literal>ページを生成する場合などです。
</simpara>
</listitem>
<listitem>
<simpara>
re-using the generated output by displaying it, saving it to a file
and/or sending it by email
生成された出力を表示したり、ファイルに保存したり、
電子メールで送るなどの用途に再利用することができます。
</simpara>
</listitem>
<listitem>
<simpara>
flushing the <literal>head</literal> of an <literal>HTML</literal> page
separate from the <literal>body</literal> allows browsers
to load external resources while the script executes
potentially more time consuming processes
(e.g. database/file access, external network connection).
This is only useful if the <literal>HTTP</literal> status code
cannot change after the headers are sent
<literal>HTML</literal>ページの <literal>head</literal>
を <literal>body</literal> とは別にフラッシュすることで、
ブラウザは時間のかかる可能性のある処理
(例: データベース/ファイルへのアクセス、外部ネットワーク接続)
をスクリプトが実行している間に、外部リソースを読み込むことができます。
これは、<literal>HTTP</literal> ステータスコード
がヘッダ送信後に変更できない場合にのみ有効です。
</simpara>
</listitem>
<listitem>
<simpara>
extracting information from functions that would otherwise produce output
(e.g. <function>phpinfo</function>)
出力を生成する関数(例: <function>phpinfo</function>)から情報を抽出する場合
</simpara>
</listitem>
<listitem>
<simpara>
controlling the output of third-party code by modifying/using parts
(e.g. extracting data, replacing words/phrases,
adding missing <literal>HTML</literal> tags),
or discarding it entirely under certain conditions (e.g. errors)
出力を部分的に修正したり、一部を採用したり
(例えば、データの抽出、単語/フレーズの置換、
足りない<literal>HTML</literal>タグの追加)、
特定の条件下(例えばエラー)では完全に破棄することで、
サードパーティのコードの出力を制御します。
</simpara>
</listitem>
<listitem>
<simpara>
polyfilling certain unavailable web server functionality
(e.g. compressing or encoding output)
特定のウェブサーバーでは利用できないある機能をサポートする場合
(出力の圧縮やエンコードなど)
</simpara>
</listitem>
</itemizedlist>
Expand Down

0 comments on commit 972fdb3

Please sign in to comment.