summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/libraries/caching.rst
blob: 709171dd331fdd76593a8396d2b1ab67c24b90de (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
##############
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 <#apc>`_
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
***************

.. class:: CI_Cache

	.. method:: is_supported($driver)

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

		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.
				}
			}

	.. method:: get($id)

		:param string $id: name of cached item
		:returns: The item if it exists, FALSE if it does not

		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');

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

		:param string $id: name of the cached item
		:param mixed $data: the data to save
		:param int $ttl: Time To Live, in seconds (default 60)
		:returns: TRUE on success, FALSE on failure

		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');

	.. method:: delete($id)

		:param string $id: name of cached item
		:returns: TRUE if deleted, FALSE if the deletion fails

		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');

	.. method:: clean()

		:returns: TRUE if deleted, FALSE if the deletion fails

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

			$this->cache->clean();

	.. method:: cache_info()

		:returns: information on the entire cache

		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.

	.. method:: get_metadata($id)

		:param string $id: name of cached item
		:returns: metadadta for the cached item

		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
=============

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);

.. important:: Redis may require one or more of the following options:
	**host**, **post**, **timeout**, **password**.

The Redis PHP extension repository is located at
`https://github.com/nicolasff/phpredis <https://github.com/nicolasff/phpredis>`_.

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.