mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 08:28:54 +00:00
57492d2928
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@330316 c90b9560-bf6c-de11-be94-00142212c4b1
300 lines
8.1 KiB
XML
300 lines
8.1 KiB
XML
<?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://<url encoded archive name>[*][#[<url encoded entry name>]]</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
|
||
-->
|
||
|