sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

- Added rarEntry::getPosition

Browse source 
- Added rar:// wrapper documentation
- Other improvements on the rar extension documentation

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@300966 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Gustavo André dos Santos Lopes 2010-07-03 08:19:20 +00:00
parent 5699ed7b61
commit d29e172cab
26 changed files with 389 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

265
appendices/wrappers.xml
View file

@ -1257,6 +1257,271 @@ $stream = fopen("ssh2.tunnel://$session/remote.example.com:1234", 'r');
</section>
<section xml:id="wrappers.rar" xreflabel="rar:// wrapper">
<title>Rar</title>
<simpara>
<filename>rar://</filename>
Available since PECL rar 3.0.0
</simpara>
<itemizedlist>
<listitem><simpara><filename>rar://&lt;url encoded archive name&gt;[*][#[&lt;url encoded entry name&gt;]]</filename></simpara></listitem>
</itemizedlist>
<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>
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.
</simpara>
<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
<type>RecursiveDirectoryIterator</type> 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 inidivual entry in the archive.
The usage of the the wrapper with <type>RecursiveDirectoryIterator</type> 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>
<para>
<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>
</para>
<para>
<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>
</para>
<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>
<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>
</section>
<section xml:id="wrappers.audio">
<title>Audio Streams</title>

4
reference/rar/examples.xml
View file

@ -4,6 +4,10 @@
<chapter xml:id="rar.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.examples;
<para>
See also the examples under <link linkend="wrappers.rar"><literal>rar://</literal> wrapper</link>.
</para>
<para>
<example>
<title>On-the-fly decompression</title>

2
reference/rar/functions/rar-wrapper-cache-stats.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="function.rar-wrapper-cache-stats" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>rar_wrapper_cache_stats</refname>
<refpurpose>Cache hits and misses for the URL wrapper.</refpurpose>
<refpurpose>Cache hits and misses for the URL wrapper</refpurpose>
</refnamediv>
<refsect1 role="description">

2
reference/rar/rararchive/close.xml
View file

@ -5,7 +5,7 @@
<refnamediv>
<refname>RarArchive::close</refname>
<refname>rar_close</refname>
<refpurpose>Close RAR archive and free all resources.</refpurpose>
<refpurpose>Close RAR archive and free all resources</refpurpose>
</refnamediv>
<refsect1 role="description">

2
reference/rar/rararchive/getcomment.xml
View file

@ -5,7 +5,7 @@
<refnamediv>
<refname>RarArchive::getComment</refname>
<refname>rar_comment_get</refname>
<refpurpose>Get comment text from the RAR archive.</refpurpose>
<refpurpose>Get comment text from the RAR archive</refpurpose>
</refnamediv>
<refsect1 role="description">

45
reference/rar/rararchive/getentries.xml
View file

@ -5,7 +5,7 @@
<refnamediv>
<refname>RarArchive::getEntries</refname>
<refname>rar_list</refname>
<refpurpose>Get full list of entries from the RAR archive.</refpurpose>
<refpurpose>Get full list of entries from the RAR archive</refpurpose>
</refnamediv>
<refsect1 role="description">
@ -23,6 +23,16 @@
<para>
Get entries list (files and directories) from the RAR archive.
</para>
<note>
<para>
If the archive has
entries with the same name, this method, together with <type>RarArchive</type>
<literal>foreach</literal> iteration and array-like access with numeric indexes,
are the only ones to access all the entries (i.e.,
<methodname>RarArchive::getEntry</methodname> and the <link linkend="wrappers.rar">
<literal>rar://</literal> wrapper</link> are insufficient).
</para>
</note>
</refsect1>
<refsect1 role="parameters">
@ -48,6 +58,30 @@
&return.falseforfailure;.
</para>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>3.0.0</entry>
<entry>
Support for RAR archives with repeated entry names is no longer defective.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
@ -113,6 +147,15 @@ rar_close($rar_arch);
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><methodname>RarArchive::getEntry</methodname></member>
<member><link linkend="wrappers.rar"><literal>rar://</literal> wrapper</link></member>
</simplelist>
</para>
</refsect1>
</refentry>

13
reference/rar/rararchive/getentry.xml
View file

@ -5,7 +5,7 @@
<refnamediv>
<refname>RarArchive::getEntry</refname>
<refname>rar_entry_get</refname>
<refpurpose>Get entry object from the RAR archive.</refpurpose>
<refpurpose>Get entry object from the RAR archive</refpurpose>
</refnamediv>
<refsect1 role="description">
@ -26,6 +26,8 @@
</para>
<note>
<para>You can also get entry objects using <methodname>RarArchive::getEntries</methodname>.</para>
<para>Note that a RAR archive can have multiple entries with the same name; this method
will retrieve only the first.</para>
</note>
</refsect1>
@ -115,6 +117,15 @@ rar_close($rar_arch);
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><methodname>RarArchive::getEntries</methodname></member>
<member><link linkend="wrappers.rar"><literal>rar://</literal> wrapper</link></member>
</simplelist>
</para>
</refsect1>
</refentry>

2
reference/rar/rararchive/issolid.xml
View file

@ -5,7 +5,7 @@
<refnamediv>
<refname>RarArchive::isSolid</refname>
<refname>rar_solid_is</refname>
<refpurpose>Check whether the RAR archive is solid.</refpurpose>
<refpurpose>Check whether the RAR archive is solid</refpurpose>
</refnamediv>
<refsect1 role="description">

12
reference/rar/rararchive/open.xml
View file

@ -5,7 +5,7 @@
<refnamediv>
<refname>RarArchive::open</refname>
<refname>rar_open</refname>
<refpurpose>Open RAR archive.</refpurpose>
<refpurpose>Open RAR archive</refpurpose>
</refnamediv>
<refsect1 role="description">
@ -208,11 +208,21 @@ function resolve($vol) {
$rar_file1 = rar_open(dirname(__FILE__).'/multi_broken.part1.rar', null, 'resolve');
$entry = $rar_file1->getEntry('file2.txt');
$entry->extract(null, dirname(__FILE__) . "/temp_file2.txt");
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><link linkend="wrappers.rar"><literal>rar://</literal> wrapper</link></member>
</simplelist>
</para>
</refsect1>
</refentry>

2
reference/rar/rararchive/tostring.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="rararchive.tostring" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>RarArchive::__toString</refname>
<refpurpose>Get text representation.</refpurpose>
<refpurpose>Get text representation</refpurpose>
</refnamediv>
<refsect1 role="description">

9
reference/rar/rarentry/extract.xml
View file

@ -3,7 +3,7 @@
<refentry xml:id="rarentry.extract" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>RarEntry::extract</refname>
<refpurpose>Extract entry from the archive.</refpurpose>
<refpurpose>Extract entry from the archive</refpurpose>
</refnamediv>
<refsect1 role="description">
@ -106,6 +106,12 @@
<parameter>extended_data</parameter> was added.
</entry>
</row>
<row>
<entry>3.0.0</entry>
<entry>
Support for RAR archives with repeated entry names is no longer defective.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
@ -163,6 +169,7 @@ rar_close($rar_file);
<para>
<simplelist>
<member><methodname>RarEntry::getStream</methodname></member>
<member><link linkend="wrappers.rar"><literal>rar://</literal> wrapper</link></member>
</simplelist>
</para>
</refsect1>

2
reference/rar/rarentry/getattr.xml
View file

@ -3,7 +3,7 @@
<refentry xml:id="rarentry.getattr" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>RarEntry::getAttr</refname>
<refpurpose>Get attributes of the entry.</refpurpose>
<refpurpose>Get attributes of the entry</refpurpose>
</refnamediv>
<refsect1 role="description">

2
reference/rar/rarentry/getcrc.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="rarentry.getcrc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>RarEntry::getCrc</refname>
<refpurpose>Get CRC of the entry.</refpurpose>
<refpurpose>Get CRC of the entry</refpurpose>
</refnamediv>
<refsect1 role="description">

2
reference/rar/rarentry/getfiletime.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="rarentry.getfiletime" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>RarEntry::getFileTime</refname>
<refpurpose>Get entry last modification time.</refpurpose>
<refpurpose>Get entry last modification time</refpurpose>
</refnamediv>
<refsect1 role="description">

2
reference/rar/rarentry/gethostos.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="rarentry.gethostos" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>RarEntry::getHostOs</refname>
<refpurpose>Get entry host OS.</refpurpose>
<refpurpose>Get entry host OS</refpurpose>
</refnamediv>
<refsect1 role="description">

2
reference/rar/rarentry/getmethod.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="rarentry.getmethod" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>RarEntry::getMethod</refname>
<refpurpose>Get pack method of the entry.</refpurpose>
<refpurpose>Get pack method of the entry</refpurpose>
</refnamediv>
<refsect1 role="description">

2
reference/rar/rarentry/getname.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="rarentry.getname" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>RarEntry::getName</refname>
<refpurpose>Get name of the entry.</refpurpose>
<refpurpose>Get name of the entry</refpurpose>
</refnamediv>
<refsect1 role="description">

2
reference/rar/rarentry/getpackedsize.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="rarentry.getpackedsize" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>RarEntry::getPackedSize</refname>
<refpurpose>Get packed size of the entry.</refpurpose>
<refpurpose>Get packed size of the entry</refpurpose>
</refnamediv>
<refsect1 role="description">

27
reference/rar/rarentry/getstream.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="rarentry.getstream" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>RarEntry::getStream</refname>
<refpurpose>Get file handler for entry.</refpurpose>
<refpurpose>Get file handler for entry</refpurpose>
</refnamediv>
<refsect1 role="description">
@ -57,6 +57,30 @@
</para>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>3.0.0</entry>
<entry>
Support for RAR archives with repeated entry names is no longer defective.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
@ -102,6 +126,7 @@ fclose($stream);
<para>
<simplelist>
<member><methodname>RarEntry::extract</methodname></member>
<member><link linkend="wrappers.rar"><literal>rar://</literal> wrapper</link></member>
</simplelist>
</para>
</refsect1>

2
reference/rar/rarentry/getunpackedsize.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="rarentry.getunpackedsize" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>RarEntry::getUnpackedSize</refname>
<refpurpose>Get unpacked size of the entry.</refpurpose>
<refpurpose>Get unpacked size of the entry</refpurpose>
</refnamediv>
<refsect1 role="description">

2
reference/rar/rarentry/getversion.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="rarentry.getversion" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>RarEntry::getVersion</refname>
<refpurpose>Get minimum version of RAR program required to unpack the entry.</refpurpose>
<refpurpose>Get minimum version of RAR program required to unpack the entry</refpurpose>
</refnamediv>
<refsect1 role="description">

2
reference/rar/rarentry/isdirectory.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="rarentry.isdirectory" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>RarEntry::isDirectory</refname>
<refpurpose>Test whether an entry represents a directory.</refpurpose>
<refpurpose>Test whether an entry represents a directory</refpurpose>
</refnamediv>
<refsect1 role="description">

2
reference/rar/rarentry/isencrypted.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="rarentry.isencrypted" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>RarEntry::isEncrypted</refname>
<refpurpose>Test whether an entry is encrypted.</refpurpose>
<refpurpose>Test whether an entry is encrypted</refpurpose>
</refnamediv>
<refsect1 role="description">

2
reference/rar/rarentry/tostring.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="rarentry.tostring" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>RarEntry::__toString</refname>
<refpurpose>Get text representation of entry.</refpurpose>
<refpurpose>Get text representation of entry</refpurpose>
</refnamediv>
<refsect1 role="description">

2
reference/rar/rarexception/isusingexceptions.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="rarexception.isusingexceptions" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>RarException::isUsingExceptions</refname>
<refpurpose>Check whether error handling with exceptions is in use.</refpurpose>
<refpurpose>Check whether error handling with exceptions is in use</refpurpose>
</refnamediv>
<refsect1 role="description">

2
reference/rar/rarexception/setusingexceptions.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="rarexception.setusingexceptions" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>RarException::setUsingExceptions</refname>
<refpurpose>Activate and deactivate error handling with exceptions.</refpurpose>
<refpurpose>Activate and deactivate error handling with exceptions</refpurpose>
</refnamediv>
<refsect1 role="description">