feat: support BackedEnum values in database binds

[memleakd]

Description

This PR adds support for PHP BackedEnum values in database escaping, query bindings, and escaped Query Builder values.

It was inspired by @maniaba's forum post and #10223.

For apps that use native PHP enums for domain values, this makes database code a bit nicer to write:

$db->table('users')
    ->where('status', UserStatus::Active)
    ->get();

CodeIgniter will use the enum's backing value when escaping it, so string-backed enums are treated like strings and int-backed enums are treated like integers.

This avoids repeating ->value at every query call site, while keeping raw SQL and escape-disabled values in the caller's control.

The implementation is intentionally small: enum cases are unwrapped during database escaping, so regular query bindings and escaped Query Builder values use the same existing path.

Checklist:

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value (without duplication)
• Unit testing, with >80% coverage
• User guide updated
• Conforms to style guide

[datamweb]

PR look good to me.

[datamweb]

While reviewing this (specifically the use of str_replace for query formatting), a broader architectural thought came to my mind: Why don't we have a dedicated assertSqlEquals method?

Currently, across many test files, we are writing boilerplate code like str_replace("\n", ' ', ...) to normalize SQL strings before comparing them. We could easily add an assertSqlEquals() method directly into use CodeIgniter\Test\DatabaseTestTrait;.

Something like this:

public function assertSqlEquals(string $expected, string $actual, string $message = ''): void
{
    $normalize = fn(string $sql) => trim(strtolower(preg_replace('/\s+/', ' ', $sql)));
    $this->assertSame($normalize($expected), $normalize($actual), $message);
}

Let's see what the team thinks about this, though I believe it should be followed up separately in its own PR.

[memleakd]

Thanks for the review!

Yeah, I like that idea as a follow-up. I'd keep this PR focused, but a small test helper for this repeated SQL formatting pattern would definitely be worth exploring separately.

Only thing I'd be careful with is making the normalization too clever, so it doesn't accidentally hide meaningful SQL differences.

[michalsn]

I'm not sure about this normalization:

trim(strtolower(preg_replace('/\s+/', ' ', $sql)))

That would transform our SQL way too much silently.

Personally, I would stick to what we use currently, so:

public function assertSqlEquals(string $expected, string $actual, string $message = ''): void
{
    $this->assertSame(
        $expected,
        str_replace("\n", ' ', $actual),
        $message,
    );
}

would make sense to me. But I would place it in the CIUnitTestCase because many builder unit tests don't use/need DatabaseTestTrait.

[michalsn]

Seems like native prepared statements are not supported.

$query = $db->prepare(...);
$query->execute(StatusEnum::ACTIVE);

[michalsn]

Please add a test to make sure objects are also supported.

[michalsn]

I'm not sure about this normalization:

trim(strtolower(preg_replace('/\s+/', ' ', $sql)))

That would transform our SQL way too much silently.

Personally, I would stick to what we use currently, so:

public function assertSqlEquals(string $expected, string $actual, string $message = ''): void
{
    $this->assertSame(
        $expected,
        str_replace("\n", ' ', $actual),
        $message,
    );
}

would make sense to me. But I would place it in the CIUnitTestCase because many builder unit tests don't use/need DatabaseTestTrait.