<!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>Open RAR archive</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="rararchive.issolid.html">RarArchive::isSolid</a></div>
<div class="next" style="text-align: right; float: right;"><a href="rararchive.setallowbroken.html">RarArchive::setAllowBroken</a></div>
<div class="up"><a href="class.rararchive.html">RarArchive</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="rararchive.open" class="refentry">
<div class="refnamediv">
<h1 class="refname">RarArchive::open</h1>
<h1 class="refname">rar_open</h1>
<p class="verinfo">(PECL rar >= 2.0.0)</p><p class="refpurpose"><span class="refname">RarArchive::open</span> -- <span class="refname">rar_open</span> — <span class="dc-title">Open RAR archive</span></p>
</div>
<div class="refsect1 description" id="refsect1-rararchive.open-description">
<h3 class="title">Description</h3>
<p class="para">Object oriented style (method):</p>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="modifier">static</span> <span class="type"><a href="class.rararchive.html" class="type RarArchive">RarArchive</a></span> <span class="methodname"><strong>RarArchive::open</strong></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$filename</code></span>
[, <span class="methodparam"><span class="type">string</span> <code class="parameter">$password</code><span class="initializer"> = NULL</span></span>
[, <span class="methodparam"><span class="type"><a href="language.types.callable.html" class="type callable">callable</a></span> <code class="parameter">$volume_callback</code><span class="initializer"> = NULL</span></span>
]] )</div>
<p class="para rdfs-comment">Procedural style:</p>
<div class="methodsynopsis dc-description">
<span class="type"><a href="class.rararchive.html" class="type RarArchive">RarArchive</a></span> <span class="methodname"><strong>rar_open</strong></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$filename</code></span>
[, <span class="methodparam"><span class="type">string</span> <code class="parameter">$password</code><span class="initializer"> = NULL</span></span>
[, <span class="methodparam"><span class="type"><a href="language.types.callable.html" class="type callable">callable</a></span> <code class="parameter">$volume_callback</code><span class="initializer"> = NULL</span></span>
]] )</div>
<p class="para rdfs-comment">
Open specified RAR archive and return <span class="type"><a href="class.rararchive.html" class="type RarArchive">RarArchive</a></span> instance representing it.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
If opening a multi-volume archive, the path of the first volume should be passed as the first parameter.
Otherwise, not all files will be shown. This is by design.
</p>
</p></blockquote>
</div>
<div class="refsect1 parameters" id="refsect1-rararchive.open-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">filename</code></em></span>
<dd>
<p class="para">
Path to the Rar archive.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">password</code></em></span>
<dd>
<p class="para">
A plain password, if needed to decrypt the headers. It will also be used by default
if encrypted files are found. Note that the files may have
different passwords in respect to the headers and among them.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">volume_callback</code></em></span>
<dd>
<p class="para">
A function that receives one parameter – the path of the volume
that was not found – and returns a string with the correct path
for such volume or <strong><code>NULL</code></strong> if such volume does
not exist or is not known. The programmer should ensure the
passed function doesn't cause loops as this function is called
repeatedly if the path returned in a previous call did not
correspond to the needed volume. Specifying this parameter omits
the notice that would otherwise be emitted whenever a volume is
not found; an implementation that only returns <strong><code>NULL</code></strong>
can therefore be used to merely omit such notices.
</p>
</dd>
</dt>
</dl>
</p>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
Prior to version 2.0.0, this function would not handle relative
paths correctly. Use <span class="function"><a href="function.realpath.html" class="function">realpath()</a></span> as a workaround.
</p>
</div>
</div>
<div class="refsect1 returnvalues" id="refsect1-rararchive.open-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns the requested <span class="type"><a href="class.rararchive.html" class="type RarArchive">RarArchive</a></span> instance or <strong><code>FALSE</code></strong> on failure.
</p>
</div>
<div class="refsect1 changelog" id="refsect1-rararchive.open-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>3.0.0</td>
<td>
<em><code class="parameter">volume_callback</code></em> was added.
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-rararchive.open-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-757">
<p><strong>Example #1 Object oriented style</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$rar_arch </span><span style="color: #007700">= </span><span style="color: #0000BB">RarArchive</span><span style="color: #007700">::</span><span style="color: #0000BB">open</span><span style="color: #007700">(</span><span style="color: #DD0000">'encrypted_headers.rar'</span><span style="color: #007700">, </span><span style="color: #DD0000">'samplepassword'</span><span style="color: #007700">);<br />if (</span><span style="color: #0000BB">$rar_arch </span><span style="color: #007700">=== </span><span style="color: #0000BB">FALSE</span><span style="color: #007700">)<br /> die(</span><span style="color: #DD0000">"Failed opening file"</span><span style="color: #007700">);<br /> <br /></span><span style="color: #0000BB">$entries </span><span style="color: #007700">= </span><span style="color: #0000BB">$rar_arch</span><span style="color: #007700">-></span><span style="color: #0000BB">getEntries</span><span style="color: #007700">();<br />if (</span><span style="color: #0000BB">$entries </span><span style="color: #007700">=== </span><span style="color: #0000BB">FALSE</span><span style="color: #007700">)<br /> die(</span><span style="color: #DD0000">"Failed fetching entries"</span><span style="color: #007700">);<br /><br />echo </span><span style="color: #DD0000">"Found " </span><span style="color: #007700">. </span><span style="color: #0000BB">count</span><span style="color: #007700">(</span><span style="color: #0000BB">$entries</span><span style="color: #007700">) . </span><span style="color: #DD0000">" files.\n"</span><span style="color: #007700">;<br /><br />if (empty(</span><span style="color: #0000BB">$entries</span><span style="color: #007700">))<br /> die(</span><span style="color: #DD0000">"No valid entries found."</span><span style="color: #007700">);<br /> <br /></span><span style="color: #0000BB">$stream </span><span style="color: #007700">= </span><span style="color: #0000BB">reset</span><span style="color: #007700">(</span><span style="color: #0000BB">$entries</span><span style="color: #007700">)-></span><span style="color: #0000BB">getStream</span><span style="color: #007700">();<br />if (</span><span style="color: #0000BB">$stream </span><span style="color: #007700">=== </span><span style="color: #0000BB">FALSE</span><span style="color: #007700">)<br /> die(</span><span style="color: #DD0000">"Failed opening first file"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$rar_arch</span><span style="color: #007700">-></span><span style="color: #0000BB">close</span><span style="color: #007700">();<br /><br />echo </span><span style="color: #DD0000">"Content of first one follows:\n"</span><span style="color: #007700">;<br />echo </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 /><br /></span><span style="color: #0000BB">fclose</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>
Found 2 files.
Content of first one follows:
Encrypted file 1 contents.
</pre></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-758">
<p><strong>Example #2 Procedural style</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$rar_arch </span><span style="color: #007700">= </span><span style="color: #0000BB">rar_open</span><span style="color: #007700">(</span><span style="color: #DD0000">'encrypted_headers.rar'</span><span style="color: #007700">, </span><span style="color: #DD0000">'samplepassword'</span><span style="color: #007700">);<br />if (</span><span style="color: #0000BB">$rar_arch </span><span style="color: #007700">=== </span><span style="color: #0000BB">FALSE</span><span style="color: #007700">)<br /> die(</span><span style="color: #DD0000">"Failed opening file"</span><span style="color: #007700">);<br /> <br /></span><span style="color: #0000BB">$entries </span><span style="color: #007700">= </span><span style="color: #0000BB">rar_list</span><span style="color: #007700">(</span><span style="color: #0000BB">$rar_arch</span><span style="color: #007700">);<br />if (</span><span style="color: #0000BB">$entries </span><span style="color: #007700">=== </span><span style="color: #0000BB">FALSE</span><span style="color: #007700">)<br /> die(</span><span style="color: #DD0000">"Failed fetching entries"</span><span style="color: #007700">);<br /><br />echo </span><span style="color: #DD0000">"Found " </span><span style="color: #007700">. </span><span style="color: #0000BB">count</span><span style="color: #007700">(</span><span style="color: #0000BB">$entries</span><span style="color: #007700">) . </span><span style="color: #DD0000">" files.\n"</span><span style="color: #007700">;<br /><br />if (empty(</span><span style="color: #0000BB">$entries</span><span style="color: #007700">))<br /> die(</span><span style="color: #DD0000">"No valid entries found."</span><span style="color: #007700">);<br /> <br /></span><span style="color: #0000BB">$stream </span><span style="color: #007700">= </span><span style="color: #0000BB">reset</span><span style="color: #007700">(</span><span style="color: #0000BB">$entries</span><span style="color: #007700">)-></span><span style="color: #0000BB">getStream</span><span style="color: #007700">();<br />if (</span><span style="color: #0000BB">$stream </span><span style="color: #007700">=== </span><span style="color: #0000BB">FALSE</span><span style="color: #007700">)<br /> die(</span><span style="color: #DD0000">"Failed opening first file"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">rar_close</span><span style="color: #007700">(</span><span style="color: #0000BB">$rar_arch</span><span style="color: #007700">);<br /><br />echo </span><span style="color: #DD0000">"Content of first one follows:\n"</span><span style="color: #007700">;<br />echo </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 /><br /></span><span style="color: #0000BB">fclose</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>
</p>
<p class="para">
<div class="example" id="example-759">
<p><strong>Example #3 Volume Callback</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/* In this example, there's a volume named multi_broken.part1.rar<br /> * whose next volume is named multi.part2.rar */<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">resolve</span><span style="color: #007700">(</span><span style="color: #0000BB">$vol</span><span style="color: #007700">) {<br /> if (</span><span style="color: #0000BB">preg_match</span><span style="color: #007700">(</span><span style="color: #DD0000">'/_broken/'</span><span style="color: #007700">, </span><span style="color: #0000BB">$vol</span><span style="color: #007700">))<br /> return </span><span style="color: #0000BB">str_replace</span><span style="color: #007700">(</span><span style="color: #DD0000">'_broken'</span><span style="color: #007700">, </span><span style="color: #DD0000">''</span><span style="color: #007700">, </span><span style="color: #0000BB">$vol</span><span style="color: #007700">);<br /> else<br /> return </span><span style="color: #0000BB">null</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">$rar_file1 </span><span style="color: #007700">= </span><span style="color: #0000BB">rar_open</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: #DD0000">'/multi_broken.part1.rar'</span><span style="color: #007700">, </span><span style="color: #0000BB">null</span><span style="color: #007700">, </span><span style="color: #DD0000">'resolve'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$entry </span><span style="color: #007700">= </span><span style="color: #0000BB">$rar_file1</span><span style="color: #007700">-></span><span style="color: #0000BB">getEntry</span><span style="color: #007700">(</span><span style="color: #DD0000">'file2.txt'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$entry</span><span style="color: #007700">-></span><span style="color: #0000BB">extract</span><span style="color: #007700">(</span><span style="color: #0000BB">null</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: #DD0000">"/temp_file2.txt"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</div>
<div class="refsect1 seealso" id="refsect1-rararchive.open-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"><a href="wrappers.rar.html" class="link"><em>rar://</em> wrapper</a></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="rararchive.issolid.html">RarArchive::isSolid</a></div>
<div class="next" style="text-align: right; float: right;"><a href="rararchive.setallowbroken.html">RarArchive::setAllowBroken</a></div>
<div class="up"><a href="class.rararchive.html">RarArchive</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
