no issue - various error handling fixes

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.
+:::

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.");

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.

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.

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) {