setup.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<chapter xml:id="wincache.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 &reftitle.setup;

 <section xml:id="wincache.requirements">
  &reftitle.required;
  <para>
   The extension is currently supported only on the following configurations:
  </para>
  <simpara>Windows OS:</simpara>
  <itemizedlist spacing="compact">
   <listitem>
    <simpara>Windows XP SP3 with IIS 5.1 and <link xlink:href="&url.iis.fastcgi.downloads;">FastCGI Extension</link></simpara>
   </listitem>
   <listitem>
    <simpara>Windows Server 2003 with IIS 6.0 and <link xlink:href="&url.iis.fastcgi.downloads;">FastCGI Extension</link></simpara>
   </listitem>
   <listitem>
    <simpara>Windows Vista SP1 with IIS 7.0 and FastCGI Module</simpara>
   </listitem>
   <listitem>
    <simpara>Windows Server 2008 with IIS 7.0 and FastCGI Module</simpara>
   </listitem>
   <listitem>
    <simpara>Windows 7 with IIS 7.5 and FastCGI Module</simpara>
   </listitem>
   <listitem>
    <simpara>Windows Server 2008 R2 with IIS 7.5 and FastCGI Module</simpara>
   </listitem>
  </itemizedlist>
  <simpara>PHP:</simpara>
  <itemizedlist spacing="compact">
   <listitem>
    <simpara>PHP 5.2.X, Non-thread-safe build</simpara>
   </listitem>
   <listitem>
    <simpara>PHP 5.3 X86, Non-thread-safe VC9 build</simpara>
   </listitem>
  </itemizedlist>
  <note>
   <simpara>
    The WinCache Extension can only be used when IIS is configured to run PHP via FastCGI.
   </simpara>
  </note>
 </section>
 <section xml:id="wincache.installation">
  &reftitle.install;
  <para>
   &pecl.moved;
  </para>
  <para>
   &pecl.info;
   <link xlink:href="&url.pecl.package;wincache">&url.pecl.package;wincache</link>.
  </para>
  <para>
   There are two packages for this extension: one package is for PHP versions 5.2.X,
   and the other package is for PHP 5.3.X. Select the package that is appropriate for
   the PHP version being used.
  </para>
  <para>
   To install and enable the extension, follow these steps:
  </para>
  <procedure>
   <step>
    <simpara>
     Unpack the package into some temporary location.
    </simpara>
   </step>
   <step>
    <simpara>
     Copy the <filename>php_wincache.dll</filename> file into the PHP extensions folder.
     Typically this folder is called "ext" and it is located in the same folder with all
     PHP binary files. For example: <filename>C:\Program Files\PHP\ext</filename>.
    </simpara>
   </step>
   <step>
    <simpara>
     Using a text editor, open the php.ini file, which is usually located in the
     same folder where all PHP binary files are. For example:
     <filename>C:\Program Files\PHP\php.ini</filename>.
    </simpara>
   </step>
   <step>
    <simpara>
     Add the following line at the end of the php.ini file:
     <literal>extension = php_wincache.dll</literal>.
    </simpara>
   </step>
   <step>
    <simpara>
     Save and close the <filename>php.ini</filename> file.
    </simpara>
   </step>
   <step>
    <simpara>
     Recycle the IIS Application Pools for PHP to pick up the configuration changes.
     To check that the extension has been enabled, create a file called
     <filename>phpinfo.php</filename> with a PHP code that calls
     <link linkend="function.phpinfo">phpinfo</link> function.
    </simpara>
   </step>
   <step>
    <simpara>
     Save the <filename>phpinfo.php</filename> file in the root folder of a
     IIS web site that uses PHP, then open a browser and make a request to
     http://localhost/phpinfo.php. Search within the returned web page
     for a section called <literal>wincache</literal>. If the extension
     is enabled, then the <link linkend="function.phpinfo">phpinfo</link>
     output will list the configuration settings provided by the WinCache.
    </simpara>
   </step>
  </procedure>
  <note>
   <simpara>
    Do not forget to remove <filename>phpinfo.php</filename> file from the web
    site's root folder after verifying that extension has been enabled.
   </simpara>
  </note>
 </section>
 &reference.wincache.ini;

 <section xml:id="wincache.stats">
  <title>WinCache Statistics Script</title>
  <para>
   The installation package for WinCache includes a PHP script,
   <filename>wincache.php</filename>, that can be used to obtain cache information
   and statistics.
  </para>
  <para>
   If the WinCache extension was installed via the Microsoft Web Platform Installer,
   then this script is located in
   <filename>%SystemDrive%\Program Files\IIS\Windows Cache for PHP\</filename>.
   On a 64-bit version of the Windows Server operating system, the script is located in
   <filename>%SystemDrive%\Program Files (x86)\IIS\Windows Cache for PHP</filename>.
   If the extension was installed manually, then the <filename>wincache.php</filename>
   will be located in the same folder from which the content of the installation package was extracted.
  </para>
  <para>
   To use <filename>wincache.php</filename>, copy it into a root folder of a Web site or
   into any subfolder. To protect the script, open it in any text editor and replace the values for
   <emphasis>USERNAME</emphasis> and <emphasis>PASSWORD</emphasis> constants.
   If any other IIS authentication is enabled on the server, then
   follow the instructions in the comments:
   <example>
    <title>Authentication configuration for <filename>wincache.php</filename></title>
    <programlisting role="php">
<![CDATA[
<?php
/**
 * ======================== CONFIGURATION SETTINGS ==============================
 * If you do not want to use authentication for this page, set USE_AUTHENTICATION to 0.
 * If you use authentication then replace the default password.
 */
define('USE_AUTHENTICATION', 1);
define('USERNAME', 'wincache');
define('PASSWORD', 'wincache');

/**
 * The Basic PHP authentication will work only when IIS is configured to support
 * Anonymous Authentication' and nothing else. If IIS is configured to support/use
 * any other kind of authentication like Basic/Negotiate/Digest etc, this will not work.
 * In that case use the array below to define the names of users in your
 * domain/network/workgroup which you want to grant access to.
 */
$user_allowed = array('DOMAIN\user1', 'DOMAIN\user2', 'DOMAIN\user3');

/**
 * If the array contains string 'all', then all the users authenticated by IIS
 * will have access to the page. Uncomment the below line and comment above line
 * to grant access to all users who gets authenticated by IIS.
 */
/* $user_allowed = array('all'); */

/** ===================== END OF CONFIGURATION SETTINGS ========================== */
?>
]]>
    </programlisting>
   </example>
   <note>
    <simpara>
     Always protect the <filename>wincache.php</filename> script by using either
     the built-in authentication or the server's authentication mechanism.
     Leaving this script unprotected may compromise the security of your
     web application and web server.
    </simpara>
   </note>
  </para>
 </section>
  <section xml:id="wincache.sessionhandler">
  <title>WinCache Session Handler</title>
  <para>
   The WinCache session handler (available since WinCache 1.1.0) can be used to configure PHP to store the session data in shared memory session cache.
   Using shared memory instead of the default file session storage helps improve performance of PHP applications
   that store large amount of data in session objects. Wincache session cache uses file-backed shared memory, which ensures
   that the session data is not lost during recycling of IIS application pools.
  </para>
  <para>
   To configure PHP to use WinCache session handler set the <filename>php.ini</filename> setting
   <link linkend="ini.session.save-handler">session.save_handler</link> to <emphasis>wincache</emphasis>.
   By default the Windows temporary file location is used for storing the
   session data. To change the location of the session file use
   <link linkend="ini.session.save-path">session.save_path</link> directive.
   <example>
    <title>Enabling WinCache session handler</title>
    <programlisting role="php.ini">
<![CDATA[
session.save_handler = wincache
session.save_path = C:\inetpub\temp\session\
]]>
    </programlisting>
   </example>
  </para>
 </section>
 <section xml:id="wincache.reroutes">
  <title>WinCache Functions Reroutes</title>
  <para>
   <emphasis>NOTE:</emphasis> <link linkend="ini.wincache.rerouteini">wincache.rerouteini</link> was removed as of
   WinCache 1.3.7.0.  It has been replaced with automatic function reroutes.  See:
   <link linkend="ini.wincache.reroute_enabled">wincache.reroute_enabled</link>.
  </para>
  <para>
   The WinCache functions reroutes (available since WinCache 1.2.0, removed since WinCache 1.3.7.0) can be used to replace built-in PHP functions with their equivalents
   that are optimized for a particular purpose. WinCache extension includes Windows-optimized implementation of PHP file functions that
   may improve performance of PHP applications in cases when PHP has to access files on network shares. The optimized implementation is
   provided for the following functions:
  </para>
  <itemizedlist spacing="compact">
   <listitem>
    <simpara>
     <link linkend="function.file-exists">file_exists</link>
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <link linkend="function.file-get-contents">file_get_contents</link>
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <link linkend="function.readfile">readfile</link>
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <link linkend="function.is-readable">is_readable</link>
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <link linkend="function.is-writable">is_writable</link>
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <link linkend="function.is-dir">is_dir</link>
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <link linkend="function.realpath">realpath</link>
    </simpara>
   </listitem>
      <listitem>
    <simpara>
     <link linkend="function.filesize">filesize</link>
    </simpara>
   </listitem>
  </itemizedlist>
  <para>
   To configure WinCache to use the functions reroutes use the file <filename>reroute.ini</filename> that is included in
   WinCache installation package. Copy this file into the same directory where <filename>php.ini</filename>
   file is located. After that add the wincache.rerouteini setting in <filename>php.ini</filename>
   and specify an absolute or relative path to the <filename>reroute.ini</filename> file.
   <example>
    <title>Enabling WinCache functions reroutes</title>
    <programlisting role="php.ini">
<![CDATA[
wincache.rerouteini = C:\PHP\reroute.ini
]]>
    </programlisting>
   </example>
  </para>
  <note>
   <simpara>
    If WinCache functions reroutes are enabled it is recommended to increase the WinCache file cache size. This
    can be done by using <link linkend="ini.wincache.fcachesize">wincache.fcachesize</link> setting.
   </simpara>
  </note>
  <para>
   The <filename>reroute.ini</filename> file contains the mappings between the native PHP functions and
   their equivalents in WinCache. Each line in the file defines a mapping by using the following syntax:
  </para>
  <simpara>
   <literal>&lt;PHP function name&gt;:[&lt;number of function parameters&gt;]=&lt;wincache function name&gt;</literal>
  </simpara>
  <para>
   The example of the file is shown below. In this example the calls to PHP function <function>file_get_contents</function>
   will be replaced with calls to <function>wincache_file_get_contents</function> only if the number of parameters passed to
   the function is less than or equals to 2. Specifying the number of parameters is useful when replacement function
   does not handle all the function's parameters.
   <example>
    <title>Reroute.ini file content</title>
    <programlisting role="php.ini">
 <![CDATA[
[FunctionRerouteList]
file_exists=wincache_file_exists
file_get_contents:2=wincache_file_get_contents
readfile:2=wincache_readfile
is_readable=wincache_is_readable
is_writable=wincache_is_writable
is_writeable=wincache_is_writable
is_file=wincache_is_file
is_dir=wincache_is_dir
realpath=wincache_realpath
filesize=wincache_filesize
]]>
    </programlisting>
   </example>
  </para>
 </section>
</chapter>

<!-- 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
-->