<?php
include_once $_SERVER['DOCUMENT_ROOT'] . '/include/shared-manual.inc';
$TOC = array();
$TOC_DEPRECATED = array();
$PARENTS = array();
include_once dirname(__FILE__) ."/toc/phar.using.inc";
$setup = array (
  'home' => 
  array (
    0 => 'index.php',
    1 => 'PHP Manual',
  ),
  'head' => 
  array (
    0 => 'UTF-8',
    1 => 'de',
  ),
  'this' => 
  array (
    0 => 'phar.using.intro.php',
    1 => 'Using Phar Archives: Introduction',
  ),
  'up' => 
  array (
    0 => 'phar.using.php',
    1 => 'Using Phar Archives',
  ),
  'prev' => 
  array (
    0 => 'phar.using.php',
    1 => 'Using Phar Archives',
  ),
  'next' => 
  array (
    0 => 'phar.using.stream.php',
    1 => 'Using Phar Archives: the phar stream wrapper',
  ),
  'alternatives' => 
  array (
  ),
  'source' => 
  array (
    'lang' => 'en',
    'path' => 'reference/phar/using.xml',
  ),
  'history' => 
  array (
  ),
);
$setup["toc"] = $TOC;
$setup["toc_deprecated"] = $TOC_DEPRECATED;
$setup["parents"] = $PARENTS;
manual_setup($setup);

contributors($setup);

?>
<div id="phar.using.intro" class="section">
 <h2 class="title">Using Phar Archives: Introduction</h2>
 <p class="para">
  Phar archives are similar in concept to Java JAR archives, but are tailored
  to the needs and to the flexibility of PHP applications.  A Phar archive is
  used to distribute a complete PHP application or library in a single file. A
  Phar archive application is used exactly like any other PHP application:
 </p>
 <div class="example-contents screen">
  <div class="cdata"><pre>
php coolapplication.phar
  </pre></div>
 </div>
 <p class="para">
  Using a Phar archive library is identical to using any other PHP library:
 </p>
 <p class="para">
  <div class="informalexample">
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000"><span style="color: #0000BB">&lt;?php<br /></span><span style="color: #007700">include </span><span style="color: #DD0000">'coollibrary.phar'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?&gt;</span></span></code></div>
   </div>

  </div>
 </p>
 <p class="para">
  The <code class="literal">phar</code> stream wrapper provides the core of the phar extension, and
  is explained in detail <a href="phar.using.stream.php" class="link">here</a>.
  The phar stream wrapper allows accessing the files within a phar archive using
  PHP&#039;s standard file functions <span class="function"><a href="function.fopen.php" class="function">fopen()</a></span>, <span class="function"><a href="function.opendir.php" class="function">opendir()</a></span>, and
  others that work on regular files.  The <code class="literal">phar</code> stream wrapper supports all
  read/write operations on both files and directories.
 </p>
 <p class="para">
  <div class="informalexample">
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000"><span style="color: #0000BB">&lt;?php<br /></span><span style="color: #007700">include </span><span style="color: #DD0000">'phar://coollibrary.phar/internal/file.php'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">header</span><span style="color: #007700">(</span><span style="color: #DD0000">'Content-type: image/jpeg'</span><span style="color: #007700">);<br /></span><span style="color: #FF8000">// phars can be accessed by full path or by alias<br /></span><span style="color: #007700">echo </span><span style="color: #0000BB">file_get_contents</span><span style="color: #007700">(</span><span style="color: #DD0000">'phar:///fullpath/to/coollibrary.phar/images/wow.jpg'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span></span></code></div>
   </div>

  </div>
 </p>
 <p class="para">
  The <span class="classname"><a href="class.phar.php" class="classname">Phar</a></span> class implements advanced functionality for accessing
  files and for creating phar archives.  The Phar class is explained in detail
  <a href="phar.using.object.php" class="link">here</a>.
 </p>
 <p class="para">
  <div class="informalexample">
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000"><span style="color: #0000BB">&lt;?php<br /></span><span style="color: #007700">try {<br />    </span><span style="color: #FF8000">// open an existing phar<br />    </span><span style="color: #0000BB">$p </span><span style="color: #007700">= new </span><span style="color: #0000BB">Phar</span><span style="color: #007700">(</span><span style="color: #DD0000">'coollibrary.phar'</span><span style="color: #007700">, </span><span style="color: #0000BB">0</span><span style="color: #007700">);<br />    </span><span style="color: #FF8000">// Phar extends SPL's DirectoryIterator class<br />    </span><span style="color: #007700">foreach (new </span><span style="color: #0000BB">RecursiveIteratorIterator</span><span style="color: #007700">(</span><span style="color: #0000BB">$p</span><span style="color: #007700">) as </span><span style="color: #0000BB">$file</span><span style="color: #007700">) {<br />        </span><span style="color: #FF8000">// $file is a PharFileInfo class, and inherits from SplFileInfo<br />        </span><span style="color: #007700">echo </span><span style="color: #0000BB">$file</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">getFileName</span><span style="color: #007700">() . </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br />        echo </span><span style="color: #0000BB">file_get_contents</span><span style="color: #007700">(</span><span style="color: #0000BB">$file</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">getPathName</span><span style="color: #007700">()) . </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">; </span><span style="color: #FF8000">// display contents;<br />    </span><span style="color: #007700">}<br />    if (isset(</span><span style="color: #0000BB">$p</span><span style="color: #007700">[</span><span style="color: #DD0000">'internal/file.php'</span><span style="color: #007700">])) {<br />        </span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$p</span><span style="color: #007700">[</span><span style="color: #DD0000">'internal/file.php'</span><span style="color: #007700">]-&gt;</span><span style="color: #0000BB">getMetadata</span><span style="color: #007700">());<br />    }<br /><br />    </span><span style="color: #FF8000">// create a new phar - phar.readonly must be 0 in php.ini<br />    // phar.readonly is enabled by default for security reasons.<br />    // On production servers, Phars need never be created,<br />    // only executed.<br />    </span><span style="color: #007700">if (</span><span style="color: #0000BB">Phar</span><span style="color: #007700">::</span><span style="color: #0000BB">canWrite</span><span style="color: #007700">()) {<br />        </span><span style="color: #0000BB">$p </span><span style="color: #007700">= new </span><span style="color: #0000BB">Phar</span><span style="color: #007700">(</span><span style="color: #DD0000">'newphar.tar.phar'</span><span style="color: #007700">, </span><span style="color: #0000BB">0</span><span style="color: #007700">, </span><span style="color: #DD0000">'newphar.tar.phar'</span><span style="color: #007700">);<br />        </span><span style="color: #FF8000">// make this a tar-based phar archive, compressed with gzip compression (.tar.gz)<br />        </span><span style="color: #0000BB">$p </span><span style="color: #007700">= </span><span style="color: #0000BB">$p</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">convertToExecutable</span><span style="color: #007700">(</span><span style="color: #0000BB">Phar</span><span style="color: #007700">::</span><span style="color: #0000BB">TAR</span><span style="color: #007700">, </span><span style="color: #0000BB">Phar</span><span style="color: #007700">::</span><span style="color: #0000BB">GZ</span><span style="color: #007700">);<br /><br />        </span><span style="color: #FF8000">// create transaction - nothing is written to newphar.phar<br />        // until stopBuffering() is called, although temporary storage is needed<br />        </span><span style="color: #0000BB">$p</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">startBuffering</span><span style="color: #007700">();<br />        </span><span style="color: #FF8000">// add all files in /path/to/project, saving in the phar with the prefix "project"<br />        </span><span style="color: #0000BB">$p</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">buildFromIterator</span><span style="color: #007700">(new </span><span style="color: #0000BB">RecursiveIteratorIterator</span><span style="color: #007700">(new </span><span style="color: #0000BB">RecursiveDirectoryIterator</span><span style="color: #007700">(</span><span style="color: #DD0000">'/path/to/project'</span><span style="color: #007700">)), </span><span style="color: #DD0000">'/path/to/'</span><span style="color: #007700">);<br /><br />        </span><span style="color: #FF8000">// add a new file via the array access API<br />        </span><span style="color: #0000BB">$p</span><span style="color: #007700">[</span><span style="color: #DD0000">'file1.txt'</span><span style="color: #007700">] = </span><span style="color: #DD0000">'Information'</span><span style="color: #007700">;<br />        </span><span style="color: #0000BB">$fp </span><span style="color: #007700">= </span><span style="color: #0000BB">fopen</span><span style="color: #007700">(</span><span style="color: #DD0000">'hugefile.dat'</span><span style="color: #007700">, </span><span style="color: #DD0000">'rb'</span><span style="color: #007700">);<br />        </span><span style="color: #FF8000">// copy all data from the stream<br />        </span><span style="color: #0000BB">$p</span><span style="color: #007700">[</span><span style="color: #DD0000">'data/hugefile.dat'</span><span style="color: #007700">] = </span><span style="color: #0000BB">$fp</span><span style="color: #007700">;<br /><br />        if (</span><span style="color: #0000BB">Phar</span><span style="color: #007700">::</span><span style="color: #0000BB">canCompress</span><span style="color: #007700">(</span><span style="color: #0000BB">Phar</span><span style="color: #007700">::</span><span style="color: #0000BB">GZ</span><span style="color: #007700">)) {<br />            </span><span style="color: #0000BB">$p</span><span style="color: #007700">[</span><span style="color: #DD0000">'data/hugefile.dat'</span><span style="color: #007700">]-&gt;</span><span style="color: #0000BB">compress</span><span style="color: #007700">(</span><span style="color: #0000BB">Phar</span><span style="color: #007700">::</span><span style="color: #0000BB">GZ</span><span style="color: #007700">);<br />        }<br /><br />        </span><span style="color: #0000BB">$p</span><span style="color: #007700">[</span><span style="color: #DD0000">'images/wow.jpg'</span><span style="color: #007700">] = </span><span style="color: #0000BB">file_get_contents</span><span style="color: #007700">(</span><span style="color: #DD0000">'images/wow.jpg'</span><span style="color: #007700">);<br />        </span><span style="color: #FF8000">// any value can be saved as file-specific meta-data<br />        </span><span style="color: #0000BB">$p</span><span style="color: #007700">[</span><span style="color: #DD0000">'images/wow.jpg'</span><span style="color: #007700">]-&gt;</span><span style="color: #0000BB">setMetadata</span><span style="color: #007700">(array(</span><span style="color: #DD0000">'mime-type' </span><span style="color: #007700">=&gt; </span><span style="color: #DD0000">'image/jpeg'</span><span style="color: #007700">));<br />        </span><span style="color: #0000BB">$p</span><span style="color: #007700">[</span><span style="color: #DD0000">'index.php'</span><span style="color: #007700">] = </span><span style="color: #0000BB">file_get_contents</span><span style="color: #007700">(</span><span style="color: #DD0000">'index.php'</span><span style="color: #007700">);<br />        </span><span style="color: #0000BB">$p</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">setMetadata</span><span style="color: #007700">(array(</span><span style="color: #DD0000">'bootstrap' </span><span style="color: #007700">=&gt; </span><span style="color: #DD0000">'index.php'</span><span style="color: #007700">));<br /><br />        </span><span style="color: #FF8000">// save the phar archive to disk<br />        </span><span style="color: #0000BB">$p</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">stopBuffering</span><span style="color: #007700">();<br />    }<br />} catch (</span><span style="color: #0000BB">Exception $e</span><span style="color: #007700">) {<br />    echo </span><span style="color: #DD0000">'Could not open Phar: '</span><span style="color: #007700">, </span><span style="color: #0000BB">$e</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">?&gt;</span></span></code></div>
   </div>

  </div>
 </p>
 <p class="para">
  In addition, verification of phar file contents can be done using any of the
  supported symmetric hash algorithms (MD5, SHA1, SHA256 and SHA512 if ext/hash is enabled)
  and using asymmetric public/private key signing using OpenSSL.  To
  take advantage of OpenSSL signing, you need to generate a public/private key pair, and
  use the private key to set the signature using
  <span class="function"><a href="phar.setsignaturealgorithm.php" class="function">Phar::setSignatureAlgorithm()</a></span>.  In addition, the public key
  as extracted using this code:
  <div class="example-contents">
   <div class="phpcode"><code><span style="color: #000000"><span style="color: #0000BB">&lt;?php<br />$public </span><span style="color: #007700">= </span><span style="color: #0000BB">openssl_get_publickey</span><span style="color: #007700">(</span><span style="color: #0000BB">file_get_contents</span><span style="color: #007700">(</span><span style="color: #DD0000">'private.pem'</span><span style="color: #007700">));<br /></span><span style="color: #0000BB">$pkey </span><span style="color: #007700">= </span><span style="color: #DD0000">''</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">openssl_pkey_export</span><span style="color: #007700">(</span><span style="color: #0000BB">$public</span><span style="color: #007700">, </span><span style="color: #0000BB">$pkey</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span></span></code></div>
  </div>

  must be saved adjacent to the phar archive it verifies.  If the phar archive
  is saved as <code class="literal">/path/to/my.phar</code>, the public key must be saved
  as <code class="literal">/path/to/my.phar.pubkey</code>, or phar will be unable to verify
  the OpenSSL signature.
 </p>
 <p class="para">
  The <span class="classname"><a href="class.phar.php" class="classname">Phar</a></span> class also provides 3 static methods, <span class="function"><a href="phar.webphar.php" class="function">Phar::webPhar()</a></span>,
  <span class="function"><a href="phar.mungserver.php" class="function">Phar::mungServer()</a></span> and <span class="function"><a href="phar.interceptfilefuncs.php" class="function">Phar::interceptFileFuncs()</a></span> that are crucial
  to packaging up PHP applications designed for usage on regular filesystems and for web-based applications.
  <span class="function"><a href="phar.webphar.php" class="function">Phar::webPhar()</a></span> implements a front controller that routes HTTP calls to the correct
  location within the phar archive.  <span class="function"><a href="phar.mungserver.php" class="function">Phar::mungServer()</a></span> is used to modify the values of
  the <var class="varname"><a href="reserved.variables.server.php" class="classname">$_SERVER</a></var> array to trick applications that process these values.
  <span class="function"><a href="phar.interceptfilefuncs.php" class="function">Phar::interceptFileFuncs()</a></span> instructs Phar to intercept calls to
  <span class="function"><a href="function.fopen.php" class="function">fopen()</a></span>, <span class="function"><a href="function.file-get-contents.php" class="function">file_get_contents()</a></span>, <span class="function"><a href="function.opendir.php" class="function">opendir()</a></span>, and
  all of the stat-based functions (<span class="function"><a href="function.file-exists.php" class="function">file_exists()</a></span>, <span class="function"><a href="function.is-readable.php" class="function">is_readable()</a></span> and so on) and
  route all relative paths to locations within the phar archive.
 </p>
 <p class="para">
  As an example, packaging up a release of the popular phpMyAdmin application for use as a phar archive requires
  only this simple script and then <code class="literal">phpMyAdmin.phar.tar.php</code> can be accessed as a regular file
  from your web server after modifying the user/password:
 </p>
 <p class="para">
  <div class="informalexample">
   <div class="example-contents">
    <div class="phpcode"><code><span style="color: #000000"><span style="color: #0000BB">&lt;?php<br /></span><span style="color: #007700">@</span><span style="color: #0000BB">unlink</span><span style="color: #007700">(</span><span style="color: #DD0000">'phpMyAdmin.phar.tar.php'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">copy</span><span style="color: #007700">(</span><span style="color: #DD0000">'phpMyAdmin-2.11.3-english.tar.gz'</span><span style="color: #007700">, </span><span style="color: #DD0000">'phpMyAdmin.phar.tar.php'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$a </span><span style="color: #007700">= new </span><span style="color: #0000BB">Phar</span><span style="color: #007700">(</span><span style="color: #DD0000">'phpMyAdmin.phar.tar.php'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$a</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">startBuffering</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">$a</span><span style="color: #007700">[</span><span style="color: #DD0000">"phpMyAdmin-2.11.3-english/config.inc.php"</span><span style="color: #007700">] = </span><span style="color: #DD0000">'&lt;?php<br />/* Servers configuration */<br />$i = 0;<br /><br />/* Server localhost (config:root) [1] */<br />$i++;<br />$cfg[\'Servers\'][$i][\'host\'] = \'localhost\';<br />$cfg[\'Servers\'][$i][\'extension\'] = \'mysqli\';<br />$cfg[\'Servers\'][$i][\'connect_type\'] = \'tcp\';<br />$cfg[\'Servers\'][$i][\'compress\'] = false;<br />$cfg[\'Servers\'][$i][\'auth_type\'] = \'config\';<br />$cfg[\'Servers\'][$i][\'user\'] = \'root\';<br />$cfg[\'Servers\'][$i][\'password\'] = \'\';<br /><br /><br />/* End of servers configuration */<br />if (strpos(PHP_OS, \'WIN\') !== false) {<br />    $cfg[\'UploadDir\'] = getcwd();<br />} else {<br />    $cfg[\'UploadDir\'] = \'/tmp/pharphpmyadmin\';<br />    @mkdir(\'/tmp/pharphpmyadmin\');<br />    @chmod(\'/tmp/pharphpmyadmin\', 0777);<br />}'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$a</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">setStub</span><span style="color: #007700">(</span><span style="color: #DD0000">'&lt;?php<br />Phar::interceptFileFuncs();<br />Phar::webPhar("phpMyAdmin.phar", "phpMyAdmin-2.11.3-english/index.php");<br />echo "phpMyAdmin is intended to be executed from a web browser\n";<br />exit -1;<br />__HALT_COMPILER();<br />'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$a</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">stopBuffering</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">?&gt;</span></span></code></div>
   </div>

  </div>
 </p>
</div><?php manual_footer($setup); ?>