reference/phar/PharData/buildFromIterator.xml
f03806fcd8fe03a0501bd40b6e3939ff6589a1d2
f03806fcd8fe03a0501bd40b6e3939ff6589a1d2
...
...
@@ -3,15 +3,15 @@
3
3
<refentry xml:id="phardata.buildfromiterator" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4
4
<refnamediv>
5
5
<refname>PharData::buildFromIterator</refname>
6
-
<refpurpose>Construct a tar or zip archive from an iterator.</refpurpose>
6
+
<refpurpose>Construct a tar or zip archive from an iterator</refpurpose>
7
7
</refnamediv>
8
8
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
-
<methodsynopsis>
12
-
<type>array</type><methodname>PharData::buildFromIterator</methodname>
13
-
<methodparam><type>Iterator</type><parameter>iter</parameter></methodparam>
14
-
<methodparam choice="opt"><type>string</type><parameter>base_directory</parameter></methodparam>
11
+
<methodsynopsis role="PharData">
12
+
<modifier>public</modifier> <type>array</type><methodname>PharData::buildFromIterator</methodname>
13
+
<methodparam><type>Traversable</type><parameter>iterator</parameter></methodparam>
14
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>baseDirectory</parameter><initializer>&null;</initializer></methodparam>
15
15
</methodsynopsis>
16
16
<para>
17
17
Populate a tar or zip archive from an iterator. Two styles of iterators are supported,
...
...
@@ -21,18 +21,94 @@
21
21
parameter is required.
22
22
</para>
23
23
</refsect1>
24
-
<refsect1 role="examples">
25
-
&reftitle.examples;
26
-
<example>
27
-
<title>A <function>PharData::buildFromIterator</function> with SplFileInfo</title>
24
+
25
+
<refsect1 role="parameters">
26
+
&reftitle.parameters;
28
27
<para>
29
-
For most tar/zip archives, the archive will reflect an actual directory layout, and
30
-
the second style is the most useful. For instance, to create a tar/zip archive
31
-
containing the files in this sample directory layout:
28
+
<variablelist>
29
+
<varlistentry>
30
+
<term><parameter>iterator</parameter></term>
31
+
<listitem>
32
+
<para>
33
+
Any iterator that either associatively maps tar/zip file to location or
34
+
returns SplFileInfo objects
35
+
</para>
36
+
</listitem>
37
+
</varlistentry>
38
+
<varlistentry>
39
+
<term><parameter>baseDirectory</parameter></term>
40
+
<listitem>
41
+
<para>
42
+
For iterators that return SplFileInfo objects, the portion of each
43
+
file's full path to remove when adding to the tar/zip archive
44
+
</para>
45
+
</listitem>
46
+
</varlistentry>
47
+
</variablelist>
32
48
</para>
49
+
50
+
</refsect1>
51
+
<refsect1 role="returnvalues">
52
+
&reftitle.returnvalues;
33
53
<para>
34
-
<screen>
35
-
<![CDATA[
54
+
<function>PharData::buildFromIterator</function> returns an associative array
55
+
mapping internal path of file to the full path of the file on the
56
+
filesystem.
57
+
</para>
58
+
</refsect1>
59
+
60
+
<refsect1 role="errors">
61
+
&reftitle.errors;
62
+
<para>
63
+
This method returns <classname>UnexpectedValueException</classname> when the
64
+
iterator returns incorrect values, such as an integer key instead of a
65
+
string, a <classname>BadMethodCallException</classname> when an
66
+
SplFileInfo-based iterator is passed without a <parameter>baseDirectory</parameter>
67
+
parameter, or a <classname>PharException</classname> if there were errors
68
+
saving the phar archive.
69
+
</para>
70
+
</refsect1>
71
+
72
+
<refsect1 role="changelog">
73
+
&reftitle.changelog;
74
+
<informaltable>
75
+
<tgroup cols="2">
76
+
<thead>
77
+
<row>
78
+
<entry>&Version;</entry>
79
+
<entry>&Description;</entry>
80
+
</row>
81
+
</thead>
82
+
<tbody>
83
+
<row>
84
+
<entry>8.1.0</entry>
85
+
<entry>
86
+
<methodname>PharData::buildFromIterator</methodname> no longer returns &false;.
87
+
</entry>
88
+
</row>
89
+
<row>
90
+
<entry>8.0.0</entry>
91
+
<entry>
92
+
<parameter>baseDirectory</parameter> is now nullable.
93
+
</entry>
94
+
</row>
95
+
</tbody>
96
+
</tgroup>
97
+
</informaltable>
98
+
</refsect1>
99
+
100
+
<refsect1 role="examples">
101
+
&reftitle.examples;
102
+
<example>
103
+
<title>A <function>PharData::buildFromIterator</function> with SplFileInfo</title>
104
+
<para>
105
+
For most tar/zip archives, the archive will reflect an actual directory layout, and
106
+
the second style is the most useful. For instance, to create a tar/zip archive
107
+
containing the files in this sample directory layout:
108
+
</para>
109
+
<para>
110
+
<screen>
111
+
<![CDATA[
36
112
/path/to/project/
37
113
config/
38
114
dist.xml
...
...
@@ -47,14 +123,14 @@
47
123
cli/
48
124
index.php
49
125
]]>
50
-
</screen>
51
-
</para>
52
-
<para>
53
-
This code could be used to add these files to the "project.tar" tar archive:
54
-
</para>
55
-
<para>
56
-
<programlisting role="php">
57
-
<![CDATA[
126
+
</screen>
127
+
</para>
128
+
<para>
129
+
This code could be used to add these files to the "project.tar" tar archive:
130
+
</para>
131
+
<para>
132
+
<programlisting role="php">
133
+
<![CDATA[
58
134
<?php
59
135
$phar = new PharData('project.tar');
60
136
$phar->buildFromIterator(
...
...
@@ -63,21 +139,21 @@ $phar->buildFromIterator(
63
139
'/path/to/project');
64
140
?>
65
141
]]>
66
-
</programlisting>
67
-
</para>
68
-
<para>
69
-
The file <literal>project.tar</literal> can then be used immediately. <function>PharData::buildFromIterator</function> does not
70
-
set values such as compression, metadata, and this can be done after creating the
71
-
tar/zip archive.
72
-
</para>
73
-
<para>
74
-
As an interesting note, <function>PharData::buildFromIterator</function> can also be used to
75
-
copy the contents of an existing phar, tar or zip archive, as the PharData object descends
76
-
from <classname>DirectoryIterator</classname>:
77
-
</para>
78
-
<para>
79
-
<programlisting role="php">
80
-
<![CDATA[
142
+
</programlisting>
143
+
</para>
144
+
<para>
145
+
The file <literal>project.tar</literal> can then be used immediately. <function>PharData::buildFromIterator</function> does not
146
+
set values such as compression, metadata, and this can be done after creating the
147
+
tar/zip archive.
148
+
</para>
149
+
<para>
150
+
As an interesting note, <function>PharData::buildFromIterator</function> can also be used to
151
+
copy the contents of an existing phar, tar or zip archive, as the PharData object descends
152
+
from <classname>DirectoryIterator</classname>:
153
+
</para>
154
+
<para>
155
+
<programlisting role="php">
156
+
<![CDATA[
81
157
<?php
82
158
$phar = new PharData('project.tar');
83
159
$phar->buildFromIterator(
...
...
@@ -87,18 +163,18 @@ $phar->buildFromIterator(
87
163
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
88
164
?>
89
165
]]>
90
-
</programlisting>
91
-
</para>
166
+
</programlisting>
167
+
</para>
92
168
</example>
93
169
<example>
94
-
<title>A <function>PharData::buildFromIterator</function> with other iterators</title>
95
-
<para>
96
-
The second form of the iterator can be used with any iterator that returns
97
-
a key => value mapping, such as an <classname>ArrayIterator</classname>:
98
-
</para>
99
-
<para>
100
-
<programlisting role="php">
101
-
<![CDATA[
170
+
<title>A <function>PharData::buildFromIterator</function> with other iterators</title>
171
+
<para>
172
+
The second form of the iterator can be used with any iterator that returns
173
+
a key => value mapping, such as an <classname>ArrayIterator</classname>:
174
+
</para>
175
+
<para>
176
+
<programlisting role="php">
177
+
<![CDATA[
102
178
<?php
103
179
$phar = new PharData('project.tar');
104
180
$phar->buildFromIterator(
...
...
@@ -109,58 +185,11 @@ $phar->buildFromIterator(
109
185
)));
110
186
?>
111
187
]]>
112
-
</programlisting>
113
-
</para>
188
+
</programlisting>
189
+
</para>
114
190
</example>
115
191
</refsect1>
116
192
117
-
<refsect1 role="parameters">
118
-
&reftitle.parameters;
119
-
<para>
120
-
<variablelist>
121
-
<varlistentry>
122
-
<term><parameter>iter</parameter></term>
123
-
<listitem>
124
-
<para>
125
-
Any iterator that either associatively maps tar/zip file to location or
126
-
returns SplFileInfo objects
127
-
</para>
128
-
</listitem>
129
-
</varlistentry>
130
-
<varlistentry>
131
-
<term><parameter>base_directory</parameter></term>
132
-
<listitem>
133
-
<para>
134
-
For iterators that return SplFileInfo objects, the portion of each
135
-
file's full path to remove when adding to the tar/zip archive
136
-
</para>
137
-
</listitem>
138
-
</varlistentry>
139
-
</variablelist>
140
-
</para>
141
-
142
-
</refsect1>
143
-
<refsect1 role="returnvalues">
144
-
&reftitle.returnvalues;
145
-
<para>
146
-
<function>PharData::buildFromIterator</function> returns an associative array
147
-
mapping internal path of file to the full path of the file on the
148
-
filesystem.
149
-
</para>
150
-
</refsect1>
151
-
152
-
<refsect1 role="errors">
153
-
&reftitle.errors;
154
-
<para>
155
-
This method returns <classname>UnexpectedValueException</classname> when the
156
-
iterator returns incorrect values, such as an integer key instead of a
157
-
string, a <classname>BadMethodCallException</classname> when an
158
-
SplFileInfo-based iterator is passed without a <parameter>base_directory</parameter>
159
-
parameter, or a <classname>PharException</classname> if there were errors
160
-
saving the phar archive.
161
-
</para>
162
-
</refsect1>
163
-
164
193
<refsect1 role="seealso">
165
194
&reftitle.seealso;
166
195
<para>
...
...
@@ -171,7 +200,6 @@ $phar->buildFromIterator(
171
200
</refsect1>
172
201
173
202
</refentry>
174
-
175
203
<!-- Keep this comment at the end of the file
176
204
Local variables:
177
205
mode: sgml
178
206