cellog Sun Jan 28 21:45:44 2007 UTC
Added files:
/phpdoc/en/reference/phar using.xml
/phpdoc/en/reference/phar/functions Phar-getMetaData.xml
Phar-setMetaData.xml
Modified files:
/phpdoc/en/reference/phar reference.xml
Log:
docs are complete now for phar
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/phar/reference.xml?r1=1.3&r2=1.4&diff_format=u
Index: phpdoc/en/reference/phar/reference.xml
diff -u phpdoc/en/reference/phar/reference.xml:1.3
phpdoc/en/reference/phar/reference.xml:1.4
--- phpdoc/en/reference/phar/reference.xml:1.3 Sun Jan 28 05:31:51 2007
+++ phpdoc/en/reference/phar/reference.xml Sun Jan 28 21:45:44 2007
@@ -1,5 +1,5 @@
<?xml version = '1.0' encoding = 'iso-8859-1'?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
<!-- Purpose: -->
<!-- Membership: pecl -->
<reference id="ref.phar" >
@@ -74,6 +74,7 @@
</member>
</simplelist>
</section>
+ &reference.phar.using;
&reference.phar.fileformat;
</partintro>
&reference.phar.functions;
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/phar/using.xml?view=markup&rev=1.1
Index: phpdoc/en/reference/phar/using.xml
+++ phpdoc/en/reference/phar/using.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<section id="phar.using.basics">
<title>Using Phar Archives: Introduction</title>
<para>
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:
</para>
<screen>
<![CDATA[
php coolapplication.phar
]]>
</screen>
<para>
Using a Phar archive library is identical to using any other PHP library:
</para>
<programlisting role="php">
<![CDATA[
<?php
include 'coollibrary.phar';
?>
]]>
</programlisting>
<para>
What makes Phar archives incredibly useful is the <literal>phar</literal>
stream wrapper, which is explained in depth <link
linkend="phar.using.stream">here</link>.
Using this stream wrapper, it is possible to access
individual files within a phar as if the phar were its own filesystem.
The <literal>phar</literal> stream wrapper supports all read/write operations
on files, and <function>opendir</function> on directories.
</para>
<programlisting role="php">
<![CDATA[
<?php
include 'phar://coollibrary.phar/internal/file.php';
header('Content-type: image/jpeg');
// phars can be accessed by full path or by alias
echo file_get_contents('phar:///fullpath/to/coollibrary.phar/images/wow.jpg');
?>
]]>
</programlisting>
<para>
Also provided with the Phar extension is the <classname>Phar</classname>
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
<link linkend="phar.using.object">here</link>.
</para>
<programlisting role="php">
<![CDATA[
<?php
try {
// open an existing phar
$p = new Phar('coollibrary.phar');
foreach ($p as $file) {
// $file is a PharFileInfo class, and inherits from SplFileInfo
echo $file->getFileName() . "\n";
echo $file . "\n"; // display contents;
}
if (isset($p['internal/file.php'])) {
var_dump($p['internal/file.php']->getMetaData());
}
// create a new phar - phar.readonly must be 0 in php.ini
// phar.readonly is enabled by default for security reasons.
// On production servers, Phars need never be created,
// only executed.
if (Phar::canWrite()) {
$p = new Phar(dirname(__FILE__) . '/newphar.phar', 0, 'newphar.phar');
// create transaction - nothing is written to disk until commit() is
called
$p->begin();
// add a new file, set its contents
$p['file1.txt'] = 'Information';
$fp = fopen('hugefile.dat', 'rb');
// copy from the stream
$p['data/hugefile.dat'] = $fp;
if (Phar::canCompress()) {
$p['data/hugefile.dat']->setCompressedGZ();
}
$p['images/wow.jpg'] = file_get_contents('images/wow.jpg');
// any value can be saved as file-specific meta-data
$p['images/wow.jpg']->setMetaData(array('mime-type' => 'image/jpeg'));
$p['index.php'] = file_get_contents('index.php');
$p->setMetaData(array('bootstrap' => 'index.php'));
// save the Phar, and set the loader stub
$p->commit('<?php
$p = new Phar(__FILE__);
$m = $p->getMetaData();
require "phar://" . __FILE__ . "/" . $m["bootstrap"];
__HALT_COMPILER();');
}
} catch (BadMethodCallException $e) {
echo 'Could not open Phar: ', $e;
}
?>
]]>
</programlisting>
</section>
<section id="phar.using.stream">
<title>Using Phar Archives: the phar stream wrapper</title>
<para>
The Phar stream wrapper fully supports <function>fopen</function> for
read, write or append, <function>unlink</function>, <function>stat</function>,
<function>fstat</function>, <function>fseek</function>,
<function>rename</function>
and directory stream operation <function>opendir</function>. 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.
</para>
<para>
Individual file compression and per-file metadata can also be manipulated
in a Phar archive using stream contexts:
</para>
<programlisting role="php">
<![CDATA[
<?php
$context = stream_context_create(array('phar' =>
array('compression' => Phar::GZ)),
array('metadata' => array('user' =>
'cellog')));
file_put_contents('phar://my.phar/somefile.php', 0, $context);
?>
]]>
</programlisting>
<para>
The <literal>phar</literal> stream wrapper does not operate on remote files,
and cannot operate on remote files, and so is allowed even when the
<link linkend="ini.allow-url-fopen">allow_url_fopen</link> INI option
is disabled.
</para>
<para>
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.
</para>
</section>
<section id="phar.using.object">
<title>Using Phar Archives: the Phar class</title>
<para>
The <classname>Phar</classname> class supports reading and manipulation
of Phar archives, as well as iteration through inherited functionality of
the
<ulink
url="http://www.php.net/~helly/php/ext/spl/classRecursiveDirectoryIterator.html";><classname>RecursiveDirectoryIterator</classname></ulink>
class. With support for the <interface>ArrayAccess</interface>
interface, files inside a Phar archive can be accessed as if they were
part of an associative array.
</para>
<para>
Assuming that <literal>$p</literal> is a Phar object initialized as follows:
<programlisting role="php">
<![CDATA[
<?php
$p = new Phar('myphar.phar');
?>
]]>
</programlisting>
The following is possible:
<itemizedlist>
<listitem>
<simpara>
<literal>$a = $p['file.php']</literal> creates a
<classname>PharFileInfo</classname>
class that refers to the contents of
<literal>phar://myphar.phar/file.php</literal>
</simpara>
</listitem>
<listitem>
<simpara>
<literal>$p['file.php'] = $v</literal> creates a new file
(<literal>phar://myphar.phar/file.php</literal>), or overwrites
an existing file within <literal>myphar.phar</literal>.
<literal>$v</literal>
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.
</simpara>
</listitem>
<listitem>
<simpara>
<literal>isset($p['file.php'])</literal> can be used to determine
whether <literal>phar://myphar.phar/file.php</literal> exists within
<literal>myphar.phar</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
<literal>unset($p['file.php'])</literal> erases
<literal>phar://myphar.phar/file.php</literal> from
<literal>myphar.phar</literal>.
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
In addition, the <classname>Phar</classname> object is the only way to access
Phar-specific metadata, through
<link
linkend="function.Phar-getMetaData"><function>Phar->getMetaData</function></link>,
and the only way to set or retrieve a Phar archive's PHP loader stub through
<link
linkend="function.Phar-getStub"><function>Phar->getStub</function></link> and
<link
linkend="function.Phar-commit"><function>Phar->commit</function></link>.
Additionally, compression for the entire Phar archive at once can only be
manipulated
using the <classname>Phar</classname> class.
</para>
<para>
The full list of <classname>Phar</classname> object functionality is
documented
below.
</para>
<para>
The <classname>PharFileInfo</classname> class extends the
<ulink
url="http://www.php.net/~helly/php/ext/spl/classSplFileInfo.html";><classname>SplFileInfo</classname></ulink>
class, and adds several methods for manipulating Phar-specific details of a
file
contained within a Phar, such as manipulating compression and metadata.
</para>
</section>
<!-- 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
-->
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/phar/functions/Phar-getMetaData.xml?view=markup&rev=1.1
Index: phpdoc/en/reference/phar/functions/Phar-getMetaData.xml
+++ phpdoc/en/reference/phar/functions/Phar-getMetaData.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.Phar-getMetaData">
<refnamediv>
<refname>Phar->getMetaData</refname>
<refpurpose>Returns phar archive meta-data</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>Phar->getMetaData</methodname>
<void/>
</methodsynopsis>
<para>
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
any PHP variable that can be serialized and is stored as meta-data for the
Phar archive,
or &null; if no meta-data is stored.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>Phar->getMetaData</function> example</title>
<para>
</para>
<programlisting role="php">
<![CDATA[
<?php
// make sure it doesn't exist
@unlink('brandnewphar.phar');
try {
$p = new Phar('brandnewphar.phar');
} catch (Exception $e) {
echo 'Could not create phar:', $e;
}
$p['file.php'] = '<?php echo "hello";';
$p->setMetaData(array('bootstrap' => 'file.php'));
var_dump($p->getMetaData());
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(1) {
["bootstrap"]=>
string(8) "file.php"
}
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><link
linkend="function.PharFileInfo-setMetaData"><function>PharFileInfo->setMetaData</function></link></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
-->
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/phar/functions/Phar-setMetaData.xml?view=markup&rev=1.1
Index: phpdoc/en/reference/phar/functions/Phar-setMetaData.xml
+++ phpdoc/en/reference/phar/functions/Phar-setMetaData.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.Phar-setMetaData">
<refnamediv>
<refname>Phar->setMetaData</refname>
<refpurpose>Sets phar archive meta-data</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>Phar->setMetaData</methodname>
<void/>
</methodsynopsis>
<para>
<function>setMetaData</function> should only be used to store customized data
that describes something about the phar archive as a complete entity.
<link
linkend="function.PharFileInfo-setMetaData"><function>PharFileInfo->setMetaData</function></link>
should be used for file-specific meta-data.
Meta-data can significantly slow down the performance of loading a phar
archive if the data is large. As with all functionality that modifies the
contents of
a phar, the <link linkend="ini.phar.readonly">phar.readonly</link> INI
variable must be
off in order to succeed.
</para>
<para>
Some possible uses for meta-data include specifying which file within the
archive
should be used to bootstrap the archive, or the location of a file manifest
like <ulink url="http://pear.php.net";>PEAR</ulink>'s package.xml file.
However, any useful data that describes the phar archive may be stored.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>metadata</parameter></term>
<listitem>
<para>
Any PHP variable containing information to store that describes the phar
archive
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>Phar->setMetaData</function> example</title>
<para>
</para>
<programlisting role="php">
<![CDATA[
<?php
// make sure it doesn't exist
@unlink('brandnewphar.phar');
try {
$p = new Phar('brandnewphar.phar');
} catch (Exception $e) {
echo 'Could not create phar:', $e;
}
$p['file.php'] = '<?php echo "hello"';
$p->setMetaData(array('bootstrap' => 'file.php'));
var_dump($p->getMetaData());
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(1) {
["bootstrap"]=>
string(8) "file.php"
}
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><link
linkend="function.Phar-getMetaData"><function>Phar->getMetaData</function></link></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
-->
