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
 162
 163 EXAMPLE:
 164 <?php
 165 require("MemCachedClient.inc.php");
 166
 167 // set the servers, with the last one having an interger weight value of 3
 168 $options["servers"] = array("10.0.0.15:11000","10.0.0.16:11001",array("10.0.0.17:11002", 3));
 169 $options["debug"] = false;
 170
 171 $memc = new MemCachedClient($options);
 172
 173
 174 /***********************
 175  * STORE AN ARRAY
 176  ***********************/
 177 $myarr = array("one","two", 3);
 178 $memc->set("key_one", $myarr);
 179 $val = $memc->get("key_one");
 180 print $val[0]."\n";     // prints 'one'
 181 print $val[1]."\n";     // prints 'two'
 182 print $val[2]."\n";     // prints 3
 183
 184
 185 print "\n";
 186
 187
 188 /***********************
 189  * STORE A CLASS
 190  ***********************/
 191 class tester
 192 {
 193         var $one;
 194         var $two;
 195         var $three;
 196 }
 197
 198 $t = new tester;
 199 $t->one = "one";
 200 $t->two = "two";
 201 $t->three = 3;
 202 $memc->set("key_two", $t);
 203 $val = $memc->get("key_two");
 204 print $val->one."\n";
 205 print $val->two."\n";
 206 print $val->three."\n";
 207
 208
 209 print "\n";
 210
 211
 212 /***********************
 213  * STORE A STRING
 214  ***********************/
 215 $memc->set("key_three", "my string");
 216 $val = $memc->get("key_three");
 217 print $val;             // prints 'my string'
 218
 219 $memc->delete("key_one");
 220 $memc->delete("key_two");
 221 $memc->delete("key_three");
 222
 223 $memc->disconnect_all();
 224
 225
 226
 227 print "\n";
 228
 229
 230 /***********************
 231  * STORE A BINARY FILE
 232  ***********************/
 233
 234  // first read the file and save it in memcache
 235 $fp = fopen( "./image.jpg", "rb" ) ;
 236 if ( !$fp )
 237 {
 238         print "Could not open ./file.dat!\n" ;
 239         exit ;
 240 }
 241 $data = fread( $fp, filesize( "./image.jpg" ) ) ;
 242 fclose( $fp ) ;
 243 print "Data length is " . strlen( $data ) . "\n" ;
 244 $memc->set( "key", $data ) ;
 245
 246 // now open a file for writing and write the data
 247 // retrieved from memcache
 248 $fp = fopen("./test.jpg","wb");
 249 $data = $memc->get( "key" ) ;
 250 print "Data length is " . strlen( $data ) . "\n" ;
 251 fwrite($fp,$data,strlen( $data ));
 252 fclose($fp);
 253
 254
 255 ?>
 256
 257