Windows Cache Extension for PHP 1.3.0

Readme


Table of Contents


Overview

The Windows Cache Extension for PHP is a PHP accelerator that is used to significantly increase the speed of PHP code running on the Windows Operating System. The extension increases PHP performance by:

  1. Caching the contents of PHP script files in shared memory, which helps to reduce the amount of file system I/O operations that is performed by the PHP engine. This is especially important when the PHP scripts are located on a remote UNC file share.
  2. Caching the resolutions of relative file paths to corresponding absolute file paths. This reduces the amount of requests to file system when PHP scripts perform any file operations.
  3. Caching the compiled PHP opcode in shared memory to avoid the overhead of parsing and compiling the PHP source code for every request.
  4. Providing API's for storing application's variables and objects in a shared memory user cache.
  5. Caching the PHP session data by using wincache session handler.

IMPORTANT: The Windows Cache Extension for PHP can only be used with the non-thread-safe builds of PHP.


Installation

There are three packages for this extension: the first package is for PHP versions 5.2.X, the second package is for PHP 5.3.X, and the third is for PHP 5.4.X. You will need to make sure that you use the appropriate package for your version of PHP.

To install and enable the extension, use the following steps:

  1. Unpack the package that is appropriate for the PHP version you are using.
  2. Copy the php_wincache.dll 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:

"C:\Program Files\PHP\ext".

  1. 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:

"C:\Program Files\PHP\php.ini".

  1. Add the following line at the end of the php.ini file:

extension = php_wincache.dll

  1. Save and close the php.ini file.
  2. Recycle your IIS Application Pools for PHP to pick up the configuration changes.

To check that the extension has been enabled, create a file called phpinfo.php with the following PHP code that calls phpinfo() function:

<?php phpinfo(); ?>

Save the phpinfo.php file in the root folder of a IIS web site that uses PHP, then open a browser and make a request to http://yoursitename/phpinfo.php. Search within the returned web page for a section called "wincache". If the extension is enabled, then you should see the configuration settings provided by the extension.

Compatibility Notes

The extension is supported only on the following configurations:

Windows OS:

PHP:

IMPORTANT: The Windows Cache Extension for PHP can only be used when IIS is configured to run PHP via FastCGI.

Configuration settings

The following table lists and explains the configuration settings provided by the Windows Cache Extension for PHP. For more detailed information about the configuration settings refer to WinCache Extension - Runtime Configuration.

Setting

Default

Minimum

Maximum

Changeable

Description

wincache.fcenabled

1 (On)

0 (Off)

1 (On)

PHP_INI_ALL

Enables or disables the file cache functionality

wincache.fcenabledfilter

no value

no value

no value

PHP_INI_SYSTEM

Defines a comma separated list of site-ids for which wincache.fcenabled property value is toggled.

wincache.fcachesize

24

5

85

PHP_INI_SYSTEM

Defines the maximum memory size (in megabytes) that is allocated for the file cache. If the total size of all the cached files exceeds the value specified in this setting, then most stale files will be removed from the file cache.

wincache.fcndetect

1 (On)

0 (Off)

1 (On)

PHP_INI_SYSTEM

Enables or disables the file change notification detection functionality. If file change notification is supported then it will be used to refresh the opcode and file cache entries as soon as the corresponding files are modified on a file system. If file change notification is not supported, for example when using network file shares, then wincache will poll for file changes at regular time intervals specified by wincache.chkinterval.

wincache.internedsize

4

4

32

PHP_INI_SYATEM

Defines the maximum memory size (in megabytes) that is allocated for the per-process interned strings cache.

wincache.maxfilesize

256

10

2048

PHP_INI_SYSTEM

Defines the maximum allowed size (in kilobytes) for a single file to be cached. If a file size exceeds the specified value, the file will not be cached. This setting applies to the file cache only.

wincache.ocenabled

1 (On)

0 (Off)

1 (On)

PHP_INI_ALL

Enables or disables the opcode cache functionality

wincache.ocenabledfilter

no value

no value

no value

PHP_INI_SYSTEM

Defines a comma separated list of site-ids for which wincache.ocenabled property value is toggled.

wincache.ocachesize

96

15

255

PHP_INI_SYSTEM

Defines the maximum memory size (in megabytes) that is allocated for the opcode cache. If the cached opcode size exceeds the specified value, then most stale opcode will be removed from the cache. Note that the opcode cache size must be at least 3 times bigger than file cache size. If that is not the case the opcode cache size will be automatically increased.

wincache.filecount

4096

1024

16384

PHP_INI_SYSTEM

Defines how many files are expected to be cached by the extension, so that appropriate memory size is allocated at the startup time. If the number of files exceeds the specified value, the WinCache will re-allocate more memory as needed.

wincache.chkinterval

30

0, 2

300

PHP_INI_SYSTEM

Defines how often (in seconds) the extension checks for file changes in order to refresh the cache. Setting it to 0 will disable the refreshing of the cache. The file changes will not be reflected in the cache unless the cache entry for that file is removed by scavenger or IIS application pool is recycled or wincache_refresh_if_changed function is called.

wincache.ttlmax

1200

0, 60

7200

PHP_INI_SYSTEM

Defines the maximum time to live (in seconds) for a cached entry without being used. Setting it to 0 will disable scavenger which takes care of removing old entries.

wincache.enablecli

0 (Off)

1 (On)

0 (Off)

PHP_INI_SYSTEM

Defines if caching is enabled when PHP is running in command line (CLI) mode.

wincache.ignorelist

no value

no value

no value

PHP_INI_ALL

Defines a list of files that should not be cached by the extension. The files list is specified by using file names only, separated by the pipe symbol - "|". For example:

wincache.ignorelist = "index.php|misc.php|admin.php"

wincache.namesalt

no value

no value

no value

PHP_INI_SYSTEM

Defines a string that will be used when naming the extension specific objects that are stored in shared memory. This is used to avoid conflicts that may be caused if other applications within an IIS worker process tries to access shared memory.

wincache.ucenabled

0 (Off)

1 (On)

1 (On)

PHP_INI_SYSTEM

Enables or disables the user cache functionality.

wincache.ucachesize

5

85

8

PHP_INI_SYSTEM

Defines the maximum memory size (in megabytes) that is allocated for the user cache. If the total size of variables stored in the user cache exceeds the specified value, then the most stale variables will be removed from the cache.

wincache. reroute_enabled

0 (Off)

0 (Off)

1 (On)

PHP_INI_SYSTEM | PHP_INI_PERDIR

Enables or disables the rerouting of certain file I/O functions through the file cache.

wincache.filemapdir

No value

No value

No value

PHP_INI_SYSTEM

Specifies an absolute path to a directory where WinCache will store the temporary files used for shared memory segments.   This directory must be on the local machine and not on a networked file system.   If the directory is not specified, WinCache will use the Windows System Page File for all shared memory segments.

wincache.internedsize

4

4

32

PHP_INI_SYSTEM

Specifies the size, in MB, of the interned strings cache.

wincache.srwlocks

1 (On)

0 (Off)

1 (On)

PHP_INI_SYSTEM

Enables or disables the use of shared reader/writer locks. Disabling is useful when troubleshooting deadlock conditions in WinCache.

Extension Statistics Functions

The Windows Cache Extension for PHP provides several functions that can be called from a PHP script in order to return extension-specific information about the cache internals. Refer to WinCache Functions for detailed description and API usage examples.

User Cache API

Windows Cache Extension 1.1 provides API's that can be used by PHP applications to store variables and objects in shared memory user cache. Refer to WinCache Functions for detailed description and API usage examples.

WinCache Session Handler

Windows Cache Extension 1.1 includes a PHP session handler that can be used to configure PHP to store the session data in shared memory user cache. Using shared memory instead of default file session storage helps improve performance of PHP applications that store large amount of data in session objects. To configure PHP to use WinCache session handler set the php.ini setting session.save_handler to wincache. By default the Windows temporary file location is used for storing the session data. To change the location of the session file use session.save_path directive.

 
sesion.save_handler = wincache
session.save_path = C:\inetpub\tmp\session\

WinCache Functions Reroutes

The WinCache functions reroutes (available since WinCache 1.3.7) 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:

          file_exists

          file_get_contents

          filesize

          readfile

          is_writable

          is_writeable (alias for is_writable)

          is_readable

          is_file

          is_dir

          realpath

The reroutes are not enabled by default.  To enable them, set the reroute_enabled directive in either the php.ini or the .user.ini.

wincache.reroute_enabled = 1

WinCache ETW Support

Windows Cache Extension 1.3.7.6 provides support for ETW tracing of internal events which are useful for developer debugging.

 

The provider GUID for the WinCache ETW provider is {F7AD0093-D5C3-46B9-BEEA-A9FCEC7E1408}.

 

To register the provider, open an Administrator cmd.exe window, change directories to the location of the Windows Cache files and type the following command:

wevtutil im wincache_etw.man

If you are upgrading, you will first need to unregister the manifest, and re-register the manifest:

wevtutil um wincache_etw.man

wevtutil im wincache_etw.man

To capture ETW traces, you can create a log profile with logman.  The following example assumes the c:\temp directory exists and is writeable:

 

  logman create trace wincache_etw -p "{F7AD0093-D5C3-46B9-BEEA-A9FCEC7E1408}" -o c:\temp\wincache_etw

  logman start wincache_etw

  <...do your repro...>

  logman stop wincache_etw

  tracerpt c:\temp\wincache_etw_<sequence#>.etl -import "%ProgramFiles(x86)\IIS\Windows Cache for PHP\wincache_etw.man"

 

You'll need to copy the wincache_etw.man to the machine where you execute tracerpt.exe, if it is not the same machine as where WinCache was installed.

More Information and Support

For more information use the following resources:


© 2012 Microsoft Corporation.