Update doc for Query::join() methods

docs/guide/en/query/join.md

@@ -3,7 +3,7 @@
 The `Yiisoft\Db\Query\Query::join()` method specifies the `JOIN` fragment of a SQL query.
 
 ```php
-$query->join('LEFT JOIN', 'post', 'post.user_id = user.id');
+$query->join('LEFT JOIN', 'post', ['post.user_id' => 'user.id']);
 ```
 
 The relevant part of SQL is:
@@ -18,10 +18,8 @@ The `Yiisoft\Db\Query\Query::join()` method takes four parameters:
 - `table`: the name of the table to join.
 - `on`: optional join condition, that's the `ON` fragment.
   Refer to `Yiisoft\Db\Query\Query::where()` for details about specifying a condition.
-  > Note: The array syntax doesn't work for specifying a column based condition.
-  > `['user.id' => 'comment.userId']` will result in a condition
-  > where the user id must be equal to the string `comment.userId`.
-  > You should use the string syntax instead and specify the condition as `user.id = comment.userId`.
+  > [!IMPORTANT]
+  > Keys and values of an associative array are treated as column names and will be quoted before being used in an SQL query.
 - `params`: optional parameters to bind to the join condition.
 
 You can use the following shortcut methods to specify `INNER JOIN`, `LEFT JOIN` and `RIGHT JOIN`, respectively.
@@ -33,7 +31,7 @@ You can use the following shortcut methods to specify `INNER JOIN`, `LEFT JOIN`
 For example:
 
 ```php
-$query->leftJoin('post', 'post.user_id = user.id');
+$query->leftJoin('post', ['post.user_id' => 'user.id']);
 ```
 
 To join with many tables, call the join methods many times, once for each table.
@@ -44,10 +42,10 @@ To do so, specify the sub-queries to join as `Yiisoft\Db\Query\Query` objects.
 For example:
 
 ```php
-use Yiisoft\Db\Query\Query;
+/** @var Yiisoft\Db\Connection\ConnectionInterface $db */
 
-$subQuery = (new Query())->from('post');
-$query->leftJoin(['u' => $subQuery], 'u.id = author_id');
+$subQuery = $db->select()->from('post');
+$query->leftJoin(['u' => $subQuery], ['u.id' => 'author_id']);
 ```
 
 In this case, you should put the subquery into array and use the array key to specify the alias.

docs/guide/en/query/with-query.md

@@ -20,7 +20,7 @@ $initialQuery = (new Query($db))
 $recursiveQuery = (new Query($db))
     ->select(['aic.parent', 'aic.child'])
     ->from(['aic' => '{{%auth_item_child}}'])
-    ->innerJoin('t1', 't1.child = aic.parent');
+    ->innerJoin('t1', ['t1.child' => 'aic.parent']);
 
 $mainQuery = (new Query($db))
     ->select(['parent', 'child'])

docs/guide/pt-BR/query/join.md

@@ -3,7 +3,7 @@
 O método `Yiisoft\Db\Query\Query::join()` especifica o fragmento `JOIN` de uma consulta SQL.
 
 ```php
-$query->join('LEFT JOIN', 'post', 'post.user_id = user.id');
+$query->join('LEFT JOIN', 'post', ['post.user_id' => 'user.id']);
 ```
 
 A parte relevante do SQL é:
@@ -18,10 +18,8 @@ O método `Yiisoft\Db\Query\Query::join()` usa quatro parâmetros:
 - `table`: o nome da tabela a ser unida.
 - `on`: condição de junção opcional, esse é o fragmento `ON`.
    Consulte `Yiisoft\Db\Query\Query::where()` para obter detalhes sobre como especificar uma condição.
-   > Nota: A sintaxe de array não funciona para especificar uma condição baseada em coluna.
-   > `['user.id' => 'comment.userId']` resultará em uma condição
-   > onde o ID do usuário deve ser igual à string `comment.userId`.
-   > Você deve usar a sintaxe de string e especificar a condição como `user.id = comment.userId`.
+  > [!IMPORTANT]
+  > Chaves e valores de uma matriz associativa são tratados como nomes de colunas e serão citados antes de serem usados em uma consulta SQL.
 - `params`: parâmetros opcionais para vincular à condição de junção.
 
 Você pode usar os seguintes métodos de atalho para especificar `INNER JOIN`, `LEFT JOIN` e `RIGHT JOIN`, respectivamente.
@@ -33,7 +31,7 @@ Você pode usar os seguintes métodos de atalho para especificar `INNER JOIN`, `
 Por exemplo:
 
 ```php
-$query->leftJoin('post', 'post.user_id = user.id');
+$query->leftJoin('post', ['post.user_id' => 'user.id']);
 ```
 
 Para unir muitas tabelas, chame os métodos de junção várias vezes, uma vez para cada tabela.
@@ -44,10 +42,10 @@ Para fazer isso, especifique as subconsultas a serem unidas como objetos `Yiisof
 Por exemplo:
 
 ```php
-use Yiisoft\Db\Query\Query;
+/** @var Yiisoft\Db\Connection\ConnectionInterface $db */
 
-$subQuery = (new Query())->from('post');
-$query->leftJoin(['u' => $subQuery], 'u.id = author_id');
+$subQuery = $db->select()->from('post');
+$query->leftJoin(['u' => $subQuery], ['u.id' => 'author_id']);
 ```
 
 Nesse caso, você deve colocar a subconsulta no array e usar a chave do array para especificar o alias.

docs/guide/pt-BR/query/with-query.md

@@ -20,7 +20,7 @@ $initialQuery = (new Query($db))
 $recursiveQuery = (new Query($db))
     ->select(['aic.parent', 'aic.child'])
     ->from(['aic' => '{{%auth_item_child}}'])
-    ->innerJoin('t1', 't1.child = aic.parent');
+    ->innerJoin('t1', ['t1.child' => 'aic.parent']);
 
 $mainQuery = (new Query($db))
     ->select(['parent', 'child'])

src/Query/QueryPartsInterface.php

@@ -424,15 +424,8 @@ public function innerJoin(array|string $table, array|string $on = '', array $par
      * The value must be a {@see Query} object representing the sub-query while the corresponding key represents the
      * alias for the sub-query.
      * @param array|string $on The join condition that should appear in the ON part. Please refer to {@see where()} on
-     * how to specify this parameter.
-     * Note that the array format of {@see where()} is designed to match columns to values instead of columns to
-     * columns, so the following would **not** work as expected: `['post.author_id' => 'user.id']`, it would match the
-     * `post.author_id` column value against the string `'user.id'`.
-     * It's recommended to use the string syntax here which is more suited for a join:
-     *
-     * ```php
-     * 'post.author_id = user.id'
-     * ```
+     * how to specify this parameter. Keys and values of an associative array are treated as column names and will be
+     * quoted before being used in an SQL query.
      * @param array $params The parameters (name => value) to bind to the query.
      *
      * @psalm-param ParamsType $params