archived-doc-fr/reference/xml/functions/xml-parse.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: b47e4bea197126359815c5e43403c4b77a0aaaa7 Maintainer: yannick Status: ready -->
<!-- Reviewed: yes -->
<refentry xml:id="function.xml-parse" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>xml_parse</refname>
  <refpurpose>Commence l'analyse d'un document XML</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>int</type><methodname>xml_parse</methodname>
   <methodparam><type>XMLParser</type><parameter>parser</parameter></methodparam>
   <methodparam><type>string</type><parameter>data</parameter></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>is_final</parameter><initializer>&false;</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>xml_parse</function> analyse un document XML. Les gestionnaires
   pour les événements configurés sont appelés autant de fois que nécessaire.
  </para>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>parser</parameter></term>
     <listitem>
      <para>
       Une référence sur l'analyseur XML à utiliser.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>data</parameter></term>
     <listitem>
      <para>
       Une partie des données à analyser. Un document peut être analysé
       morceau par morceau par appels successifs à 
       <function>xml_parse</function> avec de nouvelles données, aussi longtemps
       que le paramètre <parameter>is_final</parameter> est défini et &true;
       lorsque les dernières données sont analysées.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>is_final</parameter></term>
     <listitem>
      <para>
       Si défini et vaut &true;, <parameter>data</parameter> sera le dernier
       morceau de données envoyées à l'analyseur.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retourne 1 en cas de succès ou 0 en cas d'échec.
  </para>
  <para>
   Lors d'un échec d'analyse, la cause de l'erreur peut être obtenue grâce 
   aux fonctions
   <function>xml_get_error_code</function>,
   <function>xml_error_string</function>,
   <function>xml_get_current_line_number</function>,
   <function>xml_get_current_column_number</function> et
   <function>xml_get_current_byte_index</function>.
  </para>
  <note>
   <para>
    Quelques erreurs (dont les erreurs d'entités) sont
    reportées à la fin des données, ceci uniquement
    si <parameter>is_final</parameter> vaut &true;.
   </para>
  </note>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     &xml.changelog.parser-param;
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example xml:id="xml_parse.example.chunked">
   <title>Analyse de gros documents XML par morceaux</title>
   <para>
    Cet exemple montre comment les gros documents XML peuvent être lus et
    analysés en morceaux, permettant ainsi de ne pas conserver en mémoire
    la totalité du document. Aucun gestionnaire d'erreur n'a été positionné
    pour rendre l'exemple plus concis.
   </para>
   <programlisting role="php">
<![CDATA[
<?php
$stream = fopen('examples/book-simple.xml', 'r');
$parser = xml_parser_create();

xml_set_element_handler(
    $parser,
    function($parser, $name, $attributes) { echo $name, PHP_EOL; },
    function($parser, $name) { echo $name, PHP_EOL; }
);

while (($data = fread($stream, 16384))) {
    xml_parse($parser, $data); // analyse du morceau courant
}
xml_parse($parser, '', true); // finalisation de l'analyse
fclose($stream);
]]>
   </programlisting>
  </example>
 </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
-->