php-doc-en/language/wrappers/rar.xml
Jakub Vrana 57492d2928 Fix wrapper usage title
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@330316 c90b9560-bf6c-de11-be94-00142212c4b1
2013-05-20 21:10:17 +00:00

300 lines
8.1 KiB
XML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="wrappers.rar" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" role="noversion">
<refnamediv>
<refname>rar://</refname>
<refpurpose>RAR</refpurpose>
</refnamediv>
<refsect1 role="description"><!-- {{{ -->
&reftitle.description;
<para>
The wrapper takes the url encoded path to the RAR archive (relative or absolute),
an optional asterik (<literal>*</literal>), an optional number sign
(<literal>#</literal>) and an optional url encoded entry name, as stored in the
archive. Specifying an entry name requires the number sign; a leading forward
slash in the entry name is optional.
</para>
<simpara>
This wrapper can open both files and directories. When opening directories, the
asterisk sign forces the directory entries names to be returned unencoded. If it's
not specified, they will be returned url encoded the reason for this is to allow
the wrapper to be correctly used with built-in functionality like the
<classname>RecursiveDirectoryIterator</classname> in the presence of file names that seem like
url encoded data.
</simpara>
<simpara>
If the pound sign and the entry name part are not included, the root of the archive
will be displayed. This differs from regular directories in that the resulting
stream will not contain information such as the modification time, as the root
directory is not stored in an individual entry in the archive.
The usage of the wrapper with <classname>RecursiveDirectoryIterator</classname> requires
the number sign to be included in the URL when accessing the root, so that the
URLs of the children may be constructed correctly.
</simpara>
<note>
<title>This wrapper is not enabled by default</title>
<simpara>
In order to use the <filename>rar://</filename> wrapper, you must install
the <link xlink:href="&url.pecl.package;rar">rar</link> extension
available from <link xlink:href="&url.pecl;">PECL</link>.
</simpara>
</note>
<simpara>
<filename>rar://</filename>
Available since PECL rar 3.0.0
</simpara>
</refsect1><!-- }}} -->
<refsect1 role="usage"> <!-- {{{ -->
&reftitle.usage;
<itemizedlist>
<listitem><simpara><filename>rar://&lt;url encoded archive name&gt;[*][#[&lt;url encoded entry name&gt;]]</filename></simpara></listitem>
</itemizedlist>
</refsect1> <!-- }}} -->
<refsect1 role="options"><!-- {{{ -->
&reftitle.options;
<para>
<table>
<title>Wrapper Summary</title>
<tgroup cols="2">
<thead>
<row>
<entry>Attribute</entry>
<entry>Supported</entry>
</row>
</thead>
<tbody>
<row>
<entry>Restricted by <link linkend="ini.allow-url-fopen">allow_url_fopen</link></entry>
<entry>No</entry>
</row>
<row>
<entry>Restricted by <link linkend="ini.allow-url-include">allow_url_include</link></entry>
<entry>No</entry>
</row>
<row>
<entry>Allows Reading</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Allows Writing</entry>
<entry>No</entry>
</row>
<row>
<entry>Allows Appending</entry>
<entry>No</entry>
</row>
<row>
<entry>Allows Simultaneous Reading and Writing</entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>stat</function></entry>
<entry>Yes</entry>
</row>
<row>
<entry>Supports <function>unlink</function></entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>rename</function></entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>mkdir</function></entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>rmdir</function></entry>
<entry>No</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<!-- FIXME: This should be context.rar ! -->
<para>
<table>
<title>Context options</title>
<tgroup cols="3">
<thead>
<row>
<entry>Name</entry>
<entry>Usage</entry>
<entry>Default</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>open_password</literal></entry>
<entry>The password used to encrypt the headers of the archive,
if any. WinRAR will encrypt all the files with the same password
as the headers password when the later is present, so for archives
with encrypted headers, <literal>file_password</literal> will be
ignored.
</entry>
<entry/>
</row>
<row>
<entry><literal>file_password</literal></entry>
<entry>The password used to encrypt a file, if any. If the headers
are also encrypted, this option will be ignored in favor of
<literal>open_password</literal>. The reason there are two options
is to cover the possibility of supporting archives with different
headers and file passwords, should those archives arise. Note that
if the archive does not have its headers encrypted,
<literal>open_password</literal> will be ignored and this option
must be used instead.
</entry>
<entry/>
</row>
<row>
<entry><literal>volume_callback</literal></entry>
<entry>A callback to determine the path of missing volumes. See
<methodname>RarArchive::open</methodname> for more information.
</entry>
<entry/>
</row>
</tbody>
</tgroup>
</table>
</para>
</refsect1> <!-- }}} -->
<refsect1 role="examples"><!-- {{{ -->
&reftitle.examples;
<example>
<title>Traversing a RAR archive</title>
<programlisting role="php">
<![CDATA[
<?php
class MyRecDirIt extends RecursiveDirectoryIterator {
function current() {
return rawurldecode($this->getSubPathName()) .
(is_dir(parent::current())?" [DIR]":"");
}
}
$f = "rar://" . rawurlencode(dirname(__FILE__)) .
DIRECTORY_SEPARATOR . 'dirs_and_extra_headers.rar#';
$it = new RecursiveTreeIterator(new MyRecDirIt($f));
foreach ($it as $s) {
echo $s, "\n";
}
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
|-allow_everyone_ni [DIR]
|-file1.txt
|-file2_אּ.txt
|-with_streams.txt
\-אּ [DIR]
|-אּ\%2Fempty%2E [DIR]
| \-אּ\%2Fempty%2E\file7.txt
|-אּ\empty [DIR]
|-אּ\file3.txt
|-אּ\file4_אּ.txt
\-אּ\אּ_2 [DIR]
|-אּ\אּ_2\file5.txt
\-אּ\אּ_2\file6_אּ.txt
]]>
</screen>
</example>
<example>
<title>Opening an encrypted file (header encryption)</title>
<programlisting role="php">
<![CDATA[
<?php
$stream = fopen("rar://" .
rawurlencode(dirname(__FILE__)) . DIRECTORY_SEPARATOR .
'encrypted_headers.rar' . '#encfile1.txt', "r", false,
stream_context_create(
array(
'rar' =>
array(
'open_password' => 'samplepassword'
)
)
)
);
var_dump(stream_get_contents($stream));
/* creation and last access date is opt-in in WinRAR, hence most
* files don't have them */
var_dump(fstat($stream));
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
string(26) "Encrypted file 1 contents."
Array
(
[0] => 0
[1] => 0
[2] => 33206
[3] => 1
[4] => 0
[5] => 0
[6] => 0
[7] => 26
[8] => 0
[9] => 1259550052
[10] => 0
[11] => -1
[12] => -1
[dev] => 0
[ino] => 0
[mode] => 33206
[nlink] => 1
[uid] => 0
[gid] => 0
[rdev] => 0
[size] => 26
[atime] => 0
[mtime] => 1259550052
[ctime] => 0
[blksize] => -1
[blocks] => -1
)
]]>
</screen>
</example>
</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:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->