lib/pear/Cache/Output.php

   1 <?php
   2 // +----------------------------------------------------------------------+
   3 // | PEAR :: Cache                                                        |
   4 // +----------------------------------------------------------------------+
   5 // | Copyright (c) 1997-2003 The PHP Group                                |
   6 // +----------------------------------------------------------------------+
   7 // | This source file is subject to version 2.0 of the PHP license,       |
   8 // | that is bundled with this package in the file LICENSE, and is        |
   9 // | available at through the world-wide-web at                           |
  10 // | http://www.php.net/license/2_02.txt.                                 |
  11 // | If you did not receive a copy of the PHP license and are unable to   |
  12 // | obtain it through the world-wide-web, please send a note to          |
  13 // | license@php.net so we can mail you a copy immediately.               |
  14 // +----------------------------------------------------------------------+
  15 // | Authors: Ulf Wendel <ulf.wendel@phpdoc.de>                           |
  16 // |          Christian Stocker <chregu@phant.ch>                         |
  17 // |          Vinai Kopp <kopp@netzarbeiter.de>                           |
  18 // +----------------------------------------------------------------------+
  19 //
  20 // $Id: Output.php 178289 2005-01-26 09:47:28Z dufuz $
  21
  22 require_once 'Cache.php';
  23
  24 /**
  25 * Class to cache the output of a script using the output buffering functions
  26 *
  27 * Simple output cache. Some pages require lots of time to compute. Caching the
  28 * output can increase the overall speed dramatically, especially if you use
  29 * a Shared Memory storage container.
  30 *
  31 * As you can see in the example the usage is extemely simple. To cache a script
  32 * simple put some few lines of code in front of your script and some at the end.
  33 * A preferrable place for this are the auto_prepend and auto_append files (=> php.ini).
  34 *
  35 * Usage example:
  36 *
  37 *  // place this somewhere in a central config file
  38 *  define(CACHE_STORAGE_CLASS, 'file');
  39 *  // file storage needs a dir to put the cache files
  40 *  define(CACHE_DIR, '/var/tmp/');
  41 *
  42 *  // get a cache object
  43 *  $cache = new Cache_Output(CACHE_STORAGE_CLASS, array('cache_dir' => CACHE_DIR));
  44 *
  45 *  // compute the unique handle.
  46 *  // if your script depends on Cookie and HTTP Post data as well
  47 *  // you should use:
  48 *  // $cache_handle = array(
  49 *  //                       'file' => $REQUEST_URI,
  50 *  //                       'post' => $HTTP_POST_VARS,
  51 *  //                       'cookie'  => $HTTP_COOKIE_VARS
  52 *  //                    );
  53 *  // But be warned, using all GET or POST Variables as a seed
  54 *  // can be used for a DOS attack. Calling http://www.example.com/example.php?whatever
  55 *  // where whatever is a random text might be used to flood your cache.
  56 *  $cache_handle = $cache->generateID($REQUEST_URI);
  57 *
  58 *  // now the magic happens: if cached call die()
  59 *  // to end the time consumptiong script script execution and use the cached value!
  60 *  if ($content = $cache->start($cache_handle)) {
  61 *     print $content;
  62 *     print '<p>Cache hit</p>';
  63 *     die();
  64 *  }
  65 *
  66 *  // time consumption script goes here.
  67 *
  68 *  // store the output of the cache into the cache and print the output.
  69 *  print $cache->end();
  70 *  print "<p>Cache miss, stored using the ID '$id'.</p>";
  71 *
  72 *  If you do not want to cache a whole page - no problem:
  73 *
  74 *  if (!($content = $cache->start($cache_handle))) {
  75 *     // do the computation here
  76 *     print $cache->end()
  77 *  } else {
  78 *     print $content;
  79 *  }
  80 *
  81 *  If you need an example script check the (auto_)prepend and (auto_)append
  82 *  files of my homepage:
  83 *
  84 *    http://www.ulf-wendel.de/php/show_source.php?file=prepend
  85 *    http://www.ulf-wendel.de/php/show_source.php?file=append
  86 *
  87 *  Don't know how to use it or you need profiling informations?`
  88 *  Ask Christian he was patient with me and he'll be so with your questions ;).
  89 *
  90 *  Have fun!
  91 *
  92 * @authors  Ulf Wendel <ulf.wendel@phpdoc.de>
  93 * @version  $ID: $
  94 * @package  Cache
  95 * @access   public
  96 */
  97 class Cache_Output extends Cache
  98 {
  99
 100     /**
 101     * ID passed to start()
 102     *
 103     * @var  string
 104     * @see  start(), end()
 105     */
 106     var $output_id = '';
 107
 108     /**
 109     * Group passed to start()
 110     *
 111     * @var  string
 112     * @see  start(), end()
 113     */
 114     var $output_group = '';
 115
 116     /**
 117     * PEAR-Deconstructor
 118     * Call deconstructor of parent
 119     */
 120     function _Cache_Output()
 121     {
 122         $this->_Cache();
 123     }
 124
 125     /**
 126     * starts the output buffering and returns an empty string or returns the cached output from the cache.
 127     *
 128     * @param    string  dataset ID
 129     * @param    string  cache group
 130     * @return   string
 131     * @access   public
 132     */
 133     function start($id, $group = 'default')
 134     {
 135         if (!$this->caching) {
 136             return '';
 137         }
 138         // this is already cached return it from the cache so that the user
 139         // can use the cache content and stop script execution
 140         if ($content = $this->get($id, $group)) {
 141             return $content;
 142         }
 143         // remember some data to be able to fill the cache on calling end()
 144         $this->output_id = $id;
 145         $this->output_group = $group;
 146
 147         // WARNING: we need the output buffer - possible clashes
 148         ob_start();
 149         ob_implicit_flush(false);
 150
 151         return '';
 152     } // end func start
 153
 154     /*
 155     * Stores the content of the output buffer into the cache and returns the content.
 156     *
 157     * @param    mixed   lifetime of the cached data in seconds - 0 for endless. More formats available. see Container::getExpiresAbsolute()
 158     * @param    string  additional userdefined data
 159     * @return   string  cached output
 160     * @access   public
 161     * @see      endPrint(), endGet(), Container::getExpiresAbsolute()
 162     */
 163     function end($expire = 0, $userdata = '')
 164     {
 165         $content = ob_get_contents();
 166         ob_end_clean();
 167
 168         // store in the cache
 169         if ($this->caching) {
 170             $this->container->save($this->output_id, $content, $expire, $this->output_group, $userdata);
 171         }
 172         return $content;
 173     } // end func end()
 174
 175     /**
 176     * Stores the content of the output buffer into the cache and prints the content.
 177     *
 178     * @brother  end()
 179     */
 180     function endPrint($expire = 0, $userdata = '')
 181     {
 182         $this->printContent($this->end($expire, $userdata));
 183     } // end func endPrint
 184
 185     /**
 186     * Sends the data to the user.
 187     * This is for compatibility with OutputCompression
 188     *
 189     * @param    string
 190     * @access   public
 191     */
 192     function printContent($content = '')
 193     {
 194         if ($content == '') {
 195             $content = &$this->container->cachedata;
 196         }
 197         print $content;
 198     }
 199     /**
 200     * Returns the content of the output buffer but does not store it into the cache.
 201     *
 202     * Use this method if the content of your script is markup (XML)
 203     * that has to be parsed/converted (XSLT) before you can output
 204     * and store it into the cache using save().
 205     *
 206     * @return   string
 207     * @access   public
 208     * @see      endPrint(), end()
 209     */
 210     function endGet()
 211     {
 212         $content = ob_get_contents();
 213         ob_end_clean();
 214
 215         $this->output_id = '';
 216         $this->output_group = '';
 217
 218         return $content;
 219     } // end func endGet
 220 } // end class output
 221 ?>