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
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 288721 $ -->
<!-- Purpose: compression -->
<!-- Membership: pecl -->
<book xml:id="book.phar" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Phar</title>
<!-- {{{ preface -->
<preface xml:id="intro.phar">
&reftitle.intro;
<para>
The phar extension provides a way to put entire PHP applications into a single file
called a "phar" (PHP Archive) for easy distribution and installation.
In addition to providing this service, the phar extension also provides a file-format
abstraction method for creating and manipulating tar and zip files through the
<classname>PharData</classname> class, much as
PDO provides a unified interface for accessing different databases. Unlike PDO,
which cannot convert between different databases, Phar also can convert between tar,
zip and phar file formats with a single line of code. see
<function>Phar::convertToExecutable</function> for one example.
</para>
<para>
What is phar? Phar archives are best characterized as a convenient way to group
several files into a single file. As such, a phar archive provides a way to
distribute a complete PHP application in a single file and run it from that file
without the need to extract it to disk. Additionally, phar archives can be
executed by PHP as easily as any other file, both on the commandline and from
a web server. Phar is kind of like a thumb drive for PHP applications.
</para>
<para>
Phar implements this functionality through a <link linkend="book.stream">Stream
Wrapper</link>. Normally, to use an external file within a PHP script, you
would use <function>include</function>
</para>
<para>
<example>
<title>Using an external file</title>
<programlisting role="php">
<![CDATA[
<?php
include '/path/to/external/file.php';
?>
]]>
</programlisting>
</example>
</para>
<para>
PHP can be thought of as actually translating
<literal>/path/to/external/file.php</literal> into a
stream wrapper as <literal>file:///path/to/external/file.php</literal>, and under
the hood it does in fact use the plain file stream wrapper stream functions to
access all local files.
</para>
<para>
To use a file named <literal>file.php</literal> contained with a phar archive
<literal>/path/to/myphar.phar</literal>,
the syntax is very similar to the <literal>file://</literal> syntax above.
</para>
<para>
<example>
<title>Using a file within a phar archive</title>
<programlisting role="php">
<![CDATA[
<?php
include 'phar:///path/to/myphar.phar/file.php';
?>
]]>
</programlisting>
</example>
</para>
<para>
In fact, one can treat a phar archive exactly as if it were an external disk, using
any of <function>fopen</function>-related functions, <function>opendir</function> and
<function>mkdir</function>-related functions to read, change, or create new files
and directories within the phar archive. This allows complete PHP applications
to be distributed in a single file and run directly from that file.
</para>
<para>
The most common usage for a phar archive is to distribute a complete application
in a single file. For instance, the PEAR Installer that is bundled with PHP
versions is distributed as a phar archive. To use a phar archive distributed
in this way, the archive can be executed on the command-line or via a web server.
</para>
<para>
Phar archives can be distributed as <literal>tar</literal> archives,
<literal>zip</literal> archives, or as the custom <literal>phar</literal> file format
designed specifically for the phar extension. Each file format has advantages
and disadvantages. The tar and zip file formats can be read or extracted by any
third-party tool that can read the format, but require the phar extension in order to
run with PHP. The phar file format is customized and unique to the phar extension,
and can only be created by the phar extension or the PEAR package
<link xlink:href="&url.pear.package;PHP_Archive">PHP_Archive</link>, but has the
advantage that applications created in this format will run even if the phar
extension is not enabled.
</para>
<para>
In other words, even with the phar extension disabled, one can execute or include
a phar-based archive. Accessing individual files within a phar archive is only
possible with the phar extension unless the phar archive was created by PHP_Archive.
</para>
<para>
The phar extension is also capable of converting a phar archive from tar to zip or
to phar file format in a single command:
</para>
<para>
<example>
<title>Converting a phar archive from phar to tar file format</title>
<programlisting role="php">
<![CDATA[
<?php
$phar = new Phar('myphar.phar');
$pgz = $phar->convertToExecutable(Phar::TAR, Phar::GZ); // makes myphar.phar.tar.gz
?>
]]>
</programlisting>
</example>
</para>
<para>
Phar can compress individual files or an entire archive
using <link linkend="book.zlib">gzip</link> compression or
<link linkend="book.bzip2">bzip2</link> compression, and can verify archive
integrity automatically through the use of <function>md5</function>,
<function>sha1</function>, <function>sha256</function>, or <function>sha512</function>
signatures.
</para>
<para>
Lastly, the Phar extension is security-conscious, and disables write access
to executable phar archives by default, and requires system-level disabling of the
<literal>phar.readonly</literal> php.ini setting in order to create or
modify phar archives. Normal tar and zip archives without an executable stub
can always be created or modified using the <classname>PharData</classname> class.
</para>
<para>
If you are creating applications for distribution, you will want to read
<link linkend="phar.creating">How to create Phar Archives</link>. If you want
more information on the differences between the three file formats that phar supports,
you should read <link linkend="phar.fileformat">Phar, Tar and Zip</link>.
</para>
<para>
If you are using phar applications, there are helpful tips in
<link linkend="phar.using">How to use Phar Archives</link>
</para>
<para>
The word <literal>phar</literal> is a contraction of <literal>PHP</literal> and
<literal>Archive</literal> and is based loosely
on the <literal>jar</literal> (Java Archive) familiar to Java developers.
</para>
<para>
The implementation for Phar archives is based on the PEAR package
<link xlink:href="&url.pear.package;PHP_Archive">PHP_Archive</link>, and
the implementation details are similar, although the Phar extension
is much more powerful. In addition, the Phar extension allows most PHP
applications to be run unmodified while PHP_Archive-based phar archives
often require extensive modification in order to work.
</para>
</preface>
<!-- }}} -->
&reference.phar.setup;
&reference.phar.constants;
&reference.phar.using;
&reference.phar.creating;
&reference.phar.fileformat;
&reference.phar.Phar;
&reference.phar.PharData;
&reference.phar.PharFileInfo;
&reference.phar.PharException;
</book>
<!-- 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
-->
|
