<!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>Mount an external path or file to a virtual location within the phar archive</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="phar.mapphar.html">Phar::mapPhar</a></div>
<div class="next" style="text-align: right; float: right;"><a href="phar.mungserver.html">Phar::mungServer</a></div>
<div class="up"><a href="class.phar.html">Phar</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="phar.mount" class="refentry">
<div class="refnamediv">
<h1 class="refname">Phar::mount</h1>
<p class="verinfo">(PHP >= 5.3.0, PECL phar >= 2.0.0)</p><p class="refpurpose"><span class="refname">Phar::mount</span> — <span class="dc-title">Mount an external path or file to a virtual location within the phar archive</span></p>
</div>
<div class="refsect1 description" id="refsect1-phar.mount-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="modifier">final</span> <span class="modifier">public</span> <span class="modifier">static</span> <span class="type"><span class="type void">void</span></span> <span class="methodname"><strong>Phar::mount</strong></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$pharpath</code></span>
, <span class="methodparam"><span class="type">string</span> <code class="parameter">$externalpath</code></span>
)</div>
<p class="para rdfs-comment">
Much like the unix file system concept of mounting external devices to paths within the
directory tree, <span class="function"><strong>Phar::mount()</strong></span> allows referring to external files
and directories as if they were inside of an archive. This allows powerful
abstraction such as referring to external configuration files as if they were
inside the archive.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-phar.mount-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">pharpath</code></em></span>
<dd>
<p class="para">
The internal path within the phar archive to use as the mounted path location.
This must be a relative path within the phar archive, and must not already exist.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">externalpath</code></em></span>
<dd>
<p class="para">
A path or URL to an external file or directory to mount within the phar archive
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-phar.mount-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
No return. <a href="class.pharexception.html" class="classname">PharException</a> is thrown on failure.
</p>
</div>
<div class="refsect1 errors" id="refsect1-phar.mount-errors">
<h3 class="title">Errors/Exceptions</h3>
<p class="para">
Throws <a href="class.pharexception.html" class="classname">PharException</a> if any problems occur mounting the path.
</p>
</div>
<div class="refsect1 examples" id="refsect1-phar.mount-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-689">
<p><strong>Example #1 A <span class="function"><strong>Phar::mount()</strong></span> example</strong></p>
<div class="example-contents"><p>
The following example shows accessing an external configuration file as if it were
a path within a phar archive.
</p></div>
<div class="example-contents"><p>
First, the code inside of a phar archive:
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$configuration </span><span style="color: #007700">= </span><span style="color: #0000BB">simplexml_load_string</span><span style="color: #007700">(</span><span style="color: #0000BB">file_get_contents</span><span style="color: #007700">(<br /> </span><span style="color: #0000BB">Phar</span><span style="color: #007700">::</span><span style="color: #0000BB">running</span><span style="color: #007700">(</span><span style="color: #0000BB">false</span><span style="color: #007700">) . </span><span style="color: #DD0000">'/config.xml'</span><span style="color: #007700">));<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>
Next the external code used to mount the configuration file:
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">// first set up the association between the abstract config.xml<br />// and the actual one on disk<br /></span><span style="color: #0000BB">Phar</span><span style="color: #007700">::</span><span style="color: #0000BB">mount</span><span style="color: #007700">(</span><span style="color: #DD0000">'phar://config.xml'</span><span style="color: #007700">, </span><span style="color: #DD0000">'/home/example/config.xml'</span><span style="color: #007700">);<br /></span><span style="color: #FF8000">// now run the application<br /></span><span style="color: #007700">include </span><span style="color: #DD0000">'/path/to/archive.phar'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>
Another method is to put the mounting code inside the stub of the phar archive.
Here is an example of setting up a default
configuration file if no user configuration is specified:
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">// first set up the association between the abstract config.xml<br />// and the actual one on disk<br /></span><span style="color: #007700">if (</span><span style="color: #0000BB">defined</span><span style="color: #007700">(</span><span style="color: #DD0000">'EXTERNAL_CONFIG'</span><span style="color: #007700">)) {<br /> </span><span style="color: #0000BB">Phar</span><span style="color: #007700">::</span><span style="color: #0000BB">mount</span><span style="color: #007700">(</span><span style="color: #DD0000">'config.xml'</span><span style="color: #007700">, </span><span style="color: #0000BB">EXTERNAL_CONFIG</span><span style="color: #007700">);<br /> if (</span><span style="color: #0000BB">file_exists</span><span style="color: #007700">(</span><span style="color: #0000BB">__DIR__ </span><span style="color: #007700">. </span><span style="color: #DD0000">'/extra_config.xml'</span><span style="color: #007700">)) {<br /> </span><span style="color: #0000BB">Phar</span><span style="color: #007700">::</span><span style="color: #0000BB">mount</span><span style="color: #007700">(</span><span style="color: #DD0000">'extra.xml'</span><span style="color: #007700">, </span><span style="color: #0000BB">__DIR__ </span><span style="color: #007700">. </span><span style="color: #DD0000">'/extra_config.xml'</span><span style="color: #007700">);<br /> }<br />} else {<br /> </span><span style="color: #0000BB">Phar</span><span style="color: #007700">::</span><span style="color: #0000BB">mount</span><span style="color: #007700">(</span><span style="color: #DD0000">'config.xml'</span><span style="color: #007700">, </span><span style="color: #DD0000">'phar://' </span><span style="color: #007700">. </span><span style="color: #0000BB">__FILE__ </span><span style="color: #007700">. </span><span style="color: #DD0000">'/default_config.xml'</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">Phar</span><span style="color: #007700">::</span><span style="color: #0000BB">mount</span><span style="color: #007700">(</span><span style="color: #DD0000">'extra.xml'</span><span style="color: #007700">, </span><span style="color: #DD0000">'phar://' </span><span style="color: #007700">. </span><span style="color: #0000BB">__FILE__ </span><span style="color: #007700">. </span><span style="color: #DD0000">'/default_extra.xml'</span><span style="color: #007700">);<br />}<br /></span><span style="color: #FF8000">// now run the application<br /></span><span style="color: #007700">include </span><span style="color: #DD0000">'phar://' </span><span style="color: #007700">. </span><span style="color: #0000BB">__FILE__ </span><span style="color: #007700">. </span><span style="color: #DD0000">'/index.php'</span><span style="color: #007700">;<br />__HALT_COMPILER();<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>
...and the code externally to load this phar archive:
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />define</span><span style="color: #007700">(</span><span style="color: #DD0000">'EXTERNAL_CONFIG'</span><span style="color: #007700">, </span><span style="color: #DD0000">'/home/example/config.xml'</span><span style="color: #007700">);<br /></span><span style="color: #FF8000">// now run the application<br /></span><span style="color: #007700">include </span><span style="color: #DD0000">'/path/to/archive.phar'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="phar.mapphar.html">Phar::mapPhar</a></div>
<div class="next" style="text-align: right; float: right;"><a href="phar.mungserver.html">Phar::mungServer</a></div>
<div class="up"><a href="class.phar.html">Phar</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
