PHP SDK 2.0.6 - how to read expiration?


How to read the expiration (meta data) of a document stored in Couchbase in PHP SDK 2.0.6?
I was checking the documentation and couldn’t find it anywhere and $this->_bucket->get(ID); doesn’t brings over the expiration value.


The expiration value is not one of the pieces of metadata returned by the server in the protocol. It can be mutated, but not fetched. Maybe @mnunberg can help identify a way to fetch it?


The expiration is not available via get(). You can determine the expiration by using the cbc commandline, e.g.

mnunberg@mbp15 ~ $ cbc stats --keystats foo -U couchbase://	key_is_dirty	0	key_exptime	0	key_flags	0	key_cas	1428075874435123000	key_vb_state	active	key_is_dirty	0	key_exptime	0	key_flags	0	key_cas	1428075874435123000	key_vb_state	replica

The metadata should mainly be used for informational purposes, and is not intended to be exposed at a programmatic level to clients. Additionally, such functionality is not available in the PHP SDK .


Thank you both.

I was working on a new sessionHandler for PHP which is using the old $_SESSION and stores the session data in JSON format too and wanted not to update the expiration value every time when there is session read, but only if the new expiration would be significantly different than the current one, hence saving some writes, as I have replication set for the bucket.

I will check back later to see whether future versions of the PHP SDK allows the retrieval of the expiration value and then will enhance my session handler with it.



In general the command used to get the expiration time is not very efficient. I suppose you can set the expiration info inside the session data itself?

Additionally, there is the getAndTouch() method (I’m not sure if that’s the name used in the PHP SDK) but it basically allows you to read the value and update the expiration in the same server operation.


Thanks, yes, there is a getAndTouch() in the PHP SDK, that is what I’m using to extend the session when the user shows activity, I was just hoping I can avoid it to be called everytime when a session read is performed, by checking the current expiration time and change it only if it would change significantly and by doing that saving some writes.


Well, there’s also a plain touch() which basically accomplishes the same without reading :slight_smile: – you can do the entire expiry tracking in your application. The only thing to consider is if something outside the control of your application happens to modify the item without setting the expiry.


Thanks, you are right, I could also store the expiration in the document itself and read it from there. It should be fine, as only the sessionhandler modifies those documents storing the session.
Unfortunately - at least based on the documentation - there is no plain touch() function in the PHP SDK, only the readAndTouch().


This would be a bug then :slight_smile: – Feel free to file one in our issue tracker as a feature request. @brett19 – any reason it’s not there?


Good idea. I have raised a feature request then, see:


I just realized that while technically this could work, it wouldn’t help much, as that means that every time I need to update the expiry I would need to update (upsert) the whole document just to update the expiry value stored in it.
Likely that this would not save me on writes, as I do have fairly big documents (15-20 session variables).

What I was trying to achieve is not to update the meta value “expiration” at every time when a session variable is read (via the touch()), but I thought I could check the current value of “expiration” and only update it if it would change significantly (more than just a few seconds).
If I store the “expiration” in the document, then the only way updating this “expiration” value in the document is by updating the whole document. Which makes it questionable whether I have saved anything at all on the writes, as earlier couchbase was only updating the “expiration” meta value, which now it needs to update the whole document.


What I meant is that you could do something like this… (as above, this assumes that all access to the document is done via your app):

You can have a script-side cache mapping keys and their expiry times. If you encounter a key that is not in the cache, you can either touch() or getAndTouch() (depending which is more suitable) and then store the new expiration time in your client-side state.

Now, whenever you want to read the session object (by “read”, i’m assuming you mean accessing it locally in your application), you simply check the application-side expiry (which should be the same as the one you set during first access), and then do the logic as appropriate.

As it turns out, you can update the expiry:

  • As a standalone operation, touch() – use this when reading something stored locally in the client side object. All you want is to ensure the item still stays alive, but you don’t actually need to read it from the network (since you’re relying on cached data)
  • During retrieval (getAndTouch) – use this when reading something from the cluster for the first time. i.e. when it’s not in your application-local cache, * During mutation (upsert() family methods, which all accept expiry). You can simply set the expiry each time, assuming the intent is to provide a “keep alive” expiration.


Okey, I understand what you meant now. Unfortunately there is no script-side cache to map the keys and their expiry times, so that is not an option.
I thought you mean writing the expiry to the Couchbase document, so I can read that, while I can’t read the ‘expiration’ value from the meta of the document.


I’d still recommend you use touch(). Keep in mind that just blindly setting the expiration time on the server (one command) is more efficient than using two commands (checking what the current expiry is, and, if it’s too old, refreshing the expiry again).


I’ve been monitoring this thread for a while, so sorry for chiming in out of nowhere:

Are you suggesting the touch() method after it’s implemented in a new version of the SDK? Because, I don’t see it documented anywhere as of 2.0.6.

I did read above where it was formally requested in [a] future versions. I’m just curious if I’m understanding you correctly where I interpret what you’re saying as we should use something that isn’t even available, yet.


Thanks, yes, today I’m “blindly” using readAndTouch() everytime to set the expiration time on the server independently of its current value. When touch() will become available (Brett has added it to the upcoming version - ) I will switch over to that.

My guess was that a read operation is about as expensive as a write operation as long as we talk about a single server, so replacing a write with a read wouldn’t save much. But when the bucket is replicated (like in my case), saving a write by having a read sounded like a good idea. (it was estimated that 90% of the times the read would determine that there is no need for a write [update of the expiration data])

In any case, as I cannot read the expiration date from the meta tags and while I could store it in the document itself (no app-side cache), then writing it requires rewriting the whole document (upsert() or replace()), I believe I wouldn’t gain much if any over just using readAndTouch() [or touch() when that becomes available].

So for now I stick to readAndTouch() and switch to touch() when the next version of the PHP API is out.



Hi Erutan,
No, I have raised the feature request to have touch() added to the PHP API on Saturday and Brett has added it to the trunk Monday, but that means it will be only available in the next PHP API version (whenever that comes).
At least that is my understanding.
See Jira ticket:


Right. The feature request is what I was referring to, previously. I’m in the process of building my library, so that’s why I was curious.


PHP SDK 2.0.6 - Wrong version number

touch() isn’t a new feature. it’s just something that was left out as an oversight, as it is one of the less common methods used (though highly useful in your use case). I believe it was present in the old SDK (1.x) and is available in every other SDK, as far as I know.


Hi Erutan409,
I just saw that the PHP API 2.0.7 is out and now the touch() function is included in it, as the JIRA ticket above requested that.
I already upgraded and started using it.