DB: Result - move parsing column values into separate object [WIP: docs]

Author: forrest79

docs/db.md

@@ -314,15 +314,6 @@ dump($columns); // (array) ['id', 'nick', 'active']
 
 All row data (columns) are automatically parsed to the correct PHP types (detected from the DB column type - but no DB structure is read, PG send type of all columns in the result).
 
-You can get your own data (manually passed, not from DB) parsed to the same type as have the column in the result:
-
-```php
-$result = $connection->query('SELECT id, nick, active FROM users');
-
-$data = $result->parseColumnValue('id', '123');
-dump($data); // (integer) 123
-```
-
 On the result object, we can also check what columns were accessed in our application. You can check this before your request ends, and you can get possible columns that are unnecessary to be selected from the DB:
 
 ```php

phpcs-ignores.neon

@@ -96,8 +96,8 @@ ignoreErrors:
 		path: src/Db/AsyncQuery.php
 
 	-
-		sniff: Squiz.Scope.MethodScope.Missing
-		message: Visibility must be declared on method "parseColumnValue"
+		sniff: SlevomatCodingStandard.Classes.RequireAbstractOrFinal.ClassNeitherAbstractNorFinal
+		message: All classes should be declared using either the "abstract" or "final" keyword.
 		count: 1
 		path: src/Db/ColumnValueParser.php
 
@@ -141,19 +141,13 @@ ignoreErrors:
 		sniff: SlevomatCodingStandard.Classes.RequireAbstractOrFinal.ClassNeitherAbstractNorFinal
 		message: All classes should be declared using either the "abstract" or "final" keyword.
 		count: 1
-		path: src/Db/DummyColumnValueParser.php
-
-	-
-		sniff: SlevomatCodingStandard.Functions.UnusedParameter.UnusedParameter
-		message: Unused parameter $column.
-		count: 1
-		path: src/Db/DummyColumnValueParser.php
+		path: src/Db/Events.php
 
 	-
 		sniff: SlevomatCodingStandard.Classes.RequireAbstractOrFinal.ClassNeitherAbstractNorFinal
 		message: All classes should be declared using either the "abstract" or "final" keyword.
 		count: 1
-		path: src/Db/Events.php
+		path: src/Db/Exceptions/ColumnValueParserException.php
 
 	-
 		sniff: SlevomatCodingStandard.Classes.RequireAbstractOrFinal.ClassNeitherAbstractNorFinal

src/Db/ColumnValueParser.php

@@ -2,9 +2,49 @@
 
 namespace Forrest79\PhPgSql\Db;
 
-interface ColumnValueParser
+class ColumnValueParser
 {
+	private DataTypeParser $dataTypeParser;
 
-	function parseColumnValue(string $column, mixed $rawValue): mixed;
+	/** @var array<string, string> */
+	private array $columnsDataTypes;
+
+	/** @var array<string, bool> */
+	private array $parsedColumns = [];
+
+
+	/**
+	 * @param array<string, string> $columnsDataTypes
+	 */
+	public function __construct(DataTypeParser $dataTypeParser, array $columnsDataTypes)
+	{
+		$this->dataTypeParser = $dataTypeParser;
+		$this->columnsDataTypes = $columnsDataTypes;
+	}
+
+
+	/**
+	 * @throws Exceptions\ColumnValueParserException
+	 */
+	public function parseColumnValue(string $column, string|null $rawValue): mixed
+	{
+		$value = $this->dataTypeParser->parse(
+			$this->columnsDataTypes[$column] ?? throw Exceptions\ColumnValueParserException::noColumn($column),
+			$rawValue,
+		);
+
+		$this->parsedColumns[$column] = true;
+
+		return $value;
+	}
+
+
+	/**
+	 * @return list<string>
+	 */
+	public function getParsedColumns(): array
+	{
+		return array_keys($this->parsedColumns);
+	}
 
 }

src/Db/DummyColumnValueParser.php

@@ -0,0 +1,15 @@
+<?php declare(strict_types=1);
+
+namespace Forrest79\PhPgSql\Db\Exceptions;
+
+class ColumnValueParserException extends Exception
+{
+	public const int NO_COLUMN = 1;
+
+
+	public static function noColumn(string $column): self
+	{
+		return new self(\sprintf('There is no column \'%s\'.', $column), self::NO_COLUMN);
+	}
+
+}

src/Db/Exceptions/ColumnValueParserException.php

@@ -6,6 +6,7 @@ class RowException extends Exception
 {
 	public const int NO_COLUMN = 1;
 	public const int NOT_STRING_KEY = 2;
+	public const int COLUMN_VALUE_PARSER_MISSING = 3;
 
 
 	public static function noColumn(string $column): self
@@ -19,4 +20,10 @@ public static function notStringKey(): self
 		return new self('Requested key must be string.', self::NOT_STRING_KEY);
 	}
 
+
+	public static function columnValueParserMissing(): self
+	{
+		return new self('You must pass the ColumnValueParser, if there are some rawValues.', self::COLUMN_VALUE_PARSER_MISSING);
+	}
+
 }

src/Db/Exceptions/RowException.php

@@ -4,7 +4,7 @@
 
 use PgSql;
 
-class Result implements ColumnValueParser, \Countable
+class Result implements \Countable
 {
 	protected PgSql\Result $queryResource;
 
@@ -28,8 +28,7 @@ class Result implements ColumnValueParser, \Countable
 	/** @var array<string, string>|null */
 	private array|null $columnsDataTypes = null;
 
-	/** @var array<string, bool> */
-	private array $parsedColumns = [];
+	private ColumnValueParser|null $columnValueParser = null;
 
 
 	/**
@@ -126,11 +125,7 @@ public function fetch(): Row|null
 			return null;
 		}
 
-		// Detecting column data types need valid query result and it can be closed before columns data types
-		//   ...are detected, that's why we're detecting it with the first fetch (before first row is created)
-		$this->detectColumnDataTypes();
-
-		$row = $this->rowFactory->create($this, $data);
+		$row = $this->rowFactory->create($this->getColumnValueParser(), $data);
 
 		if ($this->rowFetchMutator !== null) {
 			call_user_func($this->rowFetchMutator, $row);
@@ -406,30 +401,31 @@ public function getColumns(): array
 	}
 
 
-	public function parseColumnValue(string $column, mixed $rawValue): mixed
+	/**
+	 * @return array<string, bool>|null null = no fetch was called yet
+	 */
+	public function getParsedColumns(): array|null
 	{
-		\assert(($rawValue === null) || \is_string($rawValue)); // database result all values as string or null
-		$value = $this->dataTypeParser->parse($this->getColumnType($column), $rawValue);
+		return $this->columnValueParser === null
+			? null
+			: \array_fill_keys($this->columnValueParser->getParsedColumns(), true) + \array_fill_keys($this->getColumns(), false);
+	}
 
-		$this->parsedColumns[$column] = true;
 
-		return $value;
+	private function getColumnValueParser(): ColumnValueParser
+	{
+		if ($this->columnValueParser === null) {
+			$this->columnValueParser = new ColumnValueParser($this->dataTypeParser, $this->getColumnsDataTypes());
+		}
+
+		return $this->columnValueParser;
 	}
 
 
 	/**
 	 * @return array<string, string>
 	 */
 	private function getColumnsDataTypes(): array
-	{
-		$this->detectColumnDataTypes();
-		\assert($this->columnsDataTypes !== null);
-
-		return $this->columnsDataTypes;
-	}
-
-
-	private function detectColumnDataTypes(): void
 	{
 		if ($this->columnsDataTypes === null) {
 			$this->columnsDataTypes = [];
@@ -455,17 +451,8 @@ private function detectColumnDataTypes(): void
 				$this->columnsDataTypes[$name] = $type;
 			}
 		}
-	}
-
 
-	/**
-	 * @return array<string, bool>|null null = no column was used
-	 */
-	public function getParsedColumns(): array|null
-	{
-		return $this->parsedColumns === []
-			? null
-			: $this->parsedColumns + \array_fill_keys($this->getColumns(), false);
+		return $this->columnsDataTypes;
 	}
 
 }

src/Db/Result.php

@@ -8,7 +8,7 @@
  */
 class Row implements \ArrayAccess, \IteratorAggregate, \Countable, \JsonSerializable
 {
-	private ColumnValueParser $columnValueParser;
+	private ColumnValueParser|null $columnValueParser;
 
 	/** @var array<string, string|null> */
 	private array $rawValues;
@@ -20,8 +20,12 @@ class Row implements \ArrayAccess, \IteratorAggregate, \Countable, \JsonSerializ
 	/**
 	 * @param array<string, string|null> $rawValues
 	 */
-	public function __construct(ColumnValueParser $columnValueParser, array $rawValues)
+	public function __construct(ColumnValueParser|null $columnValueParser, array $rawValues)
 	{
+		if ($columnValueParser === null && $rawValues !== []) {
+			throw Exceptions\RowException::columnValueParserMissing();
+		}
+
 		$this->columnValueParser = $columnValueParser;
 		$this->rawValues = $rawValues;
 
@@ -185,14 +189,15 @@ public function __serialize(): array
 	 */
 	public function __unserialize(array $values): void
 	{
-		$this->columnValueParser = new DummyColumnValueParser();
+		$this->columnValueParser = null;
 		$this->rawValues = [];
 		$this->values = $values;
 	}
 
 
 	private function parseValue(string $column): void
 	{
+		assert($this->columnValueParser !== null);
 		$this->values[$column] = $this->columnValueParser->parseColumnValue($column, $this->rawValues[$column]);
 		unset($this->rawValues[$column]);
 	}
@@ -226,7 +231,9 @@ public function jsonSerialize(): array
 	 */
 	public static function from(array $values): static
 	{
-		return new static(new DummyColumnValueParser(), $values);
+		$row = new static(null, []);
+		$row->values = $values;
+		return $row;
 	}
 
 }

src/Db/Row.php

@@ -266,24 +266,6 @@ public function testResultGetQuery(): void
 	}
 
 
-	public function testRowFrom(): void
-	{
-		$row = Db\Row::from(['column1' => 1, 'column2' => 'text', 'column3' => true, 'column4' => null]);
-
-		Tester\Assert::same(1, $row->column1);
-		Tester\Assert::same('text', $row->column2);
-		Tester\Assert::same(true, $row->column3);
-		Tester\Assert::same(null, $row->column4);
-
-		Tester\Assert::true(isset($row->column3));
-		Tester\Assert::false(isset($row->column4));
-		Tester\Assert::true($row->hasColumn('column4'));
-
-		$blankRow = Db\Row::from([]);
-		Tester\Assert::same([], $blankRow->toArray());
-	}
-
-
 	public function testRowSerialize(): void
 	{
 		$this->connection->query('

tests/Integration/BasicTest.php

@@ -49,11 +49,6 @@ public function testResultCollector(): void
 
 		$resultSelect = $results[2];
 
-		// Try also parse some non-existing column
-		Tester\Assert::exception(static function () use ($resultSelect): void {
-			$resultSelect->parseColumnValue('non_existing_column', 'someValue');
-		}, Db\Exceptions\ResultException::class, code: Db\Exceptions\ResultException::NO_COLUMN);
-
 		$querySelect = $resultSelect->getQuery();
 
 		Tester\Assert::same('SELECT id, name FROM test', $querySelect->sql);