ob-start.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: d715365c098db000eaf7dcd987ee6093f6e83091 Maintainer: takagi Status: ready -->
<!-- CREDITS: hirokawa,mumumu -->
<refentry xml:id="function.ob-start" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>ob_start</refname>
  <refpurpose>出力のバッファリングを有効にする</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>ob_start</methodname>
   <methodparam choice="opt"><type class="union"><type>callable</type><type>null</type></type><parameter>callback</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>chunk_size</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>PHP_OUTPUT_HANDLER_STDFLAGS</constant></initializer></methodparam>
  </methodsynopsis>
  <para>
   この関数は出力のバッファリングをオンにします。
   出力のバッファリングを有効にすると、
   (ヘッダ以外の) スクリプトからの出力は実際には行われず、
   代わりに内部バッファに保存されます。
  </para>
  <para>
   この内部バッファの内容は、<function>ob_get_contents</function>
   を用いて文字列変数にコピーされます。
   内部バッファの内容を出力するには
   <function>ob_end_flush</function> を使用します。
   <function>ob_end_clean</function>
   は、バッファの内容を出力せずに消去します。
  </para>
  <warning>
   <para>
    web サーバーによっては (例: Apache)、コールバック関数からコールされた際に、
    スクリプトの実行ディレクトリを変更するものがあります。
    コールバック関数の内部で <literal>chdir(dirname($_SERVER['SCRIPT_FILENAME']))</literal>
    などと指定することで、これをもとに戻すことが可能です。
   </para>
  </warning>
  <para>
   出力バッファはスタッカブルであり、このため、他の
   <function>ob_start</function> がアクティブの間に
   <function>ob_start</function> をコールすることが可能です。この場合、
   <function>ob_end_flush</function> を適切な回数コールするようにしてください。
   複数の出力コールバック関数がアクティブの場合、
   ネストした順番で逐次連続的に出力がフィルタ処理されます。
  </para>
  <para>
   スクリプトが終了した際に、
   出力バッファリングがまだアクティブな場合、
   PHP はバッファリングされた内容を自動的に出力します。
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>callback</parameter></term>
     <listitem>
      <para>
       オプションの引数 <parameter>callback</parameter>
       関数を指定することが可能です。この関数は、パラメータとして文字列をとり、
       文字列を返します。このコールバック関数は、
       出力バッファがフラッシュ (送信) あるいは消去
       (<function>ob_flush</function>, <function>ob_clean</function>
       あるいは同等の関数で) された場合、
       またはリクエストの最後にブラウザに出力をフラッシュする際にコールされます。
       <parameter>callback</parameter> がコールされた際に、
       この関数は出力バッファの内容をパラメータとして受け取ります。このコールバック関数は、
       新規の出力バッファを実際に出力される結果として返す必要があり、
       この結果はブラウザに送信されます。
       <parameter>callback</parameter> がコール可能な関数ではない場合は
       &false; を返します。
       コールバックのシグネチャは、次のとおりです。
      </para>
      <para>
       <methodsynopsis>
        <type>string</type><methodname><replaceable>handler</replaceable></methodname>
        <methodparam><type>string</type><parameter>buffer</parameter></methodparam>
        <methodparam choice="opt"><type>int</type><parameter>phase</parameter></methodparam>
       </methodsynopsis>
       <variablelist>
        <varlistentry>
         <term><parameter>buffer</parameter></term>
         <listitem>
          <simpara>
           出力バッファの内容。
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>phase</parameter></term>
         <listitem>
          <simpara>
           <link
           linkend="outcontrol.constants"><constant>PHP_OUTPUT_HANDLER_*</constant>
           定数</link> のビットマスク
          </simpara>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
      <para>
       <parameter>callback</parameter> が &false;
       を返すと、元の入力がそのままブラウザに送信されます。
      </para>
      <para>
       <parameter>callback</parameter> パラメータに &null; 値を渡すと、
       これをバイパスすることができます。
      </para>
      <para>
       <function>ob_end_clean</function>、
       <function>ob_end_flush</function>、<function>ob_clean</function>、
       <function>ob_flush</function> および <function>ob_start</function>
       をコールバック関数の内部からコールすることはできません。
       実際にコールした際の挙動は未定義です。バッファの内容を消去したい際には、
       コールバック関数から "" (空文字列) を返してください。
       同じく、<literal>print_r($expression, true)</literal> や
       <literal>highlight_file($filename, true)</literal> のような
       出力バッファリング関数も、
       コールバック関数の内部からコールすることはできません。
      </para>
      <note>
       <para>
        Web ページの圧縮をサポートする圧縮 gz エンコード
        されたデータの Web ブラウザへの送信を容易にするために
        <function>ob_gzhandler</function> が存在します。
        <function>ob_gzhandler</function> は、ブラウザが受け入れる content
        encoding の型を調べ、それに基づいて出力を返します。
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>chunk_size</parameter></term>
     <listitem>
      <para>
       オプションのパラメータ <parameter>chunk_size</parameter> が渡された場合、
       バッファの長さが <parameter>chunk_size</parameter> バイトを超えるたびに、
       出力の後でバッファがフラッシュされます。
       デフォルト値は <literal>0</literal> で、これは出力関数がコールされるのが
       出力バッファが閉じたときだけであることを意味します。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       <parameter>flags</parameter> はビットマスクで、出力バッファ上でどんな操作ができるのかを制御します。
       デフォルトでは、出力バッファのクリーン、フラッシュ、削除がすべてできるようになっています。
       これは、明示的に
       <constant>PHP_OUTPUT_HANDLER_CLEANABLE</constant> |
       <constant>PHP_OUTPUT_HANDLER_FLUSHABLE</constant> |
       <constant>PHP_OUTPUT_HANDLER_REMOVABLE</constant> と設定したり、あるいは短縮形で
       <constant>PHP_OUTPUT_HANDLER_STDFLAGS</constant> と設定したりするのと同じです。
      </para>
      <para>
       各フラグが、次の表のように関数へのアクセスを制御します。
       <informaltable>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>定数</entry>
           <entry>関数</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><constant>PHP_OUTPUT_HANDLER_CLEANABLE</constant></entry>
           <entry>
            <function>ob_clean</function>、
            <function>ob_end_clean</function> および
            <function>ob_get_clean</function>
           </entry>
          </row>
          <row>
           <entry><constant>PHP_OUTPUT_HANDLER_FLUSHABLE</constant></entry>
           <entry>
            <function>ob_end_flush</function>、
            <function>ob_flush</function> および
            <function>ob_get_flush</function>
           </entry>
          </row>
          <row>
           <entry><constant>PHP_OUTPUT_HANDLER_REMOVABLE</constant></entry>
           <entry>
            <function>ob_end_clean</function>、
            <function>ob_end_flush</function> および
            <function>ob_get_flush</function>
           </entry>
          </row>
         </tbody>
        </tgroup>
       </informaltable>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>ユーザー定義のコールバック関数の例</title>
    <programlisting role="php">
<![CDATA[
<?php

function callback($buffer)
{
  // apples を全て 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();

?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
<html>
<body>
<p>It's like comparing oranges to oranges.</p>
</body>
</html>
]]>
    </screen>
   </example>
  </para>

  <para>
   <example xml:id="function.ob-start.flags-bc">
    <title>削除不可能な出力バッファを作る例</title>
    <programlisting role="php">
<![CDATA[
<?php

ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^ PHP_OUTPUT_HANDLER_REMOVABLE);

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>ob_get_contents</function></member>
    <member><function>ob_end_clean</function></member>
    <member><function>ob_end_flush</function></member>
    <member><function>ob_implicit_flush</function></member>
    <member><function>ob_gzhandler</function></member>
    <member><function>ob_iconv_handler</function></member>
    <member><function>mb_output_handler</function></member>
    <member><function>ob_tidyhandler</function></member>
   </simplelist>
  </para>
 </refsect1>  

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->