Instead of storing the session data in a local file, it stores the data to
Cloud Datastore. The biggest benefit of doing this is the data can be
shared by multiple instances, so it's suitable for cloud applications.
The downside of using Cloud Datastore is the write operations will cost you
some money, so it is highly recommended to minimize the write operations
with your session data with this handler. In order to do so, keep the data
in the session as limited as possible; for example, it is ok to put only
signed-in state and the user id in the session with this handler. However,
for example, it is definitely not recommended that you store your
application's whole undo history in the session, because every user
operations will cause the Datastore write and then it will cost you lot of
money.
This handler doesn't provide pessimistic lock for session data. Instead, it
uses Datastore Transaction for data consistency. This means that if
multiple requests are modifying the same session data simultaneously, there
will be more probablity that some of the write operations will fail.
If you are building an ajax application which may issue multiple requests
to the server, please design the session data carefully, in order to avoid
possible data contentions. Also please see the 2nd example below for how to
properly handle errors on write operations.
It uses the session.save_path as the Datastore namespace for isolating the
session data from your application data, it also uses the session.name as
the Datastore kind, the session id as the Datastore id. By default, it
does nothing on gc for reducing the cost. Pass positive value up to 1000
for $gcLimit parameter to delete entities in gc.
Note: The datastore transaction only lasts 60 seconds. If this handler is
used for long running requests, it will fail on write.
Example without error handling:
use Google\Cloud\ServiceBuilder;
$cloud = new ServiceBuilder();
$datastore = $cloud->datastore();
or just $datastore = new \Google\Cloud\Datastore\DatastoreClient();
$handler = new DatastoreSessionHandler($datastore);
session_set_save_handler($handler, true);
session_save_path('sessions');
session_start();
Then read and write the $_SESSION array.
The above example automatically writes the session data. It's handy, but
the code doesn't stop even if it fails to write the session data, because
the write happens when the code exits. If you want to know the session
data is correctly written to the Datastore, you need to call
session_write_close() explicitly and then handle E_USER_WARNING
properly like the following example.
Example with error handling:
use Google\Cloud\ServiceBuilder;
$cloud = new ServiceBuilder();
$datastore = $cloud->datastore();
or just $datastore = new \Google\Cloud\Datastore\DatastoreClient();
$handler = new DatastoreSessionHandler($datastore);
session_set_save_handler($handler, true);
session_save_path('sessions');
session_start();
Then read and write the $_SESSION array.
function handle_session_error($errNo, $errStr, $errFile, $errLine) {
# We throw an exception here, but you can do whatever you need.
throw new Exception("$errStr in $errFile on line $errLine", $errNo);
}
set_error_handler('handle_session_error', E_USER_WARNING);
If write fails for any reason, an exception will be thrown.
session_write_close();
restore_error_handler();
You can still read the $_SESSION array after closing the session.
/**
* @expectedException PHPUnit_Framework_Error_Warning
*/
public function testGcWithException()
{
$key1 = new Key('projectid');
$key1->pathElement(self::KIND, 'sessionid1');
$key2 = new Key('projectid');
$key2->pathElement(self::KIND, 'sessionid2');
$entity1 = new Entity($key1);
$entity2 = new Entity($key2);
$query = $this->prophesize(Query::class);
$query->kind(self::KIND)->shouldBeCalledTimes(1)->willReturn($query->reveal());
$that = $this;
$query->filter(Argument::type('string'), Argument::type('string'), Argument::type('int'))->shouldBeCalledTimes(1)->will(function ($args) use($that, $query) {
$that->assertEquals('t', $args[0]);
$that->assertEquals('<', $args[1]);
$that->assertInternalType('int', $args[2]);
$diff = time() - $args[2];
// 2 seconds grace period should be enough
$that->assertTrue($diff <= 102);
$that->assertTrue($diff >= 100);
return $query->reveal();
});
$query->order('t')->shouldBeCalledTimes(1)->willReturn($query->reveal());
$query->keysOnly()->shouldBeCalledTimes(1)->willReturn($query->reveal());
$query->limit(1000)->shouldBeCalledTimes(1)->willReturn($query->reveal());
$this->datastore->transaction()->shouldBeCalledTimes(1)->willReturn($this->transaction->reveal());
$this->datastore->query()->shouldBeCalledTimes(1)->willReturn($query->reveal());
$this->datastore->runQuery(Argument::type(Query::class), Argument::type('array'))->shouldBeCalledTimes(1)->will(function ($args) use($that, $query, $entity1, $entity2) {
$that->assertEquals($query->reveal(), $args[0]);
$that->assertEquals(['namespaceId' => self::NAMESPACE_ID], $args[1]);
return [$entity1, $entity2];
});
$this->datastore->deleteBatch([$key1, $key2])->shouldBeCalledTimes(1)->willThrow(new Exception());
$datastoreSessionHandler = new DatastoreSessionHandler($this->datastore->reveal(), 1000);
$datastoreSessionHandler->open(self::NAMESPACE_ID, self::KIND);
$ret = $datastoreSessionHandler->gc(100);
$this->assertEquals(false, $ret);
}
