archived-doc-fr/reference/phar/PharData/buildFromIterator.xml

<?xml version='1.0' encoding='utf-8'?>
<!-- EN-Revision: f03806fcd8fe03a0501bd40b6e3939ff6589a1d2 Maintainer: gui Status: ready -->
<!-- Reviewed: yes -->
<refentry xml:id="phardata.buildfromiterator" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>PharData::buildFromIterator</refname>
  <refpurpose>Construit une archive tar ou zip à partir d'un itérateur</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis role="PharData">
   <modifier>public</modifier> <type>array</type><methodname>PharData::buildFromIterator</methodname>
   <methodparam><type>Traversable</type><parameter>iterator</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>baseDirectory</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Remplit une archive tar ou zip à partir d'un itérateur. Deux styles d'itérateurs sont supportés,
   les itérateurs qui font correspondre le chemin de fichier au sein de l'archive avec le chemin sur le disque
   et les itérateurs comme DirectoryIterator qui retournent des objets
   SplFileInfo. Pour les itérateurs qui retournent des objets SplFileInfo, le second paramètre est requis.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>iterator</parameter></term>
     <listitem>
      <para>
       N'importe quel itérateur qui fait correspondre de façon associative un fichier tar/zip ou
       qui retourne des objets SplFileInfo
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>baseDirectory</parameter></term>
     <listitem>
      <para>
       Pour les itérateurs qui retournent des objets SplFileInfo, la partie du chemin complet
       vers le fichier à enlever lors de l'ajout à l'archive tar/zip
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>

 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   <function>PharData::buildFromIterator</function> retourne un tableau associatif
   faisant correspondre un chemin de fichier interne avec un chemin complet vers
   le fichier sur le système de fichiers.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Cette méthode retourne une exception <classname>UnexpectedValueException</classname> quand
   l'itérateur retourne des valeurs incorrectes, comme une clé entière plutôt qu'une chaîne,
   une exception <classname>BadMethodCallException</classname> quand un itérateur basé sur
   SplFileInfo-based est passé sans paramètre <parameter>baseDirectory</parameter>, ou une
   exception <classname>PharException</classname> si des erreurs ont été rencontrées lors de 
   la sauvegarde de l'archive phar.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.1.0</entry>
      <entry>
       <methodname>PharData::buildFromIterator</methodname> ne retourne plus &false; désormais.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       <parameter>baseDirectory</parameter> est désormais nullable.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title>Exemple avec <function>PharData::buildFromIterator</function> et <classname>SplFileInfo</classname></title>
   <para>
    Pour la plupart de l'archive tar/zip, l'archive reflétera la structure
    de répertoire actuelle et le second style est le plus utile. Par
    exemple, pour créer une archive tar/zip contenant les fichiers
    contenant la structure de répertoire ci-dessous :
   </para>
   <para>
    <screen>
<![CDATA[
/chemin/vers/projet/
                 config/
                        dist.xml
                        debug.xml
                 lib/
                     fichier1.php
                     fichier2.php
                 src/
                     processthing.php
                 www/
                     index.php
                 cli/
                     index.php
]]>
    </screen>
   </para>
   <para>
    Ce code peut être utilisé pour ajouter des fichiers à
    l'archive &quot;projet.tar&quot; tar :
   </para>
   <para>
    <programlisting role="php">
<![CDATA[
<?php
$phar = new PharData('projet.tar');
$phar->buildFromIterator(
    new RecursiveIteratorIterator(
     new RecursiveDirectoryIterator('/chemin/vers/projet')),
    '/chemin/vers/projet');
?>
]]>
    </programlisting>
   </para>
   <para>
    Le fichier <literal>projet.tar</literal> peut alors être effacé
    immédiatement. <function>PharData::buildFromIterator</function>
    ne règle pas les paramètres tels que la compression, les métadonnées,
    ce qui peut être fait après avoir créé l'archive tar/zip.
   </para>
   <para>
    À noter que <function>Phar::buildFromIterator</function> peut aussi
    être utilisé pour copier le contenu d'une archive phar, tar ou zip
    existante, car l'objet <classname>PharData</classname> est dérivé
    de <classname>DirectoryIterator</classname> :
   </para>
   <para>
    <programlisting role="php">
<![CDATA[
<?php
$phar = new PharData('projet.tar');
$phar->buildFromIterator(
    new RecursiveIteratorIterator(
     new Phar('/chemin/vers/unautrephar.phar')),
    'phar:///chemin/vers/unautrephar.phar/chemin/vers/projet');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>
]]>
    </programlisting>
   </para>
  </example>
  <example>
   <title>Exemple avec <function>PharData::buildFromIterator</function> et d'autres itérateurs</title>
   <para>
    La seconde forme d'itérateur peut être utilisée avec n'importe quel itérateur qui retourne
    une association clé =&gt; valeur, tel que <classname>ArrayIterator</classname> :
   </para>
   <para>
    <programlisting role="php">
<![CDATA[
<?php
$phar = new PharData('projet.tar');
$phar->buildFromIterator(
    new ArrayIterator(
     array(
        'interne/fichier.php' => dirname(__FILE__) . '/unfichier.php',
        'unautre/fichier.jpg' => fopen('/chemin/vers/grosfichier.jpg', 'rb'),
     )));
?>
]]>
    </programlisting>
   </para>
  </example>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>Phar::buildFromIterator</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
-->