[Summary view] [Print] [Text view]

   1  Ryan Gilfether <[email protected]>
   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