vendor/zendframework/zend-cache/doc/book/pattern/capture-cache.md

   1 # CaptureCache
   2
   3 The `CaptureCache` pattern is useful for generating static resources to return
   4 via HTTP request. When used in such a fashion, the web server needs to be
   5 configured to run a PHP script generating the requested resource so that
   6 subsequent requests for the same resource can be shipped without calling PHP
   7 again.
   8
   9 This pattern comes with basic logic for managing generated resources.
  10
  11 ## Quick Start
  12
  13 For use with an Apache 404 handler:
  14
  15 ```apacheconf
  16 # .htdocs
  17 ErrorDocument 404 /index.php
  18 ```
  19
  20 ```php
  21 // index.php
  22 use Zend\Cache\PatternFactory;
  23 $capture = Zend\Cache\PatternFactory::factory('capture', [
  24     'public_dir' => __DIR__,
  25 ]);
  26
  27 // Start capturing all output, excluding headers, and write to the public
  28 // directory:
  29 $capture->start();
  30
  31 // Don't forget to change the HTTP response code
  32 header('Status: 200', true, 200);
  33
  34 // do stuff to dynamically generate output
  35 ```
  36
  37 ## Configuration Options
  38
  39 Option | Data Type | Default Value | Description
  40 ------ | --------- | ------------- | -----------
  41 `public_dir` | `string` | none | Location of the public web root directory in which to write output.
  42 `index_filename` | `string` | "index.html" | The name of the index file if only a directory was requested.
  43 `file_locking` | `bool` | `true` | Whether or not to lock output files when writing.
  44 `file_permission` | `int | bool` | `0600` (`false` on Windows) | Default permissions for generated output files.
  45 `dir_permission` | `int | bool` | `0700` (`false` on Windows) | Default permissions for generated output directories.
  46 `umask` | `int` | `bool` | `false` | Whether or not to umask generated output files / directories.
  47
  48 ## Available Methods
  49
  50 In addition to the methods exposed in `PatternInterface`, this implementation
  51 exposes the following methods.
  52
  53 ```php
  54 namespace Zend\Cache\Pattern;
  55
  56 use Zend\Cache\Exception;
  57 use Zend\Stdlib\ErrorHandler;
  58
  59 class CaptureCache extends AbstractPattern
  60 {
  61     /**
  62      * Start the cache.
  63      *
  64      * @param  string $pageId  Page identifier
  65      * @return void
  66      */
  67     public function start($pageId = null);
  68
  69     /**
  70      * Write a page to the requested path.
  71      *
  72      * @param string      $content
  73      * @param null|string $pageId
  74      * @throws Exception\LogicException
  75      */
  76     public function set($content, $pageId = null);
  77
  78     /**
  79      * Retrieve a generated page from the cache.
  80      *
  81      * @param  null|string $pageId
  82      * @return string|null
  83      * @throws Exception\LogicException
  84      * @throws Exception\RuntimeException
  85      */
  86     public function get($pageId = null);
  87
  88     /**
  89      * Check if a cache exists for the given page.
  90      *
  91      * @param  null|string $pageId
  92      * @throws Exception\LogicException
  93      * @return bool
  94      */
  95     public function has($pageId = null);
  96
  97     /**
  98      * Remove a page from the cache.
  99      *
 100      * @param  null|string $pageId
 101      * @throws Exception\LogicException
 102      * @throws Exception\RuntimeException
 103      * @return bool
 104      */
 105     public function remove($pageId = null);
 106
 107     /**
 108      * Clear cached pages that match the specified glob pattern.
 109      *
 110      * @param string $pattern
 111      * @throws Exception\LogicException
 112      */
 113     public function clearByGlob($pattern = '**');
 114
 115     /**
 116      * Returns the generated file name.
 117      *
 118      * @param null|string $pageId
 119      * @return string
 120      */
 121     public function getFilename($pageId = null);
 122 }
 123 ```
 124
 125 ## Examples
 126
 127 ### Scaling images in the web root
 128
 129 Using the following Apache 404 configuration:
 130
 131 ```apacheconf
 132 # .htdocs
 133 ErrorDocument 404 /index.php
 134 ```
 135
 136 Use the following script:
 137
 138 ```php
 139 // index.php
 140 $captureCache = Zend\Cache\PatternFactory::factory('capture', [
 141     'public_dir' => __DIR__,
 142 ]);
 143
 144 // TODO
 145 ```