php-doc-en/reference/var/functions/var-export.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- splitted from ./en/functions/var.xml, last change in rev 1.6 -->
<refentry xml:id="function.var-export" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>var_export</refname>
  <refpurpose>Outputs or returns a parsable string representation of a variable</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>mixed</type><methodname>var_export</methodname>
   <methodparam><type>mixed</type><parameter>expression</parameter></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>return</parameter><initializer>false</initializer></methodparam>
  </methodsynopsis>
  <simpara>
   <function>var_export</function> gets structured information about the 
   given variable. It is similar to <function>var_dump</function>
   with one exception: the returned representation is valid PHP code.
  </simpara>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>expression</parameter></term>
     <listitem>
      <para>
       The variable you want to export.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>return</parameter></term>
     <listitem>
      <para>
       If used and set to &true;, <function>var_export</function> will return
       the variable representation instead of outputting it.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the variable representation when the <parameter>return</parameter> 
   parameter is used and evaluates to &true;. Otherwise, this function will
   return &null;.
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  &note.uses-ob;
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>5.1.0</entry>
       <entry>
        Possibility to export classes and arrays containing classes using the
        <link linkend="object.set-state">__set_state()</link> magic
        method.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>var_export</function> Examples</title>
    <programlisting role="php">
<![CDATA[
<?php
$a = array (1, 2, array ("a", "b", "c"));
var_export($a);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array (
  0 => 1,
  1 => 2,
  2 => 
  array (
    0 => 'a',
    1 => 'b',
    2 => 'c',
  ),
)
]]>
    </screen>
    <programlisting role="php">
<![CDATA[
<?php

$b = 3.1;
$v = var_export($b, true);
echo $v;

?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
3.1
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Exporting classes since PHP 5.1.0</title>
    <programlisting role="php">
<![CDATA[
<?php
class A { public $var; }
$a = new A;
$a->var = 5;
var_export($a);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
A::__set_state(array(
   'var' => 5,
))
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Using <link linkend="object.set-state">__set_state()</link> (since PHP 5.1.0)</title>
    <programlisting role="php">
<![CDATA[
<?php
class A
{
    public $var1;
    public $var2;

    public static function __set_state($an_array)
    {
        $obj = new A;
        $obj->var1 = $an_array['var1'];
        $obj->var2 = $an_array['var2'];
        return $obj;
    }
}

$a = new A;
$a->var1 = 5;
$a->var2 = 'foo';

eval('$b = ' . var_export($a, true) . ';'); // $b = A::__set_state(array(
                                            //    'var1' => 5,
                                            //    'var2' => 'foo',
                                            // ));
var_dump($b);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
object(A)#2 (2) {
  ["var1"]=>
  int(5)
  ["var2"]=>
  string(3) "foo"
}
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Variables of type <type>resource</type> couldn't be exported by this
    function.
   </para>
  </note>
  <note>
   <para>
    <function>var_export</function> does not handle circular references as
    it would be close to impossible to generate parsable PHP code for that.
    If you want to do something with the full representation of an array
    or object, use <function>serialize</function>.
   </para>
  </note>
  <warning>
   <para>
    When <function>var_export</function> exports objects, the leading backslash is not included in the class name of namespaced classes for maximum compatibility.
   </para>
  </warning>
  <note>
   <para>
    To be able to evaluate the PHP generated by <function>var_export</function>,
    all processed objects must implement the magic <link
    linkend="object.set-state">__set_state</link> method. Note that StdClass
    does not implement __set_state().
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>print_r</function></member>
    <member><function>serialize</function></member>
    <member><function>var_dump</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
-->