Feature/added shortcuts

.php_cs.cache

@@ -1 +1 @@
-{"php":"7.4.1","version":"2.16.1","indent":"    ","lineEnding":"\n","rules":{"blank_line_after_namespace":true,"braces":{"allow_single_line_closure":true},"class_definition":{"single_line":true},"constant_case":true,"elseif":true,"function_declaration":true,"indentation_type":true,"line_ending":true,"lowercase_keywords":true,"method_argument_space":true,"no_break_comment":true,"no_closing_tag":true,"no_spaces_after_function_name":true,"no_spaces_inside_parenthesis":true,"no_trailing_whitespace":true,"no_trailing_whitespace_in_comment":true,"single_blank_line_at_eof":true,"single_class_element_per_statement":true,"single_import_per_statement":true,"switch_case_semicolon_to_colon":true,"switch_case_space":true,"visibility_required":true,"encoding":true,"full_opening_tag":true,"array_syntax":{"syntax":"short"},"binary_operator_spaces":true,"blank_line_after_opening_tag":true,"blank_line_before_statement":{"statements":["return"]},"cast_spaces":true,"class_attributes_separation":{"elements":["method"]},"concat_space":true,"declare_equal_normalize":true,"function_typehint_space":true,"include":true,"increment_style":true,"lowercase_cast":true,"lowercase_static_reference":true,"magic_constant_casing":true,"magic_method_casing":true,"native_function_casing":true,"native_function_type_declaration_casing":true,"new_with_braces":true,"no_blank_lines_after_class_opening":true,"no_blank_lines_after_phpdoc":true,"no_empty_comment":true,"no_empty_phpdoc":true,"no_empty_statement":true,"no_extra_blank_lines":{"tokens":["curly_brace_block","extra","parenthesis_brace_block","square_brace_block","throw","use"]},"no_leading_import_slash":true,"no_leading_namespace_whitespace":true,"no_mixed_echo_print":true,"no_multiline_whitespace_around_double_arrow":true,"no_short_bool_cast":true,"no_singleline_whitespace_before_semicolons":true,"no_spaces_around_offset":true,"no_trailing_comma_in_list_call":true,"no_trailing_comma_in_singleline_array":true,"no_unneeded_control_parentheses":true,"no_unneeded_curly_braces":true,"no_unneeded_final_method":true,"no_unused_imports":true,"no_whitespace_before_comma_in_array":true,"no_whitespace_in_blank_line":true,"normalize_index_brace":true,"object_operator_without_whitespace":true,"ordered_imports":true,"php_unit_fqcn_annotation":true,"phpdoc_align":{"tags":["method","param","property","return","throws","type","var"]},"phpdoc_annotation_without_dot":true,"phpdoc_indent":true,"phpdoc_inline_tag":true,"phpdoc_no_access":true,"phpdoc_no_alias_tag":true,"phpdoc_no_package":true,"phpdoc_no_useless_inheritdoc":true,"phpdoc_return_self_reference":true,"phpdoc_scalar":true,"phpdoc_separation":true,"phpdoc_single_line_var_spacing":true,"phpdoc_summary":true,"phpdoc_to_comment":true,"phpdoc_trim":true,"phpdoc_trim_consecutive_blank_line_separation":true,"phpdoc_types":true,"phpdoc_types_order":{"null_adjustment":"always_last","sort_algorithm":"none"},"phpdoc_var_without_name":true,"return_type_declaration":true,"semicolon_after_instruction":true,"short_scalar_cast":true,"single_blank_line_before_namespace":true,"single_line_comment_style":{"comment_types":["hash"]},"single_line_throw":true,"single_quote":true,"single_trait_insert_per_statement":true,"space_after_semicolon":{"remove_in_empty_for_expressions":true},"standardize_increment":true,"standardize_not_equals":true,"ternary_operator_spaces":true,"trailing_comma_in_multiline_array":true,"trim_array_spaces":true,"unary_operator_spaces":true,"whitespace_after_comma_in_array":true,"yoda_style":true},"hashes":{"src\/Driver\/MysqlDriver.php":197127788,"src\/Driver\/SQLiteDriver.php":1109810055,"src\/Driver\/Driver.php":2379534927,"src\/Driver\/PostgreSQLDriver.php":1279477825,"src\/Credentials.php":1470751445,"src\/Result.php":1940786624,"src\/Connection.php":2724048866,"src\/Mock\/MockedDBALConnection.php":2847858253,"src\/Mock\/MockedDriver.php":3163021275,"tests\/ConnectionTest.php":3573353698,"tests\/SQLiteConnectionTest.php":624031957,"tests\/PostgreSQLConnectionTest.php":4136564836,"tests\/MysqlConnectionTest.php":3860731532,"src\/Driver\/Mysql\/MysqlDriver.php":893576140,"src\/Driver\/Mysql\/EmptyDoctrineMysqlDriver.php":3752159343,"src\/Driver\/PlainDriverException.php":1979220338,"src\/Driver\/SQLite\/SQLiteDriver.php":821709053,"src\/Driver\/SQLite\/EmptyDoctrineSQLiteDriver.php":117021226,"src\/Driver\/PostgreSQL\/EmptyDoctrinePostgreSQLDriver.php":2852569520,"src\/Driver\/PostgreSQL\/PostgreSQLDriver.php":3569795044}}
+{"php":"7.4.2","version":"2.16.1","indent":"    ","lineEnding":"\n","rules":{"blank_line_after_namespace":true,"braces":{"allow_single_line_closure":true},"class_definition":{"single_line":true},"constant_case":true,"elseif":true,"function_declaration":true,"indentation_type":true,"line_ending":true,"lowercase_keywords":true,"method_argument_space":true,"no_break_comment":true,"no_closing_tag":true,"no_spaces_after_function_name":true,"no_spaces_inside_parenthesis":true,"no_trailing_whitespace":true,"no_trailing_whitespace_in_comment":true,"single_blank_line_at_eof":true,"single_class_element_per_statement":true,"single_import_per_statement":true,"switch_case_semicolon_to_colon":true,"switch_case_space":true,"visibility_required":true,"encoding":true,"full_opening_tag":true,"array_syntax":{"syntax":"short"},"binary_operator_spaces":true,"blank_line_after_opening_tag":true,"blank_line_before_statement":{"statements":["return"]},"cast_spaces":true,"class_attributes_separation":{"elements":["method"]},"concat_space":true,"declare_equal_normalize":true,"function_typehint_space":true,"include":true,"increment_style":true,"lowercase_cast":true,"lowercase_static_reference":true,"magic_constant_casing":true,"magic_method_casing":true,"native_function_casing":true,"native_function_type_declaration_casing":true,"new_with_braces":true,"no_blank_lines_after_class_opening":true,"no_blank_lines_after_phpdoc":true,"no_empty_comment":true,"no_empty_phpdoc":true,"no_empty_statement":true,"no_extra_blank_lines":{"tokens":["curly_brace_block","extra","parenthesis_brace_block","square_brace_block","throw","use"]},"no_leading_import_slash":true,"no_leading_namespace_whitespace":true,"no_mixed_echo_print":true,"no_multiline_whitespace_around_double_arrow":true,"no_short_bool_cast":true,"no_singleline_whitespace_before_semicolons":true,"no_spaces_around_offset":true,"no_trailing_comma_in_list_call":true,"no_trailing_comma_in_singleline_array":true,"no_unneeded_control_parentheses":true,"no_unneeded_curly_braces":true,"no_unneeded_final_method":true,"no_unused_imports":true,"no_whitespace_before_comma_in_array":true,"no_whitespace_in_blank_line":true,"normalize_index_brace":true,"object_operator_without_whitespace":true,"ordered_imports":true,"php_unit_fqcn_annotation":true,"phpdoc_align":{"tags":["method","param","property","return","throws","type","var"]},"phpdoc_annotation_without_dot":true,"phpdoc_indent":true,"phpdoc_inline_tag":true,"phpdoc_no_access":true,"phpdoc_no_alias_tag":true,"phpdoc_no_package":true,"phpdoc_no_useless_inheritdoc":true,"phpdoc_return_self_reference":true,"phpdoc_scalar":true,"phpdoc_separation":true,"phpdoc_single_line_var_spacing":true,"phpdoc_summary":true,"phpdoc_to_comment":true,"phpdoc_trim":true,"phpdoc_trim_consecutive_blank_line_separation":true,"phpdoc_types":true,"phpdoc_types_order":{"null_adjustment":"always_last","sort_algorithm":"none"},"phpdoc_var_without_name":true,"return_type_declaration":true,"semicolon_after_instruction":true,"short_scalar_cast":true,"single_blank_line_before_namespace":true,"single_line_comment_style":{"comment_types":["hash"]},"single_line_throw":true,"single_quote":true,"single_trait_insert_per_statement":true,"space_after_semicolon":{"remove_in_empty_for_expressions":true},"standardize_increment":true,"standardize_not_equals":true,"ternary_operator_spaces":true,"trailing_comma_in_multiline_array":true,"trim_array_spaces":true,"unary_operator_spaces":true,"whitespace_after_comma_in_array":true,"yoda_style":true},"hashes":{"src\/Driver\/Mysql\/MysqlDriver.php":1496639553,"src\/Driver\/Mysql\/EmptyDoctrineMysqlDriver.php":3752159343,"src\/Driver\/PlainDriverException.php":1220843308,"src\/Driver\/SQLite\/SQLiteDriver.php":1552696176,"src\/Driver\/SQLite\/EmptyDoctrineSQLiteDriver.php":117021226,"src\/Driver\/Driver.php":2379534927,"src\/Driver\/PostgreSQL\/EmptyDoctrinePostgreSQLDriver.php":2852569520,"src\/Driver\/PostgreSQL\/PostgreSQLDriver.php":2231856679,"src\/Credentials.php":1470751445,"src\/Result.php":1940786624,"src\/Connection.php":297218298,"src\/Mock\/MockedDBALConnection.php":2847858253,"src\/Mock\/MockedDriver.php":1506357739,"tests\/ConnectionTest.php":4000367914,"tests\/SQLiteConnectionTest.php":624031957,"tests\/PostgreSQLConnectionTest.php":2591829216,"tests\/MysqlConnectionTest.php":3860731532}}

README.md

@@ -59,10 +59,10 @@ use Drift\DBAL\Result;
  */
 $promise = $connection
     ->insert('test', [
-        'id' => '?',
-        'field1' => '?',
-        'field2' => '?',
-    ], ['1', 'val11', 'val12'])
+        'id' => '1',
+        'field1' => 'val1',
+        'field2' => 'val2',
+    ])
     ->then(function(Result $_) use ($connection) {
         $queryBuilder = $connection->createQueryBuilder();
 
@@ -85,6 +85,104 @@ $promise = $connection
 
 You can use, at this moment, adapters for `mysql`, `postgresql`, and `sqlite`.
 
+## Connection shortcuts
+
+This DBAL introduce some shortcuts useful for your projects on top of Doctrine
+query builder and escaping parametrization.
+
+### Insert
+
+Inserts a new row in a table. Needs the table and an array with fields and their
+values. Returns a Promise.
+
+```php
+$connection->insert('test', [
+    'id' => '1',
+    'field1' => 'value1'
+]);
+```
+
+### Update
+
+Updates an existing row from a table. Needs the table, an identifier as array
+and an array of fields with their values. Returns a Promise.
+
+```php
+$connection->update(
+    'test',
+    ['id' => '1'],
+    [
+        'field1' => 'value1',
+        'field2' => 'value2',
+    ]
+);
+```
+
+### Upsert
+
+Insert a row if not exists. Otherwise, it will update the existing row with
+given values. Needs the table, an identifier as array and an array of fields
+with their values. Returns a Promise.
+
+```php
+$connection->upsert(
+    'test',
+    ['id' => '1'],
+    [
+        'field1' => 'value1',
+        'field2' => 'value2',
+    ]
+);
+```
+
+### Delete
+
+Deletes a row if exists. Needs the table and the identifier as array. Returns a
+Promise.
+
+```php
+$connection->delete('test', [
+    'id' => '1'
+]);
+```
+
+### Find one by
+
+Find a row given a where clause. Needs the table and an array of fields with 
+their values. Returns a Promise with, eventually, the result as array of all
+found rows.
+
+```php
+$connection
+    ->findOneById('test', [
+        'id' => '1'
+    ])
+    ->then(function(?array $result) {
+        if (is_null($result)) {
+            // Row with ID=1 not found
+        } else {
+            // Row with ID=1 found.
+            echo $result['id'];
+        }   
+    });
+```
+
+### Find by
+
+Find all rows given an array of where clauses. Needs the table and an array of
+fields with their values. Returns a Promise with, eventually, the result as
+array of all found rows.
+
+```php
+$connection
+    ->findBy('test', [
+        'age' => '33'
+    ])
+    ->then(function(array $result) {
+        echo 'Found ' . count($result) . ' rows'; 
+    });
+```
+
 ## Tests
 
 You can run tests by running `docker-compose up` and by doing `phpunit`.

src/Connection.php

@@ -129,7 +129,7 @@ public function createQueryBuilder(): QueryBuilder
      *
      * @param QueryBuilder $queryBuilder
      *
-     * @return PromiseInterface
+     * @return PromiseInterface<Result>
      */
     public function query(QueryBuilder $queryBuilder): PromiseInterface
     {
@@ -145,56 +145,222 @@ public function query(QueryBuilder $queryBuilder): PromiseInterface
      * @param string $sql
      * @param array  $parameters
      *
-     * @return PromiseInterface
+     * @return PromiseInterface<Result>
      */
-    public function queryBySQL(string $queryBuilder, array $parameters = []): PromiseInterface
+    public function queryBySQL(string $sql, array $parameters = []): PromiseInterface
     {
         return $this
             ->driver
-            ->query($queryBuilder, $parameters);
+            ->query($sql, $parameters);
+    }
+
+    /**
+     * Shortcuts.
+     */
+
+    /**
+     * Find one by.
+     *
+     * connection->findOneById('table', ['id' => 1]);
+     *
+     * @param string $table
+     * @param array  $where
+     *
+     * @return PromiseInterface<array|null>
+     */
+    public function findOneBy(
+        string $table,
+        array $where
+    ): PromiseInterface {
+        return $this
+            ->getResultByWhereClause($table, $where)
+            ->then(function (Result $result) {
+                return $result->fetchFirstRow();
+            });
+    }
+
+    /**
+     * Find by.
+     *
+     * connection->findBy('table', ['id' => 1]);
+     *
+     * @param string $table
+     * @param array  $where
+     *
+     * @return PromiseInterface<array>
+     */
+    public function findBy(
+        string $table,
+        array $where = []
+    ): PromiseInterface {
+        return $this
+            ->getResultByWhereClause($table, $where)
+            ->then(function (Result $result) {
+                return $result->fetchAllRows();
+            });
     }
 
     /**
-     * Insert.
+     * @param string $table
+     * @param array  $values
      *
      * @return PromiseInterface
      */
     public function insert(
         string $table,
-        array $values,
-        array $parameters
+        array $values
     ): PromiseInterface {
         $queryBuilder = $this
             ->createQueryBuilder()
             ->insert($table)
-            ->values($values)
-            ->setParameters($parameters);
+            ->values(array_combine(
+                array_keys($values),
+                array_fill(0, count($values), '?')
+            ))
+            ->setParameters(array_values($values));
+
+        return $this->query($queryBuilder);
+    }
+
+    /**
+     * @param string $table
+     * @param array  $id
+     * @param array  $values
+     *
+     * @return PromiseInterface
+     *
+     * @throws InvalidArgumentException
+     */
+    public function delete(
+        string $table,
+        array $id,
+        array $values
+    ): PromiseInterface {
+        if (empty($id)) {
+            throw InvalidArgumentException::fromEmptyCriteria();
+        }
+
+        $queryBuilder = $this
+            ->createQueryBuilder()
+            ->delete($table);
+
+        $this->applyWhereClausesFromArray($queryBuilder, $values);
 
         return $this->query($queryBuilder);
     }
 
     /**
-     * Update.
+     * @param string $table
+     * @param array  $id
+     * @param array  $values
      *
      * @return PromiseInterface
      *
      * @throws InvalidArgumentException
      */
-    public function deleteById(
+    public function update(
         string $table,
         array $id,
-        array $parameters
+        array $values
     ): PromiseInterface {
         if (empty($id)) {
             throw InvalidArgumentException::fromEmptyCriteria();
         }
 
         $queryBuilder = $this
             ->createQueryBuilder()
-            ->delete($table)
-            ->where($id)
-            ->setParameters($parameters);
+            ->update($table);
+
+        $parameters = $queryBuilder->getParameters();
+        foreach ($values as $field => $value) {
+            $queryBuilder->set($field, '?');
+            $parameters[] = $value;
+        }
+        $queryBuilder->setParameters($parameters);
+        $this->applyWhereClausesFromArray($queryBuilder, $id);
+
+        return $this
+            ->query($queryBuilder)
+            ->then(function (Result $result) {
+                return $result->fetchAllRows();
+            });
+    }
+
+    /**
+     * @param string $table
+     * @param array  $id
+     * @param array  $values
+     *
+     * @return PromiseInterface
+     *
+     * @throws InvalidArgumentException
+     */
+    public function upsert(
+        string $table,
+        array $id,
+        array $values
+    ) {
+        return $this
+            ->findOneBy($table, $id)
+            ->then(function (?array $result) use ($table, $id, $values) {
+                return is_null($result)
+                    ? $this->insert($table, array_merge($id, $values))
+                    : $this->update($table, $id, $values);
+            });
+    }
+
+    /**
+     * Get result by where clause.
+     *
+     * @param string $table
+     * @param array  $where
+     *
+     * @return PromiseInterface<Result>
+     */
+    private function getResultByWhereClause(
+        string $table,
+        array $where
+    ): PromiseInterface {
+        $queryBuilder = $this
+            ->createQueryBuilder()
+            ->select('t.*')
+            ->from($table, 't');
+
+        $this->applyWhereClausesFromArray($queryBuilder, $where);
 
         return $this->query($queryBuilder);
     }
+
+    /**
+     * Apply where clauses.
+     *
+     * [
+     *      "id" => 1,
+     *      "name" => "Marc"
+     * ]
+     *
+     * to
+     *
+     * [
+     *      [ "id = ?", "name = ?"],
+     *      [1, "Marc"]
+     * ]
+     *
+     * @param QueryBuilder $queryBuilder
+     * @param array        $array
+     */
+    private function applyWhereClausesFromArray(
+        QueryBuilder $queryBuilder,
+        array $array
+    ) {
+        $params = $queryBuilder->getParameters();
+        foreach ($array as $field => $value) {
+            $queryBuilder->andWhere(
+                $queryBuilder->expr()->eq($field, '?')
+            );
+            $params[] = $value;
+        }
+
+        $queryBuilder->setParameters($params);
+    }
 }

src/Driver/PlainDriverException.php

@@ -39,8 +39,7 @@ final class PlainDriverException extends Exception implements DriverException
     public static function createFromMessageAndErrorCode(
         string $message,
         string $sqlState
-    ): self
-    {
+    ): self {
         $exception = new self($message);
         $exception->sqlState = $sqlState;