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

<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[
/**
 * ======================== 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">
<![CDATA[
session.save_handler = wincache
session.save_path = C:\inetpub\temp\session\
]]>
    </programlisting>
   </example>
  </para>
 </section>
 <section xml:id="wincache.resources">
  &reftitle.resources;
  &no.resource;
 </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
-->