Cursor (#7)

Author: Charlotte Dunois

.gitignore

@@ -1,3 +1,5 @@
+.idea
+.idea/*
 cache
 cache/*
 sami/*

src/Client.php

@@ -330,6 +330,28 @@ function runQuery(\Plasma\QueryBuilderInterface $query): \React\Promise\PromiseI
  }
  }
 
+ /**
+ * Creates a new cursor to seek through SELECT query results.
+ * @param string $query
+ * @param array $params
+ * @return \React\Promise\PromiseInterface
+ * @throws \Plasma\Exception
+ */
+ function createCursor(string $query, array $params = array()): \React\Promise\PromiseInterface {
+ if($this->goingAway) {
+ return \React\Promise\reject((new \Plasma\Exception('Client is closing all connections')));
+ }
+ 
+ $connection = $this->getOptimalConnection();
+ 
+ try {
+ return $connection->createCursor($this, $query, $params);
+ } catch (\Throwable $e) {
+ $this->checkinConnection($connection);
+ throw $e;
+ }
+ }
+ 
  /**
  * Get the optimal connection.
  * @return \Plasma\DriverInterface

src/ClientInterface.php

@@ -81,4 +81,13 @@ function quit(): void;
  * @throws \Plasma\Exception Thrown if the client is closing all connections.
  */
  function runCommand(\Plasma\CommandInterface $command);
+ 
+ /**
+ * Creates a new cursor to seek through SELECT query results.
+ * @param string $query
+ * @param array $params
+ * @return \React\Promise\PromiseInterface
+ * @throws \Plasma\Exception
+ */
+ function createCursor(string $query, array $params = array()): \React\Promise\PromiseInterface;
 }

src/CursorInterface.php

@@ -0,0 +1,37 @@
+<?php
+/**
+ * Plasma Core component
+ * Copyright 2018-2019 PlasmaPHP, All Rights Reserved
+ *
+ * Website: https://github.com/PlasmaPHP
+ * License: https://github.com/PlasmaPHP/core/blob/master/LICENSE
+ */
+
+namespace Plasma;
+
+/**
+ * The cursor interface describes how a cursor can be accessed to fetch rows
+ * from the server interactively.
+ */
+interface CursorInterface {
+ /**
+ * Whether the cursor has been closed.
+ * @return bool
+ */
+ function isClosed(): bool;
+ 
+ /**
+ * Closes the cursor and frees the associated resources on the server.
+ * Closing a cursor more than once has no effect.
+ * @return \React\Promise\PromiseInterface
+ */
+ function close(): \React\Promise\PromiseInterface;
+ 
+ /**
+ * Fetches the given amount of rows using the cursor. Resolves with the row, an array of rows (if amount > 1), or false if no more results exist.
+ * @param int $amount
+ * @return \React\Promise\PromiseInterface
+ * @throws \Plasma\Exception Thrown if the underlying statement has been closed.
+ */
+ function fetch(int $amount = 1): \React\Promise\PromiseInterface;
+}

src/DriverInterface.php

@@ -250,4 +250,14 @@ function runCommand(\Plasma\ClientInterface $client, \Plasma\CommandInterface $c
  * @throws \Plasma\Exception
  */
  function runQuery(\Plasma\ClientInterface $client, \Plasma\QueryBuilderInterface $query): \React\Promise\PromiseInterface;
+ 
+ /**
+ * Creates a new cursor to seek through SELECT query results.
+ * @param \Plasma\ClientInterface $client
+ * @param string $query
+ * @param array $params
+ * @return \React\Promise\PromiseInterface
+ * @throws \Plasma\Exception
+ */
+ function createCursor(\Plasma\ClientInterface $client, string $query, array $params = array()): \React\Promise\PromiseInterface;
 }

tests/ClientTest.php

@@ -413,6 +413,33 @@ function testRunQueryGoingAway() {
  $this->await($promise);
  }
 
+ function testCreateCursor() {
+ $client = $this->createClient();
+ 
+ $query = 'SELECT 1';
+ 
+ $this->driver
+ ->expects($this->once())
+ ->method('createCursor')
+ ->with($client, $query, array())
+ ->will($this->returnValue(\React\Promise\resolve()));
+ 
+ $promise = $client->createCursor('SELECT 1', array());
+ $this->assertInstanceOf(\React\Promise\PromiseInterface::class, $promise);
+ }
+ 
+ function testCreateCursorGoingAway() {
+ $client = $this->createClient();
+ 
+ $this->assertNull($client->quit());
+ 
+ $promise = $client->createCursor('SELECT 1', array());
+ $this->assertInstanceOf(\React\Promise\PromiseInterface::class, $promise);
+ 
+ $this->expectException(\Plasma\Exception::class);
+ $this->await($promise);
+ }
+ 
  function testLazyCreateConnection() {
  $client = $this->createClient(array('connections.lazy' => true));
 

tests/ClientTestHelpers.php

@@ -95,6 +95,7 @@ function getDriverMock(): \Plasma\DriverInterface {
  'endTransaction',
  'runCommand',
  'runQuery',
+ 'createCursor',
  'listeners',
  'on',
  'once',