Page MenuHomeDevCentral
Files F11726330

No OneTemporary
Actions

View Options

diff --git a/README.md b/README.md
index 4cc5a29..fcf3657 100644
--- a/README.md
+++ b/README.md
@@ -1,54 +1,99 @@
# keruald/database
This library offers a simple layer of abstraction for database operations.
## Configuration
To get a database instance, you need to pass configuration as an array.
The properties and values depend on the engine you want to use.
### MySQLi
| Key | Value | |
|----------|--------------------------------------|:--------:|
| engine | MySQLiEngine class reference | |
| host | The MySQL hostname, e.g. "localhost" | |
| username | The MySQL user to use for connection | |
| password | The clear text password to use | |
| database | The default db to select for queries | optional |
For example:
```php
[
'engine' => Keruald\Database\Engines\MySQLiEngine::class,
'host' => 'localhost',
'username' => 'app',
'password' => 'someSecret',
'database' => 'app', // optional
]
```
## Legacy drivers
The mysql extension has been deprecated in PHP 5.7 and removed in PHP 7.
As such, this extension isn't supported anymore. You can use straightforwardly
replace 'MySQL' by 'MySQLi' as engine.
-## Specialized drivers
+## Specialized drivers for tests
### Blackhole
The blackhole engine does nothing and always returns `true` as query result.
This engine can be used for mocks:
- directly, when database behavior does not matter
- to build a mock by overriding behavior of query() or any other method
It can also be used with the loader, without any engine-specific configuration:
```php
[
'engine' => Keruald\Database\Engines\BlackholeEngine::class,
]
```
+
+### MockDatabaseEngine
+
+The mock database is a simple implementation of the blackhole engine as mocking
+service to use when you want to return a deterministic response to known
+queries.
+
+A benefit is you don't need a running database server for your unit tests.
+
+You can pass to the `withQueries` method an array with one item per query:
+ - key: the SQL query
+ - value: an array with all rows for that query
+ -
+For example:
+
+```php
+ public function testGetFruits () : void {
+ $queries = [
+ "SELECT name, color FROM fruits" => [
+ [ "name" => "strawberry", "color" => "red" ],
+ [ "name" => "blueberry", "color" => "violet" ],
+ ],
+ ];
+
+ $db = (new MockDatabaseEngine())
+ ->withQueries($queries);
+
+ // Inject $db to a class and test it
+ }
+```
+
+To return only one row, you can use `[[…]]` to represent an array of one array:
+
+```php
+ $queries = [
+ "SELECT 1+1" => [[ "1+1" => 2 ]],
+ ];
+```
+
+The queries results are then wrapped in the MockDatabaseResult class.
+
+When the query doesn't exist, an exception is thrown.
+
+We recommend a mixed approach of the Blackhole engine when results don't matter,
+and of this class when you need some control on it.
diff --git a/src/Engines/BlackholeEngine.php b/src/Engines/BlackholeEngine.php
index ff67774..f12924c 100644
--- a/src/Engines/BlackholeEngine.php
+++ b/src/Engines/BlackholeEngine.php
@@ -1,42 +1,43 @@
<?php
namespace Keruald\Database\Engines;
use Keruald\Database\DatabaseEngine;
+use Keruald\Database\Result\DatabaseResult;
class BlackholeEngine extends DatabaseEngine {
public function escape (string $expression) : string {
return $expression;
}
- public function query (string $query) : bool {
+ public function query (string $query) : bool|DatabaseResult {
return true;
}
public function nextId () : int|string {
return 0;
}
public function countAffectedRows () : int {
return 0;
}
protected function getExceptionContext () : array {
return [];
}
public static function load (array $config): DatabaseEngine {
return new self;
}
public function getUnderlyingDriver () : mixed {
return null;
}
public function isExistingTable (string $database, string $table) : bool {
// Everything and nothing exists in a blackhole
return true;
}
}
diff --git a/src/Engines/MockDatabaseEngine.php b/src/Engines/MockDatabaseEngine.php
new file mode 100644
index 0000000..2c3fbe9
--- /dev/null
+++ b/src/Engines/MockDatabaseEngine.php
@@ -0,0 +1,32 @@
+<?php
+
+namespace Keruald\Database\Engines;
+
+use Keruald\Database\DatabaseEngine;
+use Keruald\Database\Result\DatabaseResult;
+use Keruald\Database\Result\MockDatabaseResult;
+
+use RuntimeException;
+
+class MockDatabaseEngine extends BlackholeEngine {
+
+ private array $query_results = [];
+
+ public function withQueries(array $query_results) : self {
+ $this->query_results = $query_results;
+
+ return $this;
+ }
+
+ public function query (string $query) : DatabaseResult|bool {
+ if (!array_key_exists($query, $this->query_results)) {
+ throw new RuntimeException("Unexpected query: " . $query);
+ }
+
+ return new MockDatabaseResult($this->query_results[$query]);
+ }
+
+ public static function load (array $config) : DatabaseEngine {
+ return new self;
+ }
+}
diff --git a/src/Result/MockDatabaseResult.php b/src/Result/MockDatabaseResult.php
new file mode 100644
index 0000000..07ae987
--- /dev/null
+++ b/src/Result/MockDatabaseResult.php
@@ -0,0 +1,42 @@
+<?php
+
+namespace Keruald\Database\Result;
+
+use ArrayIterator;
+use Traversable;
+
+class MockDatabaseResult extends DatabaseResult {
+
+ ///
+ /// Constructor
+ ///
+
+ public function __construct (private readonly array $results) {
+ }
+
+ ///
+ /// IteratorAggregate
+ ///
+
+ public function getIterator () : Traversable {
+ return new ArrayIterator($this->results);
+ }
+
+ ///
+ /// DatabaseResult
+ ///
+
+ public function numRows () : int {
+ return count($this->results);
+ }
+
+ public function fetchRow () : ?array {
+ static $position = 0;
+
+ if ($position < $this->numRows()) {
+ return $this->results[$position];
+ }
+
+ return null;
+ }
+}
diff --git a/tests/Engines/MockDatabaseEngineTest.php b/tests/Engines/MockDatabaseEngineTest.php
new file mode 100644
index 0000000..30b269a
--- /dev/null
+++ b/tests/Engines/MockDatabaseEngineTest.php
@@ -0,0 +1,69 @@
+<?php
+
+namespace Keruald\Database\Tests\Engines;
+
+use Keruald\Database\Engines\MockDatabaseEngine;
+
+use Keruald\Database\Result\DatabaseResult;
+use PHPUnit\Framework\TestCase;
+
+class MockDatabaseEngineTest extends TestCase {
+
+ private MockDatabaseEngine $db;
+
+ const QUERY = "SELECT name, color FROM fruits";
+
+ const RESULT = [
+ [ "name" => "strawberry", "color" => "red" ],
+ [ "name" => "blueberry", "color" => "violet" ],
+ ];
+
+ protected function setUp () : void {
+ $queries = [
+ self::QUERY => self::RESULT,
+ ];
+
+ $this->db = (new MockDatabaseEngine())
+ ->withQueries($queries);
+ }
+
+ public function testNumRowsWithoutRequest () {
+ $this->assertEquals(0, $this->db->numRows());
+ }
+
+ public function testNumRowsWithRequest () {
+ $result = $this->db->query(self::QUERY);
+
+ $this->assertEquals(2, $this->db->numRows($result));
+ }
+
+ public function testQuery () {
+ $result = $this->db->query(self::QUERY);
+
+ $this->assertInstanceOf(DatabaseResult::class, $result);
+ $this->assertEquals(self::RESULT[0], $result->fetchRow());
+ }
+
+ public function testLoad () {
+ $db = MockDatabaseEngine::load([]);
+
+ $this->assertInstanceOf(MockDatabaseEngine::class, $db);
+ }
+
+ public function testFetchRow () {
+ $result = $this->db->query(self::QUERY);
+
+ $this->assertEquals(self::RESULT[0], $this->db->fetchRow($result));
+ }
+
+ public function testWithQueriesFollowsChainingPattern () {
+ $queries = [
+ self::QUERY => self::RESULT,
+ ];
+
+ $db = new MockDatabaseEngine();
+ $db = $db->withQueries($queries);
+
+ $this->assertInstanceOf(MockDatabaseEngine::class, $db);
+ }
+}
diff --git a/tests/Result/MockDatabaseResultTest.php b/tests/Result/MockDatabaseResultTest.php
new file mode 100644
index 0000000..6a2a777
--- /dev/null
+++ b/tests/Result/MockDatabaseResultTest.php
@@ -0,0 +1,40 @@
+<?php
+
+namespace Keruald\Database\Tests\Result;
+
+use Keruald\Database\Result\MockDatabaseResult;
+use PHPUnit\Framework\TestCase;
+
+class MockDatabaseResultTest extends TestCase {
+
+ const RESULT = [
+ [ "name" => "strawberry", "color" => "red" ],
+ [ "name" => "blueberry", "color" => "violet" ],
+ ];
+
+ private MockDatabaseResult $result;
+
+ protected function setUp () : void {
+ $this->result = new MockDatabaseResult(self::RESULT);
+ }
+
+ public function testFetchRow () {
+ $this->assertEquals(
+ [ "name" => "strawberry", "color" => "red" ],
+ $this->result->fetchRow(),
+ );
+ }
+
+ public function testNumRows () {
+ $this->assertEquals(2, $this->result->numRows());
+ }
+
+ public function testGetIterator () {
+ $i = 0;
+ foreach ($this->result as $row) {
+ $this->assertEquals(self::RESULT[$i], $row);
+ $i++;
+ }
+ }
+
+}

File Metadata

Mime Type
text/x-diff
Expires
Fri, Sep 19, 02:53 (1 d, 11 h)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
2992096
Default Alt Text
(9 KB)

Event Timeline

Nasqueron DevCentral · If it had been much bigger the moon would have had a core of ice. · Powered by Phabricator