update phar docs to current API for 2.0 (still some work to do on modifying the compress\* methods of Phar)

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@256055 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Greg Beaver 2008-03-25 14:04:25 +00:00
parent ab9294e481
commit 85c97f2f3a
23 changed files with 1605 additions and 49 deletions

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="phar.compress">
<refnamediv>
<refname>Phar::compress</refname>
@ -39,6 +39,25 @@
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>compression</parameter></term>
<listitem>
<para>
Compression must be one of <literal>Phar::GZ</literal>,
<literal>Phar::BZ2</literal> to add compression, or <literal>Phar::NONE</literal>
to remove compression.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
@ -82,6 +101,7 @@ $p3 = $p2->compress(Phar::NONE); // exception: /path/to/my.phar already exists
<member><function>PharFileInfo::setCompressedBZIP2</function></member>
<member><function>PharFileInfo::setUncompressed</function></member>
<member><function>PharFileInfo::setCompressedGZ</function></member>
<member><function>PharData::compress</function></member>
<member><function>Phar::canCompress</function></member>
<member><function>Phar::isCompressed</function></member>
<member><function>Phar::compressAllFilesBZIP2</function></member>

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="phar.construct">
<refnamediv>
<refname>Phar::__construct</refname>
@ -23,7 +23,7 @@
<term><parameter>fname</parameter></term>
<listitem>
<para>
Path to an existing Phar archive
Path to an existing Phar archive or to-be-created archive
</para>
</listitem>
</varlistentry>

View file

@ -1,9 +1,9 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<!-- $Revision: 1.3 $ -->
<refentry xml:id="phar.converttophar" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Phar::convertToPhar</refname>
<refpurpose>Convert the phar archive to the phar file format, optionally compressing the entire archive using gzip or bzip2 compression</refpurpose>
<refpurpose>Convert the phar archive to the phar file format</refpurpose>
</refnamediv>
@ -11,7 +11,7 @@
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>Phar::convertToPhar</methodname>
<methodparam><type>int</type><parameter>compression</parameter></methodparam>
<methodparam><type>string</type><parameter>extension</parameter></methodparam>
</methodsynopsis>
&phar.write;
<para>
@ -25,11 +25,13 @@
<para>
<variablelist>
<varlistentry>
<term><parameter>compression</parameter></term>
<term><parameter>extension</parameter></term>
<listitem>
<para>
This can be one of <literal>Phar::GZ</literal> or <literal>Phar::BZ2</literal>.
By default, no compression is applied.
By default, the extension is <literal>.phar</literal> for converting
from uncompressed tar archives or any zip archive, <literal>.phar.gz</literal> for
conversion from zlib-compressed tar archives, or <literal>.phar.bz2</literal>
for conversion from bzip2-compressed tar archives.
</para>
</listitem>
</varlistentry>
@ -40,9 +42,8 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The method returns &true; on success, but it is safer to encase the
call within a try/catch block and assume success if an exception is
not thrown.
The method returns a <classname>Phar</classname> object on success and throws an
exception on failure.
</para>
</refsect1>
@ -71,10 +72,10 @@
<![CDATA[
<?php
try {
$phar = new Phar('myphar.tar.phar');
// compress the entire archive with gzip compression
// as well as converting it to the phar file format
$phar->convertToPhar(Phar::GZ);
$tarphar = new Phar('myphar.tar.phar');
// convert it to the phar file format
// note that myphar.tar.phar is *not* unlinked
$phar = $tarphar->convertToPhar();
$phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
} catch (Exception $e) {
// handle the error here
@ -90,10 +91,10 @@ try {
&reftitle.seealso;
<para>
<simplelist>
<member><function>PharData::convertToPhar</function></member>
<member><function>Phar::convertToTar</function></member>
<member><function>Phar::convertToZip</function></member>
<member><function>Phar::compressAllFilesGZ</function></member>
<member><function>Phar::compressAllFilesBZIP2</function></member>
<member><function>Phar::compress</function></member>
</simplelist>
</para>
</refsect1>

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<!-- $Revision: 1.3 $ -->
<refentry xml:id="phar.converttotar" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Phar::convertToTar</refname>
@ -71,10 +71,8 @@
<![CDATA[
<?php
try {
$phar = new Phar('myphar.zip.phar');
// compress the entire archive with bzip2 compression
// as well as converting it to the phar file format
$phar->convertToPhar(Phar::BZ2);
$zip = new Phar('myphar.zip.phar');
$tar = $zip->convertToTar();
$phar->setStub('<?php include "phar://" . __FILE__ . "/cli.php"; __HALT_COMPILER();');
} catch (Exception $e) {
// handle the error here

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<!-- $Revision: 1.3 $ -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="phar.setstub">
<refnamediv>
<refname>Phar::setStub</refname>
@ -43,6 +43,24 @@ include 'phar://myphar.phar/somefile.php';
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>stub</parameter></term>
<listitem>
<para>
A string or an open stream handle to use as the executable stub for this
phar archive.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>

View file

@ -0,0 +1,83 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<reference xml:id="class.PharData" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>The PharData class</title>
<titleabbrev>PharData</titleabbrev>
<partintro>
<!-- {{{ Phar intro -->
<section xml:id="PharData.intro">
&reftitle.intro;
<para>
The PharData class provides a high-level interface to accessing and creating
non-executable tar and zip archives. Because these archives do not contain
a stub and cannot be executed by the phar extension, it is possible to create
and manipulate regular zip and tar files using the PharData class even if
<literal>phar.readonly</literal> php.ini setting is <literal>1</literal>.
</para>
</section>
<!-- }}} -->
<section xml:id="PharData.synopsis">
&reftitle.classsynopsis;
<!-- {{{ Synopsis -->
<classsynopsis>
<ooclass><classname>PharData</classname></ooclass>
<!-- {{{ Class synopsis -->
<classsynopsisinfo>
<ooclass>
<classname>PharData</classname>
</ooclass>
<ooclass>
<modifier>extends</modifier>
<classname>Phar</classname>
</ooclass>
</classsynopsisinfo>
<!-- }}} -->
<classsynopsisinfo role="comment">Properties</classsynopsisinfo>
<classsynopsisinfo role="comment">Methods</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.PharData')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
<classsynopsisinfo role="comment">Inherited methods</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.Phar')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
</classsynopsis>
<!-- }}} -->
</section>
</partintro>
&reference.phar.entities.PharData;
</reference>
<!-- 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:"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
-->

View file

@ -0,0 +1,194 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<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>Construct a tar or zip archive from an iterator.</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>PharData::buildFromIterator</methodname>
<methodparam><type>Iterator</type><parameter>iter</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>base_directory</parameter></methodparam>
</methodsynopsis>
<para>
Populate a tar or zip archive from an iterator. Two styles of iterators are supported,
iterators that map the filename within the tar/zip to the name of a file on disk,
and iterators like DirectoryIterator that return
SplFileInfo objects. For iterators that return SplFileInfo objects, the second
parameter is required.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title>A <function>PharData::buildFromIterator</function> with SplFileInfo</title>
<para>
For most tar/zip archives, the archive will reflect an actual directory layout, and
the second style is the most useful. For instance, to create a tar/zip archive
containing the files in this sample directory layout:
</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>
This code could be used to add these files to the &quot;project.tar&quot; tar archive:
</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>
The file <literal>project.tar</literal> can then be used immediately. <function>buildFromIterator</function> does not
set values such as compression, metadata, and this can be done after creating the
tar/zip archive.
</para>
<para>
As an interesting note, <function>buildFromIterator</function> can also be used to
copy the contents of an existing phar, tar or zip archive, as the PharData object descends
from <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->createDefaultWebStub('cli/index.php', 'www/index.php'));
?>
]]>
</programlisting>
</para>
</example>
<example>
<title>A <function>PharData::buildFromIterator</function> with other iterators</title>
<para>
The second form of the iterator can be used with any iterator that returns
a key => value mapping, such as an <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="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>iter</parameter></term>
<listitem>
<para>
Any iterator that either associatively maps tar/zip file to location or
returns SplFileInfo objects
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>base_directory</parameter></term>
<listitem>
<para>
For iterators that return SplFileInfo objects, the portion of each
file's full path to remove when adding to the tar/zip archive
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<function>buildFromIterator</function> returns an associative array
mapping internal path of file to the full path of the file on the
filesystem.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
This method returns <classname>UnexpectedValueException</classname> when the
iterator returns incorrect values, such as an integer key instead of a
string, a <classname>BadMethodCallException</classname> when an
SplFileInfo-based iterator is passed without a <parameter>base_directory</parameter>
parameter, or a <classname>PharException</classname> if there were errors
saving the phar archive.
</para>
</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:"../../../../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
-->

View file

@ -0,0 +1,125 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="phardata.compressallfilesbzip2">
<refnamediv>
<refname>PharData::compressAllFilesBZIP2</refname>
<refpurpose>Compresses all files in the current tar/zip archive using Bzip2 compression</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>PharData::compressAllFilesBZIP2</methodname>
<void/>
</methodsynopsis>
<para>
For tar archives, this method fails with a <classname>PharException</classname>, as
there is no provision in the tar file format to compress individual files. To compress
an entire tar archive, use <function>PharData::compress</function>.
</para>
<para>
This method compresses all files in the zip archive using bzip2 compression.
The <link linkend="ref.bzip2">bzip2</link> extension must be enabled to take
advantage of this feature. In addition, if any files are already compressed using
gzip compression, the <link linkend="ref.zlib">zlib</link> extension must be enabled in order
to decompress the files prior to re-compressing with bzip2 compression.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>BadMethodCallException</classname> if
the <link linkend="ref.bzip2">bzip2</link>
extension is not available, or if any files are compressed using
gzip compression and the <link linkend="ref.zlib">zlib</link> extension
is not enabled.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>PharData::compressAllFilesBZIP2</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$p = new PharData('/path/to/my.zip');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressedBZIP2());
var_dump($file->isCompressedGZ());
}
$p->compressAllFilesBZIP2();
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressedBZIP2());
var_dump($file->isCompressedGZ());
}
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
string(10) "myfile.txt"
bool(false)
bool(false)
bool(false)
string(11) "myfile2.txt"
bool(false)
bool(false)
bool(false)
string(10) "myfile.txt"
bool(true)
bool(true)
bool(false)
string(11) "myfile2.txt"
bool(true)
bool(true)
bool(false)
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>Phar::compressAllFilesBZIP2</function></member>
<member><function>PharData::compress</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:"../../../../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
-->

View file

@ -0,0 +1,126 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="phardata.compressallfilesgz">
<refnamediv>
<refname>PharData::compressAllFilesGZ</refname>
<refpurpose>Compresses all files in the current tar/zip archive using Gzip compression</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>PharData::compressAllFilesGZ</methodname>
<void/>
</methodsynopsis>
<para>
For tar archives, this method fails with a <classname>PharException</classname>, as
there is no provision in the tar file format to compress individual files. To compress
an entire tar archive, use <function>PharData::compress</function>.
</para>
<para>
For zip archives, this method compresses all files in the
Phar archive using gzip compression.
The <link linkend="ref.zlib">zlib</link> extension must be enabled to take
advantage of this feature. In addition, if any files are already compressed using
bzip2 compression, the <link linkend="ref.bzip2">bzip2</link> extension must be
enabled in order to decompress the files prior to re-compressing with gzip compression.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>BadMethodCallException</classname> if
the <link linkend="ini.phar.readonly">phar.readonly</link>
INI variable is on, the <link linkend="ref.zlib">zlib</link>
extension is not available, or if any files are compressed using
bzip2 compression and the <link linkend="ref.bzip2">bzip2</link> extension
is not enabled.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>PharData::compressAllFilesGZ</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$p = new PharData('/path/to/my.zip');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressedBZIP2());
var_dump($file->isCompressedGZ());
}
$p->compressAllFilesGZ();
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressedBZIP2());
var_dump($file->isCompressedGZ());
}
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
string(10) "myfile.txt"
bool(false)
bool(false)
bool(false)
string(11) "myfile2.txt"
bool(false)
bool(false)
bool(false)
string(10) "myfile.txt"
bool(true)
bool(false)
bool(true)
string(11) "myfile2.txt"
bool(true)
bool(false)
bool(true)
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>Phar::compressAllFilesGZ</function></member>
<member><function>PharData::compress</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:"../../../../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
-->

View file

@ -0,0 +1,97 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="phardata.construct">
<refnamediv>
<refname>PharData::__construct</refname>
<refpurpose>Construct a non-executable tar or zip archive object</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>void</type><methodname>PharData::__construct</methodname>
<methodparam><type>string</type><parameter>fname</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>fname</parameter></term>
<listitem>
<para>
Path to an existing tar/zip archive or to-be-created archive
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
flags to pass to <classname>Phar</classname> parent class <classname>RecursiveDirectoryIterator</classname>.
See <link xlink:href="http://www.php.net/~helly/php/ext/spl/classRecursiveDirectoryIterator.html#be0e1176d512c66500e5c26f248c89c4">SPL RecursiveDirectoryIterator docs</link>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws BadMethodCallException if called twice, UnexpectedValueException
if the phar archive can't be opened.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>PharData::__construct</function> example</title>
<para>
<programlisting role="php">
<![CDATA[
<?php
try {
$p = new PharData('/path/to/my.tar', CURRENT_AS_FILEINFO | KEY_AS_FILENAME);
} catch (UnexpectedValueException $e) {
die('Could not open my.tar');
} catch (BadMethodCallException $e) {
echo 'technically, this cannot happen';
}
echo file_get_contents('phar:///path/to/my.tar/example.txt');
?>
]]>
</programlisting>
</para>
</example>
</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:"../../../../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
-->

View file

@ -0,0 +1,120 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<refentry xml:id="phardata.converttophar" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>PharData::convertToPhar</refname>
<refpurpose>Convert the tar/zip archive to the phar file format</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>PharData::convertToPhar</methodname>
<methodparam><type>string</type><parameter>extension</parameter></methodparam>
</methodsynopsis>
&phar.write;
<para>
This method is used to convert a tar/zip archive to
the executable phar file format.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>extension</parameter></term>
<listitem>
<para>
By default, the extension is <literal>.phar</literal> for converting
from uncompressed tar archives or any zip archive, <literal>.phar.gz</literal> for
conversion from zlib-compressed tar archives, or <literal>.phar.bz2</literal>
for conversion from bzip2-compressed tar archives.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The method returns a <classname>Phar</classname> object on success and throws an
exception on failure.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
This method throws <classname>BadMethodCallException</classname> when unable
to compress, an unknown compression method has been specified, the requested
archive is buffering with <function>PharData::startBuffering</function> and
has not concluded with <function>PharData::stopBuffering</function>, an
<classname>UnexpectedValueException</classname> if write support is disabled,
and a <classname>PharException</classname> if any problems are encountered
during the phar creation process.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>PharData::convertToPhar</function> example</title>
<para>
Using PharData::convertToPhar():
</para>
<programlisting role="php">
<![CDATA[
<?php
try {
$tarphar = new PharData('myphar.tar');
// convert it to the phar file format
// note that myphar.tar is *not* unlinked
$phar = $tarphar->convertToPhar(); // creates myphar.phar
$phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
} catch (Exception $e) {
// handle the error here
}
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>Phar::convertToPhar</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:"../../../../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
-->

View file

@ -0,0 +1,113 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<refentry xml:id="phardata.converttotar" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>PharData::convertToTar</refname>
<refpurpose>Convert a zip archive to the tar file format</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>PharData::convertToTar</methodname>
<methodparam><type>string</type><parameter>extension</parameter></methodparam>
</methodsynopsis>
<para>
This method is used to convert a phar archive in phar or zip format to
the tar file format.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>extension</parameter></term>
<listitem>
<para>
By default, the extension is <literal>.tar</literal> for converting
from zip archives.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The method returns a <classname>PharData</classname> object on success and throws an
exception on failure.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
This method throws <classname>BadMethodCallException</classname> when unable
to compress, an unknown compression method has been specified, the requested
archive is buffering with <function>PharData::startBuffering</function> and
has not concluded with <function>PharData::stopBuffering</function>, and a
<classname>PharException</classname> if any problems are encountered
during the tar creation process.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>PharData::convertToTar</function> example</title>
<para>
Using PharData::convertToTar():
</para>
<programlisting role="php">
<![CDATA[
<?php
try {
$zip = new PharData('myphar.zip');
$tar = $zip->convertToTar();
} catch (Exception $e) {
// handle the error here
}
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>Phar::convertToTar</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:"../../../../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
-->

View file

@ -0,0 +1,115 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<refentry xml:id="phardata.converttozip" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>PharData::convertToZip</refname>
<refpurpose>Convert a tar archive to the zip file format</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>PharData::convertToZip</methodname>
<methodparam><type>string</type><parameter>extension</parameter></methodparam>
</methodsynopsis>
<para>
This method is used to convert a phar archive in phar or tar format to
the zip file format.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>extension</parameter></term>
<listitem>
<para>
By default, the extension is <literal>.zip</literal> for converting
from tar archives.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The method returns a <classname>PharData</classname> object on success and throws an
exception on failure.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
This method throws <classname>BadMethodCallException</classname> when the
requested archive is buffering with <function>PharData::startBuffering</function> and
has not concluded with <function>PharData::stopBuffering</function>, and
a <classname>PharException</classname> if any problems are encountered
during the zip creation process.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>PharData::convertToZip</function> example</title>
<para>
Using PharData::convertToZip():
</para>
<programlisting role="php">
<![CDATA[
<?php
try {
$tar = new PharData('myphar.tar.gz');
// convert it to the zip file format
$zip = $tar->convertToZip();
} catch (Exception $e) {
// handle the error here
}
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>Phar::convertToZip</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:"../../../../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
-->

View file

@ -0,0 +1,119 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<refentry xml:id="phardata.copy" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>PharData::copy</refname>
<refpurpose>Copy a file internal to the phar archive to another new file within the phar</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>PharData::copy</methodname>
<methodparam><type>string</type><parameter>oldfile</parameter></methodparam>
<methodparam><type>string</type><parameter>newfile</parameter></methodparam>
</methodsynopsis>
<para>
Copy a file internal to the tar/zip archive to another new file within the same archive.
This is an object-oriented alternative to using <function>copy</function> with
the phar stream wrapper.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>oldfile</parameter></term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>newfile</parameter></term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
returns &true; on success, but it is safer to encase method call in a
try/catch block and assume success if no exception is thrown.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
throws <classname>UnexpectedValueException</classname> if the source file does not
exist, the destination file already exists, write access is disabled, opening either
file fails, reading the source file fails, or a <classname>PharException</classname>
if writing the changes to the phar fails.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>PharData::copy</function> example</title>
<para>
This example shows using <function>PharData::copy</function> and the
equivalent stream wrapper performance of the same thing. The primary
difference between the two approaches is error handling. All PharData methods
throw exceptions, whereas the stream wrapper uses <function>trigger_error</function>.
</para>
<programlisting role="php">
<![CDATA[
<?php
try {
$phar = new PharData('myphar.tar');
$phar['a'] = 'hi';
$phar->copy('a', 'b');
echo $phar['b']; // outputs "hi"
} catch (Exception $e) {
// handle error
}
// the stream wrapper equivalent of the above code.
// E_WARNINGS are triggered on error rather than exceptions.
copy('phar://myphar.tar/a', 'phar//myphar.tar/c');
echo file_get_contents('phar://myphar.tar/c'); // outputs "hi"
?>
]]>
</programlisting>
</example>
</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:"../../../../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
-->

View file

@ -0,0 +1,108 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<refentry xml:id="phardata.delmetadata" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>PharData::delMetadata</refname>
<refpurpose>Deletes the global metadata of a zip archive</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>PharData::delMetadata</methodname>
<void/>
</methodsynopsis>
&phar.write;
<para>
Deletes the global metadata of the zip archive
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
returns &true; on success, but it is better to check for thrown exception,
and assume success if none is thrown.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>PharException</classname> if errors occur while flushing
changes to disk.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>PharData::delMetaData</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
try {
$phar = new PharData('myphar.zip');
var_dump($phar->getMetadata());
$phar->setMetadata("hi there");
var_dump($phar->getMetadata());
$phar->delMetadata();
var_dump($phar->getMetadata());
} catch (Exception $e) {
// handle errors
}
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
NULL
string(8) "hi there"
NULL
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>Phar::delMetadata</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:"../../../../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
-->

View file

@ -0,0 +1,121 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="phardata.offsetset">
<refnamediv>
<refname>PharData::offsetSet</refname>
<refpurpose>set the contents of a file within the tar/zip to those of an external file or string</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>void</type><methodname>PharData::offsetSet</methodname>
<methodparam><type>string</type><parameter>offset</parameter></methodparam>
<methodparam><type>string</type><parameter>value</parameter></methodparam>
</methodsynopsis>
<para>
This is an implementation of the <interfacename>ArrayAccess</interfacename> interface allowing
direct manipulation of the contents of a tar/zip archive using
array access brackets. offsetSet is used for modifying an
existing file, or adding a new file to a tar/zip archive.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<para>
The filename (relative path) to modify in a tar or zip archive.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
Content of the file.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
No return values.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws
<classname>PharException</classname> if there are any problems flushing
changes made to the tar/zip archive to disk.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>PharData::offsetSet</function> example</title>
<para>
offsetSet should not be accessed directly, but instead used
via array access with the <literal>[]</literal> operator.
</para>
<programlisting role="php">
<![CDATA[
<?php
$p = new PharData('/path/to/my.tar');
try {
// calls offsetSet
$p['file.txt'] = 'Hi there';
} catch (Exception $e) {
echo 'Could not modify file.txt:', $e;
}
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>Phar::offsetSet</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:"../../../../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
-->

View file

@ -0,0 +1,82 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<refentry xml:id="phardata.setalias" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>PharData::setAlias</refname>
<refpurpose>dummy function (Phar::setAlias is not valid for PharData)</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>PharData::setAlias</methodname>
<methodparam><type>string</type><parameter>alias</parameter></methodparam>
</methodsynopsis>
<para>
Non-executable tar/zip archives cannot have an alias, so this method simply
throws an exception.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>alias</parameter></term>
<listitem>
<para>
A shorthand string that this archive can be referred to in <literal>phar</literal>
stream wrapper access. This parameter is ignored.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>PharException</classname> on all method calls
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>Phar::setAlias</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:"../../../../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
-->

View file

@ -0,0 +1,77 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="phardata.setstub">
<refnamediv>
<refname>PharData::setStub</refname>
<refpurpose>dummy function (Phar::setStub is not valid for PharData)</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>void</type><methodname>PharData::setStub</methodname>
<methodparam><type>string</type><parameter>stub</parameter></methodparam>
</methodsynopsis>
<para>
Non-executable tar/zip archives cannot have a stub, so this method simply
throws an exception.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>stub</parameter></term>
<listitem>
<para>
A string or an open stream handle to use as the executable stub for this
phar archive. This parameter is ignored.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>PharException</classname> on all method calls
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>Phar::setStub</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:"../../../../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
-->

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<!-- Purpose: compression -->
<!-- Membership: pecl -->
@ -9,11 +9,24 @@
<!-- {{{ 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::convertToTar</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.
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
@ -71,22 +84,23 @@
</para>
<para>
Phar archives can be distributed as <literal>tar</literal> archives,
<literal>zip</literal> archives (if the <link linkend="book.zip">zip</link>
extension is enabled), or as the custom <literal>phar</literal> file format
<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 custom, and can only be created by the phar
extension, but has the advantage that applications created in this format will run
without having the phar extension installed.
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
<ulink url="http://pear.php.net/PHP_Archive">PHP_Archive</ulink>, 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.
possible with the phar extension unless the phar archive was created by PHP_Archive.
</para>
<para>
The phar extension is capable of converting a phar archive from tar to zip or
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>
@ -103,7 +117,7 @@
</example>
</para>
<para>
Phar is also capable of compressing individual files or an entire archive
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>,
@ -112,9 +126,10 @@
</para>
<para>
Lastly, the Phar extension is security-conscious, and disables write access
to phar archives by default, and requires system-level disabling of the
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.
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
@ -148,6 +163,7 @@
&reference.phar.creating;
&reference.phar.fileformat;
&reference.phar.Phar;
&reference.phar.PharData;
&reference.phar.PharFileInfo;
&reference.phar.PharException;

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.9 $ -->
<!-- $Revision: 1.10 $ -->
<chapter xml:id="phar.fileformat" xmlns="http://docbook.org/ns/docbook">
<title>What makes a phar a phar and not a tar or a zip?</title>
<section xml:id="phar.fileformat.ingredients" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
@ -148,6 +148,14 @@ __HALT_COMPILER();
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Can be created/modified even if phar.readonly=1
<link linkend="phar.fileformat.phartip3">[3]</link>
</entry>
<entry>No</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
</tbody>
</tgroup>
</table>
@ -172,6 +180,15 @@ __HALT_COMPILER();
</para>
</tip>
</para>
<para xml:id="phar.fileformat.phartip3">
<tip>
<para>
[3] Only tar and zip archives without <literal>.phar</literal> in their
filename and without an executable stub <literal>.phar/stub.php</literal>
can be created if phar.readonly=1.
</para>
</tip>
</para>
</section>
<section xml:id="phar.fileformat.tar" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Tar-based phars</title>
@ -185,9 +202,9 @@ __HALT_COMPILER();
gzip or bzip2 format and still be executed by the Phar extension.
</para>
<para>
To compress an entire archive, use <function>Phar::compressAllFilesGZ</function>
or <function>Phar::compressAllFilesBZIP2</function>. To decompress an entire
archive, use <function>Phar::uncompressAllFiles</function>
To compress an entire archive, use <function>Phar::compress</function>.
To decompress an entire archive, use <function>Phar::compress</function> with
the <literal>Phar::NONE</literal> constant.
</para>
</section>
<section xml:id="phar.fileformat.zip" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<section xml:id="phar.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.install;
<simpara>
@ -8,14 +8,13 @@
</simpara>
<simpara>
To install on Windows, follow the instructions above, modify your php.ini and restarting your web server.
To install on Windows, follow the instructions above, modify your php.ini and restart your web server.
</simpara>
<screen>
<![CDATA[
extension_dir=c:/php5/exts/
extension=php_phar.dll
extension=php_zip.dll
;; optional extensions
extension=php_bz2.dll
]]>

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<chapter xml:id="phar.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.setup;
@ -16,8 +16,7 @@
<para>
You may optionally wish to enable the <link linkend="book.zlib" >zlib</link>
and <link linkend="book.bzip2" >bzip2</link> extensions to take
advantage of compressed phar support and the <link linkend="book.zip">zip</link> extension
to enable zip-based phar archive support (Phar version 1.3.0 or newer).
advantage of compressed phar support.
</para>
<para>
Note that a bug in the <link linkend="filters.compression">zlib.deflate</link> stream filter

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
<!-- $Revision: 1.11 $ -->
<chapter xml:id="phar.using" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Using Phar Archives</title>
@ -84,7 +84,7 @@ try {
if (Phar::canWrite()) {
$p = new Phar('newphar.tar.phar', 0, 'newphar.tar.phar');
// make this a tar-based phar archive, compressed with gzip compression (.tar.gz)
$p->convertToTar(Phar::GZ);
$p = $p->convertToTar()->compress(Phar::GZ);
// create transaction - nothing is written to newphar.phar
// until stopBuffering() is called, although temporary storage is needed
@ -223,7 +223,7 @@ file_put_contents('phar://my.phar/somefile.php', 0, $context);
</para>
</section>
<section xml:id="phar.using.object" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Using Phar Archives: the Phar class</title>
<title>Using Phar Archives: the Phar and PharData class</title>
<para>
The <classname>Phar</classname> class supports reading and manipulation
of Phar archives, as well as iteration through inherited functionality of
@ -233,6 +233,14 @@ file_put_contents('phar://my.phar/somefile.php', 0, $context);
interface, files inside a Phar archive can be accessed as if they were
part of an associative array.
</para>
<para>
The <classname>PharData</classname> class extends the <classname>Phar</classname>, and
allows creating and modifying non-executable (data) tar and zip archives even if
<literal>phar.readonly</literal>=1 in php.ini. As such,
<function>PharData::setAlias</function> and <function>PharData::setStub</function>
are both disabled as the concept of alias and stub are unique to executable phar
archives.
</para>
<para>
It is important to note that when creating a Phar archive, the full path
should be passed to the <classname>Phar</classname> object constructor.