****************************************************************************** Installation Notes for PHPA Release 1.3.4r1 ****************************************************************************** QUICK INSTALL ------------- 1. Add the following line to your php.ini file, e.g. near the extensions section. Set the correct path to where you installed the accelerator library. /usr/local/lib is a typical directory to use. ; PHP Accelerator extension zend_extension="/path/to/php_accelerator_1.3.4r1.so" Note that the Accelerator is not a module, and you must use the 'zend_extension' keyword in the php.ini file and not 'extension'. 2. The dbg.so debugger module is not compatible with PHPA, so check your php.ini and disable the debugger if you use it on your system. 3. Restart your web server. 4. If PHPA is installed it creates and sets a key in the $GLOBALS array called _PHPA. Create and execute a script such as the following to dump the $_PHPA global. If PHPA is installed then there should be output, and if enabled, you should see output similar to the following: array(3) { ["ENABLED"]=> bool(true) ["iVERSION"]=> int(10303) ["VERSION"]=> string(5) "1.3.4r1" If PHPA was installed but not enabled then the value of the ENABLED key would be false. Check the apache error log for indications of the problem. If there is no output then PHPA is probably not installed correctly, and so was not loaded by PHP. Run a script calling phpinfo() to check this. If installed you should see text similar to the following: This program makes use of the Zend scripting language engine: Zend Engine v1.3.0, Copyright (c) 1998-2002 Zend Technologies with the ionCube PHP Accelerator v1.3.4r1, Copyright (c) 2001-2003, by Nick Lindridge If this text is not present then PHPA wasn't installed. This could be because the wrong php.ini file was edited (check the filename from the phpinfo() output), because the path name was wrong, or because file permissions prevented PHP from loading it, etc. The apache error log may contain an error message that helps in diagnosis. 5. If you haven't succeeded to successfully install PHPA, please email support@phpa.co.uk for help in diagnosing the installation or configuration problem. 6. Read the CONFIGURATION notes about configuration options, and set any additional entries in the php.ini file or apache configuration files having first had PHPA running. In particular you may wish to resize the cache. INSTALLING WITH THE IONCUBE LOADER ---------------------------------- The ionCube PHP Accelerator may be installed with the ionCube Loader, although the current version of PHPA will not cache encoded files. If installing both, the loader must be installed first. e.g. zend_extension = /usr/local/lib/ioncube_loader_1.0.4r2.so zend_extension = /usr/local/lib/php_accelerator_1.3.4r1.so MORE DETAILED INFORMATION ------------------------- Having untarred the release you should have this INSTALL file, release notes, configuration information, and the accelerator library 'php_accelerator_1.3.4r1.so'. You can install the library wherever you wish. Editing the php.ini file ------------------------ If you're unsure where the php.ini file is, or which one your server is using, run a script that calls phpinfo() and the output should include the location of your php.ini file. At runtime ---------- When running, the Accelerator creates files beginning with 'phpa_' in the file cache directory, which by default is /tmp. One file is created per source file that has been read unless the accelerator is disabled for a particular file. You can delete these at any time and they will be recreated for each source file subsequently accessed. The Accelerator performs automatic 'garbage collection', and deletes any cache files that it hasn't seen accessed for more than a specified period. If you are timing your scripts, you may observe that the time taken to load a given script will decrease during the first few page accesses. This is while the accelerator caches the files on disc and in shared memory. After the first few page loads then performance should settle. Performance Notes ----------------- Normally the Accelerator will never degrade your system performance, however two situations in particular may affect performance - very frequently changed pages and an undersized cache. If your application very frequently generates or modified pages, then each time these are hit they will be optimised and recached, and this overhead may degrade performance a little. The Accelerator allows files to be excluded from the shared memory cache, or even ignored by the Accelerator entirely, and taking advantage of this feature for any frequently changing files is recommended to maximise performance. However this is not an issue for most sites. Setting the shared memory cache size ------------------------------------ This defaults to 8MB, but can be set to any value in 1MB increments up to the limit for a single shared memory segment (32MB is common). Entries in the shm cache will be removed automatically if they haven't been accessed in a while (similar to the garbage collection of cache files), and also if there is no space available when a new script needs to be stored. If the cache is too small, then this second case may occur often. After a while run 'phpa_cache_admin -mv' to see what the memory usage is like. You must run this as root or as the same owner as the webserver processes, and PHPA must be running at the time. You should see output similar to the following: shm size 8.0MB bytes mempool size 8.0MB mempool bytes allocated 947.4KB mempool max bytes allocated 961.8KB mempool bytes free 7.0MB mempool overhead 42.2KB cache enabled This is saying that the shared memory is 8MB, that 947KBytes is allocated now, and that the maximum ever allocated was nearly 962KBytes. From this information you might decide to reduce or increase the size of the cache. If the maximum ever allocated is nearly the same as the cache size then you should probably increase the size. 2MB more than the maximum used should be a comfortable setting, but remember that any new scripts may further increase the memory usage. Getting Support --------------- If you haven't already, please join the PHPA forum to keep up to date with new releases. You can do this from http://www.php-accelerator.co.uk/forum.php This is an announcements only forum, and very low volume, carrying just information that existing or potential PHPA users should be aware of. A web forum is also available at http://phpa.phorum.org. Official support may be obtained by emailing support@phpa.co.uk Bug reporting ------------- If you suspect a problem or system incompatibility with the Accelerator, please report details to bugs@php-accelerator.co.uk (or bugs@phpa.co.uk) with as much information as possible relating to the problem. Please try to reproduce the problem, and a test case is always the most ideal. Error Logging ------------- Any errors will appear in the Apache error_log file, and it's recommended to check this to ensure that the Accelerator is starting and activating successfully, and also in the event that any unexpected behaviour occurs. If Apache crashes for any reason then in rare cases it's possible that the Accelerator may be in a state that prevent Apache from serving pages. In this case the shared memory cache must be removed and the server restarted. When phpa.shm_release_at_exit is set, which is the default, then restarting the server also reset the shm cache and so a problem is unlikely. If you're completely stuck, follow the procedure at http://www.php-accelerator.co.uk/server_hang.php -- Copyright (c) 2002-2003, ionCube Ltd., 26 January 2003 --