summaryrefslogtreecommitdiff
path: root/docs/php-memcached/Documentation
blob: 32e340ac31bfa863de8c1bbedacd726abb013ac7 (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
Ryan Gilfether <hotrodder@rocketmail.com>
http://www.gilfether.com
This module is Copyright (c) 2003 Ryan Gilfether.
All rights reserved.

You may distribute under the terms of the GNU General Public License
This is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.

See the memcached website: http://www.danga.com/memcached/


// Takes one parameter, a array of options.  The most important key is
// options["servers"], but that can also be set later with the set_servers()
// method.  The servers must be an array of hosts, each of which is
// either a scalar of the form <10.0.0.10:11211> or an array of the
// former and an integer weight value.  (the default weight if
// unspecified is 1.)  It's recommended that weight values be kept as low
// as possible, as this module currently allocates memory for bucket
// distribution proportional to the total host weights.
// $options["debug"] turns the debugging on if set to true
MemCachedClient::MemCachedClient($options);

// sets up the list of servers and the ports to connect to
// takes an array of servers in the same format as in the constructor
MemCachedClient::set_servers($servers);

// Retrieves a key from the memcache.  Returns the value (automatically
// unserialized, if necessary) or FALSE if it fails.
// The $key can optionally be an array, with the first element being the
// hash value, if you want to avoid making this module calculate a hash
// value.  You may prefer, for example, to keep all of a given user's
// objects on the same memcache server, so you could use the user's
// unique id as the hash value.
// Possible errors set are:
// 		MC_ERR_GET
MemCachedClient::get($key);

// just like get(), but takes an array of keys, returns FALSE on error
// Possible errors set are:
// 		MC_ERR_NOT_ACTIVE
MemCachedClient::get_multi($keys)

// Unconditionally sets a key to a given value in the memcache.  Returns true
// if it was stored successfully.
// The $key can optionally be an arrayref, with the first element being the
// hash value, as described above.
// returns TRUE on success else FALSE
// Possible errors set are:
// 		MC_ERR_NOT_ACTIVE
// 		MC_ERR_GET_SOCK
// 		MC_ERR_SOCKET_WRITE
// 		MC_ERR_SOCKET_READ
// 		MC_ERR_SET
MemCachedClient::set($key, $value, $exptime);

// Like set(), but only stores in memcache if the key doesn't already exist.
// returns TRUE on success else FALSE
// Possible errors set are:
// 		MC_ERR_NOT_ACTIVE
// 		MC_ERR_GET_SOCK
// 		MC_ERR_SOCKET_WRITE
// 		MC_ERR_SOCKET_READ
// 		MC_ERR_SET
MemCachedClient::add($key, $value, $exptime);

// Like set(), but only stores in memcache if the key already exists.
// returns TRUE on success else FALSE
// Possible errors set are:
// 		MC_ERR_NOT_ACTIVE
// 		MC_ERR_GET_SOCK
// 		MC_ERR_SOCKET_WRITE
// 		MC_ERR_SOCKET_READ
// 		MC_ERR_SET
MemCachedClient::replace($key, $value, $exptime);

// removes the key from the MemCache
// $time is the amount of time in seconds (or Unix time) until which
// the client wishes the server to refuse "add" and "replace" commands
// with this key. For this amount of item, the item is put into a
// delete queue, which means that it won't possible to retrieve it by
// the "get" command, but "add" and "replace" command with this key
// will also fail (the "set" command will succeed, however). After the
// time passes, the item is finally deleted from server memory.
// The parameter $time is optional, and, if absent, defaults to 0
// (which means that the item will be deleted immediately and further
// storage commands with this key will succeed).
// returns TRUE on success else returns FALSE
// Possible errors set are:
// 		MC_ERR_NOT_ACTIVE
// 		MC_ERR_GET_SOCK
// 		MC_ERR_SOCKET_WRITE
// 		MC_ERR_SOCKET_READ
// 		MC_ERR_DELETE
MemCachedClient::delete($key, $time = 0);

// Sends a command to the server to atomically increment the value for
// $key by $value, or by 1 if $value is undefined.  Returns FALSE if $key
// doesn't exist on server, otherwise it returns the new value after
// incrementing.  Value should be zero or greater.  Overflow on server
// is not checked.  Be aware of values approaching 2**32.  See decr.
// Possible errors set are:
// 		MC_ERR_NOT_ACTIVE
// 		MC_ERR_GET_SOCK
// 		MC_ERR_SOCKET_WRITE
// 		MC_ERR_SOCKET_READ
// returns new value on success, else returns FALSE
// ONLY WORKS WITH NUMERIC VALUES
MemCachedClient::incr($key[, $value]);

// Like incr, but decrements.  Unlike incr, underflow is checked and new
// values are capped at 0.  If server value is 1, a decrement of 2
// returns 0, not -1.
// Possible errors set are:
// 		MC_ERR_NOT_ACTIVE
// 		MC_ERR_GET_SOCK
// 		MC_ERR_SOCKET_WRITE
// 		MC_ERR_SOCKET_READ
// returns new value on success, else returns FALSE
// ONLY WORKS WITH NUMERIC VALUES
MemCachedClient::decr($key[, $value]);

// disconnects from all servers
MemCachedClient::disconnect_all();

// if $do_debug is set to true, will print out
// debugging info, else debug is turned off
MemCachedClient::set_debug($do_debug);

// remove all cached hosts that are no longer good
MemCachedClient::forget_dead_hosts();

// When a function returns FALSE, an error code is set.
// This funtion will return the error code.
// See error_string()
// returns last error code set
MemCachedClient::error()

// Returns a string describing the error set in error()
// See error()
// returns a string describing the error code given
MemCachedClient::error_string()

// Resets the error number and error string
MemCachedClient::error_clear()

Error codes are as follows:
MC_ERR_NOT_ACTIVE		// no active servers
MC_ERR_SOCKET_WRITE		// socket_write() failed
MC_ERR_SOCKET_READ		// socket_read() failed
MC_ERR_SOCKET_CONNECT	// failed to connect to host
MC_ERR_DELETE			// delete() did not recieve DELETED command
MC_ERR_HOST_FORMAT		// sock_to_host() invalid host format
MC_ERR_HOST_DEAD		// sock_to_host() host is dead
MC_ERR_GET_SOCK			// get_sock() failed to find a valid socket
MC_ERR_SET				// _set() failed to receive the STORED response
MC_ERR_LOADITEM_HEADER	// _load_items failed to receive valid data header
MC_ERR_LOADITEM_END		// _load_items failed to receive END response
MC_ERR_LOADITEM_BYTES	// _load_items bytes read larger than bytes available
MC_ERR_GET				// failed to get value associated with key

// Turns compression on or off; 0=off, 1=on
MemCacheClient::set_compression($setting)

EXAMPLE:
<?php
require 'MemCachedClient.inc.php';

// set the servers, with the last one having an integer weight value of 3
$options["servers"] = array("10.0.0.15:11000","10.0.0.16:11001",array("10.0.0.17:11002", 3));
$options["debug"] = false;

$memc = new MemCachedClient($options);


/***********************
 * STORE AN ARRAY
 ***********************/
$myarr = array("one","two", 3);
$memc->set("key_one", $myarr);
$val = $memc->get("key_one");
print $val[0]."\n";	// prints 'one'
print $val[1]."\n";	// prints 'two'
print $val[2]."\n";	// prints 3


print "\n";


/***********************
 * STORE A CLASS
 ***********************/
class tester
{
	var $one;
	var $two;
	var $three;
}

$t = new tester;
$t->one = "one";
$t->two = "two";
$t->three = 3;
$memc->set("key_two", $t);
$val = $memc->get("key_two");
print $val->one."\n";
print $val->two."\n";
print $val->three."\n";


print "\n";


/***********************
 * STORE A STRING
 ***********************/
$memc->set("key_three", "my string");
$val = $memc->get("key_three");
print $val;		// prints 'my string'

$memc->delete("key_one");
$memc->delete("key_two");
$memc->delete("key_three");

$memc->disconnect_all();



print "\n";


/***********************
 * STORE A BINARY FILE
 ***********************/

 // first read the file and save it in memcache
$fp = fopen( "./image.jpg", "rb" ) ;
if ( !$fp )
{
	print "Could not open ./file.dat!\n" ;
	exit ;
}
$data = fread( $fp, filesize( "./image.jpg" ) ) ;
fclose( $fp ) ;
print "Data length is " . strlen( $data ) . "\n" ;
$memc->set( "key", $data ) ;

// now open a file for writing and write the data
// retrieved from memcache
$fp = fopen("./test.jpg","wb");
$data = $memc->get( "key" ) ;
print "Data length is " . strlen( $data ) . "\n" ;
fwrite($fp,$data,strlen( $data ));
fclose($fp);


?>