diff --git a/CHANGELOG.md b/CHANGELOG.md index ed1b3147d..01733c66c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -95,6 +95,7 @@ - Chg #980: Add constructor with DB connection to `AbstractCommand` (@vjik) - Enh #979: Allow `ExpressionInterface` for column definitions when create table (@Tigrov) - Enh #982: Reduce binding parameters (@Tigrov) +- Chg #985: Rename `insertWithReturningPks()` to `insertReturningPks()` in `CommandInterface` and `DMLQueryBuilderInterface` (@Tigrov) ## 1.3.0 March 21, 2024 diff --git a/UPGRADE.md b/UPGRADE.md index b78853cff..b81f25328 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -237,6 +237,7 @@ Each table column has its own class in the `Yiisoft\Db\Schema\Column` namespace - Change `$distinct` parameter type in `DQLQueryBuilderInterface::buildSelect()` to `bool`; - Add `QueryInterface` to type of `$columns` parameter of `insertWithReturningPks()` method in `CommandInterface` and `AbstractCommand` class; +- Rename `insertWithReturningPks()` to `insertReturningPks()` method in `CommandInterface` and `DMLQueryBuilderInterface`; - Remove `$params` parameter from `upsert()` method in `CommandInterface` and `AbstractCommand` class; - Add default value to `$updateColumns` and `$params` parameters of `upsert()` method in `DMLQueryBuilderInterface` and `AbstractDMLQueryBuilder` and `AbstractQueryBuilder` classes; diff --git a/docs/guide/en/schema/typecasting.md b/docs/guide/en/schema/typecasting.md index 253939cd2..79f5099ae 100644 --- a/docs/guide/en/schema/typecasting.md +++ b/docs/guide/en/schema/typecasting.md @@ -17,8 +17,9 @@ flowchart LR When saving a value to the database, the value must be in the correct type. For example, if saving a value to a column that is of type `bit`, the value must be an `integer` or `string` depends on DBMS. -By default `update()`, `upsert()`, `insert()`, `insertBatch()` and `insertWithReturningPks()` methods -of `CommandInterface` and `QueryBuilderInterface` instances cast the values to the correct type. +By default `update()`, `insert()`, `insertBatch()`, `insertReturningPks()`, `upsert()`, `upsertReturning()` and +`upsertReturningPks()` methods of `CommandInterface` and `QueryBuilderInterface` instances cast the values +to the correct type. ```php use Yiisoft\Db\Connection\ConnectionInterface; diff --git a/src/Command/AbstractCommand.php b/src/Command/AbstractCommand.php index c9f6af147..c92872710 100644 --- a/src/Command/AbstractCommand.php +++ b/src/Command/AbstractCommand.php @@ -385,7 +385,7 @@ public function insert(string $table, array|QueryInterface $columns): static return $this->setSql($sql)->bindValues($params); } - public function insertWithReturningPks(string $table, array|QueryInterface $columns): array|false + public function insertReturningPks(string $table, array|QueryInterface $columns): array|false { if (empty($this->db->getSchema()->getTableSchema($table)?->getPrimaryKey())) { if ($this->insert($table, $columns)->execute() === 0) { @@ -395,7 +395,7 @@ public function insertWithReturningPks(string $table, array|QueryInterface $colu } $params = []; - $sql = $this->getQueryBuilder()->insertWithReturningPks($table, $columns, $params); + $sql = $this->getQueryBuilder()->insertReturningPks($table, $columns, $params); $this->setSql($sql)->bindValues($params); @@ -405,6 +405,14 @@ public function insertWithReturningPks(string $table, array|QueryInterface $colu return is_array($result) ? $result : false; } + /** + * @deprecated Use {@see insertReturningPks()} instead. It will be removed in version 3.0.0. + */ + public function insertWithReturningPks(string $table, array|QueryInterface $columns): array|false + { + return $this->insertReturningPks($table, $columns); + } + public function execute(): int { $sql = $this->getSql(); diff --git a/src/Command/CommandInterface.php b/src/Command/CommandInterface.php index 6de4e26b1..54ffe4fd6 100644 --- a/src/Command/CommandInterface.php +++ b/src/Command/CommandInterface.php @@ -617,7 +617,7 @@ public function insert(string $table, array|QueryInterface $columns): static; * * Note: The method will quote the `table` and `columns` parameter before using it in the generated SQL. */ - public function insertWithReturningPks(string $table, array|QueryInterface $columns): array|false; + public function insertReturningPks(string $table, array|QueryInterface $columns): array|false; /** * Prepares the SQL statement to be executed. diff --git a/src/Debug/CommandInterfaceProxy.php b/src/Debug/CommandInterfaceProxy.php index f99ad4d22..2062aab35 100644 --- a/src/Debug/CommandInterfaceProxy.php +++ b/src/Debug/CommandInterfaceProxy.php @@ -315,7 +315,7 @@ public function insert(string $table, array|QueryInterface $columns): static return new self($this->decorated->{__FUNCTION__}(...func_get_args()), $this->collector); } - public function insertWithReturningPks(string $table, array|QueryInterface $columns): array|false + public function insertReturningPks(string $table, array|QueryInterface $columns): array|false { /** @var array|false */ return $this->decorated->{__FUNCTION__}(...func_get_args()); diff --git a/src/Driver/Pdo/AbstractPdoCommand.php b/src/Driver/Pdo/AbstractPdoCommand.php index a9e9d9e4f..bbaef80f8 100644 --- a/src/Driver/Pdo/AbstractPdoCommand.php +++ b/src/Driver/Pdo/AbstractPdoCommand.php @@ -192,7 +192,7 @@ protected function getQueryMode(int $queryMode): string self::QUERY_MODE_COLUMN => 'queryColumn', self::QUERY_MODE_CURSOR => 'query', self::QUERY_MODE_SCALAR => 'queryScalar', - self::QUERY_MODE_ROW | self::QUERY_MODE_EXECUTE => 'insertWithReturningPks' + self::QUERY_MODE_ROW | self::QUERY_MODE_EXECUTE => 'insertReturningPks' }; } diff --git a/src/QueryBuilder/AbstractDMLQueryBuilder.php b/src/QueryBuilder/AbstractDMLQueryBuilder.php index 9a66a4a07..2156d53b8 100644 --- a/src/QueryBuilder/AbstractDMLQueryBuilder.php +++ b/src/QueryBuilder/AbstractDMLQueryBuilder.php @@ -121,7 +121,7 @@ public function insert(string $table, array|QueryInterface $columns, array &$par } /** @throws NotSupportedException */ - public function insertWithReturningPks(string $table, array|QueryInterface $columns, array &$params = []): string + public function insertReturningPks(string $table, array|QueryInterface $columns, array &$params = []): string { throw new NotSupportedException(__METHOD__ . '() is not supported by this DBMS.'); } diff --git a/src/QueryBuilder/AbstractQueryBuilder.php b/src/QueryBuilder/AbstractQueryBuilder.php index 176ee89d6..1369b9cad 100644 --- a/src/QueryBuilder/AbstractQueryBuilder.php +++ b/src/QueryBuilder/AbstractQueryBuilder.php @@ -420,9 +420,9 @@ public function insert(string $table, array|QueryInterface $columns, array &$par return $this->dmlBuilder->insert($table, $columns, $params); } - public function insertWithReturningPks(string $table, array|QueryInterface $columns, array &$params = []): string + public function insertReturningPks(string $table, array|QueryInterface $columns, array &$params = []): string { - return $this->dmlBuilder->insertWithReturningPks($table, $columns, $params); + return $this->dmlBuilder->insertReturningPks($table, $columns, $params); } public function isTypecastingEnabled(): bool diff --git a/src/QueryBuilder/DMLQueryBuilderInterface.php b/src/QueryBuilder/DMLQueryBuilderInterface.php index 1b6640805..50cd4e1c4 100644 --- a/src/QueryBuilder/DMLQueryBuilderInterface.php +++ b/src/QueryBuilder/DMLQueryBuilderInterface.php @@ -138,7 +138,7 @@ public function insert(string $table, array|QueryInterface $columns, array &$par * * Note: The method will escape the table and column names. */ - public function insertWithReturningPks(string $table, array|QueryInterface $columns, array &$params = []): string; + public function insertReturningPks(string $table, array|QueryInterface $columns, array &$params = []): string; /** * Returns whether type casting is enabled for the query builder. diff --git a/tests/AbstractQueryBuilderTest.php b/tests/AbstractQueryBuilderTest.php index 4ae938ea4..2b206e6b9 100644 --- a/tests/AbstractQueryBuilderTest.php +++ b/tests/AbstractQueryBuilderTest.php @@ -1968,8 +1968,8 @@ public function testInsert( $this->assertEquals($expectedParams, $params); } - #[DataProviderExternal(QueryBuilderProvider::class, 'insertWithReturningPks')] - public function testInsertWithReturningPks( + #[DataProviderExternal(QueryBuilderProvider::class, 'insertReturningPks')] + public function testInsertReturningPks( string $table, array|QueryInterface $columns, array $params, @@ -1979,7 +1979,7 @@ public function testInsertWithReturningPks( $db = $this->getConnection(true); $qb = $db->getQueryBuilder(); - $this->assertSame($expectedSQL, $qb->insertWithReturningPks($table, $columns, $params)); + $this->assertSame($expectedSQL, $qb->insertReturningPks($table, $columns, $params)); $this->assertSame($expectedParams, $params); } diff --git a/tests/Common/CommonCommandTest.php b/tests/Common/CommonCommandTest.php index 724d02286..071bc64b1 100644 --- a/tests/Common/CommonCommandTest.php +++ b/tests/Common/CommonCommandTest.php @@ -1221,7 +1221,7 @@ public function testInsert(): void $db->close(); } - public function testInsertWithReturningPks(): void + public function testInsertReturningPks(): void { $db = $this->getConnection(true); @@ -1234,20 +1234,20 @@ public function testInsertWithReturningPks(): void $this->assertSame( $expected, - $command->insertWithReturningPks('{{customer}}', ['name' => 'test_1', 'email' => 'test_1@example.com']), + $command->insertReturningPks('{{customer}}', ['name' => 'test_1', 'email' => 'test_1@example.com']), ); $db->close(); } - public function testInsertWithReturningPksWithCompositePK(): void + public function testInsertReturningPksWithCompositePK(): void { $db = $this->getConnection(true); $command = $db->createCommand(); $params = ['id_1' => 99, 'id_2' => 100.5, 'type' => 'test']; - $result = $command->insertWithReturningPks('{{%notauto_pk}}', $params); + $result = $command->insertReturningPks('{{%notauto_pk}}', $params); $this->assertEquals($params['id_1'], $result['id_1']); $this->assertEquals($params['id_2'], $result['id_2']); @@ -2174,7 +2174,7 @@ public function testDecimalValue(): void $db = $this->getConnection(true); $inserted = $db->createCommand() - ->insertWithReturningPks( + ->insertReturningPks( '{{%order}}', ['customer_id' => 1, 'created_at' => 0, 'total' => $decimalValue] ); @@ -2190,11 +2190,11 @@ public function testDecimalValue(): void $this->assertSame($decimalValue, $phpTypecastValue); } - public function testInsertWithReturningPksEmptyValues() + public function testInsertReturningPksEmptyValues() { $db = $this->getConnection(true); - $pkValues = $db->createCommand()->insertWithReturningPks('null_values', []); + $pkValues = $db->createCommand()->insertReturningPks('null_values', []); $expected = match ($db->getDriverName()) { 'pgsql' => ['id' => 1], @@ -2204,7 +2204,7 @@ public function testInsertWithReturningPksEmptyValues() $this->assertSame($expected, $pkValues); } - public function testInsertWithReturningPksWithQuery(): void + public function testInsertReturningPksWithQuery(): void { $db = $this->getConnection(true); @@ -2213,27 +2213,27 @@ public function testInsertWithReturningPksWithQuery(): void 'email' => new Expression("'test_1@example.com'"), ]); - $pkValues = $db->createCommand()->insertWithReturningPks('customer', $query); + $pkValues = $db->createCommand()->insertReturningPks('customer', $query); $this->assertEquals(['id' => 4], $pkValues); } - public function testInsertWithReturningPksEmptyValuesAndNoPk() + public function testInsertReturningPksEmptyValuesAndNoPk() { $db = $this->getConnection(true); - $pkValues = $db->createCommand()->insertWithReturningPks('negative_default_values', []); + $pkValues = $db->createCommand()->insertReturningPks('negative_default_values', []); $this->assertSame([], $pkValues); } - public function testInsertWithReturningPksWithPhpTypecasting(): void + public function testInsertReturningPksWithPhpTypecasting(): void { $db = $this->getConnection(true); $result = $db->createCommand() ->withPhpTypecasting() - ->insertWithReturningPks('notauto_pk', ['id_1' => 1, 'id_2' => 2.5, 'type' => 'test1']); + ->insertReturningPks('notauto_pk', ['id_1' => 1, 'id_2' => 2.5, 'type' => 'test1']); $this->assertSame(['id_1' => 1, 'id_2' => 2.5], $result); } diff --git a/tests/Db/QueryBuilder/QueryBuilderTest.php b/tests/Db/QueryBuilder/QueryBuilderTest.php index 1a047fe1a..78a854595 100644 --- a/tests/Db/QueryBuilder/QueryBuilderTest.php +++ b/tests/Db/QueryBuilder/QueryBuilderTest.php @@ -182,12 +182,12 @@ public function testInsert( $this->assertEquals($expectedParams, $params); } - #[DataProviderExternal(QueryBuilderProvider::class, 'insertWithReturningPks')] - public function testInsertWithReturningPks( + #[DataProviderExternal(QueryBuilderProvider::class, 'insertReturningPks')] + public function testInsertReturningPks( string $table, array|QueryInterface $columns, array $params, - string $expectedSQL, + string $expectedSql, array $expectedParams ): void { $db = $this->getConnection(); @@ -196,10 +196,10 @@ public function testInsertWithReturningPks( $this->expectException(NotSupportedException::class); $this->expectExceptionMessage( - 'Yiisoft\Db\QueryBuilder\AbstractDMLQueryBuilder::insertWithReturningPks() is not supported by this DBMS.' + 'Yiisoft\Db\QueryBuilder\AbstractDMLQueryBuilder::insertReturningPks() is not supported by this DBMS.' ); - $qb->insertWithReturningPks($table, $columns, $params); + $qb->insertReturningPks($table, $columns, $params); } public function testResetSequence(): void diff --git a/tests/Provider/QueryBuilderProvider.php b/tests/Provider/QueryBuilderProvider.php index 7127762f9..587805f4b 100644 --- a/tests/Provider/QueryBuilderProvider.php +++ b/tests/Provider/QueryBuilderProvider.php @@ -1137,7 +1137,7 @@ public static function insert(): array ]; } - public static function insertWithReturningPks(): array + public static function insertReturningPks(): array { return [ ['{{table}}', [], [], '', []],