xref: /PHP-7.3/ext/opcache/README (revision 4b4cd690)
1The Zend OPcache
2================
3
4The Zend OPcache provides faster PHP execution through opcode caching and
5optimization. It improves PHP performance by storing precompiled script
6bytecode in the shared memory. This eliminates the stages of reading code from
7the disk and compiling it on future access. In addition, it applies a few
8bytecode optimization patterns that make code execution faster.
9
10Compatibility
11-------------
12
13This version of Zend OPcache is compatible with PHP 5.2.*, 5.3.*, 5.4.*
14and PHP-5.5 development branch.  PHP 5.2 support may be removed in the future.
15
16Quick Install
17-------------
18
19- Compile
20
21 $PHP_DIR/bin/phpize
22 ./configure \
23      --with-php-config=$PHP_DIR/bin/php-config
24 make
25
26- Install
27
28 make install # this will copy opcache.so into PHP extension directory
29
30- Edit php.ini
31
32 zend_extension=/...full path.../opcache.so
33
34NOTE: In case you are going to use Zend OPcache together with Xdebug or Zend Debugger,
35be sure that the debugger is loaded after OPcache. "php -v" must show the debugger
36after OPcache.
37
38- Restart PHP
39
40Speed Tuning
41-------------
42
43We recommend the following configuration options for best performance
44in a production environment.
45
46opcache.memory_consumption=128
47opcache.interned_strings_buffer=8
48opcache.max_accelerated_files=4000
49opcache.revalidate_freq=60
50opcache.enable_cli=1
51
52You also may add the following, but it may break some applications and
53frameworks. Please, read description of these directives and add them on your
54own risk.
55
56opcache.save_comments=0
57opcache.enable_file_override=1
58
59In some cases you may like to prefer enabling/disabling some features
60to avoid incompatibilities at the cost of some performance degradation.
61
62For development environment we would recommend setting opcache.revalidate_freq
63into 0.
64
65Configuration Directives
66------------------------
67
68opcache.enable (default "1")
69	OPcache On/Off switch. When set to Off, code is not optimized and cached.
70
71opcache.enable_cli (default "0")
72	Enables the OPcache for the CLI version of PHP. It's mostly for testing
73	and debugging.
74
75opcache.memory_consumption (default "64")
76	The OPcache shared memory storage size. The amount of memory for storing
77	precompiled PHP code in Mbytes.
78
79opcache.interned_strings_buffer (default "4")
80	The amount of memory for interned strings in Mbytes.
81
82opcache.max_accelerated_files (default "2000")
83	The maximum number of keys (scripts) in the OPcache hash table.
84	The number is actually the first one in the following set of prime
85	numbers that is bigger than the one supplied: { 223, 463, 983, 1979, 3907,
86	7963, 16229, 32531, 65407, 130987, 262237, 524521, 1048793 }. Only numbers
87	between 200 and 1000000 are allowed.
88
89opcache.max_wasted_percentage (default "5")
90    When the cache fills up this setting decides when to actually reset (dump
91    all entries) it. At the default of 5% it means that if less than 5% of
92    the entries in the now full cache are wasted/orphaned, then you have a good
93    active cache. There is no point emptying a cache full of good entries
94    only to most likely refill it with those same entries. Once more than 5%
95    of the cache consists of wasted entries, the cache will reset in this
96    cache-full scenario. This can be set up to as high as 50%.
97
98opcache.use_cwd (default "1")
99	When this directive is enabled, the OPcache appends the current working
100	directory to the script key, thus eliminating possible collisions between
101	files with the same name (basename). Disabling the directive improves
102	performance, but may break existing applications.
103
104opcache.validate_timestamps (default "1")
105	When disabled, you must reset the OPcache manually or restart the
106	webserver for changes to the filesystem to take effect.
107	The frequency of the check is controlled by the directive
108	"opcache.revalidate_freq".
109
110opcache.validate_permission (default "0")
111	Leads OPcache to check file readability on each access to cached file.
112	This directive should be enabled in shared hosting environment, when few
113	users (PHP-FPM pools) reuse the common OPcache shared memory.
114
115opcache.validate_root (default "0")
116	This directive prevents file name collisions in different "chroot"
117	environments. It should be enabled for sites that may serve requests in
118	different "chroot" environments.
119
120opcache.revalidate_freq (default "2")
121	How often (in seconds) to check file timestamps for changes to the shared
122	memory storage allocation. ("1" means validate once per second, but only
123	once per request. "0" means always validate)
124
125opcache.file_update_protection (default "2")
126	Prevents caching files that are less than this number of seconds old.
127	It protects from caching of incompletely updated files. In case all file
128	updates on your site are atomic, you may increase performance setting it
129	to "0".
130
131opcache.revalidate_path (default "0")
132	Enables or disables file search in include_path optimization
133	If the file search is disabled and a cached file is found that uses
134	the same include_path, the file is not searched again. Thus, if a file
135	with the same name appears somewhere else in include_path, it
136	won't be found. Enable this directive if this optimization has an effect on
137	your applications. The default for this directive is disabled, which means
138	that optimization is active.
139
140opcache.save_comments (default "1")
141	If disabled, all PHPDoc comments are dropped from the code to reduce the
142	size of the optimized code. Disabling "Doc Comments" may break some
143	existing applications and frameworks (e.g. Doctrine, ZF2, PHPUnit)
144
145opcache.enable_file_override (default "0")
146	Allow file existence override (file_exists, etc.) performance feature.
147
148opcache.optimization_level (default "0xffffffff")
149	A bitmask, where each bit enables or disables the appropriate OPcache
150	passes
151
152opcache.dups_fix (default "0")
153	Enable this hack as a workaround for "Cannot redeclare class" errors.
154
155opcache.blacklist_filename
156	The location of the OPcache blacklist file (wildcards allowed).
157	Each OPcache blacklist file is a text file that holds the names of files
158	that should not be accelerated. The file format is to add each filename
159	to a new line. The filename may be a full path or just a file prefix
160	(i.e., /var/www/x  blacklists all the files and directories in /var/www
161	that start with 'x'). Line starting with a ; are ignored (comments).
162	Files are usually triggered by one of the following three reasons:
163	1) Directories that contain auto generated code, like Smarty or ZFW cache.
164	2) Code that does not work well when accelerated, due to some delayed
165	   compile time evaluation.
166	3) Code that triggers an OPcache bug.
167
168opcache.max_file_size (default "0")
169	Allows exclusion of large files from being cached. By default all files
170	are cached.
171
172opcache.consistency_checks (default "0")
173	Check the cache checksum each N requests.
174	The default value of "0" means that the checks are disabled.
175	Because calculating the checksum impairs performance, this directive should
176	be enabled only as part of a debugging process.
177
178opcache.force_restart_timeout (default "180")
179	How long to wait (in seconds) for a scheduled restart to begin if the cache
180	is not being accessed.
181	The OPcache uses this directive to identify a situation where there may
182	be a problem with a process. After this time period has passed, the
183	OPcache assumes that something has happened and starts killing the
184	processes that still hold the locks that are preventing a restart.
185	If the log level is 3 or above, a "killed locker" error is recorded
186	in the Apache logs when this happens.
187
188opcache.error_log
189	OPcache error_log file name. Empty string assumes "stderr".
190
191opcache.log_verbosity_level (default "1")
192	All OPcache errors go to the Web server log.
193	By default, only fatal errors (level 0) or errors (level 1) are logged.
194	You can also enable warnings (level 2), info messages (level 3) or
195	debug messages (level 4).
196
197opcache.preferred_memory_model
198	Preferred Shared Memory back-end. Leave empty and let the system decide.
199
200opcache.protect_memory (default "0")
201	Protect the shared memory from unexpected writing during script execution.
202	Useful for internal debugging only.
203
204opcache.restrict_api (default "")
205	Allows calling OPcache API functions only from PHP scripts which path is
206	started from specified string. The default "" means no restriction.
207
208opcache.mmap_base
209	Mapping base of shared memory segments (for Windows only). All the PHP
210	processes have to map shared memory into the same address space. This
211	directive allows to manually fix the "Unable to reattach to base address"
212	errors.
213
214opcache.lockfile_path (default "/tmp")
215	Absolute path used to store shared lockfiles (for *nix only)
216