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 class="union"><type>string</type><type>null</type></type><methodname>var_export</methodname>
   <methodparam><type>mixed</type><parameter>value</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>value</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="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>8.2.0</entry>
       <entry>
        Exported class names are now fully qualified; previously, the leading
        backslash was ommitted.
       </entry>
      </row>
      <row>
       <entry>7.3.0</entry>
       <entry>
        Now exports <classname>stdClass</classname> objects as an array cast to
        an object (<code>(object) array( ... )</code>), rather than using the
        nonexistent method <methodname>stdClass::__setState</methodname>.
        The practical effect is that now <classname>stdClass</classname> is
        exportable, and the resulting code will even work on earlier versions of
        PHP.
       </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 stdClass (since PHP 7.3.0)</title>
    <programlisting role="php">
<![CDATA[
<?php
$person = new stdClass;
$person->name = 'ElePHPant ElePHPantsdotter';
$person->website = 'https://php.net/elephpant.php';

var_export($person);
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
(object) array(
   'name' => 'ElePHPant ElePHPantsdotter',
   'website' => 'https://php.net/elephpant.php',
)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Exporting classes</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></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>
    Prior to PHP 8.2.0, 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. The only exception is
    <classname>stdClass</classname>, which is exported using an array cast to
    an object.
   </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
-->