root/eaccelerator/tags/start/README

eAccelerator for PHP
=====================

What is eAccelerator?
----------------------
eAccelerator is a free open source PHP accelerator, optimizer, encoder and
dynamic content cache for PHP. It increases performance of PHP scripts
by caching them in compiled state, so that the overhead of compiling is almost
completely eliminated. Also it uses some optimizations to speed up execution
of PHP scripts. eAccelerator typically reduces server load and increases
the speed of your PHP code by 1-10 times.

eAccelerator stores compiled PHP scripts in shared memory and executes code
directly from it. It creates locks only for short time, while searching
compiled PHP script in the cache, so one script can be executed simultaneously
by several engines. MM shared memory library (http://www.engelschall.com/sw/mm/)
was used by eAccelerator before version 2.3.13 for management of the shared
memory and locking. Files that can't fit in shared memory are cached on disk only.

eAccelerator was first launched in 2001 to speed up the www.guestbooks4all.com
service. It has been tested with PHP 4.1.0 - 4.3.3 under GNU/Linux and Windows
with Apache 1.3 and 2.0.
Patches for ports to other OSs and PHP versions are welcome.

Since version 2.3.10, eAccelerator contains a PHP encoder and loader.
You can encode PHP scripts using encoder.php in order to distribute them without
sources. Encoded files can be run on any site which runs PHP with eAccelerator
2.3.10 or above. The sources of encoded scripts can't be restored because
they are stored in a compiled form and the encoded version doesn't contain
the source. Of course, some internals of the scripts can be restored with
different reverse engineering tools (disassemblers, debuggers, etc), but it is
not trivial.

Since version 2.3.15, eAccelerator is compatible with Zend Optimizer's
loader. Zend Optimizer must be installed after eAccelerator in php.ini.
If you don't use scripts encoded with Zend Encoder then we do not recommend
you install Zend Optimizer with eAccelerator.

eAccelerator does not work in CGI mode.

Here are some other products that provide the same functionality:

 - Zend Performance Suite (http://www.zend.com/)
 - PHP Accelerator (http://www.php-accelerator.co.uk/)
 - Alternative PHP Cache (http://apc.communityconnect.com/)
 - AfterBurner Cache (http://www.bwcache.bware.it/)


Where is eAccelerator already used?
-----------------------------------
The following you will find a list of sites that use eAccelerator
If you want to be added, please send e-mail to frankalcantara@users.sourceforge.net

 - HomePage Title (http://www.xxx.com)
   homepage description


Download
--------
Latest eAccelerator versions can be downloaded at the sourceforge page:
http://sourceforge.net/projects/eaccelerator/


Requirements
------------
apache 1.3, mod_php 4.1, autoconf, automake, libtool, m4


Compatibility
-------------
This version of the eAccelerator has been successfully tested on PHP
4.1.0-4.3.3 under RedHat Linux 7.0, 7.3, 8.0 and Windows
with Apache 1.3 and 2.0.


Quick install
-------------
Step 1. Compiling eAccelerator

  export PHP_PREFIX="/usr"
  $PHP_PREFIX/bin/phpize
  ./configure --enable-eaccelerator=shared --with-php-config=$PHP_PREFIX/bin/php-config
  make

  You must specify the real prefix where PHP is installed in the "export"
  command. It may be "/usr" "/usr/local", or something else.

Step 2. Installing eAccelerator

  make install

Step 3. Configuring eAccelerator

eAccelerator can be installed both as Zend or PHP extension, so you need
to edit your php.ini file (usually /etc/php.ini).

To install as Zend extension:

  zend_extension="/usr/lib/php4/eaccelerator.so"
  eaccelerator.shm_size="16"
  eaccelerator.cache_dir="/tmp/eaccelerator"
  eaccelerator.enable="1"
  eaccelerator.optimizer="1"
  eaccelerator.check_mtime="1"
  eaccelerator.debug="0"
  eaccelerator.filter=""
  eaccelerator.shm_max="0"
  eaccelerator.shm_ttl="0"
  eaccelerator.shm_prune_period="0"
  eaccelerator.shm_only="0"
  eaccelerator.compress="1"
  eaccelerator.compress_level="9"

  If you use thread safe build of PHP you must use "zend_extension_ts" instead
  of "zend_extension".

To install as PHP extension:

  extension="eaccelerator.so"
  eaccelerator.shm_size="16"
  eaccelerator.cache_dir="/tmp/eaccelerator"
  eaccelerator.enable="1"
  eaccelerator.optimizer="1"
  eaccelerator.check_mtime="1"
  eaccelerator.debug="0"
  eaccelerator.filter=""
  eaccelerator.shm_max="0"
  eaccelerator.shm_ttl="0"
  eaccelerator.shm_prune_period="0"
  eaccelerator.shm_only="0"
  eaccelerator.compress="1"
  eaccelerator.compress_level="9"  

Step 4. Creating cache directory

  mkdir /tmp/eaccelerator
  chmod 0777 /tmp/eaccelerator


Configuration Options
---------------------

eaccelerator.shm_size
    The amount of shared memory (in megabytes) that eAccelerator will use.
    "0" means OS default. Default value is "0".

eaccelerator.cache_dir
    The directory that is used for disk cache. eAccelerator stores precompiled
    code, session data, content and user entries  here. The same data can be
    stored in shared memory also (for more quick access). Default value is
    "/tmp/eaccelerator".

eaccelerator.enable
    Enables or disables eAccelerator. Should be "1" for enabling or
    "0" for disabling. Default value is "1".

eaccelerator.optimizer
    Enables or disables internal peephole optimizer which may speed up code
    execution. Should be "1" for enabling or "0" for disabling.
    Default value is "1".

eaccelerator.debug
    Enables or disables debug logging. Should be "1" for enabling or
    "0" for disabling. Default value is "0".

eaccelerator.check_mtime
    Enables or disables PHP file modification checking. Should be "1"
    for enabling or "0" for disabling. You should set it to "1" if you want
    to recompile PHP files after modification. Default value is "1".

eaccelerator.filter
    Determine which PHP files must be cached. You may specify the number of
    patterns (for example "*.php *.phtml") which specifies to cache or
    not to cache. If pattern starts with the character "!", it means to ignore
    files which are matched by the following pattern. Default value is "" that
    means - all PHP scripts will be cached.

eaccelerator.shm_max
    Disables putting large values into shared memory by "eaccelerator_put()"
    function.
    It indicates the largest allowed size in bytes (10240, 10K, 1M). The "0"
    disables the limit. Default value is "0".

eaccelerator.shm_ttl
    When eaccelerator fails to get shared memory for new script it removes all
    scripts which were not accessed at last "shm_ttl" seconds from shared
    memory. Default value is "0" that means - don't remove any files from
    shared memory.

eaccelerator.shm_prune_period
    When eaccelerator fails to get shared memory for new script it tryes to 
    remove old script if the previous try was made more then "shm_prune_period"
    seconds ago. Default value is "0" that means - don't try to remove any
    files from shared memory.

eaccelerator.shm_only
    Enables or disables caching of compiled scripts on disk. It has no effect
    on session data and content caching. Default value is "0" that means -
    use disk and shared memory for caching.

eaccelerator.compress
    Enables or disables cached content compression. Default value is "1" that
    means enable compression.

eaccelerator.compress_level
    Compression level used for content caching.  Default value is "9" which
    is the maximum value
    
eaccelerator.keys
eaccelerator.sessions
eaccelerator.content
    Determine where keys, session data and content will be cached. The possible
    values are:
    "shm_and_disk" - cache data in shared memory and on disk (default value)
    "shm"          - cache data in shared memory or on disk if shared memory
                     is full or data size greater then "eaccelerator.shm_max"
    "shm_only"     - cache data in shared memory
    "disk_only"    - cache data on disk
    "none"         - don't cache data


eAccelerator API
----------------

eaccelerator_put($key, $value, $ttl=0)
  puts the $value into shard memory for $ttl seconds.

eaccelerator_get($key)
  returns the value from shared memory which was stored by eaccelerator_put() or
  null if it is not exists or was expired.

eaccelerator_rm($key)
  removres the $key from shared memory

eaccelerator_gc()
  removes all expired keys from shared memory

eaccelerator_lock($lock)
  creates a lock with specified name. The lock can be released by function
  eaccelerator_unlock() or automatic on the end of request.
  For Example:
  <?php
    eaccelerator_lock("count");
    eaccelerator_put("count",eaccelerator_get("count")+1));
  ?>

eaccelerator_unlock($lock)
  release lock with specified name

eaccelerator_set_session_handlers()
  install the eaccelerator session handlers.
  Since PHP 4.2.0 you can install eaccelerator session handlers
  in "php.ini" by "session.save_handler=eaccelerator".

eaccelerator_cache_output($key, $eval_code, $ttl=0)
  caches the output of $eval_code in shared memory for $ttl seconds.
  Output can be removed from cache by calling mmcach_rm() with the same $key.
  For Example:
  <?php eaccelerator_cache_output('test', 'echo time(); phpinfo();', 30); ?>

eaccelerator_cache_result($key, $eval_code, $ttl=0)
  caches the result of $eval_code in shared memory for $ttl seconds.
  Result can be removed from cache by calling mmcach_rm() with the same $key.
  For Example:
  <?php eaccelerator_cache_output('test', 'time()." Hello";', 30); ?>

eaccelerator_cache_page($key, $ttl=0)
  caches the full page for $ttl seconds.
  For Example:
  <?php
    eaccelerator_cache_page($_SERVER['PHP_SELF'].'?GET='.serialize($_GET), 30);
    echo time();
    phpinfo();
  ?>

eaccelerator_rm_page($key)
  removes the page which was cached by eaccelerator_cache_page() with the same 
  $key from cache

eaccelerator_encode($filename)
  returns the encoded bytecode of compiled file $filename

eaccelerator_load($code)
  loads script which was encoded by eaccelerator_encode()

WEB interface
-------------
eAccelerator can be managed through web interface script eaccelerator.php.
So you need to put this file on your web site. For security reasons it is
recommended to restrict the usage of this script by your local IP.

Since version 2.3.18 admin interface may be protected by password.
To generate password run the eaccelerator_password.php from command line and
follow the instruction.

  $ php -q eaccelerator_password.php
  Changing password for eAccelerator Web Interface (eaccelerator.php)

  Enter admin name: admin
  New admin password: eaccelerator
  Retype new admin password: eaccelerator

  Add the following lines into your php.ini and restart HTTPD

  eaccelerator.admin.name="admin"
  eaccelerator.admin.password="$1$0ScD9gkb$nOEmFerNMvQ576hELeLrG0"

If you use eaccelerator.php in directory that is password-protected by HTTPD 
then eaccelerator's admin name and password must be the same.


Contact us
----------
To contact us with questions, patches or bugs, please send e-mail to
Frank Alcantara <frankalcantara@users.sourceforge.net>