<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Phar archive stream and classes</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="PHP 手册"
HREF="index.html"><LINK
REL="UP"
TITLE="函数参考"
HREF="funcref.html"><LINK
REL="PREVIOUS"
TITLE="PDOStatement->setFetchMode()"
HREF="function.pdostatement-setfetchmode.html"><LINK
REL="NEXT"
TITLE="Phar::apiVersion"
HREF="function.phar-apiversion.html"><META
HTTP-EQUIV="Content-type"
CONTENT="text/html; charset=UTF-8"></HEAD
><BODY
CLASS="reference"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>PHP 手册</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="function.pdostatement-setfetchmode.html"
ACCESSKEY="P"
>上一页</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="function.phar-apiversion.html"
ACCESSKEY="N"
>下一页</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="reference"
><A
NAME="ref.phar"
></A
><DIV
CLASS="TITLEPAGE"
><H1
CLASS="title"
>CXXIII. Phar archive stream and classes</H1
><DIV
CLASS="PARTINTRO"
><A
NAME="AEN178235"
></A
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="phar.intro"
>简介</A
></H1
><P
> The phar extension
provides the <TT
CLASS="literal"
>phar</TT
> stream wrapper and the <B
CLASS="classname"
>Phar</B
>
class for manipulating self-contained PHP Archive (phar) files. The
Phar class can be used to create and to extract contents of phar files as
well as iterating over their contents.
</P
><P
> PHP Archive files (Phars) are special collections of files that can be transparently
run right out of the file, similar to Java's jar archive files. Using a phar archive,
it is possible to distribute a complete PHP application in a single file that will
run out of the file without modification or extraction. Phar
archives can also be used to store files for extraction similar to tar or zip
archive files. Phars support compression using gzip if the
<A
HREF="ref.zlib.html"
>zlib</A
> extension is present, and using bzip2 if
the <A
HREF="ref.bzip2.html"
>bz2</A
> extension is present. In addition,
iteration and other features are available if the <A
HREF="ref.spl.html"
>SPL</A
>
extension is available. Phar signature verification using md5 or sha1 is natively
supported to ensure archive integrity.
</P
><P
> The original implementation for Phar archives was in the PEAR package
<A
HREF="http://pear.php.net/PHP_Archive"
TARGET="_top"
>PHP_Archive</A
>, and
the implementation details are very similar, although the Phar extension
is more full-featured. PHP_Archive has more flexibility in Phar creation,
and helpful debugging tools like the <B
CLASS="classname"
>PHP_Archive_Manager</B
>
class, and the Phar extension supports iteration, array access, and
directly manipulating Phar contents through a simple interface. PHP_Archive
supports creation of Phar archives that can be processed using the Phar
extension or PHP_Archive seamlessly, whereas the Phar extension is designed
to create extensions that function with the Phar extension. In addition,
the Phar extension will continue to work even if the
<A
HREF="missing-stuff.html#ini.allow-url-include"
>allow_url_include</A
> or
<A
HREF="ref.filesystem.html#ini.allow-url-fopen"
>allow_url_fopen</A
> INI variables
are disabled, while PHP_Archive-based Phar archives (without the Phar extension)
will not function.
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="phar.requirements"
>需求</A
></H1
><P
> Phar requires PHP 5.2.0 or newer. Additional features require the
<A
HREF="ref.spl.html"
>SPL</A
> extension in order to take advantage
of iteration and array access to a Phar's file contents. The <TT
CLASS="literal"
>phar</TT
>
stream does not require any additional extensions to function.
</P
><P
> You may optionally wish to enable the <A
HREF="ref.zlib.html"
>zlib</A
>
and <A
HREF="ref.bzip2.html"
>bzip2</A
> extensions to take
advantage of compressed phar support.
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="phar.installation"
>安装</A
></H1
><P
> <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>Windows</I
></SPAN
> binaries may be found at
<A
HREF="http://snaps.php.net/"
TARGET="_top"
>http://snaps.php.net/</A
>.
To install, download php_phar.dll to the folder specified
by your php.ini file's <TT
CLASS="literal"
>extension_dir</TT
> directive.
Enable it by adding <TT
CLASS="literal"
>extension=php_phar.dll</TT
>
to your php.ini and restarting your web server.
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
>extension_dir=c:/php5/exts/
extension=php_phar.dll</PRE
></TD
></TR
></TABLE
><P
> <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>Linux, BSD, and other *nix variants</I
></SPAN
>
can be compiled using the following steps:
</P
><P
></P
><UL
><LI
><P
> Either:
</P
><P
> <P
></P
><UL
><LI
><P
> Run the pear installer for PECL/phar: <TT
CLASS="literal"
>pecl install phar</TT
>
</P
></LI
><LI
><P
> Copy <TT
CLASS="literal"
>phar.so</TT
> from the directory indicated by the
build process to the location specified in your php.ini file under
<TT
CLASS="literal"
>extension_dir</TT
>.
</P
></LI
><LI
><P
> Add <TT
CLASS="literal"
>extension=phar.so</TT
> to your php.ini
</P
></LI
></UL
>
</P
><P
> Or:
</P
><P
> <P
></P
><UL
><LI
><P
> Set the path to your php.ini via:
</P
><P
> <TT
CLASS="literal"
>pecl config-set php_ini /path/to/php.ini</TT
>
</P
></LI
><LI
><P
> Run the pear installer for PECL/phar: <TT
CLASS="literal"
>pecl install phar</TT
>
</P
></LI
></UL
>
</P
></LI
><LI
><P
> Restart your web server to reload your php.ini settings.
</P
></LI
></UL
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Development Versions: </B
>
There are currently no <TT
CLASS="literal"
>stable</TT
> versions of PECL/phar,
to force installation of the <TT
CLASS="literal"
>alpha</TT
> version of PECL/phar
execute: <TT
CLASS="literal"
>pecl install phar-</TT
><SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>alpha</I
></SPAN
>
</P
></BLOCKQUOTE
></DIV
><DIV
CLASS="tip"
><BLOCKQUOTE
CLASS="tip"
><P
><B
>Compiling PECL/phar without using the PEAR command: </B
>
Rather than using <TT
CLASS="literal"
>pecl install phar</TT
> to automatically
download and install PECL/phar, you may download the tarball from
<A
HREF="http://pecl.php.net/package/phar"
TARGET="_top"
>PECL</A
>.
From the root of the unpacked tarball, run:
<TT
CLASS="literal"
>phpize && ./configure --enable-phar && make</TT
>
to generate <TT
CLASS="literal"
>phar.so</TT
>.
Once built, continue the installation from step 4 above.
</P
></BLOCKQUOTE
></DIV
><P
> 安装此 PECL 扩展库的信息可在手册中标题为 <A
HREF="install.pecl.html"
>PECL 扩展库安装</A
>的一章中找到。 更多信息如新版本，下载，源文件，维护者信息以及更新日志等可以在这里找到：
<A
HREF="http://pecl.php.net/package/phar"
TARGET="_top"
>http://pecl.php.net/package/phar</A
>.
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="phar.configuration"
>运行时配置</A
></H1
><P
>这些函数的行为受 <TT
CLASS="filename"
>php.ini</TT
> 的影响。</P
><P
> <DIV
CLASS="table"
><A
NAME="AEN178317"
></A
><P
><B
>表 1. Filesystem and Streams Configuration Options</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><COL><COL><THEAD
><TR
><TH
>Name</TH
><TH
>Default</TH
><TH
>Changeable</TH
><TH
>Changelog</TH
></TR
></THEAD
><TBODY
><TR
><TD
>phar.readonly</TD
><TD
>"1"</TD
><TD
>PHP_INI_SYSTEM disable/enable, PHP_INI_ALL enable</TD
><TD
>Available Since version 1.0.0</TD
></TR
><TR
><TD
>phar.require_hash</TD
><TD
>"0"</TD
><TD
>PHP_INI_SYSTEM disable/enable, PHP_INI_ALL enable</TD
><TD
>Available Since version 1.0.0</TD
></TR
></TBODY
></TABLE
></DIV
>
</P
><P
>以下是配置选项的简要解释。</P
><P
> <P
></P
><DIV
CLASS="variablelist"
><DL
><DT
><A
NAME="ini.phar.readonly"
></A
><CODE
CLASS="parameter"
>phar.readonly</CODE
>
<A
HREF="language.types.boolean.html"
><B
CLASS="type"
>boolean</B
></A
></DT
><DD
><P
> This option disables creation or modification of Phar archives
using the <TT
CLASS="literal"
>phar</TT
> stream or <B
CLASS="classname"
>Phar</B
>
object's write support. This setting should always be enabled on
production machines, as the phar extension's convenient write support
could allow straightforward creation of a php-based virus when coupled
with other common security vulnerabilities.
</P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>注意: </B
>
This setting can only be unset in php.ini due to security reasons.
If <TT
CLASS="literal"
>phar.readonly</TT
> is disabled in php.ini, the
user may enable <TT
CLASS="literal"
>phar.readonly</TT
> in a script
or disable it later. If <TT
CLASS="literal"
>phar.readonly</TT
> is
enabled in php.ini, a script may harmlessly "re-enable"
the INI variable, but may not disable it.
</P
></BLOCKQUOTE
></DIV
></DD
><DT
><A
NAME="ini.phar.require-hash"
></A
><CODE
CLASS="parameter"
>phar.require_hash</CODE
>
<A
HREF="language.types.boolean.html"
><B
CLASS="type"
>boolean</B
></A
></DT
><DD
><P
> This option will force all opened Phar archives to contain some
kind of signature (currently MD5 and SHA1 are supported), and will
refuse to process any Phar archive that does not contain a signature.
</P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>注意: </B
>
This setting can only be unset in php.ini due to security reasons.
If <TT
CLASS="literal"
>phar.require_hash</TT
> is disabled in php.ini, the
user may enable <TT
CLASS="literal"
>phar.require_hash</TT
> in a script
or disable it later. If <TT
CLASS="literal"
>phar.require_hash</TT
> is
enabled in php.ini, a script may harmlessly "re-enable"
the INI variable, but may not disable it.
</P
></BLOCKQUOTE
></DIV
></DD
></DL
></DIV
>
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="phar.resources"
>资源类型</A
></H1
><P
> The Phar extension provides the <TT
CLASS="literal"
>phar</TT
> stream, which
allows accessing files contained within a phar transparently. The
file format of a Phar is described <A
HREF="ref.phar.html#phar.fileformat"
>here</A
>
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="AEN178369"
>预定义类</A
></H1
><P
></P
><TABLE
BORDER="0"
><TBODY
><TR
><TD
> <B
CLASS="classname"
>Phar</B
>
</TD
></TR
><TR
><TD
> <B
CLASS="classname"
>PharFileInfo</B
>
</TD
></TR
><TR
><TD
> <B
CLASS="classname"
>PharException</B
>
</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="phar.using.basics"
>Using Phar Archives: Introduction</A
></H1
><P
> Phar archives are similar in concept to Java JAR archives, but are
tailored to the needs and to the flexibility of PHP applications. A
Phar archive is used to distribute a complete PHP application
or library in a single file. Unlike Java's implementation of JAR archives,
no external tool is required to process or run a PHP Phar archive. A
Phar archive application is processed exactly like any other PHP application:
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
>php coolapplication.phar</PRE
></TD
></TR
></TABLE
><P
> Using a Phar archive library is identical to using any other PHP library:
</P
><P
> <DIV
CLASS="informalexample"
><P
></P
><A
NAME="AEN178384"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br /></font><font color="#007700">include </font><font color="#DD0000">'coollibrary.phar'</font><font color="#007700">;<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
><P
></P
></DIV
>
</P
><P
> What makes Phar archives incredibly useful is the <TT
CLASS="literal"
>phar</TT
>
stream wrapper, which is explained in depth <A
HREF="ref.phar.html#phar.using.stream"
>here</A
>.
Using this stream wrapper, it is possible to access
individual files within a phar as if the phar were its own filesystem.
The <TT
CLASS="literal"
>phar</TT
> stream wrapper supports all read/write operations
on files, and <A
HREF="function.opendir.html"
><B
CLASS="function"
>opendir()</B
></A
> on directories.
</P
><P
> <DIV
CLASS="informalexample"
><P
></P
><A
NAME="AEN178392"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br /></font><font color="#007700">include </font><font color="#DD0000">'phar://coollibrary.phar/internal/file.php'</font><font color="#007700">;<br /></font><font color="#0000BB">header</font><font color="#007700">(</font><font color="#DD0000">'Content-type: image/jpeg'</font><font color="#007700">);<br /></font><font color="#FF8000">// phars can be accessed by full path or by alias<br /></font><font color="#007700">echo </font><font color="#0000BB">file_get_contents</font><font color="#007700">(</font><font color="#DD0000">'phar:///fullpath/to/coollibrary.phar/images/wow.jpg'</font><font color="#007700">);<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
><P
></P
></DIV
>
</P
><P
> Also provided with the Phar extension is the <B
CLASS="classname"
>Phar</B
> class,
which allows accessing the files of the Phar archive as if it were an
associative array, and other functionality. The Phar class is explained
<A
HREF="ref.phar.html#phar.using.object"
>here</A
>.
</P
><P
> <DIV
CLASS="informalexample"
><P
></P
><A
NAME="AEN178398"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br />try </font><font color="#007700">{<br /> </font><font color="#FF8000">// open an existing phar<br /> </font><font color="#0000BB">$p </font><font color="#007700">= new </font><font color="#0000BB">Phar</font><font color="#007700">(</font><font color="#DD0000">'coollibrary.phar'</font><font color="#007700">);<br /> foreach (</font><font color="#0000BB">$p </font><font color="#007700">as </font><font color="#0000BB">$file</font><font color="#007700">) {<br /> </font><font color="#FF8000">// $file is a PharFileInfo class, and inherits from SplFileInfo<br /> </font><font color="#007700">echo </font><font color="#0000BB">$file</font><font color="#007700">-></font><font color="#0000BB">getFileName</font><font color="#007700">() . </font><font color="#DD0000">"\n"</font><font color="#007700">;<br /> echo </font><font color="#0000BB">$file </font><font color="#007700">. </font><font color="#DD0000">"\n"</font><font color="#007700">; </font><font color="#FF8000">// display contents;<br /> </font><font color="#007700">}<br /> if (isset(</font><font color="#0000BB">$p</font><font color="#007700">[</font><font color="#DD0000">'internal/file.php'</font><font color="#007700">])) {<br /> </font><font color="#0000BB">var_dump</font><font color="#007700">(</font><font color="#0000BB">$p</font><font color="#007700">[</font><font color="#DD0000">'internal/file.php'</font><font color="#007700">]-></font><font color="#0000BB">getMetaData</font><font color="#007700">());<br /> }<br /><br /> </font><font color="#FF8000">// create a new phar - phar.readonly must be 0 in php.ini<br /> // phar.readonly is enabled by default for security reasons.<br /> // On production servers, Phars need never be created,<br /> // only executed.<br /> </font><font color="#007700">if (</font><font color="#0000BB">Phar</font><font color="#007700">::</font><font color="#0000BB">canWrite</font><font color="#007700">()) {<br /> </font><font color="#0000BB">$p </font><font color="#007700">= new </font><font color="#0000BB">Phar</font><font color="#007700">(</font><font color="#0000BB">dirname</font><font color="#007700">(</font><font color="#0000BB">__FILE__</font><font color="#007700">) . </font><font color="#DD0000">'/newphar.phar'</font><font color="#007700">, </font><font color="#0000BB">0</font><font color="#007700">, </font><font color="#DD0000">'newphar.phar'</font><font color="#007700">);<br /> </font><font color="#FF8000">// create transaction - nothing is written to newphar.phar<br /> // until commit() is called, although temporary storage is needed<br /> </font><font color="#0000BB">$p</font><font color="#007700">-></font><font color="#0000BB">begin</font><font color="#007700">();<br /> </font><font color="#FF8000">// add a new file, set its contents<br /> </font><font color="#0000BB">$p</font><font color="#007700">[</font><font color="#DD0000">'file1.txt'</font><font color="#007700">] = </font><font color="#DD0000">'Information'</font><font color="#007700">;<br /> </font><font color="#0000BB">$fp </font><font color="#007700">= </font><font color="#0000BB">fopen</font><font color="#007700">(</font><font color="#DD0000">'hugefile.dat'</font><font color="#007700">, </font><font color="#DD0000">'rb'</font><font color="#007700">);<br /> </font><font color="#FF8000">// copy from the stream<br /> </font><font color="#0000BB">$p</font><font color="#007700">[</font><font color="#DD0000">'data/hugefile.dat'</font><font color="#007700">] = </font><font color="#0000BB">$fp</font><font color="#007700">;<br /> if (</font><font color="#0000BB">Phar</font><font color="#007700">::</font><font color="#0000BB">canCompress</font><font color="#007700">()) {<br /> </font><font color="#0000BB">$p</font><font color="#007700">[</font><font color="#DD0000">'data/hugefile.dat'</font><font color="#007700">]-></font><font color="#0000BB">setCompressedGZ</font><font color="#007700">();<br /> }<br /> </font><font color="#0000BB">$p</font><font color="#007700">[</font><font color="#DD0000">'images/wow.jpg'</font><font color="#007700">] = </font><font color="#0000BB">file_get_contents</font><font color="#007700">(</font><font color="#DD0000">'images/wow.jpg'</font><font color="#007700">);<br /> </font><font color="#FF8000">// any value can be saved as file-specific meta-data<br /> </font><font color="#0000BB">$p</font><font color="#007700">[</font><font color="#DD0000">'images/wow.jpg'</font><font color="#007700">]-></font><font color="#0000BB">setMetaData</font><font color="#007700">(array(</font><font color="#DD0000">'mime-type' </font><font color="#007700">=> </font><font color="#DD0000">'image/jpeg'</font><font color="#007700">));<br /> </font><font color="#0000BB">$p</font><font color="#007700">[</font><font color="#DD0000">'index.php'</font><font color="#007700">] = </font><font color="#0000BB">file_get_contents</font><font color="#007700">(</font><font color="#DD0000">'index.php'</font><font color="#007700">);<br /> </font><font color="#0000BB">$p</font><font color="#007700">-></font><font color="#0000BB">setMetaData</font><font color="#007700">(array(</font><font color="#DD0000">'bootstrap' </font><font color="#007700">=> </font><font color="#DD0000">'index.php'</font><font color="#007700">));<br /> </font><font color="#FF8000">// set the loader stub<br /> </font><font color="#0000BB">$p</font><font color="#007700">-></font><font color="#0000BB">setStub</font><font color="#007700">(</font><font color="#DD0000">'<?php<br />$p = new Phar(__FILE__);<br />$m = $p->getMetaData();<br />require "phar://" . __FILE__ . "/" . $m["bootstrap"];<br />__HALT_COMPILER();'</font><font color="#007700">);<br /> </font><font color="#FF8000">// save the phar archive to disk<br /> </font><font color="#0000BB">$p</font><font color="#007700">-></font><font color="#0000BB">commit</font><font color="#007700">();<br /> }<br />} </font><font color="#0000BB">catch </font><font color="#007700">(</font><font color="#0000BB">Exception $e</font><font color="#007700">) {<br /> echo </font><font color="#DD0000">'Could not open Phar: '</font><font color="#007700">, </font><font color="#0000BB">$e</font><font color="#007700">;<br />}<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
><P
></P
></DIV
>
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="phar.using.stream"
>Using Phar Archives: the phar stream wrapper</A
></H1
><P
> The Phar stream wrapper fully supports <A
HREF="function.fopen.html"
><B
CLASS="function"
>fopen()</B
></A
> for
read, write or append, <A
HREF="function.unlink.html"
><B
CLASS="function"
>unlink()</B
></A
>, <A
HREF="function.stat.html"
><B
CLASS="function"
>stat()</B
></A
>,
<A
HREF="function.fstat.html"
><B
CLASS="function"
>fstat()</B
></A
>, <A
HREF="function.fseek.html"
><B
CLASS="function"
>fseek()</B
></A
>, <A
HREF="function.rename.html"
><B
CLASS="function"
>rename()</B
></A
>
and directory stream operation <A
HREF="function.opendir.html"
><B
CLASS="function"
>opendir()</B
></A
>. The Phar stream wrapper
does not support creating or erasing a directory, as files are stored only
as files, and the concept of an abstract directory does not exist.
</P
><P
> Individual file compression and per-file metadata can also be manipulated
in a Phar archive using stream contexts:
</P
><P
> <DIV
CLASS="informalexample"
><P
></P
><A
NAME="AEN178412"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br />$context </font><font color="#007700">= </font><font color="#0000BB">stream_context_create</font><font color="#007700">(array(</font><font color="#DD0000">'phar' </font><font color="#007700">=><br /> array(</font><font color="#DD0000">'compression' </font><font color="#007700">=> </font><font color="#0000BB">Phar</font><font color="#007700">::</font><font color="#0000BB">GZ</font><font color="#007700">)),<br /> array(</font><font color="#DD0000">'metadata' </font><font color="#007700">=> array(</font><font color="#DD0000">'user' </font><font color="#007700">=> </font><font color="#DD0000">'cellog'</font><font color="#007700">)));<br /></font><font color="#0000BB">file_put_contents</font><font color="#007700">(</font><font color="#DD0000">'phar://my.phar/somefile.php'</font><font color="#007700">, </font><font color="#0000BB">0</font><font color="#007700">, </font><font color="#0000BB">$context</font><font color="#007700">);<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
><P
></P
></DIV
>
</P
><P
> The <TT
CLASS="literal"
>phar</TT
> stream wrapper does not operate on remote files,
and cannot operate on remote files, and so is allowed even when the
<A
HREF="ref.filesystem.html#ini.allow-url-fopen"
>allow_url_fopen</A
> and
<A
HREF="missing-stuff.html#ini.allow-url-include"
>allow_url_include</A
> INI options
are disabled.
</P
><P
> Although it is possible to create phar archives from scratch just using
stream operations, it is best to use the functionality built into
the Phar class. The stream wrapper is best used for read operations.
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="phar.using.object"
>Using Phar Archives: the Phar class</A
></H1
><P
> The <B
CLASS="classname"
>Phar</B
> class supports reading and manipulation
of Phar archives, as well as iteration through inherited functionality of
the
<A
HREF="http://www.php.net/~helly/php/ext/spl/classRecursiveDirectoryIterator.html"
TARGET="_top"
><B
CLASS="classname"
>RecursiveDirectoryIterator</B
></A
>
class. With support for the <SPAN
CLASS="interface"
>ArrayAccess</SPAN
>
interface, files inside a Phar archive can be accessed as if they were
part of an associative array.
</P
><P
> It is important to note that when creating a Phar archive, the full path
should be passed to the <B
CLASS="classname"
>Phar</B
> object constructor.
Relative paths will fail to initialize.
</P
><P
> Assuming that <TT
CLASS="literal"
>$p</TT
> is a Phar object initialized as follows:
</P
><P
> <DIV
CLASS="informalexample"
><P
></P
><A
NAME="AEN178431"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br />$p </font><font color="#007700">= new </font><font color="#0000BB">Phar</font><font color="#007700">(</font><font color="#DD0000">'/path/to/myphar.phar'</font><font color="#007700">, </font><font color="#0000BB">0</font><font color="#007700">, </font><font color="#DD0000">'myphar.phar'</font><font color="#007700">);<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
><P
></P
></DIV
>
</P
><P
> An empty Phar archive will be created at <TT
CLASS="literal"
>/path/to/myphar.phar</TT
>,
or if <TT
CLASS="literal"
>/path/to/myphar.phar</TT
> already exists, it will be opened
again. The literal <TT
CLASS="literal"
>myphar.phar</TT
> deomnstrates the concept of an alias
that can be used to reference <TT
CLASS="literal"
>/path/to/myphar.phar</TT
> in URLs as in:
</P
><P
> <DIV
CLASS="informalexample"
><P
></P
><A
NAME="AEN178439"
></A
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br /></font><font color="#FF8000">// these two calls to file_get_contents() are equivalent if<br />// /path/to/myphar.phar has an explicit alias of "myphar.phar"<br />// in its manifest, or if the phar was initialized with the<br />// previous example's Phar object setup<br /></font><font color="#0000BB">$f </font><font color="#007700">= </font><font color="#0000BB">file_get_contents</font><font color="#007700">(</font><font color="#DD0000">'phar:///path/to/myphar.phar/whatever.txt'</font><font color="#007700">);<br /></font><font color="#0000BB">$f </font><font color="#007700">= </font><font color="#0000BB">file_get_contents</font><font color="#007700">(</font><font color="#DD0000">'phar://myphar.phar/whatever.txt'</font><font color="#007700">);<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
><P
></P
></DIV
>
</P
><P
> With the newly created <TT
CLASS="literal"
>$p</TT
> <B
CLASS="classname"
>Phar</B
> object,
the following is possible:
<P
></P
><UL
><LI
><P
> <TT
CLASS="literal"
>$a = $p['file.php']</TT
> creates a <B
CLASS="classname"
>PharFileInfo</B
>
class that refers to the contents of <TT
CLASS="literal"
>phar://myphar.phar/file.php</TT
>
</P
></LI
><LI
><P
> <TT
CLASS="literal"
>$p['file.php'] = $v</TT
> creates a new file
(<TT
CLASS="literal"
>phar://myphar.phar/file.php</TT
>), or overwrites
an existing file within <TT
CLASS="literal"
>myphar.phar</TT
>. <TT
CLASS="literal"
>$v</TT
>
can be either a string or an open file pointer, in which case the entire
contents of the file will be used to create the new file.
</P
></LI
><LI
><P
> <TT
CLASS="literal"
>isset($p['file.php'])</TT
> can be used to determine
whether <TT
CLASS="literal"
>phar://myphar.phar/file.php</TT
> exists within
<TT
CLASS="literal"
>myphar.phar</TT
>.
</P
></LI
><LI
><P
> <TT
CLASS="literal"
>unset($p['file.php'])</TT
> erases
<TT
CLASS="literal"
>phar://myphar.phar/file.php</TT
> from
<TT
CLASS="literal"
>myphar.phar</TT
>.
</P
></LI
></UL
>
</P
><P
> In addition, the <B
CLASS="classname"
>Phar</B
> object is the only way to access
Phar-specific metadata, through
<A
HREF="function.phar-getmetadata.html"
><B
CLASS="function"
>Phar->getMetaData()</B
></A
>,
and the only way to set or retrieve a Phar archive's PHP loader stub through
<A
HREF="function.phar-getstub.html"
><B
CLASS="function"
>Phar->getStub()</B
></A
> and
<A
HREF="function.phar-setstub.html"
><B
CLASS="function"
>Phar->setStub()</B
></A
>.
Additionally, compression for the entire Phar archive at once can only be manipulated
using the <B
CLASS="classname"
>Phar</B
> class.
</P
><P
> The full list of <B
CLASS="classname"
>Phar</B
> object functionality is documented
below.
</P
><P
> The <B
CLASS="classname"
>PharFileInfo</B
> class extends the
<A
HREF="http://www.php.net/~helly/php/ext/spl/classSplFileInfo.html"
TARGET="_top"
><B
CLASS="classname"
>SplFileInfo</B
></A
>
class, and adds several methods for manipulating Phar-specific details of a file
contained within a Phar, such as manipulating compression and metadata.
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="phar.fileformat"
>Phar file format</A
></H1
><P
> All Phar files contain three to four sections:
<P
></P
><OL
TYPE="1"
><LI
><P
>a stub</P
></LI
><LI
><P
>a manifest describing the contents</P
></LI
><LI
><P
>the file contents</P
></LI
><LI
><P
>[optional] a signature for verifying Phar integrity</P
></LI
></OL
>
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="AEN178493"
>Phar file stub</A
></H1
><P
> A Phar's stub is a simple PHP file. The smallest possible stub follows:
</P
><P
> <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php __HALT_COMPILER</font><font color="#007700">();</font>
</font>
</code></TD
></TR
></TABLE
>
</P
><P
> A stub must contain as a minimum, the <TT
CLASS="literal"
>__HALT_COMPILER();</TT
> token
at its conclusion. Typically, a stub will contain loader functionality
like so:
</P
><P
> <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br />Phar</font><font color="#007700">::</font><font color="#0000BB">mapPhar</font><font color="#007700">();<br />include </font><font color="#DD0000">'phar://myphar.phar/index.php'</font><font color="#007700">;<br /></font><font color="#0000BB">__HALT_COMPILER</font><font color="#007700">();</font>
</font>
</code></TD
></TR
></TABLE
>
</P
><P
> There are no restrictions on the contents of a Phar stub, except for the requirement
that it conclude with <TT
CLASS="literal"
>__HALT_COMPILER();</TT
>. The closing PHP tag
<TT
CLASS="literal"
>?></TT
> may be included or omitted, but there can be
no more than 1 space between the <TT
CLASS="literal"
>;</TT
> and the close tag
<TT
CLASS="literal"
>?></TT
> or the phar extension will be unable
to process the Phar archive's manifest.
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="AEN178507"
>Phar Manifest Format</A
></H1
><P
> The Phar manifest is a highly optimized format that allows per-file
specification of file compression, file permissions, and even user-defined
meta-data such as file user or group. All values greater than 1 byte are stored
in little-endian byte order, with the exception of the API version, which
for historical reasons is stored as 3 nibbles in big-endian order.
</P
><P
> All unused flags are reserved for future use, and must not be used
to store custom information. Use the per-file meta-data facility
to store customized information about particular files.
</P
><P
> The basic file format of a Phar archive manifest is as follows:
</P
><P
> <DIV
CLASS="table"
><A
NAME="AEN178513"
></A
><P
><B
>表 2. Global Phar manifest format</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>Size in bytes</TH
><TH
>Description</TH
></TR
></THEAD
><TBODY
><TR
><TD
>4 bytes</TD
><TD
>Length of manifest in bytes (1 MB limit)</TD
></TR
><TR
><TD
>4 bytes</TD
><TD
>Number of files in the Phar</TD
></TR
><TR
><TD
>2 bytes</TD
><TD
>API version of the Phar manifest (currently 1.0.0)</TD
></TR
><TR
><TD
>4 bytes</TD
><TD
>Global Phar bitmapped flags</TD
></TR
><TR
><TD
>4 bytes</TD
><TD
>Length of Phar alias</TD
></TR
><TR
><TD
>??</TD
><TD
>Phar alias (length based on previous)</TD
></TR
><TR
><TD
>4 bytes</TD
><TD
>Length of Phar metadata (<TT
CLASS="literal"
>0</TT
> for none)</TD
></TR
><TR
><TD
>??</TD
><TD
>Serialized Phar Meta-data, stored in <A
HREF="function.serialize.html"
><B
CLASS="function"
>serialize()</B
></A
> format</TD
></TR
><TR
><TD
>at least 24 * number of entries bytes</TD
><TD
>entries for each file</TD
></TR
></TBODY
></TABLE
></DIV
>
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="AEN178550"
>Global Phar bitmapped flags</A
></H1
><P
> Here are the bitmapped flags currently recognized by the Phar extension
for the global Phar flat bitmap:
</P
><P
> <DIV
CLASS="table"
><A
NAME="AEN178554"
></A
><P
><B
>表 3. Bitmap values recognized</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>Value</TH
><TH
>Description</TH
></TR
></THEAD
><TBODY
><TR
><TD
><TT
CLASS="literal"
>0x00010000</TT
></TD
><TD
>If set, this Phar contains a verification signature</TD
></TR
><TR
><TD
><TT
CLASS="literal"
>0x00001000</TT
></TD
><TD
> If set, this Phar contains at least 1 file that
is compressed with zlib compression
</TD
></TR
><TR
><TD
><TT
CLASS="literal"
>0x00002000</TT
></TD
><TD
> If set, this Phar contains at least 1 file that
is compressed with bzip compression
</TD
></TR
></TBODY
></TABLE
></DIV
>
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="AEN178574"
>Phar manifest file entry definition</A
></H1
><P
> Each file in the manifest contains the following information:
</P
><P
> <DIV
CLASS="table"
><A
NAME="AEN178578"
></A
><P
><B
>表 4. Phar Manifest file entry</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>Size in bytes</TH
><TH
>Description</TH
></TR
></THEAD
><TBODY
><TR
><TD
>4 bytes</TD
><TD
>Filename length in bytes</TD
></TR
><TR
><TD
>??</TD
><TD
>Filename (length specified in previous)</TD
></TR
><TR
><TD
>4 bytes</TD
><TD
>Un-compressed file size in bytes</TD
></TR
><TR
><TD
>4 bytes</TD
><TD
>Unix timestamp of file</TD
></TR
><TR
><TD
>4 bytes</TD
><TD
>Compressed file size in bytes</TD
></TR
><TR
><TD
>4 bytes</TD
><TD
>CRC32 checksum of un-compressed file contents</TD
></TR
><TR
><TD
>4 bytes</TD
><TD
>Bit-mapped File-specific flags</TD
></TR
><TR
><TD
>4 bytes</TD
><TD
>Serialized File Meta-data length (<TT
CLASS="literal"
>0</TT
> for none)</TD
></TR
><TR
><TD
>??</TD
><TD
>Serialized File Meta-data, stored in <A
HREF="function.serialize.html"
><B
CLASS="function"
>serialize()</B
></A
> format</TD
></TR
></TBODY
></TABLE
></DIV
>
</P
><P
> The File-specific bitmap values recognized are:
</P
><P
> <DIV
CLASS="table"
><A
NAME="AEN178617"
></A
><P
><B
>表 5. Bitmap values recognized</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>Value</TH
><TH
>Description</TH
></TR
></THEAD
><TBODY
><TR
><TD
><TT
CLASS="literal"
>0x000001FF</TT
></TD
><TD
> These bits are reserved for defining specific file permissions
of a file. Permissions are used for <A
HREF="function.fstat.html"
><B
CLASS="function"
>fstat()</B
></A
>
and can be used to recreate desired permissions upon extraction.
</TD
></TR
><TR
><TD
><TT
CLASS="literal"
>0x00001000</TT
></TD
><TD
> If set, this file is compressed with zlib compression
</TD
></TR
><TR
><TD
><TT
CLASS="literal"
>0x00002000</TT
></TD
><TD
> If set, this file is compressed with bzip compression
</TD
></TR
></TBODY
></TABLE
></DIV
>
</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="AEN178638"
>Phar Signature format</A
></H1
><P
> Phars containing a signature always have the signature appended to the
end of the Phar archive after the loader, manifest, and file contents.
The two signature formats supported at this time are MD5 and SHA1.
</P
><P
> <DIV
CLASS="table"
><A
NAME="AEN178642"
></A
><P
><B
>表 6. Signature format</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>Length in bytes</TH
><TH
>Description</TH
></TR
></THEAD
><TBODY
><TR
><TD
>16 or 20 bytes</TD
><TD
> The actual signature, 20 bytes for an SHA1 signature,
16 bytes for an MD5 signature.
</TD
></TR
><TR
><TD
>4 bytes</TD
><TD
> Signature flags. <TT
CLASS="literal"
>0x0001</TT
> is used to
define an MD5 signature, and <TT
CLASS="literal"
>0x0002</TT
> is used
to define an SHA1 signature.
</TD
></TR
><TR
><TD
>4 bytes</TD
><TD
> Magic <TT
CLASS="literal"
>GBMB</TT
> used to define the presence of a signature.
</TD
></TR
></TBODY
></TABLE
></DIV
>
</P
></DIV
></DIV
><DIV
CLASS="TOC"
><DL
><DT
><B
>目录</B
></DT
><DT
><A
HREF="function.phar-apiversion.html"
>Phar::apiVersion</A
> -- Returns the api version</DT
><DT
><A
HREF="function.phar-cancompress.html"
>Phar::canCompress</A
> -- Returns whether phar extension supports compression using either zlib or bzip2</DT
><DT
><A
HREF="function.phar-canwrite.html"
>Phar::canWrite</A
> -- Returns whether phar extension supports writing and creating phars</DT
><DT
><A
HREF="function.phar-compressallfilesbzip2.html"
>Phar->compressAllFilesBZIP2</A
> -- Compresses all files in the current Phar archive using Bzip2 compression</DT
><DT
><A
HREF="function.phar-compressallfilesgz.html"
>Phar->compressAllFilesGZ</A
> -- Compresses all files in the current Phar archive using Gzip compression</DT
><DT
><A
HREF="function.phar-construct.html"
>Phar::__construct</A
> -- Construct a Phar archive object</DT
><DT
><A
HREF="function.phar-count.html"
>Phar->count</A
> -- Returns the number of entries (files) in the Phar archive</DT
><DT
><A
HREF="function.phar-getmetadata.html"
>Phar->getMetaData</A
> -- Returns phar archive meta-data</DT
><DT
><A
HREF="function.phar-getmodified.html"
>Phar->getModified</A
> -- Return whether phar was modified</DT
><DT
><A
HREF="function.phar-getsignature.html"
>Phar->getSignature</A
> -- Return MD5/SHA1 signature of a Phar archive</DT
><DT
><A
HREF="function.phar-getstub.html"
>Phar->getStub</A
> -- Return the PHP loader or bootstrap stub of a Phar archive</DT
><DT
><A
HREF="function.phar-getversion.html"
>Phar->getVersion</A
> -- Return version info of Phar archive</DT
><DT
><A
HREF="function.phar-isbuffering.html"
>Phar->isBuffering</A
> -- Used to determine whether Phar write operations are being buffered, or are flushing directly to disk</DT
><DT
><A
HREF="function.phar-loadphar.html"
>Phar::loadPhar</A
> -- Loads any phar archive with an alias</DT
><DT
><A
HREF="function.phar-mapphar.html"
>Phar::mapPhar</A
> -- Reads the currently executed file (a phar) and registers its manifest</DT
><DT
><A
HREF="function.phar-offsetexists.html"
>Phar::offsetExists</A
> -- determines whether a file exists in the phar</DT
><DT
><A
HREF="function.phar-offsetget.html"
>Phar::offsetGet</A
> -- get a PharFileInfo object for a specific file</DT
><DT
><A
HREF="function.phar-offsetset.html"
>Phar::offsetSet</A
> -- set the contents of an internal file to those of an external file</DT
><DT
><A
HREF="function.phar-offsetunset.html"
>Phar::offsetUnset</A
> -- remove a file from a phar</DT
><DT
><A
HREF="function.phar-setmetadata.html"
>Phar->setMetaData</A
> -- Sets phar archive meta-data</DT
><DT
><A
HREF="function.phar-setstub.html"
>Phar->setStub</A
> -- Used to set the PHP loader or bootstrap stub of a Phar archive</DT
><DT
><A
HREF="function.phar-startbuffering.html"
>Phar->startBuffering</A
> -- Start buffering Phar write operations, do not modify the Phar object on disk</DT
><DT
><A
HREF="function.phar-stopbuffering.html"
>Phar->stopBuffering</A
> -- Stop buffering write requests to the Phar archive, and save changes to disk</DT
><DT
><A
HREF="function.phar-uncompressallfiles.html"
>Phar->uncompressAllFiles</A
> -- Uncompresses all files in the current Phar archive</DT
><DT
><A
HREF="function.pharfileinfo-chmod.html"
>PharFileInfo->chmod</A
> -- Sets file-specific meta-data saved with a file</DT
><DT
><A
HREF="function.pharfileinfo-construct.html"
>PharFileInfo::__construct</A
> -- Construct a Phar entry object</DT
><DT
><A
HREF="function.pharfileinfo-getcompressedsize.html"
>PharFileInfo->getCompressedSize</A
> -- Returns the actual size of the file (with compression) inside the Phar archive</DT
><DT
><A
HREF="function.pharfileinfo-getcrc32.html"
>PharFileInfo->getCRC32</A
> -- Returns CRC32 code or throws an exception if not CRC checked</DT
><DT
><A
HREF="function.pharfileinfo-getmetadata.html"
>PharFileInfo->getMetaData</A
> -- Returns file-specific meta-data saved with a file</DT
><DT
><A
HREF="function.pharfileinfo-getpharflags.html"
>PharFileInfo->getPharFlags</A
> -- Returns the Phar file entry flags</DT
><DT
><A
HREF="function.pharfileinfo-iscompressed.html"
>PharFileInfo->isCompressed</A
> -- Returns whether the entry is compressed</DT
><DT
><A
HREF="function.pharfileinfo-iscompressedbzip2.html"
>PharFileInfo->isCompressedBZIP2</A
> -- Returns whether the entry is compressed using bzip2</DT
><DT
><A
HREF="function.pharfileinfo-iscompressedgz.html"
>PharFileInfo->isCompressedGZ</A
> -- Returns whether the entry is compressed using gz</DT
><DT
><A
HREF="function.pharfileinfo-iscrcchecked.html"
>PharFileInfo->isCRCChecked</A
> -- Returns whether file entry has had its CRC verified</DT
><DT
><A
HREF="function.pharfileinfo-setcompressedbzip2.html"
>PharFileInfo->setCompressedBZIP2</A
> -- Compresses the current Phar entry within the phar using Bzip2 compression</DT
><DT
><A
HREF="function.pharfileinfo-setcompressedgz.html"
>PharFileInfo->setCompressedGZ</A
> -- Compresses the current Phar entry within the phar using gz compression</DT
><DT
><A
HREF="function.pharfileinfo-setmetadata.html"
>PharFileInfo->setMetaData</A
> -- Sets file-specific meta-data saved with a file</DT
><DT
><A
HREF="function.pharfileinfo-setuncompressed.html"
>PharFileInfo->setUncompressed</A
> -- Uncompresses the current Phar entry within the phar, if it is compressed</DT
></DL
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="function.pdostatement-setfetchmode.html"
ACCESSKEY="P"
>上一页</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>起始页</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="function.phar-apiversion.html"
ACCESSKEY="N"
>下一页</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>PDOStatement->setFetchMode()</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="funcref.html"
ACCESSKEY="U"
>上一级</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Phar::apiVersion</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
