merging Connection & Explorer classes into one (BC break)

Author: dg

readme.md

@@ -59,7 +59,7 @@ Database Core
 To create a new database connection just create a new instance of `Nette\Database\Connection` class:
 
 ```php
-$database = new Nette\Database\Connection($dsn, $user, $password); // the same arguments as uses PDO
+$database = new Nette\Database\Explorer($dsn, $user, $password); // the same arguments as uses PDO
 ```
 
 Connection allows you to easily query your database by calling `query` method:

src/Bridges/DatabaseDI/DatabaseExtension.php

@@ -98,38 +98,30 @@ private function setupDatabase(\stdClass $config, string $name): void
 		$cacheId = 'Nette.Database.' . hash('xxh128', $name . $config->dsn);
 		$cache = new Statement(Nette\Caching\Cache::class, [1 => $cacheId]);
 
-		$connection = $builder->addDefinition($this->prefix("$name.connection"))
-			->setFactory(Nette\Database\Connection::class, [$config->dsn, $config->user, $config->password, $config->options])
+		$explorer = $builder->addDefinition($this->prefix($name))
+			->setFactory(Nette\Database\Explorer::class, [$config->dsn, $config->user, $config->password, $config->options])
+			->addSetup('setCache', [$cache])
 			->setAutowired($config->autowired);
 
-		$structure = $builder->addDefinition($this->prefix("$name.structure"))
-			->setFactory(Nette\Database\Structure::class)
-			->setArguments([new Statement([$connection, 'getDatabaseEngine']), $cache])
-			->setAutowired($config->autowired);
-
-		if (!$config->conventions) {
-			$conventions = null;
+		if (!$config->conventions || $config->conventions === 'discovered') {
 
 		} elseif (is_string($config->conventions)) {
 			$conventions = $builder->addDefinition($this->prefix("$name.conventions"))
 				->setFactory(preg_match('#^[a-z]+$#Di', $config->conventions)
 					? 'Nette\Database\Conventions\\' . ucfirst($config->conventions) . 'Conventions'
 					: $config->conventions)
-				->setArguments(strtolower($config->conventions) === 'discovered' ? [$structure] : [])
 				->setAutowired($config->autowired);
+			$explorer->addSetup('setConventions', [$conventions]);
 
 		} else {
-			$conventions = Nette\DI\Helpers::filterArguments([$config->conventions])[0];
+			$explorer->addSetup('setConventions', [Nette\DI\Helpers::filterArguments([$config->conventions])[0]]);
 		}
 
-		$builder->addDefinition($this->prefix("$name.explorer"))
-			->setFactory(Nette\Database\Explorer::class, [$connection, $structure, $conventions, $cache])
-			->setAutowired($config->autowired);
-
-		$builder->addAlias($this->prefix("$name.context"), $this->prefix("$name.explorer"));
+		$builder->addAlias($this->prefix("$name.connection"), $this->prefix($name));
+		$builder->addAlias($this->prefix("$name.context"), $this->prefix($name));
+		$builder->addAlias($this->prefix("$name.explorer"), $this->prefix($name));
 
 		if ($this->name === 'database') {
-			$builder->addAlias($this->prefix($name), $this->prefix("$name.connection"));
 			$builder->addAlias("nette.database.$name", $this->prefix($name));
 			$builder->addAlias("nette.database.$name.context", $this->prefix("$name.explorer"));
 		}

src/Bridges/DatabaseTracy/ConnectionPanel.php

@@ -10,8 +10,8 @@
 namespace Nette\Bridges\DatabaseTracy;
 
 use Nette;
-use Nette\Database\Connection;
 use Nette\Database\DriverException;
+use Nette\Database\Explorer;
 use Nette\Database\Helpers;
 use Nette\Database\Result;
 use Tracy;
@@ -34,7 +34,7 @@ class ConnectionPanel implements Tracy\IBarPanel
 
 
 	public static function initialize(
-		Connection $connection,
+		Explorer $explorer,
 		bool $addBarPanel = true,
 		string $name = '',
 		bool $explain = true,
@@ -46,7 +46,7 @@ public static function initialize(
 		$blueScreen->addPanel(self::renderException(...));
 
 		if ($addBarPanel) {
-			$panel = new self($connection, $blueScreen);
+			$panel = new self($explorer, $blueScreen);
 			$panel->explain = $explain;
 			$panel->name = $name;
 			$bar ??= Tracy\Debugger::getBar();
@@ -57,14 +57,14 @@ public static function initialize(
 	}
 
 
-	public function __construct(Connection $connection, Tracy\BlueScreen $blueScreen)
+	public function __construct(Explorer $explorer, Tracy\BlueScreen $blueScreen)
 	{
-		$connection->onQuery[] = $this->logQuery(...);
+		$explorer->onQuery[] = $this->logQuery(...);
 		$this->blueScreen = $blueScreen;
 	}
 
 
-	private function logQuery(Connection $connection, $result): void
+	private function logQuery(Explorer $connection, $result): void
 	{
 		if ($this->disabled) {
 			return;
@@ -82,7 +82,7 @@ private function logQuery(Connection $connection, $result): void
 				&& preg_match('~\.(php.?|phtml)$~', $row['file'])
 				&& !$this->blueScreen->isCollapsed($row['file']))
 				&& ($row['class'] ?? '') !== self::class
-				&& !is_a($row['class'] ?? '', Connection::class, allow_string: true)
+				&& !is_a($row['class'] ?? '', Explorer::class, allow_string: true)
 			) {
 				$source = [$row['file'], (int) $row['line']];
 				break;

src/Database/Connection.php renamed to src/Database/Explorer.php

@@ -11,13 +11,14 @@
 
 use JetBrains\PhpStorm\Language;
 use Nette;
+use Nette\Caching\Cache;
 use Nette\Utils\Arrays;
 
 
 /**
- * Represents a connection between PHP and a database server.
+ * The central access point to Nette Database functionality.
  */
-class Connection
+class Explorer
 {
 	private const Drivers = [
 		'pdo-mssql' => Drivers\PDO\MSSQL\Driver::class,
@@ -42,6 +43,9 @@ class Connection
 	private TypeConverter $typeConverter;
 	private ?SqlLiteral $lastQuery = null;
 	private int $transactionDepth = 0;
+	private ?Cache $cache = null;
+	private ?Conventions $conventions = null;
+	private ?IStructure $structure = null;
 
 
 	public function __construct(
@@ -385,4 +389,57 @@ public static function literal(string $value, ...$params): SqlLiteral
 	{
 		return new SqlLiteral($value, $params);
 	}
+
+
+	/********************* active row ****************d*g**/
+
+
+	public function table(string $table): Table\Selection
+	{
+		return new Table\Selection($this, $table);
+	}
+
+
+	public function setCache(Cache $cache): static
+	{
+		if (isset($this->structure)) {
+			throw new \LogicException('Cannot set cache after structure is created.');
+		}
+		$this->cache = $cache;
+		return $this;
+	}
+
+
+	/** @internal */
+	public function getCache(): ?Cache
+	{
+		return $this->cache;
+	}
+
+
+	public function setConventions(Conventions $conventions): static
+	{
+		if (isset($this->conventions)) {
+			throw new \LogicException('Conventions are already set.');
+		}
+		$this->conventions = $conventions;
+		return $this;
+	}
+
+
+	/** @internal */
+	public function getConventions(): Conventions
+	{
+		return $this->conventions ??= new Conventions\DiscoveredConventions($this->getStructure());
+	}
+
+
+	/** @internal */
+	public function getStructure(): IStructure
+	{
+		return $this->structure ??= new Structure($this->getDatabaseEngine(), $this->getCache());
+	}
 }
+
+
+class_exists(Connection::class);

src/Database/Helpers.php

@@ -75,7 +75,7 @@ public static function dumpResult(Result $result): void
 	/**
 	 * Returns syntax highlighted SQL command.
 	 */
-	public static function dumpSql(SqlLiteral $query, ?Connection $connection = null): string
+	public static function dumpSql(SqlLiteral $query, ?Explorer $explorer = null): string
 	{
 		$keywords1 = 'SELECT|(?:ON\s+DUPLICATE\s+KEY)?UPDATE|INSERT(?:\s+INTO)?|REPLACE(?:\s+INTO)?|DELETE|CALL|UNION|FROM|WHERE|HAVING|GROUP\s+BY|ORDER\s+BY|LIMIT|OFFSET|SET|VALUES|LEFT\s+JOIN|INNER\s+JOIN|TRUNCATE';
 		$keywords2 = 'ALL|DISTINCT|DISTINCTROW|IGNORE|AS|USING|ON|AND|OR|IN|IS|NOT|NULL|[RI]?LIKE|REGEXP|TRUE|FALSE';
@@ -110,7 +110,7 @@ public static function dumpSql(SqlLiteral $query, ?Connection $connection = null
 
 		// parameters
 		$params = $query->getParameters();
-		$sql = preg_replace_callback('#\?#', function () use ($params, $connection): string {
+		$sql = preg_replace_callback('#\?#', function () use ($params, $explorer): string {
 			static $i = 0;
 			$param = $params[$i++] ?? null;
 			if ($param === null) {
@@ -128,7 +128,7 @@ public static function dumpSql(SqlLiteral $query, ?Connection $connection = null
 			} elseif (is_string($param)) {
 				$length = Nette\Utils\Strings::length($param);
 				$truncated = Nette\Utils\Strings::truncate($param, self::$maxLength);
-				$text = htmlspecialchars($connection ? $connection->quote($truncated) : '\'' . $truncated . '\'', ENT_NOQUOTES, 'UTF-8');
+				$text = htmlspecialchars($explorer ? $explorer->quote($truncated) : '\'' . $truncated . '\'', ENT_NOQUOTES, 'UTF-8');
 				return '<span title="Length ' . $length . ' characters">' . $text . '</span>';
 
 			} elseif (is_resource($param)) {
@@ -157,7 +157,7 @@ public static function dumpSql(SqlLiteral $query, ?Connection $connection = null
 	 * @param  ?array<callable(int, ?float): void>  $onProgress
 	 * @return int  count of commands
 	 */
-	public static function loadFromFile(Connection $connection, string $file, ?callable $onProgress = null): int
+	public static function loadFromFile(Explorer $explorer, string $file, ?callable $onProgress = null): int
 	{
 		@set_time_limit(0); // @ function may be disabled
 
@@ -170,7 +170,7 @@ public static function loadFromFile(Connection $connection, string $file, ?calla
 		$count = $size = 0;
 		$delimiter = ';';
 		$sql = '';
-		$connection = $connection->getConnection(); // native query without logging
+		$connection = $explorer->getConnection(); // native query without logging
 		while (($s = fgets($handle)) !== false) {
 			$size += strlen($s);
 			if (!strncasecmp($s, 'DELIMITER ', 10)) {
@@ -204,7 +204,7 @@ public static function loadFromFile(Connection $connection, string $file, ?calla
 
 	/** @deprecated  use Nette\Bridges\DatabaseTracy\ConnectionPanel::initialize() */
 	public static function createDebugPanel(
-		Connection $connection,
+		Explorer $connection,
 		bool $explain,
 		string $name,
 		Tracy\Bar $bar,
@@ -218,7 +218,7 @@ public static function createDebugPanel(
 
 	/** @deprecated  use Nette\Bridges\DatabaseTracy\ConnectionPanel::initialize() */
 	public static function initializeTracy(
-		Connection $connection,
+		Explorer $connection,
 		bool $addBarPanel = false,
 		string $name = '',
 		bool $explain = true,

src/Database/Result.php

@@ -27,7 +27,7 @@ class Result implements \Iterator
 
 
 	public function __construct(
-		private readonly Connection $connection,
+		private readonly Explorer $explorer,
 		private readonly SqlLiteral $query,
 		private readonly ?Drivers\Result $result,
 		private float $time,
@@ -36,10 +36,10 @@ public function __construct(
 
 
 	/** @deprecated */
-	public function getConnection(): Connection
+	public function getConnection(): Explorer
 	{
 		trigger_error(__METHOD__ . '() is deprecated.', E_USER_DEPRECATED);
-		return $this->connection;
+		return $this->explorer;
 	}
 
 
@@ -237,8 +237,8 @@ private function normalizeRow(array $row): array
 	private function chooseColumnConverters(): array
 	{
 		$res = [];
-		$engine = $this->connection->getDatabaseEngine();
-		$converter = $this->connection->getTypeConverter();
+		$engine = $this->explorer->getDatabaseEngine();
+		$converter = $this->explorer->getTypeConverter();
 		foreach ($this->result->getColumnsInfo() as $meta) {
 			$res[$meta['name']] = isset($meta['nativeType'])
 				? $engine->chooseColumnConverter($meta, $converter)

src/Database/SqlPreprocessor.php

@@ -59,10 +59,10 @@ class SqlPreprocessor
 	private ?string $arrayMode;
 
 
-	public function __construct(Connection $connection)
+	public function __construct(Explorer $explorer)
 	{
-		$this->connection = $connection->getConnection();
-		$this->engine = $connection->getDatabaseEngine();
+		$this->connection = $explorer->getConnection();
+		$this->engine = $explorer->getDatabaseEngine();
 	}
 
 

src/compatibility.php

@@ -26,3 +26,11 @@ class ResultSet extends Result
 } elseif (!class_exists(ResultSet::class)) {
 	class_alias(Result::class, ResultSet::class);
 }
+
+if (false) {
+	class Connection extends Explorer
+	{
+	}
+} elseif (!class_exists(Connection::class)) {
+	class_alias(Explorer::class, Connection::class);
+}

tests/Database.DI/DatabaseExtension.basic.phpt

@@ -36,18 +36,12 @@ test('', function () {
 	$container = new Container1;
 	$container->initialize();
 
-	$connection = $container->getService('database.default');
-	Assert::type(Nette\Database\Connection::class, $connection);
-
-	$explorer = $container->getService('database.default.explorer');
+	$explorer = $container->getService('database.default');
 	Assert::type(Nette\Database\Explorer::class, $explorer);
-	Assert::same($connection, $explorer->getConnection());
-	Assert::same($container->getService('database.default.context'), $explorer);
-
-	Assert::type(Nette\Database\Structure::class, $explorer->getStructure());
-	Assert::type(Nette\Database\Conventions\DiscoveredConventions::class, $explorer->getConventions());
+	Assert::type(Nette\Caching\Cache::class, $explorer->getCache());
 
 	// aliases
-	Assert::same($connection, $container->getService('nette.database.default'));
+	Assert::same($explorer, $container->getService('database.default.explorer'));
+	Assert::same($explorer, $container->getService('nette.database.default'));
 	Assert::same($explorer, $container->getService('nette.database.default.context'));
 });

tests/Database.DI/DatabaseExtension.multiple.phpt

@@ -41,22 +41,13 @@ test('', function () {
 	$container = new Container1;
 	$container->initialize();
 
-	$connection = $container->getService('database.first');
-	Assert::type(Nette\Database\Connection::class, $connection);
-	Assert::same($connection, $container->getByType(Nette\Database\Connection::class));
-
-	$explorer = $container->getService('database.first.explorer');
+	$explorer = $container->getService('database.first');
 	Assert::type(Nette\Database\Explorer::class, $explorer);
 	Assert::same($explorer, $container->getByType(Nette\Database\Explorer::class));
-	Assert::same($connection, $explorer->getConnection());
-	Assert::same($container->getService('database.first.context'), $explorer);
-
-	Assert::type(Nette\Database\Structure::class, $explorer->getStructure());
-	Assert::same($explorer->getStructure(), $container->getByType(Nette\Database\IStructure::class));
-	Assert::type(Nette\Database\Conventions\DiscoveredConventions::class, $explorer->getConventions());
-	Assert::same($explorer->getConventions(), $container->getByType(Nette\Database\Conventions::class));
+	Assert::type(Nette\Caching\Cache::class, $explorer->getCache());
 
 	// aliases
-	Assert::same($connection, $container->getService('nette.database.first'));
+	Assert::same($explorer, $container->getService('database.first.explorer'));
+	Assert::same($explorer, $container->getService('nette.database.first'));
 	Assert::same($explorer, $container->getService('nette.database.first.context'));
 });