-
Notifications
You must be signed in to change notification settings - Fork 70
/
buildFromIterator.xml
225 lines (216 loc) · 7.96 KB
/
buildFromIterator.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: f03806fcd8fe03a0501bd40b6e3939ff6589a1d2 Maintainer: rjhdby Status: ready -->
<!-- Reviewed: no -->
<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>Создание tar/zip-архива с помощью итератора</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>
Наполнение архив tar или zip с помощью итератора. Поддерживаются два типа
итераторов: итератор, связывающий файл на диске с файлом внутри архива и
итератор в стиле DirectoryIterator, который возвращает объекты SplFileInfo.
Для итераторов, возвращающих объекты SplFileInfo, второй параметр является
обязательным.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>iterator</parameter></term>
<listitem>
<para>
Итератор, предоставляющий связки ключ=>значение, либо
объекты SplFileInfo
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>baseDirectory</parameter></term>
<listitem>
<para>
Для итераторов, возвращающих объекты SplFileInfo, часть полного пути
добавляемых файлов, которая будет удаляться из полного пути внутри
архива.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<function>PharData::buildFromIterator</function> возвращает ассоциативный массив,
связывающий путь к файлу внутри архива с полным путём к файлу на диске.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Метод выбрасывает исключение <classname>UnexpectedValueException</classname>, если
итератор вернул некорректное значение, например целочисленный ключ вместо строки.
Исключение <classname>BadMethodCallException</classname> выбрасывается когда
задан итератор, возвращающий объекты SplFileInfo без задания параметра
<parameter>baseDirectory</parameter>. В случае проблем с записью на диск бросается
исключение <classname>PharException</classname>.
</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> больше не возвращает значение &false;.
</entry>
</row>
<row>
<entry>8.0.0</entry>
<entry>
<parameter>baseDirectory</parameter> теперь допускает значение null.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title>Пример использования <function>PharData::buildFromIterator</function> с SplFileInfo</title>
<para>
Для большинства tar/zip-архивов, структура отражает имеющееся дерево директорий
на файловой системе. К примеру, для создания tar/zip-архива, содержащего
следующую структуру директорий и файлов:
</para>
<para>
<screen>
<![CDATA[
/path/to/project/
config/
dist.xml
debug.xml
lib/
file1.php
file2.php
src/
processthing.php
www/
index.php
cli/
index.php
]]>
</screen>
</para>
<para>
Нужно использовать такой код, для создания архива "project.tar":
</para>
<para>
<programlisting role="php">
<![CDATA[
<?php
$phar = new PharData('project.tar');
$phar->buildFromIterator(
new RecursiveIteratorIterator(
new RecursiveDirectoryIterator('/path/to/project')),
'/path/to/project');
?>
]]>
</programlisting>
</para>
<para>
Файл <literal>project.tar</literal> можно использовать сразу же после его создания.
<function>PharData::buildFromIterator</function> не производит настройки
сжатия или добавления метаданных. Эти действия необходимо произвести
самостоятельно, после создания архива.
</para>
<para>
Интересное замечание: <function>PharData::buildFromIterator</function> также можно
использовать для копирования контента уже существующего phar, tar или zip-архива,
так как объект PharData наследует от <classname>DirectoryIterator</classname>:
</para>
<para>
<programlisting role="php">
<![CDATA[
<?php
$phar = new PharData('project.tar');
$phar->buildFromIterator(
new RecursiveIteratorIterator(
new Phar('/path/to/anotherphar.phar')),
'phar:///path/to/anotherphar.phar/path/to/project');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>
]]>
</programlisting>
</para>
</example>
<example>
<title>Пример использования <function>PharData::buildFromIterator</function> с другим итератором</title>
<para>
Можно использовать итераторы, возвращающие связку "ключ" => "значение",
например <classname>ArrayIterator</classname>:
</para>
<para>
<programlisting role="php">
<![CDATA[
<?php
$phar = new PharData('project.tar');
$phar->buildFromIterator(
new ArrayIterator(
array(
'internal/file.php' => dirname(__FILE__) . '/somefile.php',
'another/file.jpg' => fopen('/path/to/bigfile.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
-->