php-doc-ru/reference/phar/Phar/buildFromIterator.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: f5a5f5ae75cf140bd3dd65da52b70f6236b0e131 Maintainer: rjhdby Status: ready -->
<!-- Reviewed: yes Maintainer: lex -->

<refentry xml:id="phar.buildfromiterator" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>Phar::buildFromIterator</refname>
  <refpurpose>Создаёт phar-архив из итератора</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>array</type><methodname>Phar::buildFromIterator</methodname>
   <methodparam><type>Iterator</type><parameter>iter</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>base_directory</parameter></methodparam>
  </methodsynopsis>
  &phar.write;
  <para>
   Заполняет phar-архив из итератора. Поддерживаются итераторы двух типов:
   такие, в которых отображается соответствие имени файла внутри phar-архива к
   файлу на диске, и такие как DirectoryIterator, которые возвращают
   объекты SplFileInfo. Для итераторов, которые возвращают объекты SplFileInfo,
   второй параметр является обязательным.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>iter</parameter></term>
     <listitem>
      <para>
       Любой итератор, который или ассоциативно отображает пути к файлам
       внутри phar-архива к файлам на диске, или возвращает объекты SplFileInfo.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>base_directory</parameter></term>
     <listitem>
      <para>
       Для итераторов, возвращающих объекты SplFileInfo, — часть полного пути каждого
       файла, которая должна быть удалена во время его добавления в phar-архив.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   <function>Phar::buildFromIterator</function> возвращает ассоциативный массив,
   в котором отображаются соответствия пути к файлу внутри архива к пути к файлу в
   файловой системе.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Этот метод выбрасывает исключение <classname>UnexpectedValueException</classname>,
   когда итератор возвращает некорректные значения, такие как целочисленный ключ
   вместо строки. Исключение <classname>BadMethodCallException</classname> будет брошено,
   когда итератор, основанный на SplFileInfo, используется без параметра
   <parameter>base_directory</parameter>. Исключение <classname>PharException</classname>
   выбрасывается в случае ошибок сохранения phar-архива.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title>Пример использования <function>Phar::buildFromIterator</function> с объектами SplFileInfo</title>
   <para>
    Для большинства phar-архивов, архив будет отражать фактическую структуру директории,
    и второй тип итератора будет наиболее полезным. Например, он будет полезным для создания phar-архива,
    содержащего файлы со структурой директорий как в этом примере:
   </para>
   <para>
    <screen>
<![CDATA[
/путь/к/проекту/
                 config/
                        dist.xml
                        debug.xml
                 lib/
                     file1.php
                     file2.php
                 src/
                     processthing.php
                 www/
                     index.php
                 cli/
                     index.php
    ]]>
    </screen>
   </para>
   <para>
    Для добавления этих файлов в phar-архив &quot;project.phar&quot; может быть использован следующий код:
   </para>
   <para>
    <programlisting role="php">
<![CDATA[
<?php
// создать с псевдонимом "project.phar"
$phar = new Phar('project.phar', 0, 'project.phar');
$phar->buildFromIterator(
    new RecursiveIteratorIterator(
     new RecursiveDirectoryIterator('/путь/к/проекту')),
    '/путь/к/проекту');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>
    ]]>
    </programlisting>
   </para>
   <para>
    После этого файл project.phar может быть использован немедленно.
    Такие значения как сжатие и метаданные не устанавливаются методом
    <function>Phar::buildFromIterator</function> и могут быть
    установлены после создания phar-архива.
   </para>
   <para>
    В качестве интересного замечания можно отметить, что <function>Phar::buildFromIterator</function>
    также может быть использован для копирования содержимого существующего phar-архива,
    поскольку класс Phar является потомком <classname>DirectoryIterator</classname>:
   </para>
   <para>
    <programlisting role="php">
<![CDATA[
<?php
// создать с псевдонимом "project.phar"
$phar = new Phar('project.phar', 0, 'project.phar');
$phar->buildFromIterator(
    new RecursiveIteratorIterator(
     new Phar('/путь/к/anotherphar.phar')),
    'phar:///путь/к/anotherphar.phar/путь/к/проекту');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>
    ]]>
    </programlisting>
   </para>
  </example>
  <example>
   <title>Пример использования <function>Phar::buildFromIterator</function> с другими типами итераторов</title>
   <para>
    Второй тип предполагает использование любого итератора, возвращаемые значения которого
    отображают соответствие имени файла внутри phar-архива к файлу на диске, как в случае с
    <classname>ArrayIterator</classname>:
   </para>
   <para>
    <programlisting role="php">
<![CDATA[
<?php
// создать с псевдонимом "project.phar"
$phar = new Phar('project.phar', 0, 'project.phar');
$phar->buildFromIterator(
    new ArrayIterator(
     array(
        'путь/внутри/архива/file.php' => dirname(__FILE__) . '/somefile.php',
        'друго/путь/внутри/архива/file.jpg' => fopen('/путь/к/bigfile.jpg', 'rb'),
     )));
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>
    ]]>
    </programlisting>
   </para>
  </example>
 </refsect1>

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