ORM autoMap produces broken fieldMapping for uppercase (Firebird) columns

[justin-k-bruce]

Bug

When $autoMap = true, the ORM's snakeToCamel() conversion produces incorrect property names for uppercase column names, which is the default for Firebird (and also common in Oracle).

Example

Firebird returns columns like ACCOUNTNO, STORENAME, CREDITLIMIT. The snakeToCamel() method applies lcfirst() which lowercases only the first character:

ACCOUNTNO  → aCCOUNTNO
STORENAME  → sTORENAME
CREDITLIMIT → cREDITLIMIT

Resulting fieldMapping:

[fieldMapping] => Array
(
    [aCCOUNTNO] => ACCOUNTNO
    [sTORENAME] => STORENAME
)

These mapped property names (aCCOUNTNO) don't match any declared PHP properties on the model, so the mapping is useless.

Root Cause

snakeToCamel() on line 98 of ORM.php:

private static function snakeToCamel(string $name): string
{
    return lcfirst(str_replace('_', '', ucwords($name, '_')));
}

This assumes columns are snake_case (e.g., credit_limit). It doesn't handle:

1. ALL-CAPS columns (ACCOUNTNO, CREDIT_LIMIT) — common in Firebird, Oracle
2. Single-word uppercase (STORENAME) — no underscores to split on

Suggested Fix

snakeToCamel() should lowercase the input first before applying the conversion:

private static function snakeToCamel(string $name): string
{
    return lcfirst(str_replace('_', '', ucwords(strtolower($name), '_')));
}

This produces:

ACCOUNTNO     → accountno
STORENAME     → storename
CREDIT_LIMIT  → creditLimit
FIRST_NAME    → firstName

Similarly, camelToSnake() may need to handle the reverse — when writing back to Firebird, column names should be uppercased:

private static function camelToSnake(string $name): string
{
    return strtolower(preg_replace('/[A-Z]/', '_$0', lcfirst($name)));
}

This already lowercases, but the generated mapping value should match the DB's actual casing. A possible improvement would be to preserve the original column casing from the DB result rather than assuming lowercase.

Environment

• PHP 8.4.8
• Tina4 v3.10.49
• Firebird 4.0 (returns all-uppercase column names by default)

[andrevanzuydam]

Thanks for the report — this is a confirmed bug specific to Firebird and Oracle databases, where column names are returned uppercase by default (e.g. CUSTOMER_NAME).

The current snakeToCamel() implementation:

return lcfirst(str_replace('_', '', ucwords($name, '_')));

Works correctly for lowercase snake_case (customer_name → customerName), but fails for all-uppercase columns like CUSTOMER_NAME. ucwords with _ as delimiter only capitalises the character after each underscore, so CUSTOMER_NAME passes through as cUSTOMERnAME rather than the expected customerName.

The fix is to lowercase the column name first before applying the camelCase conversion, so CUSTOMER_NAME → customer_name → customerName. Explicit $fieldMapping entries will continue to take precedence over autoMap as today.

[andrevanzuydam]

Fixed in v3.10.54 — snakeToCamel() now calls strtolower() first, so Firebird/Oracle uppercase columns like CUSTOMER_NAME correctly map to customerName.

[justin-k-bruce]

The strtolower() fix for snakeToCamel() is working — the mapping is now correct (e.g., CREDIT_LIMIT → creditLimit). However there's a follow-on issue:

fill() stores data in _data private array, not in declared public properties

When an ORM model declares public properties (which was the standard pattern in v2):

class Customer extends \Tina4\ORM {
    public string $tableName = "customer";
    public string $primaryKey = "accountno";
    public $accountno;
    public $firstName;
    public $creditLimit = 0;
}

And autoMap correctly maps FIRST_NAME → firstName, CREDIT_LIMIT → creditLimit, the fill() method (line 236) stores all values into $this->_data[$propName]:

$this->_data[$propName] = $value;

But it never sets the actual public property ($this->firstName = $value). Since $firstName exists as a declared property, PHP's __get() magic method is never called for it — so $customer->firstName returns the default/uninitialized value, not the database value.

The only way to access the data is via $customer->getData() which returns a plain array, losing ORM type safety.

Expected: fill() should check if a public property exists on the class and set it directly:

foreach ($data as $key => $value) {
    $propName = $reverseMapping[$key] ?? $key;
    if (property_exists($this, $propName)) {
        $this->$propName = $value;  // Set declared property directly
    }
    $this->_data[$propName] = $value;  // Also keep in _data for magic access
}

This way $customer->firstName returns the correct value whether accessed via the declared property or __get().

[andrevanzuydam]

Investigating: When autoMap = true, the ORM generates fieldMapping from camelCase PHP properties to snake_case DB columns. Firebird returns uppercase column names (e.g., FIRST_NAME). The autoMap logic may need to handle uppercase → camelCase conversion. Checking...

[andrevanzuydam]

Already fixed in a prior commit — snakeToCamel() at line 136 already calls strtolower($name) before the conversion. Uppercase Firebird columns like ACCOUNTNO now map correctly to accountno.

[andrevanzuydam]

Thanks for the detailed report on the Firebird uppercase column issue — that's a real edge case we hadn't fully covered.

On the broader field mapping topic: field mapping is alive and well in v3 across all four frameworks (PHP, Ruby, Node.js, Python). The autoMap flag was formalized in v3.10.1 specifically to handle the camelCase ↔ snake_case bridging automatically.

The fix you've suggested for snakeToCamel() — adding strtolower() before the conversion — is exactly right and was already applied in an earlier commit (the method at line 136 already has strtolower in the current codebase). If you're on v3.10.49 and still seeing the aCCOUNTNO behaviour, it's possible there's a caching issue or the fix didn't make it into that release build.

For the write path (Firebird expecting uppercase column names back), the cleanest approach is to store the original DB column casing in the fieldMapping value rather than lowercasing it — so the mapping becomes accountno => ACCOUNTNO and the write path uses the stored original. We'll track this as part of the broader field mapping parity work across frameworks.

Worth noting: explicit $fieldMapping declarations still work as a reliable escape hatch for any adapter with non-standard column naming.

[justin-k-bruce]

Re-checked against v3.10.85.

The original snakeToCamel() fix is in place (strtolower() at line 136) and Firebird uppercase columns now map correctly to their camelCase equivalents. ✅

However the follow-on issue I raised in my earlier comment is still unresolved: fill() at lines 264-292 still only writes values into the private $this->_data[$propName] array and never sets declared public properties on the model. For any ORM class that declares typed public properties (the standard v2 pattern), $model->firstName will still return the default/uninitialised value because PHP's __get() magic method is skipped when a declared property exists.

Current fill():

foreach ($data as $key => $value) {
    $propName = $reverseMapping[$key] ?? $key;
    $this->_data[$propName] = $value;
}

Suggested:

foreach ($data as $key => $value) {
    $propName = $reverseMapping[$key] ?? $key;
    if (property_exists($this, $propName)) {
        $this->$propName = $value;
    }
    $this->_data[$propName] = $value;
}

Leaving this open until the declared-property path of fill() is addressed.

[justin-k-bruce]

Another manifestation of the same root cause — ORM::load()'s no-argument branch is effectively dead code as long as fill() only writes to _data and declared public properties are the convention.

ORM::load() (lines 369-400):

public function load(?string \$filter = null, array \$params = [], ?array \$include = null): bool
{
    \$this->ensureDb();

    \$sql = "SELECT * FROM {\$this->tableName}";

    if (\$filter === null) {
        // No args — use the primary key value already set on this instance
        \$pkValue = \$this->getPrimaryKeyValue();
        if (\$pkValue === null) {
            return false;
        }
        \$pkColumn = \$this->getDbColumn(\$this->primaryKey);
        \$sql .= " WHERE {\$pkColumn} = ?";
        \$params = [\$pkValue];
    } else {
        ...
    }
    ...
}

ORM::getPrimaryKeyValue() (lines 688-691):

public function getPrimaryKeyValue(): int|string|null
{
    return \$this->_data[\$this->primaryKey] ?? null;
}

The natural v2 pattern (still shown in docs) is:

\$customer = new Customer();
\$customer->accountno = \$accountNo;
if (\$customer->load()) { ... }

But because \$customer->accountno = ... hits the declared public property — PHP's __set() is skipped when the property exists — _data['accountno'] is never populated. So getPrimaryKeyValue() returns null and load() short-circuits with false without ever building a query.

The only way to reach the if (\$filter === null) branch successfully is to have called fill() first (which populates _data), at which point you already have the row and there was no reason to call load() anyway.

Suggested fix

Have getPrimaryKeyValue() prefer the declared public property when one exists:

public function getPrimaryKeyValue(): int|string|null
{
    if (property_exists(\$this, \$this->primaryKey)) {
        \$value = \$this->{\$this->primaryKey};
        if (\$value !== null && \$value !== '') {
            return \$value;
        }
    }
    return \$this->_data[\$this->primaryKey] ?? null;
}

This is the same shape of fix as the fill() → declared-property mirror — both fill() (writes) and getPrimaryKeyValue() (reads) currently ignore declared public properties, which makes the v2 API surface largely non-functional on v3.10.85.

Version observed: tina4stack/tina4php v3.10.85

[justin-k-bruce]

A third manifestation of the same root area — ORM::fill()'s autoMap path corrupts _data when it receives already-camelCase keys, which happens in practice because load() calls $this->fill($result->getData()).

The corruption

snakeToCamel() starts with strtolower() (the correct fix from the original Firebird report):

private static function snakeToCamel(string $name): string
{
    $name = strtolower($name); // normalise uppercase column names (Firebird/Oracle)
    return lcfirst(str_replace('_', '', ucwords($name, '_')));
}

But fill()'s autoMap loop calls it on every incoming key, not just snake_case ones:

if ($this->autoMap) {
    $existingMappedColumns = array_values($this->fieldMapping);
    foreach (array_keys($data) as $col) {
        if (in_array($col, $existingMappedColumns, true)) continue;
        $camel = self::snakeToCamel($col);
        if ($camel !== $col && !isset($this->fieldMapping[$camel])) {
            $this->fieldMapping[$camel] = $col;
        }
    }
}

So a key like vwEmailPassword (already camelCase) is fed through snakeToCamel, which lowercases it to vwemailpassword. Since vwemailpassword !== vwEmailPassword, a bogus mapping ['vwemailpassword' => 'vwEmailPassword'] is added. The subsequent $reverseMapping[$key] lookup then writes the value under the lowercased key:

_data: {"vwemailpassword":"secret",...}
fieldMapping: {"vwEmailPassword":"VW_EMAIL_PASSWORD","vwemailpassword":"vwEmailPassword"}

Why this bites load()

load() ends with:

$result = $this->selectOne($sql, $params, $include);
if ($result === null) return false;
$this->fill($result->getData());  // <-- already camelCase!

selectOne() already populated $result->_data with camelCase keys via its own fill() of the raw row. Then $this->fill($result->getData()) receives those camelCase keys and runs them through autoMap a second time — which is exactly when the strtolower corruption fires.

Repro

class Customer extends \Tina4\ORM {
    public string $tableName = 'customer';
    public string $primaryKey = 'accountno';
    public bool $autoMap = true;
    public $accountno;
    public $vwEmailPassword;
    public $firstName;
}

$a = new Customer();
$a->fill(['ACCOUNTNO' => 'T-1', 'VW_EMAIL_PASSWORD' => 'secret', 'FIRST_NAME' => 'John']);
// $a->_data (via reflection) is correct: {"accountno":"T-1","vwEmailPassword":"secret","firstName":"John"}

$b = new Customer();
$b->fill($a->getData());  // what load() does
// $b->_data is now: {"accountno":"T-1","vwemailpassword":"secret","firstname":"John"}
// $b->fieldMapping picked up two corrupted identity-ish mappings:
//   vwemailpassword => vwEmailPassword
//   firstname       => firstName

Suggested fix

Skip the autoMap loop for any key that is clearly already camelCase (no underscore and not all-caps), so snakeToCamel only runs on snake_case or uppercase input:

if ($this->autoMap) {
    $existingMappedColumns = array_values($this->fieldMapping);
    foreach (array_keys($data) as $col) {
        if (in_array($col, $existingMappedColumns, true)) continue;

        // Skip keys that are already camelCase — snakeToCamel would
        // lowercase them via its strtolower normalisation and produce
        // a bogus mapping.
        if (!str_contains($col, '_') && !ctype_upper($col)) continue;

        $camel = self::snakeToCamel($col);
        if ($camel !== $col && !isset($this->fieldMapping[$camel])) {
            $this->fieldMapping[$camel] = $col;
        }
    }
}

Alternatively, load() could skip the second fill() entirely and copy _data + fieldMapping directly from the freshly-loaded $result, since selectOne() has already done the mapping work once.

Version observed: tina4stack/tina4php v3.10.85

[justin-k-bruce]

A fourth manifestation — save() silently drops writes to declared public properties because it reads from _data, which is never updated by direct property assignment.

Repro

class Customer extends \Tina4\ORM {
    public string \$tableName = 'customer';
    public string \$primaryKey = 'accountno';
    public bool \$autoMap = true;
    public \$accountno;
    public \$vwEmailPassword;
    public \$firstName;
}

\$c = new Customer();
\$c->load('accountno = ?', [\$accountNo]);
\$c->vwEmailPassword = 'new-secret';
\$c->firstName = 'Johnny';
\$c->save();

After save(), the row in the database still has the old vw_email_password and first_name. The assignments never made it.

Trace

1. load() ends up populating _data with the row from the DB. That part now mostly works (modulo the double-fill issue reported earlier) so _data = ['vwEmailPassword' => 'old', 'firstName' => 'John', ...].

2. \$c->vwEmailPassword = 'new-secret' hits the declared public property. PHP does not call __set() because the property exists, so _data['vwEmailPassword'] stays 'old'.

3. save() → insert() / update() → getDbData() at line 1179:

   private function getDbData(): array
   {
       if (\$this->autoMap) {
           foreach (array_keys(\$this->_data) as \$prop) {
               ...
           }
       }
       \$data = [];
       foreach (\$this->_data as \$prop => \$value) {
           \$column = \$this->getDbColumn(\$prop);
           \$data[\$column] = \$value;
       }
       return \$data;
   }

   Reads \$this->_data — which still holds 'old' — so UPDATE customer SET vw_email_password = 'old' ... is emitted. The user's new value is silently discarded.

Symmetry with the other three manifestations

All four manifestations in this issue boil down to the same root cause: _data is the authoritative store, but declared public properties shadow it in both directions.

Path	Affected method	Effect
fill() write → property read	fill()	Declared public props stay null after load
Property write → load() read	getPrimaryKeyValue()	\$c->pk = …; \$c->load(); is dead code
camelCase keys → fill() write	fill() autoMap	Bogus vwemailpassword entries corrupt _data and fieldMapping
Property write → save() read	getDbData()	Writes the stale value, silently drops user assignments

All of them stem from the single invariant "fill/save only touch _data, never the declared public properties". Fixing them feels like it belongs to one coordinated change on fill() / getDbData() (and maybe a sync() helper) rather than four separate patches.

What I'm doing locally

In our project's BaseORM extends \Tina4\ORM, save() is overridden to sync every user-declared (i.e. not also declared on \Tina4\ORM) public property into _data via reflection before delegating to parent::save():

public function save(): static|false
{
    \$parentRef = new \ReflectionClass(\Tina4\ORM::class);
    \$dataProp = \$parentRef->getProperty('_data');
    \$dataProp->setAccessible(true);
    \$data = \$dataProp->getValue(\$this);

    foreach ((new \ReflectionObject(\$this))->getProperties(\ReflectionProperty::IS_PUBLIC) as \$prop) {
        if (\$prop->isStatic()) continue;
        \$name = \$prop->getName();
        // Subclasses often redeclare tableName/primaryKey/autoMap with
        // their own defaults, so getDeclaringClass() returns the
        // subclass. Check the parent directly.
        if (\$parentRef->hasProperty(\$name)) continue;
        if (!\$prop->isInitialized(\$this)) continue;
        \$data[\$name] = \$this->\$name;
    }

    \$dataProp->setValue(\$this, \$data);
    return parent::save();
}

Combined with the fill() identity-map guard and the load() override from the earlier comments, this gets the full v2-style load → modify → save flow working on v3.10.85.

Suggested upstream fix direction

The cleanest upstream fix is probably to make _data the single source of truth and have fill() mirror into declared public properties (and either use __set() + virtual storage for assignments, or have save() mirror declared public properties back into _data). Whichever way is chosen, load() should not double-fill — selectOne() already populates state correctly and the second \$this->fill(\$result->getData()) is where the autoMap corruption originates.

Version observed: tina4stack/tina4php v3.10.85