DefaultEntityMapping: added except map for columns with no camelCase form

Digits have no letter case, so an underscore directly before a digit
(address_2) is not representable in camelCase and mapping validation
rejects such columns. The except option (DI key mapping.except) declares
explicit property-to-column pairs that take precedence over the
conversion in both directions; the validation message now hints at it.

Author: dg

docs/internals/explorer.md

@@ -121,10 +121,17 @@ Boundaries and traps:
   why the implementation is context-free.
 - **Validation runs only at structure rebuild.** Enabling the mapping requires the
   whole schema to be invertible, including tables and views the application never
-  touches. A warm structure cache skips
+  touches (the except map is the escape hatch). A warm structure cache skips
   validation entirely, so a change of the mapping configuration requires a cache
   flush, same as a schema change; a structure cache built by a process without the
   mapping (CLI, another app sharing the DSN and cache dir) is trusted unvalidated.
+- **Digits have no letter case**, so the invertible subset is stricter than plain
+  snake_case: digit runs must attach to the preceding word (`address2`,
+  `sha256_hash`, `oauth2_token` are fine); an underscore directly before a digit
+  (`address_2`) is not representable in camelCase and is rejected by validation.
+  The `except` map of `DefaultEntityMapping` (DI key `mapping: except:`) declares
+  explicit property→column pairs that take precedence over the conversion in both
+  directions — the escape hatch for such legacy columns.
 
 ## `accessColumn`: the single shared seam
 

src/Bridges/DatabaseDI/DatabaseExtension.php

@@ -44,6 +44,7 @@ public function getConfigSchema(): Nette\Schema\Schema
 						Expect::arrayOf('string', 'string'),
 					)->default([]),
 					'camelCase' => Expect::bool(false),
+					'except' => Expect::arrayOf('string', 'string'),
 				]),
 			]),
 		)->before(fn($val) => is_array($val) && $val && !array_key_exists('dsn', $val)
@@ -126,10 +127,10 @@ private function setupDatabase(\stdClass $config, string $name): void
 				->setAutowired($config->autowired)
 			: null;
 
-		$entityMapping = $config->mapping?->tables || $config->mapping?->camelCase
+		$entityMapping = $config->mapping?->tables || $config->mapping?->camelCase || $config->mapping?->except
 			? new Nette\DI\Definitions\Statement(
 				Nette\Database\DefaultEntityMapping::class,
-				[$config->mapping->tables, $config->mapping->camelCase],
+				[$config->mapping->tables, $config->mapping->camelCase, $config->mapping->except],
 			)
 			: null;
 

src/Database/DefaultEntityMapping.php

@@ -21,6 +21,11 @@ final class DefaultEntityMapping implements EntityMapping
 	private array $columnCache = [];
 
 
+	/**
+	 * @param array<string, string> $except explicit property-to-column pairs (e.g. ['address2' => 'address_2'])
+	 *     that take precedence over the camelCase conversion in both directions; the escape hatch
+	 *     for columns whose name has no camelCase form
+	 */
 	public function __construct(
 		/**
 		 * @var array<string, class-string<Table\ActiveRow>|string> table-to-class map; keys
@@ -32,7 +37,12 @@ public function __construct(
 		private readonly array $tables = [],
 		/** whether to convert snake_case column names to camelCase properties */
 		private readonly bool $camelCase = false,
+		array $except = [],
 	) {
+		foreach ($except as $property => $column) {
+			$this->propertyCache[$column] = $property;
+			$this->columnCache[$property] = $column;
+		}
 	}
 
 
@@ -72,27 +82,28 @@ 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').
+	 * and returns its camelCase property form (e.g. 'firstName'). Pairs from the
+	 * except map take precedence.
 	 */
 	public function getPropertyName(string $name): string
 	{
-		return $this->camelCase
-			? $this->propertyCache[$name] ??= lcfirst(self::toPascalCase($name))
-			: $name;
+		return $this->propertyCache[$name] ??= $this->camelCase ? 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.
+	 * so the first letter is expected to be lowercase. Digits have no letter case,
+	 * so an underscore directly before a digit ('address_2') has no camelCase form;
+	 * digit runs attach to the preceding word ('sha256_hash' → 'sha256Hash') and
+	 * columns like 'address_2' must go through the except map. Pairs from the
+	 * except map take precedence.
 	 */
 	public function getColumnName(string $name): string
 	{
-		return $this->camelCase
-			? $this->columnCache[$name] ??= strtolower((string) preg_replace('#[A-Z]#', '_$0', $name))
-			: $name;
+		return $this->columnCache[$name] ??= $this->camelCase ? strtolower((string) preg_replace('#[A-Z]#', '_$0', $name)) : $name;
 	}
 
 

src/Database/Explorer.php

@@ -158,7 +158,10 @@ public function validateEntityMapping(): void
 				$property = $this->entityMapping->getPropertyName($column['name']);
 				$back = $this->entityMapping->getColumnName($property);
 				if ($back !== $column['name']) {
-					throw new Nette\InvalidStateException("Column '$table.{$column['name']}' cannot be addressed through entity mapping: its property name '$property' translates back to column '$back'. Rename the column or adjust the mapping.");
+					$hint = preg_match('#_\d#', $column['name'])
+						? "An underscore directly before a digit has no camelCase form; map the column explicitly via the mapping's except option, or rename it."
+						: 'Rename the column or adjust the mapping.';
+					throw new Nette\InvalidStateException("Column '$table.{$column['name']}' cannot be addressed through entity mapping: its property name '$property' translates back to column '$back'. $hint");
 				}
 			}
 		}

tests/Database.DI/DatabaseExtension.entityMapping.phpt

@@ -67,6 +67,24 @@ test('tables string shortcut', function () {
 });
 
 
+test('mapping with except only', function () {
+	$container = createContainer('
+	database:
+		dsn: "sqlite::memory:"
+		mapping:
+			except:
+				address2: address_2
+		debugger: no
+
+	services:
+		cache: Nette\Caching\Storages\DevNullStorage
+	', 'Container2c');
+
+	$explorer = $container->getService('database.default.explorer');
+	Assert::type(DefaultEntityMapping::class, getEntityMapping($explorer));
+});
+
+
 test('no mapping by default', function () {
 	$container = createContainer('
 	database:
@@ -154,6 +172,26 @@ test('DefaultEntityMapping: camelCase roundtrip', function () {
 });
 
 
+test('DefaultEntityMapping: except pairs take precedence in both directions', function () {
+	$mapping = new DefaultEntityMapping(camelCase: true, except: ['address2' => 'address_2']);
+
+	Assert::same('address2', $mapping->getPropertyName('address_2'));
+	Assert::same('address_2', $mapping->getColumnName('address2'));
+	Assert::same('firstName', $mapping->getPropertyName('first_name'));
+	Assert::same('first_name', $mapping->getColumnName('firstName'));
+});
+
+
+test('DefaultEntityMapping: except works without camelCase', function () {
+	$mapping = new DefaultEntityMapping(except: ['address2' => 'address_2']);
+
+	Assert::same('address2', $mapping->getPropertyName('address_2'));
+	Assert::same('address_2', $mapping->getColumnName('address2'));
+	Assert::same('other_col', $mapping->getPropertyName('other_col'));
+	Assert::same('otherCol', $mapping->getColumnName('otherCol'));
+});
+
+
 test('DefaultEntityMapping: schema prefix is stripped in class name', function () {
 	$mapping = new DefaultEntityMapping(['*' => 'App\Model\*Row']);
 

tests/Database.DI/EntityMapping.validation.phpt

@@ -3,8 +3,9 @@
 /**
  * Test: entity-mapping name translation is validated against the actual schema when
  * the structure cache is being (re)built: a column unreachable through the mapping
- * (camelCase column under camelCase mapping, colliding column pair) fails loudly
- * instead of silently, and the failure aborts caching so it repeats until fixed.
+ * (camelCase column under camelCase mapping, colliding column pair, underscore
+ * directly before a digit) fails loudly instead of silently, and the failure aborts
+ * caching so it repeats until fixed; the except map is the escape hatch.
  */
 
 use Nette\Caching\Storages\MemoryStorage;
@@ -15,7 +16,7 @@ use Tester\Assert;
 require __DIR__ . '/../bootstrap.php';
 
 
-function createExplorer(array $schema, bool $camelCase): Explorer
+function createExplorer(array $schema, bool $camelCase, array $except = []): Explorer
 {
 	$connection = new Connection('sqlite::memory:');
 	foreach ($schema as $sql) {
@@ -28,7 +29,7 @@ function createExplorer(array $schema, bool $camelCase): Explorer
 		$structure,
 		new DiscoveredConventions($structure),
 		$storage,
-		new DefaultEntityMapping([], camelCase: $camelCase),
+		new DefaultEntityMapping([], camelCase: $camelCase, except: $except),
 	);
 }
 
@@ -78,6 +79,72 @@ test('a colliding column pair fails loudly', function () {
 });
 
 
+test('digit runs attached to the preceding word are invertible and pass', function () {
+	$explorer = createExplorer(
+		['CREATE TABLE digits (id INTEGER PRIMARY KEY AUTOINCREMENT, address2 INT, sha256_hash TEXT, oauth2_token TEXT, utf8mb4_name TEXT, col_v2 INT)'],
+		camelCase: true,
+	);
+	$explorer->table('digits')->insert(['address2' => 1, 'sha256Hash' => 'x', 'oauth2Token' => 'y', 'utf8mb4Name' => 'z', 'colV2' => 2]);
+	$row = $explorer->table('digits')->fetch();
+	Assert::same(1, $row->address2);
+	Assert::same('x', $row->sha256Hash);
+	Assert::same(2, $row->colV2);
+});
+
+
+test('an underscore directly before a digit fails with a digit hint', function () {
+	$explorer = createExplorer(
+		['CREATE TABLE legacy (id INTEGER PRIMARY KEY AUTOINCREMENT, address_2 INT)'],
+		camelCase: true,
+	);
+	Assert::exception(
+		fn() => $explorer->table('legacy'),
+		Nette\InvalidStateException::class,
+		"Column 'legacy.address_2' cannot be addressed through entity mapping: its property name 'address2' translates back to column 'address2'. An underscore directly before a digit has no camelCase form; map the column explicitly via the mapping's except option, or rename it.",
+	);
+});
+
+
+test('except map makes such a column addressable in both directions', function () {
+	$explorer = createExplorer(
+		['CREATE TABLE legacy (id INTEGER PRIMARY KEY AUTOINCREMENT, address_2 INT)'],
+		camelCase: true,
+		except: ['address2' => 'address_2'],
+	);
+	$explorer->table('legacy')->insert(['address2' => 5]);
+	$row = $explorer->table('legacy')->where('address2', 5)->fetch();
+	Assert::same(5, $row->address2);
+	Assert::same(['id' => 1, 'address2' => 5], $row->toArray());
+	$row->update(['address2' => 6]);
+	Assert::same(6, $explorer->table('legacy')->fetch()->address2);
+});
+
+
+test('except pair whose column collides with a real column fails loudly', function () {
+	$explorer = createExplorer(
+		['CREATE TABLE digits (id INTEGER PRIMARY KEY AUTOINCREMENT, address2 INT)'],
+		camelCase: true,
+		except: ['address2' => 'address_2'],
+	);
+	Assert::exception(
+		fn() => $explorer->table('digits'),
+		Nette\InvalidStateException::class,
+		"Column 'digits.address2' cannot be addressed through entity mapping: its property name 'address2' translates back to column 'address_2'. Rename the column or adjust the mapping.",
+	);
+});
+
+
+test('except map works without camelCase conversion', function () {
+	$explorer = createExplorer(
+		['CREATE TABLE legacy (id INTEGER PRIMARY KEY AUTOINCREMENT, address_2 INT)'],
+		camelCase: false,
+		except: ['address2' => 'address_2'],
+	);
+	$explorer->table('legacy')->insert(['address2' => 3]);
+	Assert::same(3, $explorer->table('legacy')->fetch()->address2);
+});
+
+
 test('identity mapping (camelCase off) accepts any schema', function () {
 	$explorer = createExplorer([
 		'CREATE TABLE broken (id INTEGER PRIMARY KEY AUTOINCREMENT, realCamel INT)',