repo_zf1/documentation/manual/en/module_specs/Zend_Debug.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.debug.dumping">

    <title>Dumping Variables</title>

    <para>
        The static method <methodname>Zend_Debug::dump()</methodname> prints or returns
        information about an expression. This simple technique of debugging is
        common because it is easy to use in an ad hoc fashion and requires no
        initialization, special tools, or debugging environment.
    </para>

    <example id="zend.debug.dumping.example">
        <title>Example of dump() method</title>

        <programlisting language="php"><![CDATA[
Zend_Debug::dump($var, $label = null, $echo = true);
]]></programlisting>
    </example>

    <para>
        The <varname>$var</varname> argument specifies the expression or variable
        about which the <methodname>Zend_Debug::dump()</methodname> method outputs
        information.
    </para>

    <para>
        The <varname>$label</varname> argument is a string to be prepended to the
        output of <methodname>Zend_Debug::dump()</methodname>. It may be useful, for
        example, to use labels if you are dumping information about multiple
        variables on a given screen.
    </para>

    <para>
        The boolean <varname>$echo</varname> argument specifies whether the output
        of <methodname>Zend_Debug::dump()</methodname> is echoed or not.
        If <constant>TRUE</constant>, the output is echoed.
        Regardless of the value of the <varname>$echo</varname> argument, the
        return value of this method contains the output.
    </para>

    <para>
        It may be helpful to understand that
        <methodname>Zend_Debug::dump()</methodname> method wraps the <acronym>PHP</acronym> function
        <ulink url="http://php.net/var_dump"><methodname>var_dump()</methodname></ulink>.
        If the output stream is detected as a web presentation,
        the output of <methodname>var_dump()</methodname> is escaped using <ulink
            url="http://php.net/htmlspecialchars"><methodname>htmlspecialchars()</methodname></ulink>
        and wrapped with (X)HTML <command>&lt;pre&gt;</command> tags.
    </para>

    <tip>
        <title>Debugging with Zend_Log</title>

        <para>
            Using <methodname>Zend_Debug::dump()</methodname> is best for ad hoc
            debugging during software development. You can add code to dump
            a variable and then remove the code very quickly.
        </para>

        <para>
            Also consider the <link linkend="zend.log.overview">Zend_Log</link>
            component when writing more permanent debugging code. For example,
            you can use the <constant>DEBUG</constant> log level and the
            <link linkend="zend.log.writers.stream">stream log writer</link> to
            output the string returned by <methodname>Zend_Debug::dump()</methodname>.
        </para>
    </tip>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->