summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/libraries/caching.rst
blob: 1fc1b5bfbd73411952d6cd7a2c91dbb19b73b003 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
##############
Caching Driver
##############

CodeIgniter features wrappers around some of the most popular forms of
fast and dynamic caching. All but file-based caching require specific
server requirements, and a Fatal Exception will be thrown if server
requirements are not met.

.. contents::
  :local:

.. raw:: html

  <div class="custom-index container"></div>

*************
Example Usage
*************

The following example will load the cache driver, specify `APC <#alternative-php-cache-apc-caching>`_
as the driver to use, and fall back to file-based caching if APC is not
available in the hosting environment.

::

	$this->load->driver('cache', array('adapter' => 'apc', 'backup' => 'file'));

	if ( ! $foo = $this->cache->get('foo'))
	{
		echo 'Saving to the cache!<br />';
		$foo = 'foobarbaz!';

		// Save into the cache for 5 minutes
		$this->cache->save('foo', $foo, 300);
	}

	echo $foo;

You can also prefix cache item names via the **key_prefix** setting, which is useful
to avoid collisions when you're running multiple applications on the same environment.

::

	$this->load->driver('cache',
		array('adapter' => 'apc', 'backup' => 'file', 'key_prefix' => 'my_')
	);

	$this->cache->get('foo'); // Will get the cache entry named 'my_foo'

***************
Class Reference
***************

.. php:class:: CI_Cache

	.. php:method:: is_supported($driver)

		:param	string	$driver: the name of the caching driver
		:returns:	TRUE if supported, FALSE if not
		:rtype:	bool

		This method is automatically called when accessing drivers via
		``$this->cache->get()``. However, if the individual drivers are used,
		make sure to call this method to ensure the driver is supported in the
		hosting environment.
		::

			if ($this->cache->apc->is_supported()
			{
				if ($data = $this->cache->apc->get('my_cache'))
				{
					// do things.
				}
			}

	.. php:method:: get($id)

		:param	string	$id: Cache item name
		:returns:	Item value or FALSE if not found
		:rtype:	mixed

		This method will attempt to fetch an item from the cache store. If the
		item does not exist, the method will return FALSE.
		::

			$foo = $this->cache->get('my_cached_item');

	.. php:method:: save($id, $data[, $ttl = 60[, $raw = FALSE]])

		:param	string	$id: Cache item name
		:param	mixed	$data: the data to save
		:param	int	$ttl: Time To Live, in seconds (default 60)
		:param	bool	$raw: Whether to store the raw value
		:returns:	TRUE on success, FALSE on failure
		:rtype:	string

		This method will save an item to the cache store. If saving fails, the
		method will return FALSE.
		::

			$this->cache->save('cache_item_id', 'data_to_cache');

		.. note:: The ``$raw`` parameter is only utilized by APC and Memcache,
			in order to allow usage of ``increment()`` and ``decrement()``.

	.. php:method:: delete($id)

		:param	string	$id: name of cached item
		:returns:	TRUE on success, FALSE on failure
		:rtype:	bool

		This method will delete a specific item from the cache store. If item
		deletion fails, the method will return FALSE.
		::

			$this->cache->delete('cache_item_id');

	.. php:method:: increment($id[, $offset = 1])

		:param	string	$id: Cache ID
		:param	int	$offset: Step/value to add
		:returns:	New value on success, FALSE on failure
		:rtype:	mixed

		Performs atomic incrementation of a raw stored value.
		::

			// 'iterator' has a value of 2

			$this->cache->increment('iterator'); // 'iterator' is now 3

			$this->cache->increment('iterator', 3); // 'iterator' is now 6

	.. php:method:: decrement($id[, $offset = 1])

		:param	string	$id: Cache ID
		:param	int	$offset: Step/value to reduce by
		:returns:	New value on success, FALSE on failure
		:rtype:	mixed

		Performs atomic decrementation of a raw stored value.
		::

			// 'iterator' has a value of 6

			$this->cache->decrement('iterator'); // 'iterator' is now 5

			$this->cache->decrement('iterator', 2); // 'iterator' is now 3

	.. php:method:: clean()

		:returns:	TRUE on success, FALSE on failure
		:rtype:	bool

		This method will 'clean' the entire cache. If the deletion of the
		cache files fails, the method will return FALSE.
		::

			$this->cache->clean();

	.. php:method:: cache_info()

		:returns:	Information on the entire cache database
		:rtype:	mixed

		This method will return information on the entire cache.
		::

			var_dump($this->cache->cache_info());

		.. note:: The information returned and the structure of the data is dependent
			on which adapter is being used.

	.. php:method:: get_metadata($id)

		:param	string	$id: Cache item name
		:returns:	Metadata for the cached item
		:rtype:	mixed

		This method will return detailed information on a specific item in the
		cache.
		::

			var_dump($this->cache->get_metadata('my_cached_item'));

		.. note:: The information returned and the structure of the data is dependent
			on which adapter is being used.

*******
Drivers
*******

Alternative PHP Cache (APC) Caching
===================================

All of the methods listed above can be accessed without passing a
specific adapter to the driver loader as follows::

	$this->load->driver('cache');
	$this->cache->apc->save('foo', 'bar', 10);

For more information on APC, please see
`http://php.net/apc <http://php.net/apc>`_.

File-based Caching
==================

Unlike caching from the Output Class, the driver file-based caching
allows for pieces of view files to be cached. Use this with care, and
make sure to benchmark your application, as a point can come where disk
I/O will negate positive gains by caching.

All of the methods listed above can be accessed without passing a
specific adapter to the driver loader as follows::

	$this->load->driver('cache');
	$this->cache->file->save('foo', 'bar', 10);

Memcached Caching
=================

Multiple Memcached servers can be specified in the memcached.php
configuration file, located in the _application/config/* directory.

All of the methods listed above can be accessed without passing a
specific adapter to the driver loader as follows::

	$this->load->driver('cache');
	$this->cache->memcached->save('foo', 'bar', 10);

For more information on Memcached, please see
`http://php.net/memcached <http://php.net/memcached>`_.

WinCache Caching
================

Under Windows, you can also utilize the WinCache driver.

All of the methods listed above can be accessed without passing a
specific adapter to the driver loader as follows::

	$this->load->driver('cache');
	$this->cache->wincache->save('foo', 'bar', 10);

For more information on WinCache, please see
`http://php.net/wincache <http://php.net/wincache>`_.

Redis Caching
=============

Redis is an in-memory key-value store which can operate in LRU cache mode. 
To use it, you need `Redis server and phpredis PHP extension <https://github.com/phpredis/phpredis>`_.

Config options to connect to redis server must be stored in the application/config/redis.php file.
Available options are::
	
	$config['socket_type'] = 'tcp'; //`tcp` or `unix`
	$config['socket'] = '/var/run/redis.sock'; // in case of `unix` socket type
	$config['host'] = '127.0.0.1';
	$config['password'] = NULL;
	$config['port'] = 6379;
	$config['timeout'] = 0;

All of the methods listed above can be accessed without passing a
specific adapter to the driver loader as follows::

	$this->load->driver('cache');
	$this->cache->redis->save('foo', 'bar', 10);

For more information on Redis, please see
`http://redis.io <http://redis.io>`_.

Dummy Cache
===========

This is a caching backend that will always 'miss.' It stores no data,
but lets you keep your caching code in place in environments that don't
support your chosen cache.