documentation/manual/en/module_specs/Zend_Cache-Backends.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.cache.backends">
   4     <title>Zend_Cache Backends</title>
   5
   6     <para>
   7         There are two kinds of backends: standard ones and extended ones. Of course, extended
   8         backends offer more features.
   9     </para>
  10
  11     <sect2 id="zend.cache.backends.file">
  12         <title>Zend_Cache_Backend_File</title>
  13
  14         <para>
  15             This (extended) backends stores cache records into files (in a chosen directory).
  16         </para>
  17
  18         <para>
  19             Available options are :
  20         </para>
  21
  22         <table id="zend.cache.backends.file.table">
  23             <title>File Backend Options</title>
  24
  25             <tgroup cols="4">
  26                 <thead>
  27                     <row>
  28                         <entry>Option</entry>
  29                         <entry>Data Type</entry>
  30                         <entry>Default Value</entry>
  31                         <entry>Description</entry>
  32                     </row>
  33                 </thead>
  34
  35                 <tbody>
  36                     <row>
  37                         <entry><emphasis>cache_dir</emphasis></entry>
  38                         <entry><type>String</type></entry>
  39                         <entry>'<filename>/tmp/</filename>'</entry>
  40                         <entry>Directory where to store cache files</entry>
  41                     </row>
  42
  43                     <row>
  44                         <entry><emphasis>file_locking</emphasis></entry>
  45                         <entry><type>Boolean</type></entry>
  46                         <entry><constant>TRUE</constant></entry>
  47
  48                         <entry>
  49                             Enable or disable file_locking : Can avoid cache corruption under
  50                             bad circumstances but it doesn't help on multithread webservers
  51                             or on <acronym>NFS</acronym> filesystems...
  52                         </entry>
  53                     </row>
  54
  55                     <row>
  56                         <entry><emphasis>read_control</emphasis></entry>
  57                         <entry><type>Boolean</type></entry>
  58                         <entry><constant>TRUE</constant></entry>
  59
  60                         <entry>
  61                             Enable / disable read control : if enabled, a control key is
  62                             embedded in the cache file and this key is compared with the
  63                             one calculated after the reading.
  64                         </entry>
  65                     </row>
  66
  67                     <row>
  68                         <entry><emphasis>read_control_type</emphasis></entry>
  69                         <entry><type>String</type></entry>
  70                         <entry>'crc32'</entry>
  71
  72                         <entry>
  73                             Type of read control (only if read control is enabled). Available values
  74                             are : 'md5' (best but slowest), 'crc32' (lightly less safe but faster,
  75                             better choice), 'adler32' (new choice, faster than crc32),
  76                             'strlen' for a length only test (fastest).
  77                         </entry>
  78                     </row>
  79
  80                     <row>
  81                         <entry><emphasis>hashed_directory_level</emphasis></entry>
  82                         <entry><type>Integer</type></entry>
  83                         <entry>0</entry>
  84
  85                         <entry>
  86                             Hashed directory structure level : 0 means "no hashed directory
  87                             structure", 1 means "one level of directory", 2 means "two levels"...
  88                             This option can speed up the cache only when you have many thousands of
  89                             cache files. Only specific benchs can help you to choose the perfect
  90                             value for you. Maybe, 1 or 2 is a good start.
  91                         </entry>
  92                     </row>
  93
  94                     <row>
  95                         <entry><emphasis>hashed_directory_umask</emphasis></entry>
  96                         <entry><type>Integer</type></entry>
  97                         <entry>0700</entry>
  98                         <entry>Umask for the hashed directory structure</entry>
  99                     </row>
 100
 101                     <row>
 102                         <entry><emphasis>file_name_prefix</emphasis></entry>
 103                         <entry><type>String</type></entry>
 104                         <entry>'zend_cache'</entry>
 105
 106                         <entry>
 107                             prefix for cache files ; be really careful with this option because
 108                             a too generic value in a system cache dir
 109                             (like <filename>/tmp</filename>) can cause disasters when cleaning
 110                             the cache
 111                         </entry>
 112                     </row>
 113
 114                     <row>
 115                         <entry><emphasis>cache_file_umask</emphasis></entry>
 116                         <entry><type>Integer</type></entry>
 117                         <entry>0700</entry>
 118                         <entry>umask for cache files</entry>
 119                     </row>
 120
 121                     <row>
 122                         <entry><emphasis>metatadatas_array_max_size</emphasis></entry>
 123                         <entry><type>Integer</type></entry>
 124                         <entry>100</entry>
 125
 126                         <entry>
 127                             internal max size for the metadatas array (don't change this value
 128                             unless you know what you are doing)
 129                         </entry>
 130                     </row>
 131                 </tbody>
 132             </tgroup>
 133         </table>
 134     </sect2>
 135
 136     <sect2 id="zend.cache.backends.sqlite">
 137         <title>Zend_Cache_Backend_Sqlite</title>
 138
 139         <para>
 140             This (extended) backends stores cache records into a SQLite database.
 141         </para>
 142
 143         <para>
 144             Available options are :
 145         </para>
 146
 147         <table id="zend.cache.backends.sqlite.table">
 148             <title>Sqlite Backend Options</title>
 149
 150             <tgroup cols="4">
 151                 <thead>
 152                     <row>
 153                         <entry>Option</entry>
 154                         <entry>Data Type</entry>
 155                         <entry>Default Value</entry>
 156                         <entry>Description</entry>
 157                     </row>
 158                 </thead>
 159
 160                 <tbody>
 161                     <row>
 162                         <entry><emphasis>cache_db_complete_path (mandatory)</emphasis></entry>
 163                         <entry><type>String</type></entry>
 164                         <entry><constant>NULL</constant></entry>
 165
 166                         <entry>
 167                             The complete path (filename included) of the SQLite database
 168                         </entry>
 169                     </row>
 170
 171                     <row>
 172                         <entry><emphasis>automatic_vacuum_factor</emphasis></entry>
 173                         <entry><type>Integer</type></entry>
 174                         <entry>10</entry>
 175
 176                         <entry>
 177                             Disable / Tune the automatic vacuum process. The automatic vacuum
 178                             process defragment the database file (and make it smaller) when a
 179                             <methodname>clean()</methodname> or <methodname>delete()</methodname>
 180                             is called: 0 means no automatic vacuum ; 1 means systematic vacuum
 181                             (when <methodname>delete()</methodname> or
 182                             <methodname>clean()</methodname> methods are called) ; x (integer) >
 183                             1 => automatic vacuum randomly 1 times on x
 184                             <methodname>clean()</methodname> or
 185                             <methodname>delete()</methodname>.
 186                         </entry>
 187                     </row>
 188                 </tbody>
 189             </tgroup>
 190         </table>
 191     </sect2>
 192
 193     <sect2 id="zend.cache.backends.memcached">
 194         <title>Zend_Cache_Backend_Memcached</title>
 195
 196         <para>
 197             This (extended) backends stores cache records into a memcached server. <ulink
 198                 url="http://www.danga.com/memcached/">memcached</ulink> is a high-performance,
 199             distributed memory object caching system. To use this backend, you need a memcached
 200             daemon and <ulink url="http://pecl.php.net/package/memcache">the memcache
 201                 <acronym>PECL</acronym> extension</ulink>.
 202         </para>
 203
 204         <para>
 205             Be careful : with this backend, "tags" are not supported for the moment as
 206             the "doNotTestCacheValidity=true" argument.
 207         </para>
 208
 209         <para>
 210             Available options are :
 211         </para>
 212
 213         <table id="zend.cache.backends.memcached.table">
 214             <title>Memcached Backend Options</title>
 215
 216             <tgroup cols="4">
 217                 <thead>
 218                     <row>
 219                         <entry>Option</entry>
 220                         <entry>Data Type</entry>
 221                         <entry>Default Value</entry>
 222                         <entry>Description</entry>
 223                     </row>
 224                 </thead>
 225
 226                 <tbody>
 227                     <row>
 228                         <entry><emphasis>servers</emphasis></entry>
 229                         <entry><type>Array</type></entry>
 230
 231                         <entry>
 232                             <command>array(array('host' => 'localhost', 'port' => 11211,
 233                                 'persistent' => true, 'weight' => 1, 'timeout' => 5,
 234                                 'retry_interval' => 15, 'status' => true,
 235                                 'failure_callback' => '' ))</command>
 236                         </entry>
 237
 238                         <entry>
 239                             An array of memcached servers ; each memcached server is described by
 240                             an associative array : 'host' => (string) : the name of the memcached
 241                             server, 'port' => (int) : the port of the memcached server,
 242                             'persistent' => (bool) : use or not persistent connections to this
 243                             memcached server 'weight' => (int) :the weight of the memcached
 244                             server, 'timeout' => (int) :the time out of the memcached server,
 245                             'retry_interval' => (int) :the retry interval of the memcached server,
 246                             'status' => (bool) :the status of the memcached server,
 247                             'failure_callback' => (callback) : the failure_callback of the
 248                             memcached server
 249                         </entry>
 250                     </row>
 251
 252                     <row>
 253                         <entry><emphasis>compression</emphasis></entry>
 254                         <entry><type>Boolean</type></entry>
 255                         <entry><constant>FALSE</constant></entry>
 256
 257                         <entry>
 258                             <constant>TRUE</constant> if you want to use on-the-fly compression
 259                         </entry>
 260                     </row>
 261
 262                     <row>
 263                         <entry><emphasis>compatibility</emphasis></entry>
 264                         <entry><type>Boolean</type></entry>
 265                         <entry><constant>FALSE</constant></entry>
 266
 267                         <entry>
 268                             <constant>TRUE</constant> if you want to use this compatibility mode
 269                             with old memcache servers or extensions
 270                         </entry>
 271                     </row>
 272                 </tbody>
 273             </tgroup>
 274         </table>
 275     </sect2>
 276
 277     <sect2 id="zend.cache.backends.apc">
 278         <title>Zend_Cache_Backend_Apc</title>
 279
 280         <para>
 281             This (extended) backends stores cache records in shared memory through
 282             the <ulink url="http://pecl.php.net/package/APC">APC</ulink> (Alternative
 283             <acronym>PHP</acronym> Cache) extension (which is of course need for using this
 284             backend).
 285         </para>
 286
 287         <para>
 288             Be careful : with this backend, "tags" are not supported for the moment as
 289             the "doNotTestCacheValidity=true" argument.
 290         </para>
 291
 292         <para>
 293             There is no option for this backend.
 294         </para>
 295     </sect2>
 296
 297     <sect2 id="zend.cache.backends.xcache">
 298         <title>Zend_Cache_Backend_Xcache</title>
 299
 300         <para>
 301             This backends stores cache records in shared memory through
 302             the <ulink url="http://xcache.lighttpd.net/">XCache</ulink> extension
 303             (which is of course need for using this backend).
 304         </para>
 305
 306         <para>
 307             Be careful : with this backend, "tags" are not supported for the moment as
 308             the "doNotTestCacheValidity=true" argument.
 309         </para>
 310
 311         <para>
 312             Available options are :
 313         </para>
 314
 315         <table id="zend.cache.backends.xcache.table">
 316             <title>Xcache Backend Options</title>
 317
 318             <tgroup cols="4">
 319                 <thead>
 320                     <row>
 321                         <entry>Option</entry>
 322                         <entry>Data Type</entry>
 323                         <entry>Default Value</entry>
 324                         <entry>Description</entry>
 325                     </row>
 326                 </thead>
 327
 328                 <tbody>
 329                     <row>
 330                         <entry><emphasis>user</emphasis></entry>
 331                         <entry><type>String</type></entry>
 332                         <entry><constant>NULL</constant></entry>
 333
 334                         <entry>
 335                             <filename>xcache.admin.user</filename>, necessary for the
 336                             <methodname>clean()</methodname> method
 337                         </entry>
 338                     </row>
 339
 340                     <row>
 341                         <entry><emphasis>password</emphasis></entry>
 342                         <entry><type>String</type></entry>
 343                         <entry><constant>NULL</constant></entry>
 344
 345                         <entry>
 346                             <filename>xcache.admin.pass</filename> (in clear form, not
 347                             <acronym>MD5</acronym>), necessary for the
 348                             <methodname>clean()</methodname> method
 349                         </entry>
 350                     </row>
 351                 </tbody>
 352             </tgroup>
 353         </table>
 354     </sect2>
 355
 356     <sect2 id="zend.cache.backends.platform">
 357         <title>Zend_Cache_Backend_ZendPlatform</title>
 358
 359         <para>
 360             This backend uses content caching <acronym>API</acronym> of the <ulink
 361                 url="http://www.zend.com/en/products/platform/">Zend Platform</ulink> product.
 362             Naturally, to use this backend you need to have Zend Platform installed.
 363         </para>
 364
 365         <para>
 366             This backend supports tags, but does not support
 367             <constant>CLEANING_MODE_NOT_MATCHING_TAG</constant> cleaning mode.
 368         </para>
 369
 370         <para>
 371             Specify this backend using a word separator -- '-', '.', ' ', or '_'
 372             -- between the words 'Zend' and 'Platform' when using the
 373             <methodname>Zend_Cache::factory()</methodname> method:
 374         </para>
 375
 376         <programlisting language="php"><![CDATA[
 377 $cache = Zend_Cache::factory('Core', 'Zend Platform');
 378 ]]></programlisting>
 379
 380         <para>
 381             There are no options for this backend.
 382         </para>
 383     </sect2>
 384
 385     <sect2 id="zend.cache.backends.twolevels">
 386         <title>Zend_Cache_Backend_TwoLevels</title>
 387
 388         <para>
 389             This (extend) backend is an hybrid one. It stores cache records in two other backends :
 390             a fast one (but limited) like Apc, Memcache... and a "slow" one like File, Sqlite...
 391         </para>
 392
 393         <para>
 394             This backend will use the priority parameter (given at the frontend level when storing a
 395             record) and the remaining space in the fast backend to optimize the usage of these two
 396             backends.
 397         </para>
 398
 399         <para>
 400             Specify this backend using a word separator -- '-', '.', ' ', or '_'
 401             -- between the words 'Two' and 'Levels' when using the
 402             <methodname>Zend_Cache::factory()</methodname> method:
 403         </para>
 404
 405         <programlisting language="php"><![CDATA[
 406 $cache = Zend_Cache::factory('Core', 'Two Levels');
 407 ]]></programlisting>
 408
 409         <para>
 410             Available options are :
 411         </para>
 412
 413         <table id="zend.cache.backends.twolevels.table">
 414             <title>TwoLevels Backend Options</title>
 415
 416             <tgroup cols="4">
 417                 <thead>
 418                     <row>
 419                         <entry>Option</entry>
 420                         <entry>Data Type</entry>
 421                         <entry>Default Value</entry>
 422                         <entry>Description</entry>
 423                     </row>
 424                 </thead>
 425
 426                 <tbody>
 427                     <row>
 428                         <entry><emphasis>slow_backend</emphasis></entry>
 429                         <entry><type>String</type></entry>
 430                         <entry>File</entry>
 431                         <entry>the "slow" backend name</entry>
 432                     </row>
 433
 434                     <row>
 435                         <entry><emphasis>fast_backend</emphasis></entry>
 436                         <entry><type>String</type></entry>
 437                         <entry>Apc</entry>
 438                         <entry>the "fast" backend name</entry>
 439                     </row>
 440
 441                     <row>
 442                         <entry><emphasis>slow_backend_options</emphasis></entry>
 443                         <entry><type>Array</type></entry>
 444                         <entry><methodname>array()</methodname></entry>
 445                         <entry>the "slow" backend options</entry>
 446                     </row>
 447
 448                     <row>
 449                         <entry><emphasis>fast_backend_options</emphasis></entry>
 450                         <entry><type>Array</type></entry>
 451                         <entry><methodname>array()</methodname></entry>
 452                         <entry>the "fast" backend options</entry>
 453                     </row>
 454
 455                     <row>
 456                         <entry><emphasis>slow_backend_custom_naming</emphasis></entry>
 457                         <entry><type>Boolean</type></entry>
 458                         <entry><constant>FALSE</constant></entry>
 459
 460                         <entry>
 461                             if <constant>TRUE</constant>, the slow_backend argument is used as a
 462                             complete class name; if <constant>FALSE</constant>,
 463                             the frontend argument is used as the end of
 464                             "<classname>Zend_Cache_Backend_</classname>[...]" class name
 465                         </entry>
 466                     </row>
 467
 468                     <row>
 469                         <entry><emphasis>fast_backend_custom_naming</emphasis></entry>
 470                         <entry><type>Boolean</type></entry>
 471                         <entry><constant>FALSE</constant></entry>
 472
 473                         <entry>
 474                             if <constant>TRUE</constant>, the fast_backend argument is used as a
 475                             complete class name; if <constant>FALSE</constant>,
 476                             the frontend argument is used as the end of
 477                             "<classname>Zend_Cache_Backend_</classname>[...]" class name
 478                         </entry>
 479                     </row>
 480
 481                     <row>
 482                         <entry><emphasis>slow_backend_autoload</emphasis></entry>
 483                         <entry><type>Boolean</type></entry>
 484                         <entry><constant>FALSE</constant></entry>
 485
 486                         <entry>
 487                             if <constant>TRUE</constant>, there will no require_once for the
 488                             slow backend (useful only for custom backends)
 489                         </entry>
 490                     </row>
 491
 492                     <row>
 493                         <entry><emphasis>fast_backend_autoload</emphasis></entry>
 494                         <entry><type>Boolean</type></entry>
 495                         <entry><constant>FALSE</constant></entry>
 496
 497                         <entry>
 498                             if <constant>TRUE</constant>, there will no require_once for the fast
 499                             backend (useful only for custom backends)
 500                         </entry>
 501                     </row>
 502
 503                     <row>
 504                         <entry><emphasis>auto_refresh_fast_cache</emphasis></entry>
 505                         <entry><type>Boolean</type></entry>
 506                         <entry><constant>TRUE</constant></entry>
 507
 508                         <entry>
 509                             if <constant>TRUE</constant>, auto refresh the fast cache when a
 510                             cache record is hit
 511                         </entry>
 512                     </row>
 513
 514                     <row>
 515                         <entry><emphasis>stats_update_factor</emphasis></entry>
 516                         <entry><type>Integer</type></entry>
 517                         <entry>10</entry>
 518
 519                         <entry>
 520                             disable / tune the computation of the fast backend filling percentage
 521                             (when saving a record into cache, computation of the fast backend
 522                             filling percentage randomly 1 times on x cache writes)
 523                         </entry>
 524                     </row>
 525                 </tbody>
 526             </tgroup>
 527         </table>
 528     </sect2>
 529
 530     <sect2 id="zend.cache.backends.zendserver">
 531         <title>Zend_Cache_Backend_ZendServer_Disk and Zend_Cache_Backend_ZendServer_ShMem</title>
 532
 533         <para>
 534             These backends store cache records using <ulink
 535                 url="http://www.zend.com/en/products/server/downloads-all?zfs=zf_download">Zend
 536                 Server</ulink> caching functionality.
 537         </para>
 538
 539         <para>
 540              Be careful: with these backends, "tags" are not supported for the moment as the
 541              "doNotTestCacheValidity=true" argument.
 542         </para>
 543
 544         <para>
 545              These backend work only withing Zend Server environment for pages requested through
 546              <acronym>HTTP</acronym> or <acronym>HTTPS</acronym> and don't work for command line
 547              script execution
 548         </para>
 549
 550         <para>
 551             Specify this backend using parameter <emphasis>customBackendNaming</emphasis> as
 552             <constant>TRUE</constant> when using the <methodname>Zend_Cache::factory()</methodname>
 553             method:
 554         </para>
 555
 556         <programlisting language="php"><![CDATA[
 557 $cache = Zend_Cache::factory('Core', 'Zend_Cache_Backend_ZendServer_Disk',
 558                              $frontendOptions, $backendOptions, false, true);
 559 ]]></programlisting>
 560
 561         <para>
 562             There is no option for this backend.
 563         </para>
 564     </sect2>
 565
 566     <sect2 id="zend.cache.backends.static">
 567         <title>Zend_Cache_Backend_Static</title>
 568
 569         <para>
 570             This backend works in concert with <classname>Zend_Cache_Frontend_Capture</classname>
 571             (the two must be used together) to save the output from requests as static files. This
 572             means the static files are served directly on subsequent requests without any
 573             involvement of <acronym>PHP</acronym> or Zend Framework at all.
 574         </para>
 575
 576         <note>
 577                 <para>
 578                     <classname>Zend_Cache_Frontend_Capture</classname> operates
 579                     by registering a callback function to be called
 580                     when the output buffering it uses is cleaned. In order for this to operate
 581                     correctly, it must be the final output buffer in the request. To guarantee
 582                     this, the output buffering used by the Dispatcher <emphasis>must</emphasis> be
 583                     disabled by calling <classname>Zend_Controller_Front</classname>'s
 584                     <methodname>setParam()</methodname> method, for example,
 585                     <command>$front->setParam('disableOutputBuffering', true);</command> or adding
 586                     "resources.frontcontroller.params.disableOutputBuffering = true"
 587                     to your bootstrap configuration file (assumed <acronym>INI</acronym>) if using
 588                     <classname>Zend_Application</classname>.
 589                 </para>
 590             </note>
 591
 592         <para>
 593             The benefits of this cache include a large throughput increase since
 594             all subsequent requests return the static file and don't need any
 595             dynamic processing. Of course this also has some disadvantages. The
 596             only way to retry the dynamic request is to purge the cached file
 597             from elsewhere in the application (or via a cronjob if timed). It
 598             is also restricted to single-server applications where only one
 599             filesystem is used. Nevertheless, it can be a powerful means of
 600             getting more performance without incurring the cost of a proxy on
 601             single machines.
 602         </para>
 603
 604         <para>
 605             Before describing its options, you should note this needs some
 606             changes to the default <filename>.htaccess</filename> file in order for requests to be
 607             directed to the static files if they exist. Here's an example of
 608             a simple application caching some content, including two specific
 609             feeds which need additional treatment to serve a correct
 610             Content-Type header:
 611         </para>
 612
 613         <programlisting language="text"><![CDATA[
 614 AddType application/rss+xml .xml
 615 AddType application/atom+xml .xml
 616
 617 RewriteEngine On
 618
 619 RewriteCond %{REQUEST_URI} feed/rss$
 620 RewriteCond %{DOCUMENT_ROOT}/cached/%{REQUEST_URI}.xml -f
 621 RewriteRule .* cached/%{REQUEST_URI}.xml [L,T=application/rss+xml]
 622
 623 RewriteCond %{REQUEST_URI} feed/atom$
 624 RewriteCond %{DOCUMENT_ROOT}/cached/%{REQUEST_URI}.xml -f
 625 RewriteRule .* cached/%{REQUEST_URI}.xml [L,T=application/atom+xml]
 626
 627 RewriteCond %{DOCUMENT_ROOT}/cached/index.html -f
 628 RewriteRule ^/*$ cached/index.html [L]
 629 RewriteCond %{DOCUMENT_ROOT}/cached/%{REQUEST_URI}.(html|xml|json|opml|svg) -f
 630 RewriteRule .* cached/%{REQUEST_URI}.%1 [L]
 631
 632 RewriteCond %{REQUEST_FILENAME} -s [OR]
 633 RewriteCond %{REQUEST_FILENAME} -l [OR]
 634 RewriteCond %{REQUEST_FILENAME} -d
 635 RewriteRule ^.*$ - [NC,L]
 636
 637 RewriteRule ^.*$ index.php [NC,L]
 638 ]]></programlisting>
 639
 640         <para>
 641             The above assumes static files are cached to the directory
 642             <filename>./public/cached</filename>. We'll cover the option setting this location,
 643             "public_dir", below.
 644         </para>
 645
 646         <para>
 647             Due to the nature of static file caching, the backend class offers two additional
 648             methods: <methodname>remove()</methodname> and
 649             <methodname>removeRecursively()</methodname>. Both accept a request
 650             <acronym>URI</acronym>, which when mapped to the "public_dir" where static files are
 651             cached, and has a pre-stored extension appended, provides the name of either a static
 652             file to delete, or a directory path to delete recursively. Due to the
 653             restraints of <classname>Zend_Cache_Backend_Interface</classname>, all
 654             other methods such as <methodname>save()</methodname> accept an ID which
 655             is calculated by applying <methodname>bin2hex()</methodname> to a request
 656             <acronym>URI</acronym>.
 657         </para>
 658
 659         <para>
 660             Given the level at which static caching operates, static file caching is addressed for
 661             simpler use with the <classname>Zend_Controller_Action_Helper_Cache</classname> action
 662             helper. This helper assists in setting which actions of a controller to cache, with what
 663             tags, and with which extension. It also offers methods for purging the cache by request
 664             <acronym>URI</acronym> or tag. Static file caching is also assisted by
 665             <classname>Zend_Cache_Manager</classname> which includes pre-configured configuration
 666             templates for a static cache (as <constant>Zend_Cache_Manager::PAGECACHE</constant> or
 667             "page"). The defaults therein can be configured as needed to set up a "public_dir"
 668             location for caching, etc.
 669         </para>
 670
 671         <note>
 672             <para>
 673                 It should be noted that the static cache actually uses a secondary cache to store
 674                 tags (obviously we can't store them elsewhere since a static cache does not invoke
 675                 <acronym>PHP</acronym> if working correctly). This is just a standard Core cache,
 676                 and should use a persistent backend such as File or TwoLevels (to take advantage of
 677                 memory storage without sacrificing permanent persistance). The backend includes the
 678                 option "tag_cache" to set this up (it is obligatory), or the
 679                 <methodname>setInnerCache()</methodname> method.
 680             </para>
 681         </note>
 682
 683         <table id="zend.cache.backends.static.table">
 684             <title>Static Backend Options</title>
 685
 686             <tgroup cols="4">
 687                 <thead>
 688                     <row>
 689                         <entry>Option</entry>
 690                         <entry>Data Type</entry>
 691                         <entry>Default Value</entry>
 692                         <entry>Description</entry>
 693                     </row>
 694                 </thead>
 695
 696                 <tbody>
 697                     <row>
 698                         <entry><emphasis>public_dir</emphasis></entry>
 699                         <entry><type>String</type></entry>
 700                         <entry><constant>NULL</constant></entry>
 701                         <entry>
 702                             Directory where to store static files. This must exist
 703                             in your public directory.
 704                         </entry>
 705                     </row>
 706
 707                     <row>
 708                         <entry><emphasis>file_locking</emphasis></entry>
 709                         <entry><type>Boolean</type></entry>
 710                         <entry><constant>TRUE</constant></entry>
 711
 712                         <entry>
 713                             Enable or disable file_locking : Can avoid cache corruption under
 714                             bad circumstances but it doesn't help on multithread webservers
 715                             or on <acronym>NFS</acronym> filesystems...
 716                         </entry>
 717                     </row>
 718
 719                     <row>
 720                         <entry><emphasis>read_control</emphasis></entry>
 721                         <entry><type>Boolean</type></entry>
 722                         <entry><constant>TRUE</constant></entry>
 723
 724                         <entry>
 725                             Enable / disable read control : if enabled, a control key is
 726                             embedded in the cache file and this key is compared with the
 727                             one calculated after the reading.
 728                         </entry>
 729                     </row>
 730
 731                     <row>
 732                         <entry><emphasis>read_control_type</emphasis></entry>
 733                         <entry><type>String</type></entry>
 734                         <entry>'crc32'</entry>
 735
 736                         <entry>
 737                             Type of read control (only if read control is enabled). Available values
 738                             are : 'md5' (best but slowest), 'crc32' (lightly less safe but faster,
 739                             better choice), 'adler32' (new choice, faster than crc32),
 740                             'strlen' for a length only test (fastest).
 741                         </entry>
 742                     </row>
 743
 744                     <row>
 745                         <entry><emphasis>cache_file_umask</emphasis></entry>
 746                         <entry><type>Integer</type></entry>
 747                         <entry>0700</entry>
 748                         <entry>umask for cached files.</entry>
 749                     </row>
 750
 751                     <row>
 752                         <entry><emphasis>cache_directory_umask</emphasis></entry>
 753                         <entry><type>Integer</type></entry>
 754                         <entry>0700</entry>
 755                         <entry>Umask for directories created within public_dir.</entry>
 756                     </row>
 757
 758                     <row>
 759                         <entry><emphasis>file_extension</emphasis></entry>
 760                         <entry><type>String</type></entry>
 761                         <entry>'<filename>.html</filename>'</entry>
 762
 763                         <entry>
 764                             Default file extension for static files created. This can be
 765                             configured on the fly, see
 766                             <methodname>Zend_Cache_Backend_Static::save()</methodname> though
 767                             generally it's recommended to rely on
 768                             <classname>Zend_Controller_Action_Helper_Cache</classname> when
 769                             doing so since it's simpler that way than messing with
 770                             arrays or serialization manually.
 771                         </entry>
 772                     </row>
 773
 774                     <row>
 775                         <entry><emphasis>index_filename</emphasis></entry>
 776                         <entry><type>String</type></entry>
 777                         <entry>'index'</entry>
 778
 779                         <entry>
 780                             If a request <acronym>URI</acronym> does not contain sufficient
 781                             information to construct a static file (usually this means an index
 782                             call, e.g. <acronym>URI</acronym> of '/'), the index_filename is used
 783                             instead. So '' or '/' would map to '<filename>index.html</filename>'
 784                             (assuming the default file_extension is '<filename>.html</filename>').
 785                         </entry>
 786                     </row>
 787
 788                     <row>
 789                         <entry><emphasis>tag_cache</emphasis></entry>
 790                         <entry><type>Object</type></entry>
 791                         <entry><constant>NULL</constant></entry>
 792
 793                         <entry>
 794                             Used to set an 'inner' cache utilised to store tags
 795                             and file extensions associated with static files. This
 796                             <emphasis>must</emphasis> be set or the static cache cannot be tracked
 797                             and managed.
 798                         </entry>
 799                     </row>
 800
 801                     <row>
 802                         <entry><emphasis>disable_caching</emphasis></entry>
 803                         <entry><type>Boolean</type></entry>
 804                         <entry><constant>FALSE</constant></entry>
 805
 806                         <entry>
 807                             If set to <constant>TRUE</constant>, static files will not be cached.
 808                             This will force all requests to be dynamic even if marked
 809                             to be cached in Controllers. Useful for debugging.
 810                         </entry>
 811                     </row>
 812                 </tbody>
 813             </tgroup>
 814         </table>
 815     </sect2>
 816 </sect1>
 817 <!--
 818 vim:se ts=4 sw=4 et:
 819 -->