feat: add UniqueConstraintViolationException

[michalsn]

Description
This PR adds:

• UniqueConstraintViolationException (extends DatabaseException), thrown on duplicate key violations across all database drivers
• $db->getLastException(): ?DatabaseException - when DBDebug is false, exceptions are not thrown. This method provides a reliable way to inspect the type of failure, since raw error codes from $db->error()['code'] differ across drivers
• DatabaseException::getDatabaseCode(): int|string - exposes the native driver error code on the exception itself, as getCode() is constrained to int by PHP Throwable interface and cannot carry string SQLSTATE codes

getLastException() is intentionally a transitional API. The long-term direction is to drop DBDebug = false entirely (v5 ?), leaving exceptions as the only error signalling mechanism - consistent with how every other major PHP framework handles database errors.

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

[paulbalandan]

Is this related to the $databaseCode property? If yes, why not proceed to promote it as it is new?

[michalsn]

Rector was proposing this:

public function __construct(string $message = '', protected int|string $databaseCode = 0, ?Throwable $previous = null)

Although named parameters are not part of our BC promise, this class extends RuntimeException, and its constructor defines the second argument as $code. So changing this introduces an inconsistency with the parent signature without providing a meaningful benefit.

[paulbalandan]

I see. Why not just make the constructor parameter as $databaseCode already, so that it would not clash with $code which do not accept any native type. Like in https://3v4l.org/hS5D0#vnull

[github-actions]

👋 Hi, @michalsn!

We detected conflicts in your PR against the base branch 🙊
You may want to sync 🔄 your branch with upstream!

Ref: Syncing Your Branch