php-doc-en/reference/phar/Phar/webPhar.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="phar.webphar" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>Phar::webPhar</refname>
  <refpurpose>Routes a request from a web browser to an internal file within the phar archive</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>final</modifier> <modifier>public</modifier> <modifier>static</modifier> <type>void</type><methodname>Phar::webPhar</methodname>
   <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>alias</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>index</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>fileNotFoundScript</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>mimeTypes</parameter><initializer>[]</initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>callable</type><type>null</type></type><parameter>rewrite</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>Phar::webPhar</function> serves as <function>Phar::mapPhar</function> for 
   web-based phars.  This method parses <varname>$_SERVER['REQUEST_URI']</varname> and 
   routes a request from a web browser to an internal file within the phar archive.  
   It simulates a web server, routing requests to the correct file, echoing the correct 
   headers and parsing PHP files as needed.  Combined with <function>Phar::mungServer</function> 
   and <function>Phar::interceptFileFuncs</function>, any web application can be used 
   unmodified from a phar archive.
  </para>
  <para>
   <function>Phar::webPhar</function> should only be
   called from the stub of a phar archive (see <link linkend="phar.fileformat.stub">here</link>
   for more information on what a stub is).
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>alias</parameter></term>
     <listitem>
      <para>
       The alias that can be used in <literal>phar://</literal> URLs to
       refer to this archive, rather than its full path.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>index</parameter></term>
     <listitem>
      <para>
       The location within the phar of the directory index.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>fileNotFoundScript</parameter></term>
     <listitem>
      <para>
       The location of the script to run when a file is not found.  This
       script should output the proper HTTP 404 headers.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>mimeTypes</parameter></term>
     <listitem>
      <para>
       An array mapping additional file extensions to MIME type.
       If the default mapping is sufficient, pass an empty array.
       By default, these extensions are mapped to these MIME types:
       <programlisting role="php">
        <![CDATA[
<?php
$mimes = array(
    'phps' => Phar::PHPS, // pass to highlight_file()
    'c' => 'text/plain',
    'cc' => 'text/plain',
    'cpp' => 'text/plain',
    'c++' => 'text/plain',
    'dtd' => 'text/plain',
    'h' => 'text/plain',
    'log' => 'text/plain',
    'rng' => 'text/plain',
    'txt' => 'text/plain',
    'xsd' => 'text/plain',
    'php' => Phar::PHP, // parse as PHP
    'inc' => Phar::PHP, // parse as PHP
    'avi' => 'video/avi',
    'bmp' => 'image/bmp',
    'css' => 'text/css',
    'gif' => 'image/gif',
    'htm' => 'text/html',
    'html' => 'text/html',
    'htmls' => 'text/html',
    'ico' => 'image/x-ico',
    'jpe' => 'image/jpeg',
    'jpg' => 'image/jpeg',
    'jpeg' => 'image/jpeg',
    'js' => 'application/x-javascript',
    'midi' => 'audio/midi',
    'mid' => 'audio/midi',
    'mod' => 'audio/mod',
    'mov' => 'movie/quicktime',
    'mp3' => 'audio/mp3',
    'mpg' => 'video/mpeg',
    'mpeg' => 'video/mpeg',
    'pdf' => 'application/pdf',
    'png' => 'image/png',
    'swf' => 'application/shockwave-flash',
    'tif' => 'image/tiff',
    'tiff' => 'image/tiff',
    'wav' => 'audio/wav',
    'xbm' => 'image/xbm',
    'xml' => 'text/xml',
);
?>
        ]]>
       </programlisting>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>rewrite</parameter></term>
     <listitem>
      <para>
       The rewrites function is passed a string as its only parameter and must return a <type>string</type> or &false;.
      </para>
      <para>
       If you are using fast-cgi or cgi then the parameter passed to the function is the value of the 
       <varname>$_SERVER['PATH_INFO']</varname> variable. Otherwise, the parameter passed to the function is the value
       of the <varname>$_SERVER['REQUEST_URI']</varname> variable.
      </para>
      <para>
       If a string is returned it is used as the internal file path. If &false; is returned then webPhar() will
       send a HTTP 403 Denied Code.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>

 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.void;
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Throws <classname>PharException</classname> when unable to open the internal
   file to output, or if
   called from a non-stub.  If an invalid array value is passed into
   <parameter>mimeTypes</parameter> or an invalid callback is passed into <parameter>rewrite</parameter>, then
   <classname>UnexpectedValueException</classname> is thrown.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.0.0</entry>
      <entry>
       <parameter>fileNotFoundScript</parameter>, <parameter>mimeTypes</parameter>
       and <parameter>rewrite</parameter> are nullable now.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>A <function>Phar::webPhar</function> example</title>
    <para>
     With the example below, the created phar will display <literal>Hello World</literal>
     if one browses to <literal>/myphar.phar/index.php</literal> or to
     <literal>/myphar.phar</literal>, and will display the source of
     <literal>index.phps</literal> if one browses to <literal>/myphar.phar/index.phps</literal>.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// creating the phar archive:
try {
    $phar = new Phar('myphar.phar');
    $phar['index.php'] = '<?php echo "Hello World"; ?>';
    $phar['index.phps'] = '<?php echo "Hello World"; ?>';
    $phar->setStub('<?php
Phar::webPhar();
__HALT_COMPILER(); ?>');
} catch (Exception $e) {
    // handle error here
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>Phar::mungServer</function></member>
    <member><function>Phar::interceptFileFuncs</function></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->