php-src/ext/opcache/README

The Zend Optimizer+
===================

The Zend Optimizer+ provides faster PHP execution through opcode caching and
optimization. It improves PHP performance by storing precompiled script
bytecode in the shared memory. This eliminates the stages of reading code from
the disk and compiling it on future access. In addition, it applies a few
bytecode optimization patterns that make code execution faster.

Compatibility
-------------

This version of Zend Optimizer+ is compatible with PHP 5.2.*, 5.3.*, 5.4.*
and PHP-5.5 development branch.  PHP 5.2 support may be removed in the future.

Quick Install
-------------

- Compile

 $PHP_DIR/bin/phpize
 ./configure \
      --with-php-config=$PHP_DIR/bin/php-config
 make

- Install

 make install # this will copy opcache.so into PHP extension directory

- Edit php.ini

 zend_extension=/...full path.../opcache.so

NOTE: In case you are going to use Zend Optimizer+ together with Xdebug,
be sure that Xdebug is loaded after Optimizer+. "php -v" must show Xdebug
after Optimizer+.

- Restart PHP

Speed Tuning
-------------

We recommend the following configuration options for best performance.

opcache.memory_consumption=128
opcache.interned_strings_buffer=8
opcache.max_accelerated_files=4000
opcache.revalidate_freq=60
opcache.fast_shutdown=1
opcache.enable_cli=1

You also may add the following, but it may break some applications and
frameworks. Please, read description of these directives and add them on your
own risk.

opcache.save_comments=0
opcache.enable_file_override=1

In some cases you may like to prefer enabling/disabling some features
to avoid incompatibilities at the cost of some performance degradation.

Configuration Directives
------------------------

opcache.enable (default "1")
	Optimizer+ On/Off switch. When set to Off, code is not optimized.

opcache.memory_consumption (default "64")
	The Optimizer+ shared memory storage size. The amount of memory for storing
	precompiled PHP code in Mbytes.

opcache.interned_strings_buffer (default "4")
	The amount of memory for interned strings in Mbytes.

opcache.max_accelerated_files (default "2000")
	The maximum number of keys (scripts) in the Optimizer+ hash table.
	The number is actually the first one in the following set of prime
	numbers that is bigger than the one supplied: { 223, 463, 983, 1979, 3907,
	7963, 16229, 32531, 65407, 130987 }. Only numbers between 200 and 100000
	are allowed.

opcache.max_wasted_percentage (default "5")
	The maximum percentage of "wasted" memory until a restart is scheduled.

opcache.use_cwd (default "1")
	When this directive is enabled, the Optimizer+ appends the current working
	directory to the script key, thus eliminating possible collisions between
	files with the same name (basename). Disabling the directive improves
	performance, but may break existing applications.

opcache.validate_timestamps (default "1")
	When disabled, you must reset the Optimizer+ manually or restart the
	webserver for changes to the filesystem to take effect.
	The frequency of the check is controlled by the directive
	"opcache.revalidate_freq".

opcache.revalidate_freq (default "2")
	How often (in seconds) to check file timestamps for changes to the shared
	memory storage allocation. ("1" means validate once per second, but only
	once per request. "0" means always validate)

opcache.revalidate_path (default "0")
	Enables or disables file search in include_path optimization
	If the file search is disabled and a cached file is found that uses
	the same include_path, the file is not searched again. Thus, if a file
	with the same name appears somewhere else in include_path, it
	won't be found. Enable this directive if this optimization has an effect on
	your applications. The default for this directive is disabled, which means
	that optimization is active.

opcache.save_comments (default "1")
	If disabled, all PHPDoc comments are dropped from the code to reduce the
	size of the optimized code. Disabling "Doc Comments" may break some
	existing applications and frameworks (e.g. Doctrine, ZF2, PHPUnit)

opcache.load_comments (default "1")
	If disabled, PHPDoc comments are not loaded from SHM, so "Doc Comments"
	may be always stored (save_comments=1), but not loaded by applications
	that don't need them anyway.

opcache.fast_shutdown (default "0")
	If enabled, a fast shutdown sequence is used for the accelerated code
	The fast shutdown sequence doesn't free each allocated block, but lets
	the Zend Engine Memory Manager do the work.

opcache.enable_file_override (default "0")
	Allow file existence override (file_exists, etc.) performance feature.

opcache.optimization_level (default "0xffffffff")
	A bitmask, where each bit enables or disables the appropriate Optimizer+
	passes

opcache.inherited_hack (default "1")
	Enable this hack as a workaround for "can't redeclare class" errors.
	The Optimizer+ stores the places where DECLARE_CLASS opcodes use
	inheritance (These are the only opcodes that can be executed by PHP,
	but which may not be executed because the parent class is missing due to
	optimization). When the file is loaded, Optimizer+ tries to bind the
	inherited classes by using the current environment. The problem with this
	scenario is that, while the DECLARE_CLASS opcode may not be needed for the
	current script, if the script requires that the opcode at least be defined,
	it may not run. The default for this directive is disabled, which means
	that optimization is active. In php-5.3 and above this hack is not needed
	anymore and this setting has no effect.

opcache.dups_fix (default "0")
	Enable this hack as a workaround for "Cannot redeclare class" errors.

opcache.blacklist_filename
	The location of the Optimizer+ blacklist file.
	The Optimizer+ blacklist file is a text file that holds the names of files
	that should not be accelerated. The file format is to add each filename
	to a new line. The filename may be a full path or just a file prefix
	(i.e., /var/www/x  blacklists all the files and directories in /var/www
	that start with 'x'). Files are usually triggered by one of the following
	three reasons:
	1) Directories that contain auto generated code, like Smarty or ZFW cache.
	2) Code that does not work well when accelerated, due to some delayed
	   compile time evaluation.
	3) Code that triggers an Optimizer+ bug.

opcache.max_file_size (default "0")
	Allows exclusion of large files from being cached. By default all files
	are cached.

opcache.consistency_checks (default "0")
	Check the cache checksum each N requests.
	The default value of "0" means that the checks are disabled.
	Because calculating the checksum impairs performance, this directive should
	be enabled only as part of a debugging process.

opcache.force_restart_timeout (default "180")
	How long to wait (in seconds) for a scheduled restart to begin if the cache
	is not being accessed.
	The Optimizer+ uses this directive to identify a situation where there may
	be a problem with a process. After this time period has passed, the
	Optimizer+ assumes that something has happened and starts killing the
	processes that still hold the locks that are preventing a restart.
	If the log level is 3 or above, a "killed locker" error is recorded
	in the Apache logs when this happens.

opcache.error_log
	Optimizer+ error_log file name. Empty string assumes "stderr".

opcache.log_verbosity_level (default "1")
	All Optimizer+ errors go to the Web server log.
	By default, only fatal errors (level 0) or errors (level 1) are logged.
	You can also enable warnings (level 2), info messages (level 3) or
	debug messages (level 4).

opcache.preferred_memory_model
	Preferred Shared Memory back-end. Leave empty and let the system decide.

opcache.protect_memory (default "0")
	Protect the shared memory from unexpected writing during script execution.
	Useful for internal debugging only.

opcache.mmap_base
	Mapping base of shared memory segments (for Windows only). All the PHP
	processes have to map shared memory into the same address space. This
	directive allows to manually fix the "Unable to reattach to base address"
	errors.