From b500631d0ab8f76e929149e3b738b2789a72b9dc Mon Sep 17 00:00:00 2001 From: Brandon Kelly Date: Thu, 9 Apr 2020 06:14:29 -0700 Subject: [PATCH] Document [alias=>table] syntax for join methods (#17967) --- framework/db/Query.php | 40 ++++++++++++++++++++++++---------------- 1 file changed, 24 insertions(+), 16 deletions(-) diff --git a/framework/db/Query.php b/framework/db/Query.php index 093b340904..6713ac08d4 100644 --- a/framework/db/Query.php +++ b/framework/db/Query.php @@ -921,16 +921,18 @@ PATTERN; * Appends a JOIN part to the query. * The first parameter specifies what type of join it is. * @param string $type the type of join, such as INNER JOIN, LEFT JOIN. - * @param string|array $table the table to be joined. + * @param string|array $table the table or sub-query to be joined. * * Use a string to represent the name of the table to be joined. * The table name can contain a schema prefix (e.g. 'public.user') and/or table alias (e.g. 'user u'). * The method will automatically quote the table name unless it contains some parenthesis * (which means the table is given as a sub-query or DB expression). * - * Use an array to represent joining with a sub-query. The array must contain only one element. - * The value must be a [[Query]] object representing the sub-query while the corresponding key - * represents the alias for the sub-query. + * You may also specify the table as an array with one element, using the array key as the table alias + * (e.g. ['u' => 'user']). + * + * To join a sub-query, use an array with one element, with the value set to a [[Query]] object + * representing the sub-query, and the corresponding key representing the alias. * * @param string|array $on the join condition that should appear in the ON part. * Please refer to [[where()]] on how to specify this parameter. @@ -955,16 +957,18 @@ PATTERN; /** * Appends an INNER JOIN part to the query. - * @param string|array $table the table to be joined. + * @param string|array $table the table or sub-query to be joined. * * Use a string to represent the name of the table to be joined. * The table name can contain a schema prefix (e.g. 'public.user') and/or table alias (e.g. 'user u'). * The method will automatically quote the table name unless it contains some parenthesis * (which means the table is given as a sub-query or DB expression). * - * Use an array to represent joining with a sub-query. The array must contain only one element. - * The value must be a [[Query]] object representing the sub-query while the corresponding key - * represents the alias for the sub-query. + * You may also specify the table as an array with one element, using the array key as the table alias + * (e.g. ['u' => 'user']). + * + * To join a sub-query, use an array with one element, with the value set to a [[Query]] object + * representing the sub-query, and the corresponding key representing the alias. * * @param string|array $on the join condition that should appear in the ON part. * Please refer to [[join()]] on how to specify this parameter. @@ -979,16 +983,18 @@ PATTERN; /** * Appends a LEFT OUTER JOIN part to the query. - * @param string|array $table the table to be joined. + * @param string|array $table the table or sub-query to be joined. * * Use a string to represent the name of the table to be joined. * The table name can contain a schema prefix (e.g. 'public.user') and/or table alias (e.g. 'user u'). * The method will automatically quote the table name unless it contains some parenthesis * (which means the table is given as a sub-query or DB expression). * - * Use an array to represent joining with a sub-query. The array must contain only one element. - * The value must be a [[Query]] object representing the sub-query while the corresponding key - * represents the alias for the sub-query. + * You may also specify the table as an array with one element, using the array key as the table alias + * (e.g. ['u' => 'user']). + * + * To join a sub-query, use an array with one element, with the value set to a [[Query]] object + * representing the sub-query, and the corresponding key representing the alias. * * @param string|array $on the join condition that should appear in the ON part. * Please refer to [[join()]] on how to specify this parameter. @@ -1003,16 +1009,18 @@ PATTERN; /** * Appends a RIGHT OUTER JOIN part to the query. - * @param string|array $table the table to be joined. + * @param string|array $table the table or sub-query to be joined. * * Use a string to represent the name of the table to be joined. * The table name can contain a schema prefix (e.g. 'public.user') and/or table alias (e.g. 'user u'). * The method will automatically quote the table name unless it contains some parenthesis * (which means the table is given as a sub-query or DB expression). * - * Use an array to represent joining with a sub-query. The array must contain only one element. - * The value must be a [[Query]] object representing the sub-query while the corresponding key - * represents the alias for the sub-query. + * You may also specify the table as an array with one element, using the array key as the table alias + * (e.g. ['u' => 'user']). + * + * To join a sub-query, use an array with one element, with the value set to a [[Query]] object + * representing the sub-query, and the corresponding key representing the alias. * * @param string|array $on the join condition that should appear in the ON part. * Please refer to [[join()]] on how to specify this parameter.