EntityMapping: added column-to-property name translation

Author: dg

src/Bridges/DatabaseDI/DatabaseExtension.php

@@ -28,6 +28,7 @@
  *     autowired: ?bool,
  *     mapping: ?object{
  *         tables: array<string, string>,
+ *         camelCase: bool,
  *     },
  * }> $config
  */
@@ -57,6 +58,7 @@ public function getConfigSchema(): Nette\Schema\Schema
 						Expect::string()->transform(fn(string $v) => ['*' => $v]),
 						Expect::arrayOf('string', 'string'),
 					)->default([]),
+					'camelCase' => Expect::bool(false),
 				]),
 			]),
 		)->before(fn($val) => is_array(reset($val)) || reset($val) === null
@@ -142,8 +144,8 @@ private function setupDatabase(\stdClass $config, string $name): void
 			$conventions = Nette\DI\Helpers::filterArguments([$config->conventions])[0];
 		}
 
-		$entityMapping = $config->mapping?->tables
-			? new Nette\DI\Definitions\Statement(Nette\Database\DefaultEntityMapping::class, [$config->mapping->tables])
+		$entityMapping = $config->mapping?->tables || $config->mapping?->camelCase
+			? new Nette\DI\Definitions\Statement(Nette\Database\DefaultEntityMapping::class, [$config->mapping->tables, $config->mapping->camelCase])
 			: null;
 
 		$builder->addDefinition($this->prefix("$name.explorer"))

src/Database/DefaultEntityMapping.php

@@ -14,15 +14,24 @@
  */
 final class DefaultEntityMapping implements EntityMapping
 {
+	/** @var array<string, string> */
+	private array $propertyCache = [];
+
+	/** @var array<string, string> */
+	private array $columnCache = [];
+
+
 	/**
 	 * @param array<string, class-string<Table\ActiveRow>|string> $tables table-to-class map; keys
 	 *     may contain a single '*' wildcard (e.g. 'forum_*'), and a bare '*' acts as a catch-all
 	 *     fallback. Class names may contain '*' which is replaced with PascalCase of the captured
 	 *     portion (or the full table name for exact keys). Exact keys take precedence; wildcard
 	 *     entries are tried in declaration order.
+	 * @param bool $camelCase whether to convert snake_case column names to camelCase properties
 	 */
 	public function __construct(
 		private readonly array $tables = [],
+		private readonly bool $camelCase = false,
 	) {
 	}
 
@@ -61,6 +70,32 @@ private function expandClass(string $class, string $capture): string
 	}
 
 
+	/**
+	 * With camelCase enabled, expects a snake_case column name (e.g. 'first_name')
+	 * and returns its camelCase property form (e.g. 'firstName').
+	 */
+	public function getPropertyName(string $name): string
+	{
+		return $this->camelCase
+			? $this->propertyCache[$name] ??= lcfirst(self::toPascalCase($name))
+			: $name;
+	}
+
+
+	/**
+	 * With camelCase enabled, expects a camelCase property name (e.g. 'firstName')
+	 * and returns its snake_case column form (e.g. 'first_name'). PascalCase
+	 * input would produce a leading underscore (e.g. 'FirstName' → '_first_name'),
+	 * so the first letter is expected to be lowercase.
+	 */
+	public function getColumnName(string $name): string
+	{
+		return $this->camelCase
+			? $this->columnCache[$name] ??= strtolower((string) preg_replace('#[A-Z]#', '_$0', $name))
+			: $name;
+	}
+
+
 	private static function toPascalCase(string $name): string
 	{
 		$name = preg_replace('#^.*\.#', '', $name); // strip schema prefix

src/Database/EntityMapping.php

@@ -9,7 +9,7 @@
 
 
 /**
- * Resolves PHP class name for each database table.
+ * Translates identifier names between PHP conventions and database conventions.
  */
 interface EntityMapping
 {
@@ -18,4 +18,17 @@ interface EntityMapping
 	 * @return ?class-string<Table\ActiveRow>
 	 */
 	function getClassName(string $table): ?string;
+
+	/**
+	 * Translates database column name to PHP property name.
+	 */
+	function getPropertyName(string $name): string;
+
+	/**
+	 * Translates PHP property name to database column name. In dotted paths
+	 * (e.g. 'book.title' in WHERE/ORDER fragments) it is invoked only on the
+	 * last segment; preceding segments are treated as table/alias names and
+	 * left untouched.
+	 */
+	function getColumnName(string $name): string;
 }

src/Database/Helpers.php

@@ -10,7 +10,7 @@
 use Nette;
 use Nette\Bridges\DatabaseTracy\ConnectionPanel;
 use Tracy;
-use function array_filter, array_keys, array_unique, count, fclose, fgets, fopen, fstat, get_resource_type, htmlspecialchars, implode, is_bool, is_float, is_resource, is_string, preg_last_error, preg_match, preg_replace, preg_replace_callback, reset, rtrim, set_time_limit, str_ends_with, str_starts_with, stream_get_meta_data, strlen, strncasecmp, substr, trim, wordwrap;
+use function array_filter, array_keys, array_unique, count, fclose, fgets, fopen, fstat, get_resource_type, htmlspecialchars, implode, is_bool, is_float, is_int, is_resource, is_string, preg_last_error, preg_match, preg_replace, preg_replace_callback, reset, rtrim, set_time_limit, str_ends_with, str_starts_with, stream_get_meta_data, strlen, strncasecmp, substr, trim, wordwrap;
 
 
 /**
@@ -405,6 +405,29 @@ public static function findDuplicates(\PDOStatement $statement): string
 	}
 
 
+	/**
+	 * Translates array keys from PHP property names to database column names via EntityMapping.
+	 * Preserves integer keys and compound assignment operator suffixes (e.g. `firstName+=`).
+	 * @param  array<int|string, mixed>  $data
+	 * @return array<int|string, mixed>
+	 * @internal
+	 */
+	public static function translateColumns(array $data, EntityMapping $mapping): array
+	{
+		$result = [];
+		foreach ($data as $key => $value) {
+			if (is_int($key)) {
+				$result[$key] = $value;
+			} elseif (preg_match('#^(.*?)([+\-]?=)$#D', $key, $m)) {
+				$result[$mapping->getColumnName($m[1]) . $m[2]] = $value;
+			} else {
+				$result[$mapping->getColumnName($key)] = $value;
+			}
+		}
+		return $result;
+	}
+
+
 	/**
 	 * Parses a SQL column type string into its components.
 	 * @return array{type: ?string, size: ?int, scale: ?int, parameters: ?string}

src/Database/Table/ActiveRow.php

@@ -8,7 +8,7 @@
 namespace Nette\Database\Table;
 
 use Nette;
-use function array_intersect_key, array_key_exists, array_keys, implode, is_array, iterator_to_array;
+use function array_intersect_key, array_key_exists, array_keys, array_map, implode, is_array, iterator_to_array;
 
 
 /**
@@ -19,6 +19,7 @@
 class ActiveRow implements \IteratorAggregate, IRow
 {
 	private bool $dataRefreshed = false;
+	private readonly ?Nette\Database\EntityMapping $entityMapping;
 
 
 	public function __construct(
@@ -27,6 +28,7 @@ public function __construct(
 		/** @var Selection<ActiveRow> */
 		private Selection $table,
 	) {
+		$this->entityMapping = $table->getExplorer()->getEntityMapping();
 	}
 
 
@@ -66,12 +68,23 @@ public function __toString(): string
 	public function toArray(): array
 	{
 		$this->accessColumn(null);
+		$entityMapping = $this->entityMapping;
+		if ($entityMapping) {
+			$translated = [];
+			foreach ($this->data as $key => $value) {
+				$translated[$entityMapping->getPropertyName($key)] = $value;
+			}
+			return $translated;
+		}
 		return $this->data;
 	}
 
 
 	/**
 	 * Returns primary key value, or an array of values for composite primary keys.
+	 * Composite key arrays are keyed by database column names (unlike toArray(),
+	 * which uses property names) so the result can be passed directly to
+	 * Selection::wherePrimary().
 	 */
 	public function getPrimary(bool $throw = true): mixed
 	{
@@ -163,7 +176,10 @@ public function update(iterable $data): bool
 			->wherePrimary($primary);
 
 		if ($selection->update($data)) {
-			if ($tmp = array_intersect_key($data, $primary)) {
+			$columnData = $this->entityMapping
+				? Nette\Database\Helpers::translateColumns($data, $this->entityMapping)
+				: $data;
+			if ($tmp = array_intersect_key($columnData, $primary)) {
 				$selection = $this->table->createSelectionInstance()
 					->wherePrimary($tmp + $primary);
 			}
@@ -205,8 +221,7 @@ public function delete(): int
 	/** @return \ArrayIterator<string, mixed> */
 	public function getIterator(): \Iterator
 	{
-		$this->accessColumn(null);
-		return new \ArrayIterator($this->data);
+		return new \ArrayIterator($this->toArray());
 	}
 
 
@@ -250,8 +265,10 @@ public function __set(string $column, mixed $value): void
 	 */
 	public function &__get(string $key): mixed
 	{
-		if ($this->accessColumn($key)) {
-			return $this->data[$key];
+		$column = $this->entityMapping?->getColumnName($key) ?? $key;
+
+		if ($this->accessColumn($column)) {
+			return $this->data[$column];
 		}
 
 		$referenced = $this->table->getReferencedTable($this, $key);
@@ -260,16 +277,21 @@ public function &__get(string $key): mixed
 			return $referenced;
 		}
 
-		$this->removeAccessColumn($key);
-		$hint = Nette\Utils\Helpers::getSuggestion(array_keys($this->data), $key);
+		$this->removeAccessColumn($column);
+		$available = $this->entityMapping
+			? array_map(fn(string $col) => $this->entityMapping->getPropertyName($col), array_keys($this->data))
+			: array_keys($this->data);
+		$hint = Nette\Utils\Helpers::getSuggestion($available, $key);
 		throw new Nette\MemberAccessException("Cannot read an undeclared column '$key'" . ($hint ? ", did you mean '$hint'?" : '.'));
 	}
 
 
 	public function __isset(string $key): bool
 	{
-		if ($this->accessColumn($key)) {
-			return isset($this->data[$key]);
+		$column = $this->entityMapping?->getColumnName($key) ?? $key;
+
+		if ($this->accessColumn($column)) {
+			return isset($this->data[$column]);
 		}
 
 		$referenced = $this->table->getReferencedTable($this, $key);
@@ -278,7 +300,7 @@ public function __isset(string $key): bool
 			return (bool) $referenced;
 		}
 
-		$this->removeAccessColumn($key);
+		$this->removeAccessColumn($column);
 		return false;
 	}
 

src/Database/Table/Selection.php

@@ -829,6 +829,12 @@ public function insert(iterable $data): ActiveRow|array|int
 				$data = iterator_to_array($data);
 			}
 
+			if ($mapping = $this->explorer->getEntityMapping()) {
+				$data = isset($data[0]) && is_array($data[0])
+					? array_map(fn(array $row) => Nette\Database\Helpers::translateColumns($row, $mapping), $data)
+					: Nette\Database\Helpers::translateColumns($data, $mapping);
+			}
+
 			$return = $this->explorer->query($this->sqlBuilder->buildInsertQuery() . ' ?values', $data);
 		}
 
@@ -910,6 +916,10 @@ public function update(iterable $data): int
 			return 0;
 		}
 
+		if ($mapping = $this->explorer->getEntityMapping()) {
+			$data = Nette\Database\Helpers::translateColumns($data, $mapping);
+		}
+
 		return $this->explorer
 			->query($this->sqlBuilder->buildUpdateQuery(), ...array_merge([$data], $this->sqlBuilder->getParameters()))
 			->getRowCount()

src/Database/Table/SqlBuilder.php

@@ -10,6 +10,7 @@
 use Nette;
 use Nette\Database\Conventions;
 use Nette\Database\Driver;
+use Nette\Database\EntityMapping;
 use Nette\Database\Explorer;
 use Nette\Database\IStructure;
 use Nette\Database\SqlLiteral;
@@ -62,6 +63,7 @@ class SqlBuilder
 	protected string $currentAlias = '';
 	private readonly Driver $driver;
 	private readonly IStructure $structure;
+	private readonly ?EntityMapping $entityMapping;
 
 	/** @var array<string, int> table fullName => exists */
 	private array $cacheTableList = [];
@@ -76,6 +78,7 @@ public function __construct(string $tableName, Explorer $explorer)
 		$this->driver = $explorer->getConnection()->getDriver();
 		$this->conventions = $explorer->getConventions();
 		$this->structure = $explorer->getStructure();
+		$this->entityMapping = $explorer->getEntityMapping();
 		$tableNameParts = explode('.', $tableName);
 		$this->delimitedTable = implode('.', array_map($this->driver->delimite(...), $tableNameParts));
 		$this->checkUniqueTableName(end($tableNameParts), $tableName);
@@ -898,11 +901,31 @@ protected function buildQueryEnd(): string
 	 */
 	protected function tryDelimite(string $s): string
 	{
+		if (!$this->entityMapping) {
+			return preg_replace_callback(
+				'#(?<=[^\w`"\[?:]|^)[a-z_][a-z0-9_]*(?=[^\w`"(\]]|$)#Di',
+				fn(array $m): string => strtoupper($m[0]) === $m[0]
+					? $m[0]
+					: $this->driver->delimite($m[0]),
+				$s,
+			);
+		}
+
 		return preg_replace_callback(
-			'#(?<=[^\w`"\[?:]|^)[a-z_][a-z0-9_]*(?=[^\w`"(\]]|$)#Di',
-			fn(array $m): string => strtoupper($m[0]) === $m[0]
-				? $m[0]
-				: $this->driver->delimite($m[0]),
+			'#(?<=[^\w`"\[?:]|^)[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)*(?=[^\w`"(\]]|$)#Di',
+			function (array $m): string {
+				$parts = explode('.', $m[0]);
+				$last = count($parts) - 1;
+				foreach ($parts as $i => &$part) {
+					if (strtoupper($part) !== $part) {
+						if ($i === $last) {
+							$part = $this->entityMapping->getColumnName($part);
+						}
+						$part = $this->driver->delimite($part);
+					}
+				}
+				return implode('.', $parts);
+			},
 			$s,
 		);
 	}

tests/Database.DI/DatabaseExtension.entityMapping.phpt

@@ -119,6 +119,42 @@ test('DefaultEntityMapping: empty map returns null', function () {
 });
 
 
+test('DefaultEntityMapping: camelCase off = identity', function () {
+	$mapping = new DefaultEntityMapping;
+
+	Assert::same('first_name', $mapping->getPropertyName('first_name'));
+	Assert::same('firstName', $mapping->getColumnName('firstName'));
+});
+
+
+test('DefaultEntityMapping: camelCase on', function () {
+	$mapping = new DefaultEntityMapping(camelCase: true);
+
+	Assert::same('firstName', $mapping->getPropertyName('first_name'));
+	Assert::same('authorId', $mapping->getPropertyName('author_id'));
+	Assert::same('id', $mapping->getPropertyName('id'));
+	Assert::same('name', $mapping->getPropertyName('name'));
+	Assert::same('createdAt', $mapping->getPropertyName('created_at'));
+	Assert::same('address2', $mapping->getPropertyName('address2'));
+
+	Assert::same('first_name', $mapping->getColumnName('firstName'));
+	Assert::same('author_id', $mapping->getColumnName('authorId'));
+	Assert::same('id', $mapping->getColumnName('id'));
+	Assert::same('name', $mapping->getColumnName('name'));
+	Assert::same('created_at', $mapping->getColumnName('createdAt'));
+	Assert::same('address2', $mapping->getColumnName('address2'));
+});
+
+
+test('DefaultEntityMapping: camelCase roundtrip', function () {
+	$mapping = new DefaultEntityMapping(camelCase: true);
+
+	foreach (['id', 'name', 'first_name', 'author_id', 'created_at', 'address2'] as $column) {
+		Assert::same($column, $mapping->getColumnName($mapping->getPropertyName($column)));
+	}
+});
+
+
 test('DefaultEntityMapping: schema prefix is stripped in class name', function () {
 	$mapping = new DefaultEntityMapping(['*' => 'App\Model\*Row']);