var-export.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 0f27fadf81b66268edf545f13891401b4d53cc38 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id="function.var-export" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>var_export</refname>
  <refpurpose>Retourne le code PHP utilisé pour générer une 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> retourne des données structurées
   sur la variable donnée. C'est le même principe que
   <function>var_dump</function> mais avec une exception :
   le résultat retourné est du code PHP valide.
  </simpara>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>value</parameter></term>
     <listitem>
      <para>
       La variable que vous voulez exporter.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>return</parameter></term>
     <listitem>
      <para>
       Si utilisé et mis à &true;, <function>var_export</function> retournera
       la représentation de la variable au lieu de l'afficher.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retourne la représentation de la variable lorsque le paramètre
   <parameter>return</parameter> est utilisé et évalué à &true;. Autrement,
   cette fonction retournera &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>
        Les noms de classe exportés sont désormais pleinement qualifiés. 
        Auparavant, l'antislash principal était omis.
       </entry>
      </row>
      <row>
       <entry>7.3.0</entry>
       <entry>
        Exporte désormais les objets <classname>stdClass</classname> en tant
        qu'un &array; transtyper vers un objet (<code>(object) array( ... )</code>),
        au lieu d'utiliser la méthode non existante
        <methodname>stdClass::__setState</methodname>.
        L'effet pratique est que désormais <classname>stdClass</classname> est
        exportable, et que le code résultant fonctionnera même sur des versions
        antérieure de PHP.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>var_export</function></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; // 3.1

?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
3.1
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Exporter stdClass (à partir de 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>Exporter des 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>Utilisation de <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>
    Les variables de type &resource; ne peuvent être exportées par cette
    fonction.
   </para>
  </note>
  <note>
   <para>
    <function>var_export</function> ne gère pas les références circulaires car il
    serait impossible de générer un code PHP analysable pour ce type de données.
    Si vous voulez faire quelque chose avec la représentation complète d'un tableau
    ou d'un objet, utilisez la fonction <function>serialize</function>.
   </para>
  </note>
  <warning>
   <para>
    Antérieur à PHP 8.2.0, lorsque <function>var_export</function> exporte des objets, 
    l'antislash initial n'est pas inclus dans l'espace de nom de la classe
    et ce, pour un maximum de compatibilité.
   </para>
  </warning>
  <note>
   <para>
    Pour être capable d'évaluer le PHP généré par <function>var_export</function>,
    tous les objets analysés doivent implémenter la méthode magique <link
    linkend="object.set-state">__set_state</link>. La seule exception est
    <classname>stdClass</classname>; qui est exportée en utilisant un cast d'un
    &array; à un objet.
   </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
-->