From e54824abb14b68bdeb367956ec32a40104a224fc Mon Sep 17 00:00:00 2001
From: Pierre Rineau <pierre.rineau@makina-corpus.com>
Date: Mon, 26 Feb 2024 13:44:55 +0100
Subject: [PATCH] no issue - various error handling fixes

---
 docs/content/bridges/error.md                 | 59 +++++++++++++++++++
 src/Bridge/AbstractBridge.php                 |  2 +-
 src/Bridge/Bridge.php                         |  2 +-
 src/Bridge/ErrorConverter.php                 |  2 +-
 .../PdoPostgreSQLErrorConverter.php           |  1 +
 5 files changed, 63 insertions(+), 3 deletions(-)
 create mode 100644 docs/content/bridges/error.md

diff --git a/docs/content/bridges/error.md b/docs/content/bridges/error.md
new file mode 100644
index 0000000..ef963f9
--- /dev/null
+++ b/docs/content/bridges/error.md
@@ -0,0 +1,59 @@
+# Error handling
+
+## Query builder errors
+
+Query builder errors are the generic exceptions for the whole API which are
+not server errors, they are used for:
+
+ - misconfiguration errors,
+ - query builder invalid arguments errors,
+ - value conversion errors,
+ - result set errors.
+
+They all inherit from `MakinaCorpus\QueryBuilder\Error\QueryBuilderError`.
+
+## Server errors
+
+All server side errors are exception, when a driver error is caught and supported,
+it will be converted to a `MakinaCorpus\QueryBuilder\Error\Bridge\*` exception.
+
+When an error is not supported then the generic
+`MakinaCorpus\QueryBuilder\Error\Bridge\ServerError` is raised.
+
+## Bridge errors passthrough
+
+Each bridge implements one or more `MakinaCorpus\QueryBuilder\Bridge\ErrorConverter`
+classes, depending upon the underlaying connector and platform.
+
+This object converts the driver error to a uniformized exception provided under
+the `MakinaCorpus\QueryBuilder\Error\Bridge` namespace.
+
+Per default, specific error converters are lazily registered when a first error
+happens. When used with Doctrine DBAL, you might want to keep a seemless integration
+with it, and let the `doctrine/dbal` exception pass, in order to do this, simply
+call the `Bridge::disableErrorConverter()` method when initializing the bridge:
+
+```php
+use Doctrine\DBAL\DriverManager;
+use MakinaCorpus\QueryBuilder\Bridge\Doctrine\DoctrineQueryBuilder;
+
+$connection = DriverManager::getConnection(['driver' => 'pdo_pgsql', /* ... */]);
+$queryBuilder = new DoctrineQueryBuilder($connection);
+
+// Here it is:
+$queryBuilder->disableErrorConverter();
+```
+
+:::note
+This works with all bridges.
+:::
+
+:::note
+The `makinacorpus/query-builder-bundle` will per default configure the `doctrine/dbal`
+bridge to disable specific error handling in order to be completely transparent for
+users that will usually expect Doctrine DBAL errors.
+:::
+
+:::warning
+This method must be called before any SQL request really happens.
+:::
diff --git a/src/Bridge/AbstractBridge.php b/src/Bridge/AbstractBridge.php
index 6ce5500..bfb9694 100644
--- a/src/Bridge/AbstractBridge.php
+++ b/src/Bridge/AbstractBridge.php
@@ -45,7 +45,7 @@ public function __construct(?ConverterPluginRegistry $converterPluginRegistry =
     /**
      * Disable error converter. Must be called prior to initilization.
      */
-    public function disableErrorConverter(): bool
+    public function disableErrorConverter(): void
     {
         if ($this->errorConverter) {
             throw new QueryBuilderError("Bridge is already initialized, configuration must happend before it gets used.");
diff --git a/src/Bridge/Bridge.php b/src/Bridge/Bridge.php
index 6c55310..9c3f474 100644
--- a/src/Bridge/Bridge.php
+++ b/src/Bridge/Bridge.php
@@ -13,7 +13,7 @@ interface Bridge extends QueryExecutor, QueryBuilder
     /**
      * Disable error converter. Must be called prior to initilization.
      */
-    public function disableErrorConverter(): bool;
+    public function disableErrorConverter(): void;
 
     /**
      * Get server name.
diff --git a/src/Bridge/ErrorConverter.php b/src/Bridge/ErrorConverter.php
index 9b45754..87adac9 100644
--- a/src/Bridge/ErrorConverter.php
+++ b/src/Bridge/ErrorConverter.php
@@ -11,7 +11,7 @@ interface ErrorConverter
      *
      * @param \Throwable $error
      *   Original error from driver.
-     * @param null|string $sqlQuery
+     * @param null|string $sql
      *   The raw SQL query that is the subject of this error.
      * @param null|string $message
      *   Overriden error message, if any.
diff --git a/src/Bridge/Pdo/ErrorConverter/PdoPostgreSQLErrorConverter.php b/src/Bridge/Pdo/ErrorConverter/PdoPostgreSQLErrorConverter.php
index be2bbfc..8e16895 100644
--- a/src/Bridge/Pdo/ErrorConverter/PdoPostgreSQLErrorConverter.php
+++ b/src/Bridge/Pdo/ErrorConverter/PdoPostgreSQLErrorConverter.php
@@ -35,6 +35,7 @@ public function convertError(\Throwable $error, ?string $sql = null, ?string $me
         }
 
         $errorCode = $error->errorInfo[1] ?? $error->getCode();
+        $sqlState = $error->errorInfo[0] ?? $error->getCode();
 
         switch ($errorCode) {