docs/php-memcached/Documentation

   1 Ryan Gilfether <hotrodder@rocketmail.com>
   2 http://www.gilfether.com
   3 This module is Copyright (c) 2003 Ryan Gilfether.
   4 All rights reserved.
   5
   6 You may distribute under the terms of the GNU General Public License
   7 This is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.
   8
   9 See the memcached website: http://www.danga.com/memcached/
  10
  11
  12 // Takes one parameter, a array of options.  The most important key is
  13 // options["servers"], but that can also be set later with the set_servers()
  14 // method.  The servers must be an array of hosts, each of which is
  15 // either a scalar of the form <10.0.0.10:11211> or an array of the
  16 // former and an integer weight value.  (the default weight if
  17 // unspecified is 1.)  It's recommended that weight values be kept as low
  18 // as possible, as this module currently allocates memory for bucket
  19 // distribution proportional to the total host weights.
  20 // $options["debug"] turns the debugging on if set to true
  21 MemCachedClient::MemCachedClient($options);
  22
  23 // sets up the list of servers and the ports to connect to
  24 // takes an array of servers in the same format as in the constructor
  25 MemCachedClient::set_servers($servers);
  26
  27 // Retrieves a key from the memcache.  Returns the value (automatically
  28 // unserialized, if necessary) or FALSE if it fails.
  29 // The $key can optionally be an array, with the first element being the
  30 // hash value, if you want to avoid making this module calculate a hash
  31 // value.  You may prefer, for example, to keep all of a given user's
  32 // objects on the same memcache server, so you could use the user's
  33 // unique id as the hash value.
  34 // Possible errors set are:
  35 //              MC_ERR_GET
  36 MemCachedClient::get($key);
  37
  38 // just like get(), but takes an array of keys, returns FALSE on error
  39 // Possible errors set are:
  40 //              MC_ERR_NOT_ACTIVE
  41 MemCachedClient::get_multi($keys)
  42
  43 // Unconditionally sets a key to a given value in the memcache.  Returns true
  44 // if it was stored successfully.
  45 // The $key can optionally be an arrayref, with the first element being the
  46 // hash value, as described above.
  47 // returns TRUE on success else FALSE
  48 // Possible errors set are:
  49 //              MC_ERR_NOT_ACTIVE
  50 //              MC_ERR_GET_SOCK
  51 //              MC_ERR_SOCKET_WRITE
  52 //              MC_ERR_SOCKET_READ
  53 //              MC_ERR_SET
  54 MemCachedClient::set($key, $value, $exptime);
  55
  56 // Like set(), but only stores in memcache if the key doesn't already exist.
  57 // returns TRUE on success else FALSE
  58 // Possible errors set are:
  59 //              MC_ERR_NOT_ACTIVE
  60 //              MC_ERR_GET_SOCK
  61 //              MC_ERR_SOCKET_WRITE
  62 //              MC_ERR_SOCKET_READ
  63 //              MC_ERR_SET
  64 MemCachedClient::add($key, $value, $exptime);
  65
  66 // Like set(), but only stores in memcache if the key already exists.
  67 // returns TRUE on success else FALSE
  68 // Possible errors set are:
  69 //              MC_ERR_NOT_ACTIVE
  70 //              MC_ERR_GET_SOCK
  71 //              MC_ERR_SOCKET_WRITE
  72 //              MC_ERR_SOCKET_READ
  73 //              MC_ERR_SET
  74 MemCachedClient::replace($key, $value, $exptime);
  75
  76 // removes the key from the MemCache
  77 // $time is the amount of time in seconds (or Unix time) until which
  78 // the client wishes the server to refuse "add" and "replace" commands
  79 // with this key. For this amount of item, the item is put into a
  80 // delete queue, which means that it won't possible to retrieve it by
  81 // the "get" command, but "add" and "replace" command with this key
  82 // will also fail (the "set" command will succeed, however). After the
  83 // time passes, the item is finally deleted from server memory.
  84 // The parameter $time is optional, and, if absent, defaults to 0
  85 // (which means that the item will be deleted immediately and further
  86 // storage commands with this key will succeed).
  87 // returns TRUE on success else returns FALSE
  88 // Possible errors set are:
  89 //              MC_ERR_NOT_ACTIVE
  90 //              MC_ERR_GET_SOCK
  91 //              MC_ERR_SOCKET_WRITE
  92 //              MC_ERR_SOCKET_READ
  93 //              MC_ERR_DELETE
  94 MemCachedClient::delete($key, $time = 0);
  95
  96 // Sends a command to the server to atomically increment the value for
  97 // $key by $value, or by 1 if $value is undefined.  Returns FALSE if $key
  98 // doesn't exist on server, otherwise it returns the new value after
  99 // incrementing.  Value should be zero or greater.  Overflow on server
 100 // is not checked.  Be aware of values approaching 2**32.  See decr.
 101 // Possible errors set are:
 102 //              MC_ERR_NOT_ACTIVE
 103 //              MC_ERR_GET_SOCK
 104 //              MC_ERR_SOCKET_WRITE
 105 //              MC_ERR_SOCKET_READ
 106 // returns new value on success, else returns FALSE
 107 // ONLY WORKS WITH NUMERIC VALUES
 108 MemCachedClient::incr($key[, $value]);
 109
 110 // Like incr, but decrements.  Unlike incr, underflow is checked and new
 111 // values are capped at 0.  If server value is 1, a decrement of 2
 112 // returns 0, not -1.
 113 // Possible errors set are:
 114 //              MC_ERR_NOT_ACTIVE
 115 //              MC_ERR_GET_SOCK
 116 //              MC_ERR_SOCKET_WRITE
 117 //              MC_ERR_SOCKET_READ
 118 // returns new value on success, else returns FALSE
 119 // ONLY WORKS WITH NUMERIC VALUES
 120 MemCachedClient::decr($key[, $value]);
 121
 122 // disconnects from all servers
 123 MemCachedClient::disconnect_all();
 124
 125 // if $do_debug is set to true, will print out
 126 // debugging info, else debug is turned off
 127 MemCachedClient::set_debug($do_debug);
 128
 129 // remove all cached hosts that are no longer good
 130 MemCachedClient::forget_dead_hosts();
 131
 132 // When a function returns FALSE, an error code is set.
 133 // This funtion will return the error code.
 134 // See error_string()
 135 // returns last error code set
 136 MemCachedClient::error()
 137
 138 // Returns a string describing the error set in error()
 139 // See error()
 140 // returns a string describing the error code given
 141 MemCachedClient::error_string()
 142
 143 // Resets the error number and error string
 144 MemCachedClient::error_clear()
 145
 146 Error codes are as follows:
 147 MC_ERR_NOT_ACTIVE               // no active servers
 148 MC_ERR_SOCKET_WRITE             // socket_write() failed
 149 MC_ERR_SOCKET_READ              // socket_read() failed
 150 MC_ERR_SOCKET_CONNECT   // failed to connect to host
 151 MC_ERR_DELETE                   // delete() did not recieve DELETED command
 152 MC_ERR_HOST_FORMAT              // sock_to_host() invalid host format
 153 MC_ERR_HOST_DEAD                // sock_to_host() host is dead
 154 MC_ERR_GET_SOCK                 // get_sock() failed to find a valid socket
 155 MC_ERR_SET                              // _set() failed to receive the STORED response
 156 MC_ERR_LOADITEM_HEADER  // _load_items failed to receive valid data header
 157 MC_ERR_LOADITEM_END             // _load_items failed to receive END response
 158 MC_ERR_LOADITEM_BYTES   // _load_items bytes read larger than bytes available
 159 MC_ERR_GET                              // failed to get value associated with key
 160
 161 // Turns compression on or off; 0=off, 1=on
 162 MemCacheClient::set_compression($setting)
 163
 164 EXAMPLE:
 165 <?php
 166 require 'MemCachedClient.inc.php';
 167
 168 // set the servers, with the last one having an integer weight value of 3
 169 $options["servers"] = array("10.0.0.15:11000","10.0.0.16:11001",array("10.0.0.17:11002", 3));
 170 $options["debug"] = false;
 171
 172 $memc = new MemCachedClient($options);
 173
 174
 175 /***********************
 176  * STORE AN ARRAY
 177  ***********************/
 178 $myarr = array("one","two", 3);
 179 $memc->set("key_one", $myarr);
 180 $val = $memc->get("key_one");
 181 print $val[0]."\n";     // prints 'one'
 182 print $val[1]."\n";     // prints 'two'
 183 print $val[2]."\n";     // prints 3
 184
 185
 186 print "\n";
 187
 188
 189 /***********************
 190  * STORE A CLASS
 191  ***********************/
 192 class tester
 193 {
 194         var $one;
 195         var $two;
 196         var $three;
 197 }
 198
 199 $t = new tester;
 200 $t->one = "one";
 201 $t->two = "two";
 202 $t->three = 3;
 203 $memc->set("key_two", $t);
 204 $val = $memc->get("key_two");
 205 print $val->one."\n";
 206 print $val->two."\n";
 207 print $val->three."\n";
 208
 209
 210 print "\n";
 211
 212
 213 /***********************
 214  * STORE A STRING
 215  ***********************/
 216 $memc->set("key_three", "my string");
 217 $val = $memc->get("key_three");
 218 print $val;             // prints 'my string'
 219
 220 $memc->delete("key_one");
 221 $memc->delete("key_two");
 222 $memc->delete("key_three");
 223
 224 $memc->disconnect_all();
 225
 226
 227
 228 print "\n";
 229
 230
 231 /***********************
 232  * STORE A BINARY FILE
 233  ***********************/
 234
 235  // first read the file and save it in memcache
 236 $fp = fopen( "./image.jpg", "rb" ) ;
 237 if ( !$fp )
 238 {
 239         print "Could not open ./file.dat!\n" ;
 240         exit ;
 241 }
 242 $data = fread( $fp, filesize( "./image.jpg" ) ) ;
 243 fclose( $fp ) ;
 244 print "Data length is " . strlen( $data ) . "\n" ;
 245 $memc->set( "key", $data ) ;
 246
 247 // now open a file for writing and write the data
 248 // retrieved from memcache
 249 $fp = fopen("./test.jpg","wb");
 250 $data = $memc->get( "key" ) ;
 251 print "Data length is " . strlen( $data ) . "\n" ;
 252 fwrite($fp,$data,strlen( $data ));
 253 fclose($fp);
 254
 255
 256 ?>
 257
 258