<!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>Extract entry from the archive</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="class.rarentry.html">RarEntry</a></div>
<div class="next" style="text-align: right; float: right;"><a href="rarentry.getattr.html">RarEntry::getAttr</a></div>
<div class="up"><a href="class.rarentry.html">RarEntry</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="rarentry.extract" class="refentry">
<div class="refnamediv">
<h1 class="refname">RarEntry::extract</h1>
<p class="verinfo">(PECL rar >= 0.1)</p><p class="refpurpose"><span class="refname">RarEntry::extract</span> — <span class="dc-title">Extract entry from the archive</span></p>
</div>
<div class="refsect1 description" id="refsect1-rarentry.extract-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type">bool</span> <span class="methodname"><strong>RarEntry::extract</strong></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$dir</code></span>
[, <span class="methodparam"><span class="type">string</span> <code class="parameter">$filepath</code><span class="initializer"> = ''</span></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">bool</span> <code class="parameter">$extended_data</code><span class="initializer"> = false</span></span>
]]] )</div>
<p class="para rdfs-comment">
<span class="methodname"><strong>RarEntry::extract()</strong></span> extracts the entry's data.
It will create new file in the specified
<em><code class="parameter">dir</code></em> with the name identical to the entry's name,
unless the second argument is specified. See below for more information.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-rarentry.extract-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">dir</code></em></span>
<dd>
<p class="para">
Path to the directory where files should be extracted. This parameter is
considered if and only if <em><code class="parameter">filepath</code></em> is not. If both
parameters are empty an extraction to the current directory will be
attempted.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">filepath</code></em></span>
<dd>
<p class="para">
Path (relative or absolute) containing the directory and filename of the
extracted file. This parameter overrides both the parameter
<em><code class="parameter">dir</code></em> and the original file name.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">password</code></em></span>
<dd>
<p class="para">
The password used to encrypt this entry. If the entry is not encrypted, this value will not be used and can
be omitted. If this parameter is omitted and the entry is encrypted, the password given to
<span class="function"><a href="rararchive.open.html" class="function">rar_open()</a></span>, if any, will be used. If a wrong password is given, either explicitly
or implicitly via <span class="function"><a href="rararchive.open.html" class="function">rar_open()</a></span>, CRC checking will fail and this method will fail and return <strong><code>FALSE</code></strong>.
If no password is given and one is required, this method will fail and return <strong><code>FALSE</code></strong>.
You can check whether an entry is encrypted with <span class="methodname"><a href="rarentry.isencrypted.html" class="methodname">RarEntry::isEncrypted()</a></span>.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">extended_data</code></em></span>
<dd>
<p class="para">
If <strong><code>TRUE</code></strong>, extended information such as NTFS ACLs and Unix owner information will be set in the extract
files, as long as it's present in the archive.
</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-rarentry.extract-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns <strong><code>TRUE</code></strong> on success or <strong><code>FALSE</code></strong> on failure.
</p>
</div>
<div class="refsect1 changelog" id="refsect1-rarentry.extract-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">extended_data</code></em> was added.
</td>
</tr>
<tr>
<td>3.0.0</td>
<td>
Support for RAR archives with repeated entry names is no longer defective.
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-rarentry.extract-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-763">
<p><strong>Example #1 <span class="methodname"><strong>RarEntry::extract()</strong></span> example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$rar_file </span><span style="color: #007700">= </span><span style="color: #0000BB">rar_open</span><span style="color: #007700">(</span><span style="color: #DD0000">'example.rar'</span><span style="color: #007700">) or die(</span><span style="color: #DD0000">"Failed to open Rar archive"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$entry </span><span style="color: #007700">= </span><span style="color: #0000BB">rar_entry_get</span><span style="color: #007700">(</span><span style="color: #0000BB">$rar_file</span><span style="color: #007700">, </span><span style="color: #DD0000">'Dir/file.txt'</span><span style="color: #007700">) or die(</span><span style="color: #DD0000">"Failed to find such entry"</span><span style="color: #007700">);<br /><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: #DD0000">'/dir/to'</span><span style="color: #007700">); </span><span style="color: #FF8000">// create /dir/to/Dir/file.txt<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">false</span><span style="color: #007700">, </span><span style="color: #DD0000">'/dir/to/new_name.txt'</span><span style="color: #007700">); </span><span style="color: #FF8000">// create /dir/to/new_name.txt<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
<div class="example" id="example-764">
<p><strong>Example #2 How to extract all files in 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: #FF8000">/* example by Erik Jenssen aka erix */<br /><br /></span><span style="color: #0000BB">$filename </span><span style="color: #007700">= </span><span style="color: #DD0000">"foobar.rar"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$filepath </span><span style="color: #007700">= </span><span style="color: #DD0000">"/home/foo/bar/"</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">$rar_file </span><span style="color: #007700">= </span><span style="color: #0000BB">rar_open</span><span style="color: #007700">(</span><span style="color: #0000BB">$filepath</span><span style="color: #007700">.</span><span style="color: #0000BB">$filename</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$list </span><span style="color: #007700">= </span><span style="color: #0000BB">rar_list</span><span style="color: #007700">(</span><span style="color: #0000BB">$rar_file</span><span style="color: #007700">);<br />foreach(</span><span style="color: #0000BB">$list </span><span style="color: #007700">as </span><span style="color: #0000BB">$file</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">$entry </span><span style="color: #007700">= </span><span style="color: #0000BB">rar_entry_get</span><span style="color: #007700">(</span><span style="color: #0000BB">$rar_file</span><span style="color: #007700">, </span><span style="color: #0000BB">$file</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: #DD0000">"."</span><span style="color: #007700">); </span><span style="color: #FF8000">// extract to the current dir<br /></span><span style="color: #007700">}<br /></span><span style="color: #0000BB">rar_close</span><span style="color: #007700">(</span><span style="color: #0000BB">$rar_file</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</div>
<div class="refsect1 seealso" id="refsect1-rarentry.extract-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="methodname"><a href="rarentry.getstream.html" class="methodname" rel="rdfs-seeAlso">RarEntry::getStream()</a> - Get file handler for entry</span></li>
<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="class.rarentry.html">RarEntry</a></div>
<div class="next" style="text-align: right; float: right;"><a href="rarentry.getattr.html">RarEntry::getAttr</a></div>
<div class="up"><a href="class.rarentry.html">RarEntry</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
