Documentation/database/caching.html

   1 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   2 <head>
   3         <title>CarbonPHP Documentation</title>
   4         <style type="text/css">
   5                 * {
   6                         margin: 0;
   7                         padding: 0;
   8                 }
   9
  10                 html {
  11                         font-family: "Lucida Sans Unicode", "Lucida Grande";
  12                         font-size: 12px;
  13                 }
  14
  15                 body {
  16                         background: #fff;
  17                         color: #666;
  18                 }
  19
  20                 h1 {
  21                         font-size: 15px;
  22                         font-weight: bold;
  23                         margin: 0 0 5px 0;
  24                 }
  25
  26                 h2 {
  27                         font-size: 13px;
  28                         font-weight: bold;
  29                         margin: 5px 0 5px 0;
  30                 }
  31
  32                 ol, ul {
  33                         margin: 10px 0 10px 0;
  34                         list-style-position: inside;
  35                 }
  36
  37                 p {
  38                         margin: 5px 0 5px 0;
  39                 }
  40
  41                 .content {
  42                         border: 1px dotted #444;
  43                         margin: 10px;
  44                         padding: 10px;
  45                         text-align: justify;
  46                         width: 700px;
  47                 }
  48
  49                 .example {
  50                         border: 1px solid #ccc;
  51                         background: #eee;
  52                         margin: 10px;
  53                         padding: 10px;
  54                         text-align: left;
  55                 }
  56         </style>
  57 </head>
  58
  59 <body>
  60         <div class="content">
  61                 <h1>Database Caching</h1>
  62
  63                 <p>The database class allows you to cache your queries as text files for reducing the database load.</p>
  64
  65                 <p>The caching class is loaded automatically loaded by the database class you do not have to manually load
  66                 it.</p>
  67         </div>
  68
  69         <div class="content">
  70                 <h1>Enabling Caching</h1>
  71
  72                 <p>Caching is enabled by following these three steps.</p>
  73
  74                 <ul>
  75                         <li>Create a directory on the server where the cache files will be stored.</li>
  76                         <li>Set the path to your cache directory in your <b>application/config/database.php</b> file.</li>
  77                         <li>Enabled the caching feature, either globally in the configuration settings or manually as described
  78                         below.</li>
  79                 </ul>
  80
  81                 <p>Once caching is enabled caching will happen automatically whenever a page is loaded that contains any
  82                 database queries.</p>
  83         </div>
  84
  85         <div class="content">
  86                 <h1>How Does Caching Work</h1>
  87
  88                 <p>CarbonPHP caching happens dynamically when your pages are viewed.  When caching is enabled the first time
  89                 a page is loaded the query result object will be serialised and stored in a text file on the server. The next
  90                 time the page is loaded the cache file will be served instead of accessing the database.</p>
  91
  92                 <p>Only 'read' type queries can be cached, since these are the only type of queries that produce a result
  93                 object.</p>
  94
  95                 <p>Cache files do not expire.  Any queries that have been called will remain cached until you delete them.
  96                 The caching system permits you to clear caches associated with individual pages, or you can delete the
  97                 whole set of cache files.</p>
  98         </div>
  99
 100         <div class="content">
 101                 <h1>Does Caching Improve Site Performance</h1>
 102
 103                 <p>Getting a performance gain as a result of caching depends on many factors.  If you have a highly optimised
 104                 database under very little load you will probably not noticed an improved performance.  If your database
 105                 is under heavy load you probably will see an improved response.</p>
 106
 107                 <p>In some clustered server environments for example caching may be detrimental since file system operations
 108                 are so instense.  On single servers in shared environments caching you probably be more benficial.</p>
 109         </div>
 110
 111         <div class="content">
 112                 <h1>How are Cache Files Stored</h1>
 113
 114                 <p>CarbonPHP places the result of each query into it's own cache file which are then organised into
 115                 subdirectories corresponding to the name of your controller and method.</p>
 116
 117                 <p>For example if you have a controller called <b>blog</b> and a method called <b>post</b> that contains
 118                 three queries, the caching system will create a cache directory called <b>blog+post</b> into which it
 119                 will create three cache files, one for each query.</p>
 120         </div>
 121
 122         <div class="content">
 123                 <h1>Managing Cache Files</h1>
 124
 125                 <p>Since cache files do not expire you will need to use the built in deletion methods to remove old cache
 126                 files.</p>
 127         </div>
 128
 129         <div class="content">
 130                 <h1>Unsupported Methods</h1>
 131
 132                 <p>Some methods are not supported by the caching system.</p>
 133
 134                 <ul>
 135                         <li>num_fields()</li>
 136                         <li>field_names()</li>
 137                         <li>field_data()</li>
 138                         <li>free_result()</li>
 139                 </ul>
 140
 141                 <p>The database connection ID and result ID are not available when caching.</p>
 142         </div>
 143
 144         <div class="content">
 145                 <h1>$this->db->cache_on() and $this->db->cache_off()</h1>
 146
 147                 <p>This method enables and disabled the caching manually.  This can be useful if you wish to keep certain
 148                 queries from being cached.</p>
 149
 150                 <div class="example">
 151                         $this->db->cache_on();<br />
 152                         $query = $this->db->query('SELECT * FROM `some_table`');<br />
 153                         <br />
 154                         $this->db->cache_off();<br />
 155                         $query = $this->db->query('SELECT * FROM `another_table`');<br />
 156                         <br />
 157                         $this->db->cache_on();<br />
 158                         $query = $this->db->query('SELECT * FROM `more_table`');
 159                 </div>
 160         </div>
 161
 162         <div class="content">
 163                 <h1>$this->db->cache_delete()</h1>
 164
 165                 <p>This method deletes the cache files associated with a particular page.  This is useful if you need to clear
 166                 a cache file after you update your database.</p>
 167
 168                 <p>The caching system saves your cache files to directories correspond to the URI of the page you are viewing.
 169                 To delete the cache files of a controller and method you should the following.</p>
 170
 171                 <div class="example">
 172                         $this->db->cache_delete('blog', 'posts');
 173                 </div>
 174
 175                 <p>If you do not pass any parameters to the function it will determine the cache files based on the current
 176                 URL.</p>
 177         </div>
 178
 179         <div class="content">
 180                 <h1>$this->db->cache_delete_all()</h1>
 181
 182                 <p>Clears all the existing cache files.</p>
 183
 184                 <div class="example">
 185                         $this->db->cache_delete_all();
 186                 </div>
 187         </div>
 188 </body>
 189
 190 </html>