<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>RAR</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="wrappers.ssh2.html">ssh2://</a></div>
<div class="next" style="text-align: right; float: right;"><a href="wrappers.audio.html">ogg://</a></div>
<div class="up"><a href="wrappers.html">Supported Protocols and Wrappers</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="wrappers.rar" class="refentry">
<div class="refnamediv">
<h1 class="refname">rar://</h1>
<p class="refpurpose"><span class="refname">rar://</span> — <span class="dc-title">RAR</span></p>
</div>
<div class="refsect1 description" id="refsect1-wrappers.rar-description">
<h3 class="title">Description</h3>
<p class="para">
The wrapper takes the url encoded path to the RAR archive (relative or absolute),
an optional asterik (<em>*</em>), an optional number sign
(<em>#</em>) 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.
</p>
<p class="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
<a href="class.recursivedirectoryiterator.html" class="classname">RecursiveDirectoryIterator</a> in the presence of file names that seem like
url encoded data.
</p>
<p class="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 <a href="class.recursivedirectoryiterator.html" class="classname">RecursiveDirectoryIterator</a> 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.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<strong>This wrapper is not enabled by default</strong><br />
<span class="simpara">
In order to use the <var class="filename">rar://</var> wrapper, you must install
the <a href="http://pecl.php.net/package/rar" class="link external">» rar</a> extension
available from <a href="http://pecl.php.net/" class="link external">» PECL</a>.
</span>
</p></blockquote>
<p class="simpara">
<var class="filename">rar://</var>
Available since PECL rar 3.0.0
</p>
</div>
<div class="refsect1 usage" id="refsect1-wrappers.rar-usage">
<h3 class="title">Usage</h3>
<ul class="itemizedlist">
<li class="listitem"><span class="simpara"><var class="filename">rar://<url encoded archive name>[*][#[<url encoded entry name>]]</var></span></li>
</ul>
</div>
<div class="refsect1 options" id="refsect1-wrappers.rar-options">
<h3 class="title">Options</h3>
<p class="para">
<table class="doctable table">
<caption><strong>Wrapper Summary</strong></caption>
<thead>
<tr>
<th>Attribute</th>
<th>Supported</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>Restricted by <a href="filesystem.configuration.html#ini.allow-url-fopen" class="link">allow_url_fopen</a></td>
<td>No</td>
</tr>
<tr>
<td>Restricted by <a href="filesystem.configuration.html#ini.allow-url-include" class="link">allow_url_include</a></td>
<td>No</td>
</tr>
<tr>
<td>Allows Reading</td>
<td>Yes</td>
</tr>
<tr>
<td>Allows Writing</td>
<td>No</td>
</tr>
<tr>
<td>Allows Appending</td>
<td>No</td>
</tr>
<tr>
<td>Allows Simultaneous Reading and Writing</td>
<td>No</td>
</tr>
<tr>
<td>Supports <span class="function"><a href="function.stat.html" class="function">stat()</a></span></td>
<td>Yes</td>
</tr>
<tr>
<td>Supports <span class="function"><a href="function.unlink.html" class="function">unlink()</a></span></td>
<td>No</td>
</tr>
<tr>
<td>Supports <span class="function"><a href="function.rename.html" class="function">rename()</a></span></td>
<td>No</td>
</tr>
<tr>
<td>Supports <span class="function"><a href="function.mkdir.html" class="function">mkdir()</a></span></td>
<td>No</td>
</tr>
<tr>
<td>Supports <span class="function"><a href="function.rmdir.html" class="function">rmdir()</a></span></td>
<td>No</td>
</tr>
</tbody>
</table>
</p>
<p class="para">
<table class="doctable table">
<caption><strong>Context options</strong></caption>
<thead>
<tr>
<th>Name</th>
<th>Usage</th>
<th>Default</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td><em>open_password</em></td>
<td>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, <em>file_password</em> will be
ignored.
</td>
<td class="empty"> </td>
</tr>
<tr>
<td><em>file_password</em></td>
<td>The password used to encrypt a file, if any. If the headers
are also encrypted, this option will be ignored in favor of
<em>open_password</em>. 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,
<em>open_password</em> will be ignored and this option
must be used instead.
</td>
<td class="empty"> </td>
</tr>
<tr>
<td><em>volume_callback</em></td>
<td>A callback to determine the path of missing volumes. See
<span class="methodname"><a href="rararchive.open.html" class="methodname">RarArchive::open()</a></span> for more information.
</td>
<td class="empty"> </td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-wrappers.rar-examples">
<h3 class="title">Examples</h3>
<div class="example" id="example-325">
<p><strong>Example #1 Traversing a RAR archive</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br /></span><span style="color: #007700">class </span><span style="color: #0000BB">MyRecDirIt </span><span style="color: #007700">extends </span><span style="color: #0000BB">RecursiveDirectoryIterator </span><span style="color: #007700">{<br /> function </span><span style="color: #0000BB">current</span><span style="color: #007700">() {<br /> return </span><span style="color: #0000BB">rawurldecode</span><span style="color: #007700">(</span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">getSubPathName</span><span style="color: #007700">()) .<br /> (</span><span style="color: #0000BB">is_dir</span><span style="color: #007700">(</span><span style="color: #0000BB">parent</span><span style="color: #007700">::</span><span style="color: #0000BB">current</span><span style="color: #007700">())?</span><span style="color: #DD0000">" [DIR]"</span><span style="color: #007700">:</span><span style="color: #DD0000">""</span><span style="color: #007700">);<br /> }<br />}<br /><br /></span><span style="color: #0000BB">$f </span><span style="color: #007700">= </span><span style="color: #DD0000">"rar://" </span><span style="color: #007700">. </span><span style="color: #0000BB">rawurlencode</span><span style="color: #007700">(</span><span style="color: #0000BB">dirname</span><span style="color: #007700">(</span><span style="color: #0000BB">__FILE__</span><span style="color: #007700">)) .<br /> </span><span style="color: #0000BB">DIRECTORY_SEPARATOR </span><span style="color: #007700">. </span><span style="color: #DD0000">'dirs_and_extra_headers.rar#'</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">$it </span><span style="color: #007700">= new </span><span style="color: #0000BB">RecursiveTreeIterator</span><span style="color: #007700">(new </span><span style="color: #0000BB">MyRecDirIt</span><span style="color: #007700">(</span><span style="color: #0000BB">$f</span><span style="color: #007700">));<br /><br />foreach (</span><span style="color: #0000BB">$it </span><span style="color: #007700">as </span><span style="color: #0000BB">$s</span><span style="color: #007700">) {<br /> echo </span><span style="color: #0000BB">$s</span><span style="color: #007700">, </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output
something similar to:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
|-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
</pre></div>
</div>
</div>
<div class="example" id="example-326">
<p><strong>Example #2 Opening an encrypted file (header encryption)</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$stream </span><span style="color: #007700">= </span><span style="color: #0000BB">fopen</span><span style="color: #007700">(</span><span style="color: #DD0000">"rar://" </span><span style="color: #007700">.<br /> </span><span style="color: #0000BB">rawurlencode</span><span style="color: #007700">(</span><span style="color: #0000BB">dirname</span><span style="color: #007700">(</span><span style="color: #0000BB">__FILE__</span><span style="color: #007700">)) . </span><span style="color: #0000BB">DIRECTORY_SEPARATOR </span><span style="color: #007700">.<br /> </span><span style="color: #DD0000">'encrypted_headers.rar' </span><span style="color: #007700">. </span><span style="color: #DD0000">'#encfile1.txt'</span><span style="color: #007700">, </span><span style="color: #DD0000">"r"</span><span style="color: #007700">, </span><span style="color: #0000BB">false</span><span style="color: #007700">,<br /> </span><span style="color: #0000BB">stream_context_create</span><span style="color: #007700">(<br /> array(<br /> </span><span style="color: #DD0000">'rar' </span><span style="color: #007700">=><br /> array(<br /> </span><span style="color: #DD0000">'open_password' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'samplepassword'<br /> </span><span style="color: #007700">)<br /> )<br /> )<br /> );<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">stream_get_contents</span><span style="color: #007700">(</span><span style="color: #0000BB">$stream</span><span style="color: #007700">));<br /></span><span style="color: #FF8000">/* creation and last access date is opt-in in WinRAR, hence most<br /> * files don't have them */<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">fstat</span><span style="color: #007700">(</span><span style="color: #0000BB">$stream</span><span style="color: #007700">));<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output
something similar to:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
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
)
</pre></div>
</div>
</div>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="wrappers.ssh2.html">ssh2://</a></div>
<div class="next" style="text-align: right; float: right;"><a href="wrappers.audio.html">ogg://</a></div>
<div class="up"><a href="wrappers.html">Supported Protocols and Wrappers</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
